style/multiple —
multiple topics in one manual page
If a small number of utilities or a small number of library functions are so
closely related to each other that writing a separate manual page for each of
them would result in large parts of duplicate text in each of the pages, write
one common manual page for all of them. However, don't let the number of
topics grow too much, or conciseness and readability will unavoidably suffer.
More than about half a dozen topics is sometimes, more than about a dozen
topics is usually problematic.
Select the name of the utility or function that best represents the whole group
as the name of the manual page. It can be the simplest version of the utility
or function, the most comprehensive one, the one used most often, or the one
usually used first, whatever fits the case at hand. In case of doubt, take the
first one in alphabetic order. The selected name is used for the
Dt macro, and it goes first in the NAME
section.
In the NAME section, provide one
Nm line for
each utility or function, each but the last one followed by a comma, the whole
group followed by one single
Nd macro line.
Except from putting the name chosen for the
Dt macro first, usually sort the remaining
names alphabetically, but sometimes, in particular when the number of names is
small, there may be good reasons to choose a different order, for example
putting a rarely used or obsolete form last. If you feel tempted to design the
ordering such that related subgroups of utilities or functions stay next to
each other, consider splitting the manual into multiple pages, one for each of
these subgroups.
In the SYNOPSIS, provide one entry for each name. Both using strictly alphabetic
ordering or the same order as in the NAME section is acceptable.
Don't forget to describe each aspect of each variant in the remaining sections,
in particular in the DESCRIPTION section, just as you would when writing
individual pages for each variant. When describing the utilities or functions,
strive for conciseness by describing them
together where they are related, but not so much
as to complicate the wording or compromise clarity or readability.
.Dd $Mdocdate: September 22 2015 $
.Dt GETLOGIN 2
.Os
.Sh NAME
.Nm getlogin ,
.Nm getlogin_r ,
.Nm setlogin
.Nd get/set login name
.Sh SYNOPSIS
.In unistd.h
.Ft char *
.Fn getlogin void
.Ft int
.Fn getlogin_r "char *name" "size_t namelen"
.Ft int
.Fn setlogin "const char *name"
.Sh DESCRIPTION
The
.Fn getlogin
routine returns the login name of the user associated with the current
session, as previously set by
.Fn setlogin .
[...]
The MANUAL STRUCTURE section in the
mdoc(7)
manual.