Gentoo Archives: gentoo-pms

From: "Michał Górny" <gentoo@××××××××××.pl>
To: gentoo-pms@l.g.o
Subject: [gentoo-pms] doman and complex man page suffixes
Date: Mon, 27 Sep 2010 18:55:49
Message-Id: 20100927205509.4d36f218@pomiocik.lan
1 Hello,
2
3 Currently PMS states that doman 'installs a man page into
4 the appropriate subdirectory of /usr/share/man depending upon its
5 apparent section suffix'.
6
7 The problem is that I am unable to find a clear statement what
8 an 'apparent section suffix' exactly is and what it is not. 'foo.1'
9 example is pretty simple but how about 'foo.1p'? Should it go into man1
10 or man1p?
11
12 FHS seems to be a little unclear in that case too [1]. It lists a set
13 of a single-digit sections, and it mentions as well that 'some large
14 sets of application-specific manual pages have an additional suffix
15 appended to the manual page filename'. But it doesn't specify clearly
16 how to distinguish that suffix from the actual section.
17
18 A quick check shows that autotools by default use only the first
19 character of a manpage suffix. Same does portage [2] (doman, l38 & l41),
20 however a few lines below you can see that it may expect '?f', '?p'
21 and '?pm' sections as well [3] (doman, l45).
22
23 A quick look at /usr/share/man shows that most manpages are installed
24 into single-character section directories, including those having
25 various suffixes appended. However, the man-pages-posix package
26 installs its manpages into man?p sections.
27
28 Moreover, sys-apps/man does allow user choosing the manpage section
29 only by the directory name. In other words, 'man 3x addch' won't work
30 as 'addch.3x.*' is installed in 'man3' but 'man 3 addch' would match
31 that page.
32
33 That basically means that two different-suffixed versions of same-named
34 manpage are installed into the same section directory, man won't allow
35 user to choose between them.
36
37 Now, what should PM do? Use single-character suffixes, complete ones or
38 maybe even a more complex rule? I think that should be clarified in PMS.
39
40 [1] http://www.pathname.com/fhs/2.2/fhs-4.11.html#4.11.5
41 [2]
42 http://git.overlays.gentoo.org/gitweb/?p=proj/portage.git;a=blob;f=bin/ebuild-helpers/doman;h=1862f83e1d51f37160372603d503a36ce8d776c4;hb=HEAD#l38
43 [3]
44 http://git.overlays.gentoo.org/gitweb/?p=proj/portage.git;a=blob;f=bin/ebuild-helpers/doman;h=1862f83e1d51f37160372603d503a36ce8d776c4;hb=HEAD#l45
45
46 --
47 Best regards,
48 Michał Górny

Attachments

File name MIME type
signature.asc application/pgp-signature