[Doc-SIG] Re: POD

[Guido van Rossum]

> > So I'd like to know why Tibs finds POD so intensely unreadable -- this
> > sounds pretty good to me, it has just the right mixture of explicit
> > (commands and everything) and implicit (paragraphs and verbatim)
> > markup.
> 
> It's the difference between reading markup and plain text.
> Programmers are going to have to read the source docstrings - the raw
> text.  Structured text offers something very much like plain text,
> while POD offers something very much like, well, typical markup.
> Which would you rather read?

If the amount of markup is as light as suggested by Greg's examples, I
have no problem reading POD.  If you ask "which would you rather
*write*", I strongly prefer a simple predictable set of rules over the
heuristics employed by ST-like systems.  *Maybe* I can live with a set
of exact ST-like rules that are designed to be exactly specified,
easily remembered, and not to cause surprises in common markup.  ST
classic and STng have way too many interacting heuristics, and are
hence neither exactly specified, not easily remembered (there always
seems to be *yet* another special case), and as a consequence create
way too many surprises.

> I know that those occasions where i've saved a web document to a file
> for later reading, the "save as text" version was infinitely more
> readable than the html version.

Hm.  You must be unusual in this respect.  I just save the HTML and
read it with a web browser later.  Who would want to read the raw
HTML?

> Have you really pictured what python
> modules are going to look like with
> 
>   """=head whatnot
> 
>    =over 4
> 
>    ..."""
> 
> in it???  Maybe such stuff looks clean in the midst of perl code, but
> such docstrings will be more cluttered and less readable than the
> code, itself!  Why the heck would you want to do that?  Have mercy on
> the programmer who wants to read docstrings.

Have you *tried* reading POD?  I just sampled some Perl files lying
around on my system in /usr/lib/perl/.  You should do the same.  The
docs in all the Perl sources that I've sampled so far are remarkably
readable -- and they don't even require a double colon in front of
literal blocks :-).  The secret seems to be that their markup is so
simple that you very quickly learn to recognize it, and it's pretty
minimal.

--Guido van Rossum (home page: http://www.python.org/~guido/)