Policy Weekly Issue #4/14: Manual page inconsistencies

[Christian Schwarz <schwarz@monet.m.isar.de>]

Topic 14: Manual page inconsistencies

STATE: DISCUSSION
REF:   cf. bug #12370

In order to get the manual pages registered in the whatis database it is
necessary, that the manual pages specify the correct name and section with
the `.SH' command.

At the moment, some manual pages don't have a .SH section.

For consistency reasons it is suggested, that all manual pages specify the
same name and section in the manual page as what is used in the file name.

As the sections that are supported by the `man' command are handcoded into
`man' we have to coordinate the use of manual page sections.

The following policy has been suggested:

     Maintainers should check that the manpages installed by the package
go
     registered in the whatis database using a correct
             .SH NAME
     section and a one-row description, as described in man(7).

     In addition, the title of the manual page has to conform to its
     file name. For example, the manual page foo.conf(5x) has to use the
     name foo.conf.5x.gz and has to contain the command
             .TH foo.conf(5x)

     Packages introducing a new section name should email the man-db
     maintainer <man-db@packages.debian.org> to let him include it in the
     static list of manual sections.

----------------------------------------------------------------------------

--                  Christian Schwarz
                     schwarz@monet.m.isar.de, schwarz@schwarz-online.com,
Debian is looking     schwarz@debian.org, schwarz@mathematik.tu-muenchen.de
for a logo! Have a
look at our drafts     PGP-fp: 8F 61 EB 6D CF 23 CA D7  34 05 14 5C C8 DC 22 BA
at    http://fatman.mathematik.tu-muenchen.de/~schwarz/debian-logo/