Debian Bug report logs - #280148
pod2man should create bold references

version graph

Package: perl; Maintainer for perl is Niko Tyni <ntyni@debian.org>; Source for perl is src:perl.

Reported by: Martin Schulze <joey@infodrom.org>

Date: Sun, 7 Nov 2004 16:18:01 UTC

Severity: normal

Found in version 5.8.4-3

Forwarded to Niko Tyni <ntyni@debian.org>

Reply or subscribe to this bug.

Toggle useless messages

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to debian-bugs-dist@lists.debian.org, Brendan O'Dea <bod@debian.org>:
Bug#280148; Package perl. Full text and rfc822 format available.

Acknowledgement sent to Martin Schulze <joey@infodrom.org>:
New Bug report received and forwarded. Copy sent to Brendan O'Dea <bod@debian.org>. Full text and rfc822 format available.

Message #5 received at submit@bugs.debian.org (full text, mbox):

From: Martin Schulze <joey@infodrom.org>
To: submit@bugs.debian.org
Subject: pod2man should create bold references
Date: Sun, 7 Nov 2004 16:57:21 +0100
Package: perl
Version: 5.8.4-3

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.

Regards,

	Joey

-- 
GNU does not eliminate all the world's problems, only some of them.
                                                -- The GNU Manifesto

Please always Cc to me when replying to me on the lists.



Reply sent to Niko Tyni <ntyni@debian.org>:
You have marked Bug as forwarded. (Sun, 22 Mar 2009 16:06:21 GMT) Full text and rfc822 format available.

Message #8 received at 280148-forwarded@bugs.debian.org (full text, mbox):

From: Niko Tyni <ntyni@debian.org>
To: Martin Schulze <joey@infodrom.org>, 280148-forwarded@bugs.debian.org
Cc: Russ Allbery <rra@debian.org>
Subject: Re: Bug#280148: pod2man should create bold references
Date: Sun, 22 Mar 2009 17:58:51 +0200
On Sun, Nov 07, 2004 at 04:57:21PM +0100, Martin Schulze wrote:
> Package: perl
> Version: 5.8.4-3
> 
> 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.

This is somewhat related to
<http://rt.cpan.org/Public/Bug/Display.html?id=43700>, which requests
that L<> would be handled better.

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.

Clearly, L<dhcpd(8)> can easily be recognized as a reference to another
man page, but a plain dhcpd(8) needs a heuristic approach. 

