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.]
> 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.
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.
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.)
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.
There was a bunch more stuff like this that I ran into when writing
Pod::Man.
> If that is true then where is it documented?
It's not, really. The problem is that a lot of the details are subjective
and tweaked to give the best output according to what people use POD to
intend. I keep meaning to write up some documentation of all of this but
as of yet haven't found the time.
--
Russ Allbery ([EMAIL PROTECTED]) <http://www.eyrie.org/~eagle/>
