Often, one man page documents information that applies to more than one program or function. For example, 'wait' and 'waitpid' both refer to the 'wait' system call. In providing documentation, there is no need to duplicate this information when a link will suffice. In order to do this, use the .So macro. Assuming the existence of wait.2 in the appropriate place (/usr/share/man/man2), waitpid.2 would need only contain the following line:

	.so man2/wait.2

Thus

% man 2 waitpid

and

% man 2 wait

will both display the wait(2)man page.

Below is an excerpt from the wait(2)source:

	...
	.Sh NAME
	.Nm wait ,				\" The system call's real name
	.Nm waitpid ,				\" Alternate name
	.Nm wait4 ,				\" Alternate name
	.Nm wait3 ,				\" Alternate name
	.Nd wait for process termination	\" The description of the system call
	...

wait, waitpid, wait4, and wait3 all refer to the same program. Notice above that all of the alternate names invoke the .Nm macro. It is important not to just list the alternate names, but to use the .Nm macro for each name in the listing. Marking the names this way not only brings attention to the names when viewed with man, but since .Nm is easy to parse for, it makes it simple to build a script that can generate the linking man pages.

% man -k some_topic

and

% apropos some_topic

both access a database based on the words in the NAME section. This section includes the lines containing both the .Nm and .Nd macros. In light of this, a man page is most useful when the description line (.Nd) contains only key words. A detailed explanation of the program should be left for the DESCRIPTION section.

This database is generated by invoking /usr/libexec/makewhatis. For more information see whatis(1), makewhatis(8), apropos(1), and man(1).

	...
	.Sh SEE ALSO 
	.Xr a 1 , 
	.Xr b 1 ,
	.Xr c 1 ,
	.Xr a 2 ,
	.Xr b 2 ,
	.Xr a 3 ,
	.Xr b 3 
	...

The SEE ALSO tag at the bottom of a man page gives the user references to other man pages that give supplementary information. The man pages referenced here should be prefaced by the .Xr macro. They should be listed first by section number. Within the sections, they should be listed alphabetically.

If the page linked to should be on the system and is not, please file a bug against that omission at http://www.opensource.apple.com/projects/bugs.html.