automake: Man Pages

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