Marek Rouchal DAT CAD HW Tel 25849 <[EMAIL PROTECTED]> writes:
> First of all I'd like to stress that "perlpod" has to be rephrased to
> reflect the abilities of existing parsers. For example, I see a lot of
> possible misinterpretations when trying to auto-link bare text like
> "foo(1)", "func()", "$var", "@arr" and so on, which IMHO should at least
> read C<$var> etc. or even L<foo(1)>.
I'm not sure what you're saying here; if you mean that the user should
have to write C<$var> and L<foo(1)>, I couldn't disagree more strongly.
To me, that goes against the entire point and purpose of POD.
> However, the black magic should be reduced.
Without black magic, it's not POD; if people don't want black magic, they
should write in HTML or texinfo. The whole point of POD is to be able to
write something very close to English and have the translator handle the
rest.
> This especially includes:
> * recognizing valid commands and choking on malformed ones
Useful but not much work.
> * parsing =over,=item,=back into genuine lists (list objects with item
> subobjects)
Completely not useful for the translators I maintain; I really don't want
to deal with another set of objects.
> * Providing short and plain-\w+ identifiers for every =head ..., =item
> ..., X<...>, which can be used for hyperlink destinations
> * recognizing =for, =begin ... =end
Useful.
> * recognizing valid entities (E<100>, E<0122>, E<0xAE>, E<auml>)
Not possible. Different translators support different entities. You
simply can't do a bunch of them in *roff unless someone cares to code the
magic and pass it along to me.
> * parsing L<...> into comprehensive objects (having ->text, ->type,
> ->destination, ->destination_node etc.)
Bleh. Useful, I suppose, but more objects. Ick.
> * Pod::Compiler will inherit from Storable, making e.g. the two-pass HTML
> translation much more efficient: Compile once, extract nodes with ids,
> store object tree, repeat for all PODs, then read each object tree and
> translate, while resolving all hyperlinks.
> Hyperlink-free destination formats of course don't need this.
As long as I can turn it off, I guess I don't care.
> * Pre-defined methods "as_text" and "as_pod": as_text gives access to the
> plain text content (ISO-88590-1 encoded), stripping all markup. as_pod
> allows for re-creation of correct POD. This will make a Pod::Lint a
> five-minute coding execise ;-)
Wouldn't use it....
> * Text objects within S<...> have an attribute set so that conversion of
> whitespace is easily done.
I don't see how this could work with Pod::Text.
> * From within each object one has access to the whole Pod object tree
> (thanks to the Tree::DAG_Node module), so that e.g. in an =item you can
> easily see what this item's sisters are. Or: You can see that a
> Pod::italic object is nested within another Pod::italic, so that you can
> turn off italic mode in order to emphasise within an emphasis ;-)
Ugh. More objects.
I'm really not thrilled again, for some of the same reasons that I've said
before. This strikes me as making life way too complicated and not taking
into account the needs of the more text-like translators. Have you taken
a look at what Pod::Man does and how it would fit into this sort of
scenario?
I can maybe live with something like this if other people *really* want
it, but it strikes me as a bunch of complexity and a bunch more speed loss
for no real gain for the translators that I personally care about.
I can definitely see a utility package for managing links for those output
formats that need hyperlink support and those databases, but I think
putting it between the POD and the translator is a bad idea. Why not
provide it as utility functions for the translator to call instead?
Way too much OO going on here for my taste.
> This leaves us - AFAICS - with the speed discussion. I agree that for
> perldoc and pod2text one does not want to wait for any OO exercises.
(Note that perldoc by default uses pod2man, not pod2text.)
--
Russ Allbery ([EMAIL PROTECTED]) <http://www.eyrie.org/~eagle/>
