[gentoo-pms] doman and complex man page suffixes

[gentoo-pms] doman and complex man page suffixes

[Michał Górny]

[-- Attachment #1: Type: text/plain, Size: 2182 bytes --]

Hello,

Currently PMS states that doman 'installs a man page into
the appropriate subdirectory of /usr/share/man depending upon its
apparent section suffix'.

The problem is that I am unable to find a clear statement what
an 'apparent section suffix' exactly is and what it is not. 'foo.1'
example is pretty simple but how about 'foo.1p'? Should it go into man1
or man1p?

FHS seems to be a little unclear in that case too [1]. It lists a set
of a single-digit sections, and it mentions as well that 'some large
sets of application-specific manual pages have an additional suffix
appended to the manual page filename'. But it doesn't specify clearly
how to distinguish that suffix from the actual section.

A quick check shows that autotools by default use only the first
character of a manpage suffix. Same does portage [2] (doman, l38 & l41),
however a few lines below you can see that it may expect '?f', '?p'
and '?pm' sections as well [3] (doman, l45).

A quick look at /usr/share/man shows that most manpages are installed
into single-character section directories, including those having
various suffixes appended. However, the man-pages-posix package
installs its manpages into man?p sections.

Moreover, sys-apps/man does allow user choosing the manpage section
only by the directory name. In other words, 'man 3x addch' won't work
as 'addch.3x.*' is installed in 'man3' but 'man 3 addch' would match
that page.

That basically means that two different-suffixed versions of same-named
manpage are installed into the same section directory, man won't allow
user to choose between them.

Now, what should PM do? Use single-character suffixes, complete ones or
maybe even a more complex rule? I think that should be clarified in PMS.

[1] http://www.pathname.com/fhs/2.2/fhs-4.11.html#4.11.5
[2]
http://git.overlays.gentoo.org/gitweb/?p=proj/portage.git;a=blob;f=bin/ebuild-helpers/doman;h=1862f83e1d51f37160372603d503a36ce8d776c4;hb=HEAD#l38
[3]
http://git.overlays.gentoo.org/gitweb/?p=proj/portage.git;a=blob;f=bin/ebuild-helpers/doman;h=1862f83e1d51f37160372603d503a36ce8d776c4;hb=HEAD#l45

-- 
Best regards,
Michał Górny

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 198 bytes --]