[Doc-SIG] Re: POD (resend)

Greg Ward gward@mems-exchange.org
Thu, 29 Mar 2001 22:40:38 -0500

On 29 March 2001, Tim Peters said:
> So the first lesson I take from that is that the doc author was markup-happy:
> I can read it just fine without *any* markup (and POD is such that it won't
> muck with anything I wrote there, apart from reflowing the text -- I don't
> even have to *think* about running afoul of its heuristics, because there
> aren't any <wink>).

Actually, that might not be true: the last I remember of the pod-people
mailing list (before I unsubscribed in frustration -- these holy wars are
not confined to Python-land!), certain parties were arguing quite
vociferously in favour of all manner of clever heuristics.  The idea was
that POD processors (or rather, the Pod::Parser module that I believe made
it into the standard library in Perl 5.6) would inspect the module whose
documentation was being parsed to figure out what words ought to be C<code>
or B<bold> or what-have-you.  However, I didn't stick around to see how the
holy wars ended -- sanity might have won out.

Needless to say, such heuristics ought to be deemed unPythonic and stamped
out in any mythical POD-for-Python implementation.  ;-)