[Fedora-packaging] Installing man pages

[Tom 'spot' Callaway]

On Tue, 2005-09-27 at 18:10 +0200, Ralf Corsepius wrote: 
> Hi,
> 
> A question:
> 
> Are packages legitimated to install man pages into
> arbitrary /usr/share/man/man* directories outside those provided by the
> "filesystem" package?

Short answer: Yes, but only in specific cases.

> I checked the FHS, but it once again seems intentionally vague to me
> wrt. this topic, so I think we need a convention, here.

OK... so the FHS says:

http://www.pathname.com/fhs/pub/fhs-2.3.html#USRSHAREMANMANUALPAGES

"Manual pages are stored in <mandir>/<locale>/man<section>/<arch>."

Where <mandir> = /usr/share/man

"Systems which use a unique language and code set for all manual pages
may omit the <locale> substring and store all manual pages in <mandir>.
For example, systems which only have English manual pages coded with
ASCII, may store manual pages (the man<section> directories) directly
in /usr/share/man. (That is the traditional circumstance and
arrangement, in fact.)"

"Similarly, provision must be made for manual pages which are
architecture-dependent, such as documentation on device-drivers or
low-level system administration commands. These must be placed under an
<arch> directory in the appropriate man<section> directory; for example,
a man page for the i386 ctrlaltdel(8) command might be placed
in /usr/share/man/<locale>/man8/i386/ctrlaltdel.8."

Or, to put it in plain english:

If you have man pages that are only in EN (the most common case), then
you need to put them in %{_mandir}/man<section>, where the section
matches the section in the man pages. This is what lapack/blas does.

If you have man pages that are provided in multiple locales, then they
need to be put in %{_mandir}/<locale>/man<section>, where the locale and
section matches the section in the man pages. Man does this for some of
its translated man pages.

If you have man pages that are architecture-dependent (aka, only true
for a specific architecture), then they should be placed in
%{_mandir}/<locale>/man<section>/<arch>. I'm not aware of anything doing
this, but this is not surprising, since this is a very obscure case.

FE Packages should not own any directories under %{_mandir}. I'm also
aware that many directories under /usr/share/man are not owned. This
should be filed as a bug against the "man" package, IMHO, but this seems
to be a point of much contention inside Red Hat.

Again, I can't control FC packaging policy (unfortunately), just FE. If
nothing else, we'll set a good example for Red Hat.

~spot
-- 
Tom "spot" Callaway: Red Hat Senior Sales Engineer || GPG ID: 93054260
Fedora Extras Steering Committee Member (RPM Standards and Practices)
Aurora Linux Project Leader: http://auroralinux.org
Lemurs, llamas, and sparcs, oh my!