From sba@ocegr.fr

Hi folks,

Following the advice of CPAN author Gisle Aas, here's my problem​:

From​: Stephane Barizien <sba@​ocegr.fr>
To​: Gisle Aas <gisle@​aas.no>
Subject​: Problem with LWP manpages on Solaris
Cc​: vons
Reply-to​: sba@​ocegr.fr
Date​: Wed, 23 Feb 2000 11​:43​:06 +0100

Hi,

My Solaris' 'man -s 5 man' says​:

man(5) FILE FORMATS man(5)

NAME
  man - macros to format Reference Manual pages

SYNOPSIS
  nroff -man filename...

  troff -man filename...

DESCRIPTION
  These macros are used to lay out the reference pages in this
  manual. Note​: if filename contains format input for a
  preprocessor, the commands shown above must be piped through
  the appropriate preprocessor. This is handled automatically
  by the man(1) command. See the ''Conventions'' section.
  Any text argument t may be zero to six words. Quotes may be
  used to include SPACE characters in a "word". If text is
  empty, the special treatment is applied to the next input
  line with text to be printed. In this way .I may be used to
  italicize a whole line, or .SB may be used to make small
  bold letters. A prevailing indent distance is remembered
  between successive indented paragraphs, and is reset to
  default value upon reaching a non-indented paragraph.
  Default units for indents i are ens. Type font and size are
  reset to default values before each paragraph, and after
  processing font and size setting macros. These strings are
  predefined by -man​:

  \*R '(Reg)', trademark symbol in troff.
  \*S Change to default type size.

  Requests
  * n.t.l. = next text line; p.i. = prevailing indent

  Request Cause If no Explanation
  Break Argument
...
  .TH n s d f m yes - Begin reference page n,

  of of section s; d is the
  date of the most recent change.
  If present, f is the left page
  footer; m is the main page
  (center) header. Sets
  prevailing indent and
  tabs to .5i.

...

  Conventions
  When formatting a manual page, man examines the first line
  to determine whether it requires special processing. For
  example a first line consisting of​:
  '\" t
  indicates that the manual page must be run through the
  tbl(1) preprocessor. A typical manual page for a command or
  function is laid out as follows​:

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

  .SH NAME
  The name, or list of names, by which the command is
  called, followed by a dash and then a one-line summary
  of the action performed. All in roman font, this sec-
  tion contains no troff(1) commands or escapes, and no
  macro requests. It is used to generate the windex
  database, which is used by the whatis(1) command.

...

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?

Regards,

Feel free to ask for more information.

Stephane

<((((º>`·.,,.·'`·.,.·'`·...,><((((º>,.
  ·'`·.,. , . .·'`·.. ><((((º>`·.,,.·'`·.,.·'`·...,><((((º>

Thought for the day​:
  Multitasking​: Screwing up several things at once...

From [Unknown Contact. See original ticket]

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

perl.org@triv.org - Status changed from 'open' to 'resolved'