[Doc-SIG] Re: POD (resend)
Thu, 29 Mar 2001 23:35:46 -0500
> the last I remember of the pod-people
> mailing list (before I unsubscribed in frustration -- these holy wars
> are not confined to Python-land!),
Perhaps not. But ours are so much ... holier than theirs <wink>.
> 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. ;-)
I don't mind at all if a doc presentation system wants to be clever about
what I wrote, just so long as I don't have to think about it. For example, I
gave up on markup for Python docstrings several aborted proposals (and years)
ago, but Ka-Ping Yee's pydoc code does a *fine* job of hyperlinking my
plain-as-the-nose-on-my-face unmarked docstrings anyway.
Now across Perl POD docs, I see an utterly incomprehensible mix of I<>, B<>
and C<> tags, as markup-obsessed coders apparently make up their own
conventions on the fly for how to spell "umm, OK, I'll use bold for package
names and italics for method names -- today, much of the time". I expect I'd
rather see no markup at all than that inconsistent gibberish -- Ping can
figure out what they meant better than they can! Class, method and function
names are indeed easily obtained via parsing the module.
markup-for-idiots-is-markup-for-everyone-ly y'rs - tim