On 4 Aug 2000, Russ Allbery wrote:
> Tim Jenness <[EMAIL PROTECTED]> writes:
>
> > This suggests to me that $variable should be written as if the author
> > had written I<$variable>, manpage(3r) should be written as
> > L<manpage(3r)> etc. [with the L<> construct distinguishing between perl
> > man pages and generic manpages]
>
> [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.
> > Are you saying that is not the case?
>
> Correct. That is not the case currently.
>
> > That writing $variable and I<$variable> imply two different states of
> > translation?
>
> Right.
>
> 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<>). 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 think you are missing the point though. You seem to be implying that
$variable and C<$variable> are in fact identical (in this example) and
Pod::Text would still work properly if the $variable was translated to
C<$variable> before Pod::Text became involved.
> Or consider Pod::Man, which translates $variable into the same thing as
> C<$variable> if you're using troff, otherwise does the same thing that
> Pod::Text does.
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...
>
> 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.
There is also Pod::List to help with list indentation etc.
> 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.
Am I making any sense here?
--
Tim Jenness
JCMT software engineer/Support scientist
http://www.jach.hawaii.edu/~timj
