Your message dated Sun, 22 Mar 2009 11:24:53 -0700
with message-id <877i2hs9e2....@windlord.stanford.edu>
has caused the report #280148,
regarding pod2man should create bold references
to be marked as having been forwarded to the upstream software
author(s) Niko Tyni <nt...@debian.org>
(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact ow...@bugs.debian.org
immediately.)
--
280148: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=280148
Debian Bug Tracking System
Contact ow...@bugs.debian.org with problems
--- Begin Message ---
Niko Tyni <nt...@debian.org> writes:
> On Sun, Nov 07, 2004 at 04:57:21PM +0100, Martin Schulze wrote:
>> man(7) contains:
>>
>> Any reference to another man page (or to the subject of the cur-
>> rent man page) is in bold. If the manual section number is
>> given, it is given in Roman (normal) font, without any spaces
>> (e.g., man(7)).
>>
>> However, pod2man creates
>>
>> \&\fIdhcpd\fR\|(8), \fItcpdump\fR\|(1), \s-1RFC2132\s0
>> ^ ^
>> B B <--- should be
>>
>> from
>>
>> dhcpd(8), tcpdump(1), RFC2132
>>
>> It would be nice if pod2man and other manpages would build similar links.
There are several different conventions, all of which go back a long time.
There's never been general agreement on how to handle references; you'll
find different conventions in different man pages on a typical Linux
system. BSD (mdoc) and Solaris 9 don't seem to use either bold or italic,
and neither do a bunch of other man pages on Linux (ifconfig(8), for
instance), but others do use bold. Italic seems to be getting rarer than
it was when I first started maintaining pod2man, but you can still see it
in non-POD pages. Looking around a bit, the ncftp man page uses italics,
for instance, as do some (but not all) of the man pages that come with MIT
Kerberos.
I'm a little reluctant to change this because pod2man has been using
italics since before I started to maintain it. man-pages(7) is a good
reference, though, since it's a concrete style guide with some general
weight behind it, although the BSD style guide is also fairly concrete and
doesn't add markup.
> This is somewhat related to
> <http://rt.cpan.org/Public/Bug/Display.html?id=43700>, which requests
> that L<> would be handled better.
There are unfortunately a practical problem with that request, namely that
L<Foo> doesn't contain the section and Pod::Man would have to come up with
it to create a valid cross-reference. It's very difficult to get the
section information right for all of L<Pod::Man>, L<perl>, L<perlpod>,
L<xsubpp>, and L<warnings>. I have a query out to perl5-porters for the
best way to handle this, but I may end up closing that bug as wontfix.
> I see the text quoted above has meanwhile been moved into man-pages(7),
> which specifically discusses Linux man pages. It also recommends the
> references to be written as to .BR rather than \f escapes. I'm not
> familiar enough with troff to know how portable that is; Solaris 10
> does have it FWIW.
.BR versus \f are completely equivalent as far as *roff is concerned.
Pod::Man uses \f uniformly because it doesn't require worrying about
newlines and because the necessary escaping for .BR to work properly can
be tricky and difficult. On many systems, .BR also has length limits to
the text that it can make bold or non-bold and arbitrarily truncate. I'd
rather stick with \f because it doesn't have any of those problems.
> Clearly, L<dhcpd(8)> can easily be recognized as a reference to another
> man page, but a plain dhcpd(8) needs a heuristic approach.
Pod::Man currently treats both of those equivalently.
--
Russ Allbery (r...@debian.org) <http://www.eyrie.org/~eagle/>
--- End Message ---
