Never use the Lb
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 Lb
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 lib.in
. All the same, that file will never be complete, so Lb
will remain a portability nightmare. For that reason, some systems, for example OpenBSD
, have decided to remove support for Lb
Precede each function prototype with the full set of headers that need to be included to use the function, using In
macros. Never use Fd
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 Ft
macro, even if it is void
, then start the next input line with an Fo
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 specify void
as the second argument to Fn
To show the prototype of a function, using Fo
usually results in more readable source code than using Fn
, 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 line.
For functions having only one single argument, Fn
is usually acceptable if the whole macro fits on one input line, but there is nothing wrong with using Fo
for consistency with other, more complicated functions on the same page. If the type and name are both very short, using Fn
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 In
macros are required in between, it may occasionally be useful to insert a paragraph (Pp
) macro between two such groups to separate the groups by a small amount of vertical whitespace.