[Doc-SIG] Re: POD

[Greg Ward]

On 29 March 2001, klm@digicool.com said:
>   """=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.

The reason I like POD is because of the low-level, word/sentence level of
markup: compare

  if you B<really> want to hose yourself, assign C<37> to C<foo> after
  system startup (but I<don't> say I didn't warn you!)

to

  if you <b>really</b> want to hose yourself, assign <code>37</code> to
  <code>foo</code> after system startup (but <i>don't</i> say I didn't warn
  you!)

It's a simple, subtle change, but it really makes a difference in both
readability and writeability.  I know that ST is even *more* readable and
writeable, but I too worry about the ambiguity of overloading apostrophes
and asterisks.

The inter-paragraph stuff -- "=head", "=over", and so forth -- I can do
without.  And most of it would be irrelevant in Python docstrings, since
they come with context "for free".  I suspect that the only time you really
need headings (etc.) in docstrings is when you're trying to write a complete
module man page in docstrings.

I've written something like 150 pages of documentation for various Perl and
C libraries using POD.  I've also written lots of LaTeX and HTML text, and
once (long ago) I even wrote a man page with troff.  Of those, only POD and
HTML are even comprehensible to a mere mortal such as myself, and POD is
far, far easier to type.  I don't recall ever getting seriously hung-up on
markup issues, except for the buggy and ill-defined L<> (hyperlink) tag.
The syntax and semantics -- except for L<>! -- are just too simple.  It's
*not* a general-purpose markup language, and it does its job just fine all
the same, thank-you-very-much.

        Greg