[Doc-SIG] Re: POD

[Ken Manheimer]

On Thu, 29 Mar 2001, Guido van Rossum wrote:

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

That makes sense to me.

>From what i've been hearing, tony and edward have been heading in the
direction of minimal, and i'd be interested (and hopeful) that that would
take care of those problems.

> > 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?

Oh, thinking about it, i realized it was occasions where i wanted to take
printed copies with me, and didn't have browser printing working, but did
have lp-style printing working.  At that point i *did* compare the html vs
plain text - even for documents where the meat was mostly paragraphs with
occasional em and strong style emphasis, there was not contest.

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

I just took a look - the first thing i found with substantial pod was
Apache.pm, and it does look pretty bad to me.  Perhaps it's an extreme
case, but one thing i notice in general is that it's used very differently
than python function/method/class docstrings - it seems more to be
situated as we situate the module docstring, and i wonder whether the
approach would be at all suited, layout wise, to embedded docstrings.

Anyway, for grins, here's an excerpt of the passage that lives up to my
fears - the first thing i found.