develooper Front page | perl.perl5.porters | Postings from February 2000

[ID 20000225.003] Problem with pod2man & Solaris?

Thread Previous | Thread Next
Stephane Barizien
February 25, 2000 03:56
[ID 20000225.003] Problem with pod2man & Solaris?
Message ID:
Hi folks,

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

From: Stephane Barizien <>
To: Gisle Aas <>
Subject: Problem with LWP manpages on Solaris
Cc: vons
Date: Wed, 23 Feb 2000 11:43:06 +0100


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

man(5)                    FILE FORMATS                     man(5)

     man - macros to format Reference Manual pages

     nroff -man filename...

     troff -man filename...

     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.

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


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


Feel free to ask for more information.


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


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

Thread Previous | Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About