Re: manpages, difference between 1 and 1p

[Russ Allbery <rra@debian.org>]

Thijs Kinkhorst <thijs@debian.org> writes:

> For package eekboek, Lintian signals a manpage-section-mismatch: the
> manpage for a command advertises itself as 1p but is placed in 1. In
> order to resolve this properly I was wondering what the exact
> distinction is. When is something in section n, and when in n'p'? For
> example, this is a command in the path.  Should the end user know that
> it is implemented in perl per se? Guidance appreciated as I'm having
> trouble finding more details about these sections.

See Perl Policy section 2.4 (which governs Perl core):

     Manual pages distributed with Perl packages must be installed into the
     standard directories:

     Programs
          Manual pages for programs and scripts are installed into
          `/usr/share/man/man1' with the extension `.1'.

     Modules
          Manual pages for modules are installed into `/usr/share/man/man3'
          with the extension `.3perl'.

and then section 4.1:

     Module packages must install manual pages into the standard
     directories (see Section 2.4, `Documentation') using the extensions
     `.1p' and `.3pm' to ensure that no conflict arises where a packaged
     module duplicates a <core> module.

So basically you should install the man page with a .1p extension if it's
part of a Perl module package to protect against possible future conflicts
with Perl core.

For an application, I think .1 is fine, but I suspect that if you use the
normal Makefile.PL magic, the man page extension will get forced to .1p
because that's the right thing to do for modules.

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