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

[Greg Ward]

On 29 March 2001, Guido van Rossum said:
> > Texinfo (and there are other more modern examples) is still "formal
> > markup to produce a document", where the markup has equal status with
> > the text, and is expected to intrude. People will not want to write it
> > in docstrings. So we'd lose.
> 
> But isn't this exactly what Javadoc does?

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.

> > 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".  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.
"""

"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.

Just for fun, here's some more POD, this time from a Perl module I wrote:

"""
=head1 DESCRIPTION

F<MNI::MiscUtilities> provides a handful of otherwise unclassifiable
utility routines.  Don't go looking for a common thread of purpose or
operation---there isn't one!

=over 4

=item timestamp ([TIME])

Formats TIME in a complete, unambiguous, ready-to-sort fashion:
C<yyyy-mm-dd hh:mm:ss>.  TIME defaults to the current time; if it is
supplied, it should be a time in the standard C/Unix representation:
seconds since 1970-01-01 00:00:00 UTC, as returned by Perl's built-in
C<time> function.

Returns a string containing the formatted time.

=cut

[...here comes a bunch of Perl code -- "=cut" means the POD is
over for now and we're back to code...]

=item userstamp ([USER [, HOST [, DIR]]])

Forms a useful complement to C<timestamp>; where C<timestamp> tells the
"when" of an action, C<userstamp> gives the "who" and "where".  That is,
C<userstamp> generates and returns a string containing the current
username, host, and working directory, e.g. C<user@host:/directory>.

Normally, no parameters are given to C<userstamp>---it uses C<$E<lt>> (the
real uid) and C<getpwuid> to get the username, C<Sys::Hostname::hostname>
to get the hostname, and C<Cwd::getcwd> to get the current directory.  If
you wish to generate a bogus "userstamp", though, you may do so by
overriding some or all of C<userstamp>'s arguments.  For instance, to
supply a fake directory, but use the defaults for USER and HOST:

   userstamp (undef, undef, '/fake/dir');

=cut
"""

That doesn't strike me as "intensely unreadable".  In this crowd, I'd expect
the evil nasty Perl code intruding in the docs to be a bigger problem than
the markup language.  ;-)

        Greg