[Doc-SIG] Re: POD

[klm@digicool.com]

[Guido]
> > [Tony J Ibbs (Tibs)]
> > > Pod is used successfully in the Perl world, and is a clear winner there.
> > > I find it intensely unreadable, as a lightweight format.
> > 
> > [Guido]
> > > I haven't seen too much POD, so you may be right there.  Is it worse
> > > than Latex?
> 
> [Tim gives a 2-minute tour of POD]
> 
> 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?

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

Ken
klm@digicool.com