On Mon, 20 Aug 2001, Sean M. Burke wrote:
> At 02:02 PM 2001-08-20 -0700, Tim Gim Yee wrote:
> >[...]
> >This is probably already implicit, but I will make it explicit. The blank
> >lines between verbatim paragraphs constitute significant whitespace, and a
> >parser must pass those blank lines verbatim to the formatter. In other
> >words, if there are 4 blank lines between two verbatim paragraphs, the
> >formatter should see and render 4 blank lines. It would be an error to do
> >otherwise.
>
> Hm, that complicates things a bit. What I was thinking of was: If you're
> building a parse tree, then after the tree is done, but before you return
> it, you should walk the tree and concatenate adjacent verbatim nodes,
> inserting just a blank line between their content.
Here's a pod example:
=head1 Printing 5 Newlines
print <<'FIVE';
FIVE
If a formatter doesn't reproduce the print statement verbatim, it is
broken behavior.
> It was my impression that this required particularly unpleasant lookahead,
> in event-based parsers. I.e., when you see a blank line terminating a
> paragraph, you can't just act on it --because what if it's that kind of
> significant-blank-line that can be between verbatims?
I think Pod::Parser (an even-based parser) already does the right thing.
It doesn't strip paragraph separators from the end of paragraphs. In
fact, I think it passes *every* character on to the formatter/procesor, a
necessary requirement for a generic pod parser.
> >How would I create links to these?
> >
> > =item rot13($text)
> > =item rot13 [TEXT]
> > =item $obj->rot13($text)
> > =item $grfg = $obj->rot13($text)
>
> The processors are assumed to have little in the way of telepathy, and
> should not be expected to
> turn L<somedoc/rot13($text)> into <a href="somedoc/rot13">...</a>, nor
> =item $grfg = $obj->rot13($text)
> into
> <dt><a name='rot13'>$grfg = $obj->rot13($text)</a>
> ^^^^^
> but instead are assumed to do something like
> <dt><a name='$grfg = $obj->rot13($text)'>$grfg =
> $obj->rot13($text)</a>
I think some DWIM magic is required. If I say L<perlfunc/open>, I expect
it to correctly reference one of the following in perlfunc:
=item open FILEHANDLE,MODE,LIST
=item open FILEHANDLE,EXPR
=item open FILEHANDLE
If I say L<IO::Handle/getlines>, I expect to cross-reference:
=item $io->getlines
> >The whole reason I'd want L<scheme:...> is so I could do
> >L<text|scheme:...>. L<http://www.perl.org/> is really not much better
> >than http://www.perl.org/ sans L<>, given that pod2xxx should mark it
> >up for me anyways.
>
>
> Lapsing into opinion here:
> Autojujufication like that -- with the URLification and the implicit C<...>
> and the quotes turning into 66s and 99s -- is a whole class of things that
> can never be done as reliably as I want; and when they're done, they're
> usually just inconsistent enough to really annoy me. And if you write
> rules complex enough to get this magic right /most/ of the time, they're
> too complex to remember, so I can never rely on them anyway -- AND THEN you
> have to have some nonapparent way to KEEP the rules from applying, like,
> say, getting Z<>$3 to suppress $3 magically turning into C<$3>.
> Also: deciding when, in the processing model, the various kinds of
> autojujufication should apply, is bothersome and possibly frought with
> minor paradoxes.
>
> If people want to try putting some of these things in their particular
> processor, they're welcome to try, but 0) not on by default!, 1) I really
> think it's not worth the bother, 2) remember that the magic heuristics
> /will/ fail and be inconsistent, annoyingly so.
I will disagree. DWIM works often enough in Perl to be useful. If DWIM
doesn't work often enough in Pod to be useful, I think this is an area a
Pod specification should, um... specify. If the plethora of pod tools
seem to be conspiring against a pod author's intentions, maybe it's
because they don't have any specs to follow. I think pod tools...
1. Should try to mark up text for the author, because Pod should
make things easier for the author not the parser/formatter.
2. Should follow a specification, so that if they fail annoyingly,
at least they can do so consistently.
3. Should provide an option to turn off. That is, the option
should be on by default.
> >What sort of parsing and rendering problems does this restriction
> >avoid? I'm clueless as to any parsing problems. I'm guessing the
> >rendering problems relate to non-hypertext formats. [...]
>
> Don't get me started on that, really. The actual code to implement just
> correct /parsing/ of L<...> is already horrendous, and adding L<text|url>
> would make it TOO CRAZY.
Since the "|" character must not appear in the "text", "name", and "sec"
parts of a L<>, it would seem a simple matter to look for a "|" character
in the contents of a L<>, and subsequently extract the "text" portion. I
cannot understand how L<text|url> is so much more difficult than L<url>.
> I'm drawing a line in the sand (with my iron fist! or, failing that, my
> iron fish), and saying THIS CRAZY, AND NO CRAZIER!
I have a magnetic cat that will eat your iron fish, so watch out!
> Moreover, yes, the L<text|url> /rendering/ problems are in non-hypertext
> formats. You outlined all the rendering possibilties that I thought of,
> and I really really don't like any of them, so that's the
> semantic/rendering reason why I say no L<text|name>.
Strange. I really liked the footnote option to rendering L<text|url>.
Speaking of footnotes, will draft 2 will include footnotes, tables, and
figures? :)
> So, is this more than you ever wanted to know about POD?
Is it "POD", "Pod", or "pod"? :)
--
Tim Gim Yee
[EMAIL PROTECTED]
