[Doc-SIG] Re: POD
Thu, 29 Mar 2001 22:32:50 -0500
On 29 March 2001, firstname.lastname@example.org 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
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!)
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
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
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.