This is the mail archive of the kawa@sourceware.org mailing list for the Kawa project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: annotations for Kawa


On Dec 10, 2010, at 10:47 PM, Per Bothner wrote:

On 12/07/2010 12:37 PM, Jamison Hope wrote:
On Dec 5, 2010, at 1:42 PM, Per Bothner wrote:

Well, documentation should probably be HTML, not a string:

IMHO those are much less readable, especially when viewed in an editor
with syntax highlighting that'll put a simple string in a different
color from surrounding code, but probably doesn't know what to do with
HTML-embedded-in-Scheme (at least I haven't found an appropriate Emacs
mode for that yet).


Clearly, the documentation-as-typed should have some sort of a syntax to
it, but I don't think full-blown HTML is the way to go, for several
reasons:


1. The documentation should be human-readable as present in the source
code,
so that it can take the place of comments. Having SGML tags around
everything stretches that a bit.

To clarify: I think the *stored* representation (as in the class file)
should be xhtml - or at least that should be supported. That doesn't
mean source in the documentation has to be HTML - it could be any expression
or syntax that can evaluate to HTML - as long as it can be evaluated
(constant-folded) at compile-time.

OK that seems reasonable.


One option I'm toying with is some kind of enhanced "rich-text" literals
with escape sequences. The Scribble system provides some ideas:
http://docs.racket-lang.org/scribble/

Yeah that's another option, if you want to eventually go the full literate-programming route.


However, I don't think I'm ready to make decisions on "rich-text" literals
yet. In the intermediate term, supporting string literals and xml literals
seems OK.

I still lean toward string literals, so that Emacs and a stock Scheme mode will render them in a different color from surrounding code.


2. When documentation is requested from the REPL (by #'documentation or
#'apropos or #'describe-function or whatever we end up having), tags
will get in the way just like they do in the source code.

That's just a matter of pretty-printing. On a dumb console you could do
the kind of transformation that makeinfo does to produce info file.

That's true. I had in mind something self-evaluating, but I guess there's no reason why that has to be the case.


Of course there is no good reason (except history) why consoles don't
support multiple fonts,  colors, and graphics:
http://per.bothner.com/blog/2007/ReplPane/

Well, we do have ANSI escape codes (at least on non-Windows). But I know what you're saying. I've adopted a ReplPane as an embedded command interpreter in some of my Java apps, as a matter of fact. Like you mention in the blog post, though, it's annoyingly easy to trigger exceptions. For general Kawa use, I usually stick to "rlwrap java kawa.repl".


3. When being used to generate reference documentation, HTML is only one
of several possibly desirable outputs.

XHTML can be translated into other output formats without much difficulty,
especially if it's a restricted standardized subset of XHTML.


That's why you use TexInfo, right?

Partly. I've considered dropping TexInfo and just using DocBook. TexInfo has the advantage that it's less verbose, and rather more readable. However, it's somewhat arcane, and I don't think it would be a good choice for documentation strings. For one I don't know of any library that can process "texinfo fragments".

I wasn't suggesting that we use TexInfo as the intermediate format, I just mentioned it as something that is intended to be translated into various outputs. If you prefer to have XHTML be the intermediate (as well as one of the outputs), that's fine.


For readability and less of a learning curve, I think the documentation
syntax should be similar to Javadoc or Doxygen, or maybe ELisp docstrings
(which specially interpret `single-quoted-function-names' and
VARS-IN-CAPS).

Javadoc-style or Doxygen-style might be worth considering. But bottom line: I have a bunch of other things I need to get done first (including getting annotation actually done ...) before I want to get too deep into documentation syntax.

Sure, no need to get too hung up on details right now, I just mentioned it now because it's an additional syntax change on top of the generic annotation format you're adding, so better to at least be thinking about it from the beginning.


For example, we might want to *store* documentation in class files
using XHTML stored in annotations, but the source syntax might be
some form of "doc comments" as in Javadoc or Doxygen.

That was my thought, although not actually as a comment, of course.


Jamie

--
Jamison Hope
The PTR Group
www.theptrgroup.com




Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]