Russ, would you consider converting at least L<foo(3)> to .BR (or \fB... if
that's better)?
-- 
Niko Tyni   ntyni@debian.org




Reply sent to Russ Allbery <rra@debian.org>:
You have marked Bug as forwarded. (Sun, 22 Mar 2009 18:27:05 GMT) Full text and rfc822 format available.

Message #11 received at 280148-forwarded@bugs.debian.org (full text, mbox):

From: Russ Allbery <rra@debian.org>
To: Niko Tyni <ntyni@debian.org>
Cc: Martin Schulze <joey@infodrom.org>, 280148-forwarded@bugs.debian.org
Subject: Re: Bug#280148: pod2man should create bold references
Date: Sun, 22 Mar 2009 11:24:53 -0700
Niko Tyni <ntyni@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 (rra@debian.org)               <http://www.eyrie.org/~eagle/>




Information forwarded to debian-bugs-dist@lists.debian.org, Brendan O'Dea <bod@debian.org>:
Bug#280148; Package perl. (Mon, 23 Mar 2009 09:00:04 GMT) Full text and rfc822 format available.

Acknowledgement sent to Niko Tyni <ntyni@debian.org>:
Extra info received and forwarded to list. Copy sent to Brendan O'Dea <bod@debian.org>. (Mon, 23 Mar 2009 09:00:05 GMT) Full text and rfc822 format available.

Message #16 received at 280148@bugs.debian.org (full text, mbox):

From: Niko Tyni <ntyni@debian.org>
To: Russ Allbery <rra@debian.org>
Cc: Martin Schulze <joey@infodrom.org>, 280148@bugs.debian.org
Subject: Re: Bug#280148: pod2man should create bold references
Date: Mon, 23 Mar 2009 10:58:21 +0200
On Sun, Mar 22, 2009 at 11:24:53AM -0700, Russ Allbery wrote:

> 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.

If there are non-trivial differences between platform-specific style
recommendations, how about making the output 'dialect' configurable?
Or do you think that's too much bloat?

I can see problems with functional differences (like enabling '--utf8')
between dialects, but for purely cosmetic things like bold vs. italic
this could work.
-- 
Niko




Information forwarded to debian-bugs-dist@lists.debian.org, Brendan O'Dea <bod@debian.org>:
Bug#280148; Package perl. (Mon, 23 Mar 2009 17:27:02 GMT) Full text and rfc822 format available.

Acknowledgement sent to Russ Allbery <rra@debian.org>:
Extra info received and forwarded to list. Copy sent to Brendan O'Dea <bod@debian.org>. (Mon, 23 Mar 2009 17:27:02 GMT) Full text and rfc822 format available.

Message #21 received at 280148@bugs.debian.org (full text, mbox):

From: Russ Allbery <rra@debian.org>
To: Niko Tyni <ntyni@debian.org>
Cc: Martin Schulze <joey@infodrom.org>, 280148@bugs.debian.org
Subject: Re: Bug#280148: pod2man should create bold references
Date: Mon, 23 Mar 2009 10:25:55 -0700
Niko Tyni <ntyni@debian.org> writes:
> On Sun, Mar 22, 2009 at 11:24:53AM -0700, Russ Allbery wrote:

>> 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.

> If there are non-trivial differences between platform-specific style
> recommendations, how about making the output 'dialect' configurable?  Or
> do you think that's too much bloat?

> I can see problems with functional differences (like enabling '--utf8')
> between dialects, but for purely cosmetic things like bold vs. italic
> this could work.

Hm, that's not a bad idea, although I'm not sure to what degree it will
address the original concern.  I think most man pages generated by pod2man
are generated as part of the build process for Perl or for Perl modules,
where there isn't a good place to add additional options.  It would work
for people running it by hand who wanted a different behavior, though.

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>




Information forwarded to debian-bugs-dist@lists.debian.org, Brendan O'Dea <bod@debian.org>:
Bug#280148; Package perl. (Tue, 24 Mar 2009 14:21:05 GMT) Full text and rfc822 format available.

Acknowledgement sent to Niko Tyni <ntyni@debian.org>:
Extra info received and forwarded to list. Copy sent to Brendan O'Dea <bod@debian.org>. (Tue, 24 Mar 2009 14:21:05 GMT) Full text and rfc822 format available.

Message #26 received at 280148@bugs.debian.org (full text, mbox):

From: Niko Tyni <ntyni@debian.org>
To: Russ Allbery <rra@debian.org>
Cc: Martin Schulze <joey@infodrom.org>, 280148@bugs.debian.org
Subject: Re: Bug#280148: pod2man should create bold references
Date: Tue, 24 Mar 2009 16:18:07 +0200
On Mon, Mar 23, 2009 at 10:25:55AM -0700, Russ Allbery wrote:
> Niko Tyni <ntyni@debian.org> writes:
> > On Sun, Mar 22, 2009 at 11:24:53AM -0700, Russ Allbery wrote:
> 
> >> 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.
> 
> > If there are non-trivial differences between platform-specific style
> > recommendations, how about making the output 'dialect' configurable?  Or
> > do you think that's too much bloat?
> 
> > I can see problems with functional differences (like enabling '--utf8')
> > between dialects, but for purely cosmetic things like bold vs. italic
> > this could work.
> 
> Hm, that's not a bad idea, although I'm not sure to what degree it will
> address the original concern.  I think most man pages generated by pod2man
> are generated as part of the build process for Perl or for Perl modules,
> where there isn't a good place to add additional options.  It would work
> for people running it by hand who wanted a different behavior, though.

Well, a logical next step would be to make the default pod2man run-time
dialect configurable at podlators build time, and the one after that would
be for the build scripts to choose the default based on $^O and the like.
-- 
Niko




Send a report that this bug log contains spam.


Debian bug tracking system administrator <owner@bugs.debian.org>. Last modified: Sat Apr 19 10:04:42 2014; Machine Name: beach.debian.org

Debian Bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.