Front page | perl.perl5.porters |
Postings from February 2000
Re: [ID 20000225.003] Problem with pod2man & Solaris?
From:
Russ Allbery
Date:
February 25, 2000 22:53
Subject:
Re: [ID 20000225.003] Problem with pod2man & Solaris?
Message ID:
yl4sawbgkm.fsf@windlord.stanford.edu
Stephane Barizien <sba@ocegr.fr> writes:
> .TH title [1-9]
> The name of the command or function, which serves as
> the title of the manual page. This is followed by the
> number of the section in which it appears.
> The problem is that your manpages, e.g. lwp-request's, contain a
> problematic construct:
> .TH LWP-REQUEST 1 "libwww-perl-5.47" "7/Dec/1999" "User Contributed
> Perl Documentation"
> (as a comparison the manpage for ls contains
> .TH ls 1 "17 Apr 1995"
> )
> I've worked around this by hacking around Brooks Davis's replacement
> /usr/lib/makewhatis.pl, but if the above manpage spec is a widely
> adopted convention, I think you should stick to it to avoid problems.
> What do you think?
Well, you didn't clearly state what the problem is, but I'll take a guess
that you're seeing the date in the wrong place when you run man on the
generated man page, or that makewhatis.pl can't handle multiple arguments
to .TH. Is that the case, or is there something else wrong?
You're correct that the man page spec is a widely adopted convention; what
I disagree with, however, is that Solaris is fully specifying it.
Consider this excerpt from man(7) on Linux:
The first command in a man page should be
.TH title section date source manual,
or man(5) on HP-UX 11.00:
.TH t1 s2 c3 n4 a5
Set the title and entry heading. t1, s2, c3, n4, and a5 are
words.
t1 Entry title.
s2 Section number. t1 is combined with s2 in parentheses
to form the top left- and righthand corners of the page
heading.
c3 Extra commentary, such as "Optional Software Required".
It is placed at the center of the bottom line in the
two- or three-line page heading space.
n4 Other notations, such as "Series 300/400 Only". It is
centered between the title and section on the first
page heading line.
a5 Support for alternate naming, such as a FORTRAN routine
name corresponding to a C function name specified in
t1.
Basically, having the first two values be the title and the section number
is consistent everywhere; what interpretation to lend to any additional
arguments to the .TH macro varies quite widely.
The current development version of Pod::Man produces the following:
.TH $name $section "$$self{release}" "$$self{date}" "$$self{center}"
where "$$self{center}" is a centered title for the manual "section",
generally "User Contributed Perl Documentation." This is somewhat at odds
with the most common conventions that I've seen in that the third argument
is the version number of Perl rather than the modification date; this is
consistent with the actual formatting that most -man macro sets use,
though. It may be worth considering whether the date and the version
number should change places on that line.
Amusingly, Solaris doesn't even follow its own documentation; if you read
the *roff source of the -man macro set used on Solaris, you'll find that
it interprets the third argument as the last modification date, and uses
the fourth and fifth arguments as additional headers at the foot and head
of each page, respectively.
--
Russ Allbery (rra@stanford.edu) <URL:http://www.eyrie.org/~eagle/>