[Doc-SIG] using the same delimiter on the left and right..

[Guido van Rossum]

[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/)