The following subsections note some details for preferred
formatting and wording conventions in various sections of the
pages in the man-pages project.
SYNOPSIS
Wrap the function prototype(s) in a .nf/.fi pair to prevent
filling.
In general, where more than one function prototype is shown in
the SYNOPSIS, the prototypes should not be separated by blank
lines. However, blank lines (achieved using .PP) may be added in
the following cases:
* to separate long lists of function prototypes into related
groups (see for example list(3));
* in other cases that may improve readability.
In the SYNOPSIS, a long function prototype may need to be
continued over to the next line. The continuation line is
indented according to the following rules:
1. If there is a single such prototype that needs to be
continued, then align the continuation line so that when the
page is rendered on a fixed-width font device (e.g., on an
xterm) the continuation line starts just below the start of
the argument list in the line above. (Exception: the
indentation may be adjusted if necessary to prevent a very
long continuation line or a further continuation line where
the function prototype is very long.) As an example:
int tcsetattr(int fd, int optional_actions,
const struct termios *termios_p);
2. But, where multiple functions in the SYNOPSIS require
continuation lines, and the function names have different
lengths, then align all continuation lines to start in the
same column. This provides a nicer rendering in PDF output
(because the SYNOPSIS uses a variable width font where spaces
render narrower than most characters). As an example:
int getopt(int argc, char * const argv[],
const char *optstring);
int getopt_long(int argc, char * const argv[],
const char *optstring,
const struct option *longopts, int *longindex);
RETURN VALUE
The preferred wording to describe how errno is set is "errno is
set to indicate the error" or similar. This wording is
consistent with the wording used in both POSIX.1 and FreeBSD.
ATTRIBUTES
Note the following:
* Wrap the table in this section in a .ad l/.ad pair to disable
text filling and a .nh/.hy pair to disable hyphenation.
* Ensure that the table occupies the full page width through the
use of an lbx description for one of the columns (usually the
first column, though in some cases the last column if it
contains a lot of text).
* Make free use of T{/T} macro pairs to allow table cells to be
broken over multiple lines (also bearing in mind that pages
may sometimes be rendered to a width of less than 80 columns).
For examples of all of the above, see the source code of various
pages.
