[Doc-SIG] Re: POD
Thu, 29 Mar 2001 17:54:00 -0500 (EST)
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
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
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.