[Doc-SIG] Re: POD (resend)

[Tim Peters]

[Greg Ward]
> ...
> the last I remember of the pod-people

Great name!

> 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