[Doc-SIG] Re: POD (resend)
Fri, 30 Mar 2001 12:39:30 -0500
[me, waxing holier-than-thou]
> 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.
After posting last night, I reconsidered a bit. A bit of clever heuristics
are OK; I think the main problem with them in POD-for-Perl land is that they
have been inconsistent (until Perl 5.6, every pod2foo tool implemented its
own Pod parser) and ill-documented.
> 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".
Absolutely true! I've been guilty of that myself.
> 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.
Yes, yes, yes.
FWIW, the main thing I would like to steal from POD is the tag syntax:
single capital later and angle braces, simply because it's the best
compromise I've yet seen of readability/writeability with unambiguousness.
Everything else, including the set of available tags, is up for discussion.