automake-1.16: Man Pages
11.2 Man Pages
==============
A package can also include man pages (but see the GNU standards on this
matter, ⇒(standards)Man Pages.) Man pages are declared using the
‘MANS’ primary. Generally the ‘man_MANS’ variable is used. Man pages
are automatically installed in the correct subdirectory of ‘mandir’,
based on the file extension.
File extensions such as ‘.1c’ are handled by looking for the valid
part of the extension and using that to determine the correct
subdirectory of ‘mandir’. Valid section names are the digits ‘0’
through ‘9’, and the letters ‘l’ and ‘n’.
Sometimes developers prefer to name a man page something like
‘foo.man’ in the source, and then rename it to have the correct suffix,
for example ‘foo.1’, when installing the file. Automake also supports
this mode. For a valid section named SECTION, there is a corresponding
directory named ‘manSECTIONdir’, and a corresponding ‘_MANS’ variable.
Files listed in such a variable are installed in the indicated section.
If the file already has a valid suffix, then it is installed as-is;
otherwise the file suffix is changed to match the section.
For instance, consider this example:
man1_MANS = rename.man thesame.1 alsothesame.1c
In this case, ‘rename.man’ will be renamed to ‘rename.1’ when installed,
but the other files will keep their names.
By default, man pages are installed by ‘make install’. However,
since the GNU project does not require man pages, many maintainers do
not expend effort to keep the man pages up to date. In these cases, the
‘no-installman’ option will prevent the man pages from being installed
by default. The user can still explicitly install them via ‘make
install-man’.
For fast installation, with many files it is preferable to use
‘manSECTION_MANS’ over ‘man_MANS’ as well as files that do not need to
be renamed.
Man pages are not currently considered to be source, because it is
not uncommon for man pages to be automatically generated. Therefore
they are not automatically included in the distribution. However, this
can be changed by use of the ‘dist_’ prefix. For instance here is how
to distribute and install the two man pages of GNU ‘cpio’ (which
includes both Texinfo documentation and man pages):
dist_man_MANS = cpio.1 mt.1
The ‘nobase_’ prefix is meaningless for man pages and is disallowed.
Executables and manpages may be renamed upon installation (⇒
Renaming). For manpages this can be avoided by use of the ‘notrans_’
prefix. For instance, suppose an executable ‘foo’ allowing to access a
library function ‘foo’ from the command line. The way to avoid renaming
of the ‘foo.3’ manpage is:
man_MANS = foo.1
notrans_man_MANS = foo.3
‘notrans_’ must be specified first when used in conjunction with
either ‘dist_’ or ‘nodist_’ (⇒Fine-grained Distribution Control).
For instance:
notrans_dist_man3_MANS = bar.3
Info Catalog
automake-1.16: Texinfo
automake-1.16: Documentation