[Doc-SIG] using the same delimiter on the left and right..
Guido van Rossum
guido@digicool.com
Thu, 29 Mar 2001 15:51:52 -0500
[Greg Ward]
> I dunno about everyone else, but my objection to Javadoc is that it's not
> really a markup language -- it just uses HTML and throws in the
> @returns/@throws/etc thingy because those are useful things when documenting
> Java code. (And would be in Python code, too.) IOW, Javadoc is easy to
> turn into HTML, but (I expect) difficult to turn into anything else, unless
> you restrict the set of tags allowed. It sounds like there's no One True
> Javadoc parser, which is probably a PITA.
But this sounds like it's easily formalizable. Pick a set of tags,
and make sure to balk about tags you don't recognize. Having just
(re)written a full HTML parser in Python, it's not that hard to parse.
This has the advantage that we don't have to invent a new language --
picking a subset is much easier. HTML is verbose, but given that
we're aiming for <b>light</b> markup anyway, it shouldn't be much of a
problem.
The big pitfall would be thinking that we could use a parser that
<i>doesn't</i> understand HTML but just passes < and > through
unscathed. That's probably how Javadoc started, but that's not where
it's now. This is another big sin of ST (or maybe of ZWiki).
> > > Pod is used successfully in the Perl world, and is a clear winner there.
> > > I find it intensely unreadable, as a lightweight format.
> >
> > I haven't seen too much POD, so you may be right there. Is it worse
> > than Latex?
>
> Dunno who you were quoting there, but I strongly disagree with "intensely
> unreadable".
It was Tibs. After Tim's post, and even more after seeing your
examples, I agree with you.
> Judge for yourself; here's a snippet of POD documentation for
> a C library I wrote:
>
> """
> =head1 NAME
>
> bt_input - input/parsing functions in B<btparse> library
>
> =head1 SYNOPSIS
> [...]
>
> =head1 DESCRIPTION
>
> The functions described here are used to read and parse BibTeX data,
> converting it from raw text to abstract-syntax trees (ASTs).
>
> =over 4
>
> =item bt_set_stringopts ()
>
> void bt_set_stringopts (bt_metatype_t metatype, ushort options);
>
> Set the string-processing options for a particular entry metatype. This
> affects the entry post-processing done by C<bt_parse_entry_s()>,
> C<bt_parse_entry()>, and C<bt_parse_file()>. If C<bt_set_stringopts()>
> is never called, the four metatypes default to the following sets of
> string options:
>
> BTE_REGULAR BTO_CONVERT | BTO_EXPAND | BTO_PASTE | BTO_COLLAPSE
> BTE_COMMENT 0
> BTE_PREAMBLE 0
> BTE_MACRODEF BTO_CONVERT | BTO_EXPAND | BTO_PASTE
>
> For example,
>
> bt_set_stringopts (BTE_COMMENT, BTO_COLLAPSE);
>
> will cause the library to collapse whitespace in the value from all
> comment entries; the AST returned by one of the C<bt_parse_*> functions
> will reflect this change.
> """
Pretty effective, I agree. ("=over 4" is the only thing I didn't
completely understand right away, although I guessed right. After
reading man perlpod, there seems to be a missing "=back" though. :-)
> "man perlpod" for the rules. The main things to know:
> * indentation means verbatim
> * C<> is code, B<> is bold, I<> is italics
>
> If this keeps up, I'll write a proposal for a POD dialect for documenting
> Python. The "=foo" headers would disappear for sure -- they're ugly, and
> that syntax is part of both Perl's parser and every POD parser. Yech.
Go for it -- would be a nice counter-proposal in the KISS family!
What would you use instead of =foo headers? I kind of like the
This is obviously a header
==========================
style myself (because that's what I've been using for years).
--Guido van Rossum (home page: http://www.python.org/~guido/)