On OpenBSD, each man
directory (e.g. /usr/share/man
for manual relating to the base system) contains a mandoc.db
database created by a weekly cron job running makewhatis
.
These databases are created by parsing the various manual sources (roff source files) for particular strings and they are used by the man
utility. One of the things that is indexed is the strings referred to by the .Nm
("name") macro in the .Sh NAME
section of the manuals typeset using OpenBSD's mdoc
macros.
For example, a part of the very start of the source of the malloc(3)
manual in /usr/share/man/man3/malloc.3
looks like this:
.Dd $Mdocdate: May 19 2019 $
.Dt MALLOC 3
.Os
.Sh NAME
.Nm malloc ,
.Nm calloc ,
.Nm realloc ,
.Nm free ,
.Nm reallocarray ,
.Nm recallocarray ,
.Nm freezero ,
.Nm aligned_alloc ,
.Nm malloc_conceal ,
.Nm calloc_conceal
.Nd memory allocation and deallocation
.Sh SYNOPSIS
The makewhatis
tool will index each .Nm
value and the man
command will show the rendered version of the malloc.3
source when a user asks for the manual of any of the listed functions (e.g. man free
).
Manuals not relating to the OpenBSD base system (i.e. 3rd party manuals under /usr/local/man
) are also parsed by makewhatis
, but since these often use roff markup that is not mdoc
(usually written for Linux which uses another macro package), it indexes the values used by other macros (the .TH
title macro).
Some 3rd party programs seems to distribute a separate manual or for each separate tool or function, even though this means duplicating manuals and just giving them different names. Using symbolic and/or hard links is also a common solution.
Others are a bit smarter. This is the complete manual source of zzip_fread(3)
(part of the zziplib
package):
.so man3/zzip_read.3
I.e., it contains a macro that makes the parser read another file.