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.
>> First off, I don't know of any translator that treats $variable as
>> I<$variable>. Rather, for translators that have a fixed-width font,
>> $variable is treated basically as C<$variable>. But for Pod::Text, no
>> markup is added; people use C<> when they want to emphasize that
>> something is code and therefore quote marks are added by Pod::Text for
>> C<>, quote marks that would horribly clutter things if $variable always
>> got them.
> Note that in perlpod it says that variables should use I<> (although
> nearly everyone uses C<>).
Different kind of variable. That's metasyntactic variables, not Perl
variables. Perl variables are a type of Perl code and should use C<>.
I'd really like to see a different interior sequence for metasyntactic
variables and reserve I<> for emphasis; it would make Pod::Text a lot
easier and more correct.
> 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.
> 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.
$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.
> If C<> is not enough to distinguish variables then maybe we need an
> extra letter V<> or something. Pity the poor person that is trying to
> help the translator by supplying the pod markup themselves...
Yup. Don't do that. It hurts.
>> Most translators don't do the right thing with L<manpage(3r)> at all right
>> now, although that could and should be fixed. (It's not clear what the
>> right thing is for an HTML translator, really.)
> 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.
> 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.
(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.)
>> There are also innumerable little things that need to be done that
>> don't correspond to any interior sequences. For example, STDIN is
>> supposed to be rendered in small-caps for those output formats that
>> support it, and -- is supposed to be translated into a proper dash
>> where possible.
> This can all be done using the pod preprocessor though and extra magic
> tags. H<> for file handle for example? Then things that can't handle
> H<> just do whatever they can. Again, though a generic bit of code has
> been used to at least find these things and mark them up ready for
> translation.
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
handling to allow for all the extra communication between the guesswork
stage and the translators. And a lot of the guesswork is still
translator-specific; for example, the thin space that Pod::Man adds
before the open paren of a man page reference.
--
Russ Allbery ([EMAIL PROTECTED]) <http://www.eyrie.org/~eagle/>
