style/multiplemultiple 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 $ 
.Nm getlogin , 
.Nm getlogin_r , 
.Nm setlogin 
.Nd get/set login name 
.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" 
.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.
November 2, 2014