Man Pages

Manual pages are reference documents installed with software. Section numbers distinguish subjects: section 1 documents user commands, 2 system calls, 3 library functions, 4 device and special files, 5 file formats and conventions, 7 overviews and protocols, and 8 administrative commands. A qualified lookup selects the intended page:

man 2 open
man 3 printf
man 5 passwd

Sections, Names, and Synopses #

Select a page by both name and section because the same name can describe a command, function, or file. Page source and installed filenames conventionally use name.section, such as printf.1 and printf.3. The NAME section provides name \- one-line description; tools such as apropos index that line. The SYNOPSIS follows command-line notation for commands and declaration notation for APIs.

Conventional sections include NAME, SYNOPSIS, DESCRIPTION, OPTIONS or PARAMETERS, RETURN VALUE, ERRORS, ENVIRONMENT, FILES, ATTRIBUTES, STANDARDS, HISTORY or VERSIONS, EXAMPLES, NOTES, BUGS, SEE ALSO, and AUTHORS. Include only applicable sections, but document observable failures and compatibility boundaries rather than leaving them implicit. Linux API pages use ATTRIBUTES to record properties such as thread safety.

Authoring with roff #

Manual pages use roff input with either the semantic mdoc macro package or the man macro package. mandoc(1) parses, validates, and renders both formats. The mdoc vocabulary records semantic structure such as function names, options, arguments, and cross-references, allowing consistent terminal, HTML, and PostScript output.

A minimal mdoc document identifies its name, synopsis, description, options, exit status, and references:

.Dd August 7, 2026
.Dt EXAMPLE 1
.Os
.Sh NAME
.Nm example
.Nd print an example message
.Sh SYNOPSIS
.Nm
.Op Fl q
.Sh DESCRIPTION
The .Nm utility writes a message to standard output.

At the start of a roff input line, . and ' introduce requests; escape a literal leading control character with \&. Write a literal backslash as \(rs or with the macro package’s documented escape, and use \- for a semantic minus sign in command options. Prefer semantic macros such as mdoc’s .Fl, .Ar, .Fn, and .Xr over font changes because renderers can preserve meaning across output formats.

Cross-references identify both name and section, for example .Xr open 2 in mdoc or open(2) in man markup. The SEE ALSO list should cite the command, API, configuration file, or specification that defines related behavior.

Linting and Rendering #

Use mandoc -T lint file.1 to detect structural problems and mandoc -T utf8 file.1 to inspect terminal output. With GNU roff, groff -man -Tutf8 file.1 or groff -mdoc -Tutf8 file.1 renders the corresponding macro language. Projects that generate pages from source metadata still need a checked rendering path because generated input can violate macro syntax or escape rules.

The Linux man-pages project documents the Linux kernel userspace ABI and many libc interfaces. Individual packages own documentation for their commands and file formats. Record standards, the first applicable version, deviations, error conditions, and thread-safety properties from the responsible upstream source rather than inferring them from one machine.