the SYNOPSIS section for library functions
Never use the
macro unless the operating
system you are writing for strictly requires it; in that case, adhere to the
conventions of that operating system, but be aware that usage of
is mostly unportable, and the result
will likely be unsatisfactory when reading the page on a different system.
This macro is not sustainable. It causes inflationary growth of the file
. All the same, that file will never
be complete, so
will remain a
portability nightmare. For that reason, some systems, for example
, have decided to remove support for
Precede each function prototype with the full set of headers that need to be
included to use the function, using
macros. Never use
macros to show
#include directives. If several functions documented in the same manual page
require inclusion of the same set of headers, group these functions together
and do not repeat the set of headers. Whenever the next function uses a
different set of headers than the previous one, provide the full set of
headers required for the next function, even if some of the headers are also
required for the previous one.
Always provide the return type of each function with an
macro, even if it is
, then start the next input line with an
For each argument of each prototype, provide both the type of the argument and a
name for the argument. If a function does not take any arguments, explicitly
as the second argument to
To show the prototype of a function, using
usually results in more readable source code than using
, in particular for functions having more
than one argument. Avoid input lines of 80 characters and more, and avoid
input line continuation with a backslash character at the end of an input
For functions having only one single argument,
is usually acceptable if the whole macro
fits on one input line, but there is nothing wrong with using
for consistency with other, more
complicated functions on the same page. If the type and name are both very
with two arguments may
result in source code that is easier to read.
Usually, manual authors do not need to consider vertical spacing in the SYNOPSIS
section; line breaks and blank lines automatically appear at useful places. If
a manual page documents a larger number of functions, these functions form two
or more logical groups, and two or more of the groups require the same header
files to be included such that no
are required in between, it may occasionally be useful to insert a paragraph
) macro between two such groups to
separate the groups by a small amount of vertical whitespace.
.Fa "double y"
.Fa "double x"
.Fn sin "double x"
.Fn sync void
The MACRO REFERENCE section in the