On Fri, 1 Sep 2000, Tom Christiansen wrote:
TC> You should write your pod as close to plain text as you possible
TC> can, with as few explicit markups as you can get away with. It
TC> is up to the individual conversion to decide how things in your
TC> text should be represented. That means letting the translator
TC> figure out how to create paired quotes, how to fill and adjust
TC> text, how to find a smaller font for words in all capitals,
TC> etc. Since these were written to process Perl documentation,
TC> most translators<footnote>If you're designing a general-purpose
TC> pod translator, not one for Perl code, your criteria may
TC> vary.</footnote> should also recognize unadorned items like
TC> these and render them appropriately:
I'd like to add my 2c: IMHO POD translators should be capable of
translating all kinds of POD, perhaps having an option to turn Perl
specific features (e.g. highlighting $_) on/off.
Concerning auto-detection of special constructs: When converting Perl
documentation, @ preceded by non-word- and followed by word-characters
(or $ and word characters ;-) is very likely an array; it might be
something different in another context. I agree that Perl will be the
context of POD documents in 90%+ of all cases, but anyway I find it
extremely annoying if a converter tries to use "artificial
intelligence" to figure out proper highlighting/markup - and fails! I'd
prefer to have the documentation's author provide a very small amount of
markup to disambiguate e.g. an URL: Let him say L<http://www.perl.org> and
it is crystal-clear what is meant. Yes, I propose a corresponding
extension of perlpod.
In other words: I'm against too much black magic in POD; if there is
supposed to be any, it should be well described in perlpod, e.g. that
"sleep(1)" is a link to a manpage and not an example of usage of a Perl
built-in command.
-Marek
