On 4 Aug 2000, Russ Allbery wrote:
> Tim Jenness <[EMAIL PROTECTED]> writes:
> > On 4 Aug 2000, Russ Allbery wrote:
>
> >> [I'd love to know how the POD translator is supposed to do that.]
>
> > It wouldn't. It would get one of those Pod::Hyperlink objects (part of
> > Pod::ParseUtils) and do what it wants with that. A perl manpage would
> > not have a section number presumably.
>
> If it doesn't have a section number, it looks like a function reference,
> which is something else entirely.
>
> And Perl's manual pages do have section numbers in some cases. Basically,
> figuring out what is and is not a Perl man page, accounting for things
> like h2xs(1) and pod2man(1), is not a simple problem.
Okay, but everyone has to sort it out :-)
> > I don't do the check in Pod::LaTeX purely because every single pod
> > translator at least needs to know how to find these constructs in the
> > pod paragraph (surely?) so if I was going to do that I would want to do
> > it in a way that worked for everyone. I hope you agree that the
> > searching for these special combinations is generic enough to be
> > factored out?
>
> I'd be happy to see that happen, but that's a significant change to the
> POD language; it would be about five or six new interior sequences, most
> of which shouldn't be used directly by writers and should only be used by
> the intuition code to add markup to things that need it.
Is that a problem? I think that documented but hidden pod sequences
sounds like a great way of simplifying this type of parsing
(Pod::Hyperlink uses a couple of those already).
>
> > I think you are missing the point though. You seem to be implying that
> > $variable and C<$variable> are in fact identical (in this example)
>
> No, I said the exact opposite, just not particularly clearly. Sorry about
> that.
Sorry, I meant to imply that $var-> C<> rather than $var->I<>
but it was ambiguous.
>
> $variable is rendered as $variable by Pod::Text. C<$variable> is rendered
> as `$variable'. The difference is intentional and fits with the way that
> people are currently using the markup.
>
> > and Pod::Text would still work properly if the $variable was translated
> > to C<$variable> before Pod::Text became involved.
>
> No, it would end up putting `' quotes all over the place and produce
> output that looks ugly as sin.
This would be overcome with V<>
> > Pod::Hyperlink is your friend. Once you have one of these objects the
> > specific translator can decide how to represent it.
>
> Does it work correctly with, say, Pod::Text? In my experience, there's
> unfortunately a major divergence between those translators that support
> hyperlinks and those that don't in how L<> is handled.
>
A Pod::Hyperlink object simply parses the link and splits it into bits. It
is up to you how you put the bits together (internal vs external link,
say).
> > There is also Pod::List to help with list indentation etc.
>
> I have no idea how that could possibly work across translators. What
> Pod::Text does with list indentation looks absolutely nothing at all like
> what Pod::Man does.
>
Pod::List simply lets you record the indent level and related things, it
is up to the translator to actually know what to do with a particular
list.
> (I also personally dislike this proliferation of extra modules, annoying
> OOP mazes of inheritence, and objects and method calls; I think it renders
> the resulting code essentially unreadable and unmaintainable without a
> graph of the class hierarchy and I really dislike working with code like
> that. But that's my personal pet peeve; I'm a curmudgeon on this topic.)
I don't think that is a problem in this case. Sub class Pod::Parser and
then deal with a few useful tools for handling lists and links.
> The problem is that it's not just file handles. The same should be done
> with UNIX. You'd need a markup tag specifically for small caps, but the
> end user shouldn't use it.
>
> You'd also need E<> sequences for real dashes, left and right quote, and a
> few other things. Some of that is doable, but when I've tried to model it
> in my head, I haven't been able to find a clean abstraction layer that
> doesn't involve a lot of really annoying changes to interior sequence
The pre-processor can catch a lot of these -- if it sees "--" it can
convert it to E<emdash> (or whatever it's called) before you even see it.
> translator-specific; for example, the thin space that Pod::Man adds
> before the open paren of a man page reference.
You will still be able to do that though.
--
Tim Jenness
JCMT software engineer/Support scientist
http://www.jach.hawaii.edu/~timj
