The formatted source files

All the manuals that are supplied in the sendmail distribution are in troff(1) input format. Before these files can be installed, each must be formatted using the command defined by confNROFF (See this section), with the macro package defined by confMANDOC (See this section). In the following example, sendmail.8 is the troff source being formatted:

${NROFF} ${MANDOC} sendmail.8 > sendmail.${MAN8SRC}

The formatted manual is placed into a file with the same base name as the input file, but with a new tag as defined by the confMAN8SRC macro. Section 1 manuals use the confMAN1SRC macro, section 5 manuals use the confMAN5SRC macro, and section 8 manuals use the confMAN8SRC macro. In general, the confMAN*SRC macros should not be redefined^[19] unless you have a pressing need to do otherwise. For example, consider:

^[19] Due to an omission in V8.9, these can be redefined only as of V8.9.1.

define(`confMAN1SRC', `txt')
define(`confMAN4SRC', `txt')
define(`confMAN5SRC', `txt')
define(`confMAN8SRC', `txt')

which would produce a formatting command that looks like this for sendmail.8:

${NROFF} ${MANDOC} sendmail.8 > sendmail.txt

The confMAN*SRC macros are also used when the manual pages are installed. In the following example (which again uses sendmail.8 as the troff source) the formatted manuals are copied with install(1) like this:

${INSTALL} -c -o ${MANOWN} -g ${MANGRP} -m ${MANMODE} sendmail.${MAN8SRC} ${MAN8}/sen
dmail.${MAN8EXT}

Where to install the manuals

Each of the three manual sections has a directory where the formatted files should be installed. For section 1, for example, that directory is usually either /usr/man/cat1 or /usr/share/man/cat1. The appropriate directories are usually predefined for you in your devtools/OS file. In the rare event that you wish to base your formatted directories elsewhere, you can define different directories using confMANROOT and one of three confMANdigit macros. For example, consider this method of moving your previously formatted manuals to /usr/local/man:

define(`confMANROOT', `/usr/local/man/cat')

The confMANdigit and confMANROOT macros are used when the manual pages are installed. Here, using newaliases.1 as the example, the formatted manuals are copied with install(1):

${INSTALL} -c -o ${MANOWN} -g ${MANGRP} -m ${MANMODE} newaliases.${MAN1SRC} \
        ${MAN1}/newaliases.${MAN1EXT}

The directory ${MANdigit} is a concatenation of the confMANROOT macro and a confMANdigit macro. If, for another example, you want all manuals to go in a single directory, you might do something like this:

define(`confMANROOT', `/usr/local/manuals')
define(`confMAN1', `')
define(`confMAN4', `')
define(`confMAN5', `')
define(`confMAN8', `')

Note that confMAN1, confMAN4, confMAN5, and confMAN8 can also be full pathnames if you set confMANROOT to nil. This might be useful if you install manuals in highly unusual paths:

define(`confMANROOT', `')
define(`confMAN1', `/usr/man/users')
define(`confMAN4', `/usr/man/libraries')
define(`confMAN5', `/usr/man/files')
define(`confMAN8', `/usr/man/sysadmin')

Also note that -E DESTDIR (See this section) can be used to relocate all installation directories.

Finally, note that there is a special macro for setting the location of the unformatted manuals. It is called confMANROOTMAN, and one way to use it is like this:

define(`confMANROOTMAN', `/usr/local/man/man')

Here, we change the location for the unformatted manual pages from the usual (for Solaris) /usr/share/man/man to a new location in /usr/local.

Adding tags to the manual

The name of each of the three manual sections ends in a dot followed by a suffix. Those suffixes are usually digits that are set with a confMAN*EXT macro. The appropriate suffixes are usually preset for you in your devtools/OS file. In the rare event you wish to use different suffixes, you can change them using one of the three confMAN*EXT macros. For example, if you wanted all the manuals in /usr/local/man to end with the suffix .man, you could do something like this:

define(`confMAN1EXT', `man')
define(`confMAN5EXT', `man')
define(`confMAN8EXT', `man')

The confMAN*EXT macros are used when the manual pages are installed. Here, using aliases as the example, formatted manuals are copied with install(1) like this:

${INSTALL} -c -o ${MANOWN} -g ${MANGRP} -m ${MANMODE} aliases.${MAN5SRC} \
       ${MAN5}/aliases.${MAN5EXT}

Permissions and ownership of the installed manuals

The manual pages have their permissions, ownership, and group set with the corresponding confMANMODE, confMANOWN, and confMANGRP macros. These are usually correctly preset for your system in your devtools/OS file, but sometimes you might prefer different settings.

In the following example, we install all manuals owned by man and the group man with group write permissions:

define(`confMANMODE', `464')
define(`confMANOWN', `man')
define(`confMANGRP', `man')

For most versions of the install(1) program, the ownership and group must be specified by name. If you use the devtools/bin/install.sh script to install (confINSTALL), you can use appropriate integers in place of names.

Program and arguments used for formatting

The troff(1) program is used to format the manual pages. That program comes in several flavors, the most typical of which are the nroff(1) and groff(1) programs. The default is:

groff -Tascii

If your site lacks the groff(1) program, you can substitute nroff like this:

define(`confNROFF', `nroff')

If, for some reason, you don't want to format the manuals, you can use the confNO_MAN_BUILD (confNO_MAN_BUILD) macro. If, for some reason, you don't want to install the manuals, you can use the confNO_MAN_INSTALL (confNO_MAN_INSTALL) macro.

Which macro package to use when formatting

Prior to V8.10, sendmail manuals had to be formatted with the tmac.andoc package, usually located in the /usr/lib/tmac directory. Beginning with V8.10 sendmail, the manual pages are formatted with the standard Tmac.an macros, just like all your other online manuals.

If, for some reason, your site calls that macro package by a different name (but with the same function), you can specify the different command-line argument with the confMANDOC macro:

define(`confMANDOC', `-newman')

Note that you cannot format with the tmac.s (-ms) or tmac.e (-me) macro packages.