[Doc-SIG] Re: POD (resend)

[Greg Ward]

[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.  ;-)

[Tim moderates]
> 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.

        Greg