legacy formatting language for manual pages
UNIX manuals for the man(1) utility. It supports limited control of presentational details like fonts, indentation and spacing. This reference document describes the structure of manual pages and the syntax and usage of the man language.In a man document, lines beginning with the control character ‘.’ are called “macro lines”. The first word is the macro name. It usually consists of two capital letters. For a list of available macros, see MACRO OVERVIEW. The words following the macro name are arguments to the macro.Lines not beginning with the control character are called “text lines”. They provide free-form text to be printed; the formatting of the text depends on the respective processing context:Many aspects of the basic syntax of the man language are based on the roff(7) language; see the LANGUAGE SYNTAX and MACRO SYNTAX sections in the roff(7) manual for details, in particular regarding comments, escape sequences, whitespace, and quoting.
Do not use man to write your manuals:It lacks support for semantic markup. Use the mdoc(7) language, instead.
.SH Macro lines change control state. Text lines are interpreted within the current state.
TH macro describing the document's section and title. It may occur anywhere in the document, although conventionally it appears as the first macro.Beyond TH, at least one macro or text line must appear in the document.The following is a well-formed skeleton man file for a utility “progname”:The sections in a man document are conventionally ordered as they appear above. Sections should be composed as follows:
.TH PROGNAME 1 2009-10-10 .SH NAME \fBprogname\fR \(en one line about what it does .\" .SH LIBRARY .\" For sections 2, 3, and 9 only. .\" Not used in OpenBSD. .SH SYNOPSIS \fBprogname\fR [\fB\-options\fR] \fIfile ...\fR .SH DESCRIPTION The \fBfoo\fR utility processes files ... .\" .Sh CONTEXT .\" For section 9 functions only. .\" .SH IMPLEMENTATION NOTES .\" Not used in OpenBSD. .\" .SH RETURN VALUES .\" For sections 2, 3, and 9 function return values only. .\" .SH ENVIRONMENT .\" For sections 1, 6, 7, and 8 only. .\" .SH FILES .\" .SH EXIT STATUS .\" For sections 1, 6, and 8 only. .\" .SH EXAMPLES .\" .SH DIAGNOSTICS .\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only. .\" .SH ERRORS .\" For sections 2, 3, 4, and 9 errno settings only. .\" .SH SEE ALSO .\" .BR foobar ( 1 ) .\" .SH STANDARDS .\" .SH HISTORY .\" .SH AUTHORS .\" .SH CAVEATS .\" .SH BUGS .\" .SH SECURITY CONSIDERATIONS .\" Not used in OpenBSD.
The name(s) and a short description of the documented material. The syntax for this is generally as follows:\fBname\fR \(en description
The name of the library containing the documented material, which is assumed to be a function in a section 2 or 3 manual. For functions in the C library, this may be as follows:Standard C Library (libc, -lc)
Documents the utility invocation syntax, function call syntax, or device configuration.\fBname\fR [-\fBab\fR] [-\fBc\fR\fIarg\fR] \fBpath\fR....B char *name(char *\fIarg\fR);.B name* at cardbus? function?
- This expands upon the brief, one-line description in NAME. It usually contains a break-down of the options (if documenting a command).
- This section lists the contexts in which functions can be called in section 9. The contexts are autoconf, process, or interrupt.
- IMPLEMENTATION NOTES
- Implementation-specific notes should be kept here. This is useful when implementing standard functions that may have side effects or notable algorithmic implications.
- RETURN VALUES
- This section documents the return values of functions in sections 2, 3, and 9.
- Documents any usages of environment variables, e.g., environ(7).
- Documents files used. It's helpful to document both the file name and a short description of how the file is used (created, modified, etc.).
- EXIT STATUS
- This section documents the command exit status for section 1, 6, and 8 utilities. Historically, this information was described in DIAGNOSTICS, a practise that is now discouraged.
- Example usages. This often contains snippets of well-formed, well-tested invocations. Make sure that examples work properly!
Documents error conditions. In section 4 and 9 manuals, these are usually messages printed by the kernel to the console and to the kernel log. In section 1, 6, 7, and 8, these are usually messages printed by userland programs to the standard error output.
- Documents errno(2) settings in sections 2, 3, 4, and 9.
- SEE ALSO
References other manuals with related topics. This section should exist for most manuals..BR bar ( 1 ),
References any standards implemented or used, such asIEEE Std 1003.2 (\(lqPOSIX.2\(rq)
- A brief history of the subject, including where support first appeared.
- Credits to the person or persons who wrote the code and/or documentation. Authors should generally be noted by both name and email address.
- Common misuses and misunderstandings should be explained in this section.
- Known bugs, limitations, and work-arounds should be described in this section.
- SECURITY CONSIDERATIONS
- Documents any security precautions that operators should consider.
|TH||set the title: title section date [source [volume]]|
|AT||display AT&T UNIX version in the page footer (<= 1 argument)|
|UC||display BSD version in the page footer (<= 1 argument)|
|SH||section header (one line)|
|SS||subsection header (one line)|
|PP, LP, P||start an undecorated paragraph (no arguments)|
|RS, RE||reset the left margin: [width]|
|IP||indented paragraph: [head [width]]|
|TP||tagged paragraph: [width]|
|HP||hanged paragraph: [width]|
|PD||set vertical paragraph distance: [height]|
|br||force output line break in text mode (no arguments)|
|sp||force vertical space: [height]|
|fi, nf||fill mode and no-fill mode (no arguments)|
|in||additional indent: [width]|
|R||roman (default) font|
|SB||small boldface font|
|SM||small roman font|
|BI||alternate between boldface and italic fonts|
|BR||alternate between boldface and roman fonts|
|IB||alternate between italic and boldface fonts|
|IR||alternate between italic and roman fonts|
|RB||alternate between roman and boldface fonts|
|RI||alternate between roman and italic fonts|
MACRO SYNTAX.Examples:The output of this example will be emboldened “bold” and italicised “italic”, with spaces stripped between arguments.See also IB, BR, RB, RI, and IR.See BI for an equivalent example.See also BI, IB, RB, RI, and IR.The width argument is a roff(7) scaling width. If specified, it's saved for later paragraph left-margins; if unspecified, the saved or default width is used.See also IP, LP, P, PP, and TP.See BI for an equivalent example.See also BI, BR, RB, RI, and IR.The width argument is a roff(7) scaling width defining the left margin. It's saved for later paragraph left-margins; if unspecified, the saved or default width is used.The head argument is used as a leading term, flushed to the left margin. This is useful for bulleted paragraphs and so on.See also HP, LP, P, PP, and TP.See BI for an equivalent example.See also BI, IB, BR, RB, and RI.See also HP, IP, P, PP, and TP.The key is usually a command-line flag and value its argument.The syntax is as follows:The height argument is a roff(7) scaling width. It defaults to 1v. If the unit is omitted, v is assumed.This macro affects the spacing before any subsequent instances of HP, IP, LP, P, PP, SH, SS, and TP.See BI for an equivalent example.See also BI, IB, BR, RI, and IR.See BI for an equivalent example.See also BI, IB, BR, RB, and IR.The width argument is a roff(7) scaling width. If not specified, the saved or default width is used.See also RE.Conventionally, the document title is given in all caps. The recommended date format is YYYY-MM-DD as specified in the ISO-8601 standard; if the argument does not conform, it is printed verbatim. If the date is empty or not specified, the current date is used. The optional source string specifies the organisation providing the utility. When unspecified, mandoc(1) uses its -Ios argument. The volume string replaces the default rendered volume, which is dictated by the manual section.Examples:The width argument is a roff(7) scaling width. If specified, it's saved for later paragraph left-margins; if unspecified, the saved or default width is used.See also HP, IP, LP, P, and PP.If width is signed, the new offset is relative. Otherwise, it is absolute. This value is reset upon the next paragraph, section, or sub-section.
.BI bold italic bold italic
mandoc(1), it does the same as fi.
mandoc(1), it does the same as nf.
.IP [head [width]]
.OP key [value]
RS. The default left margin is restored to the state before that RS invocation.The syntax is as follows:Without an argument, the most recent RS block is closed out. If level is 1, all open RS blocks are closed out. Otherwise, level
− 1nested RS blocks remain open.
.TH title section date [source [volume]]
.TH CVS 5 1992-02-12 GNU
BSD releases. The optional first argument specifies which release it is from.
fi. Literal mode is implicitly ended by SH or SS.
.YO [body...] [body...]
Line Macros apply here as well).The syntax is as follows:The closure of body scope may be to the section, where a macro is closed by SH; sub-section, closed by a section or SS; part, closed by a section, sub-section, or RE; or paragraph, closed by a section, sub-section, part, HP, IP, LP, P, PP, or TP. No closure refers to an explicit block closing macro.As a rule, block macros may not be nested; thus, calling a block macro while another block macro scope is open, and the open scope is not implicitly closed, is syntactically incorrect.
Macros marked “compat” are as mentioned in Line Macros.If a block macro is next-line scoped, it may only be followed by in-line macros for decorating text.
.YO [head...] [head...] [body...]
|Macro||Arguments||Head Scope||Body Scope||Notes|
Physical markup macros and roff(7) ‘
\f’ font escape sequences can be used to choose fonts. In text lines, the effect of manual font selection by escape sequences only lasts until the next macro invocation; in macro lines, it only lasts until the end of the macro scope. Note that macros like BR open and close a font scope for each argument.
mandoc(1) utility written by Kristaps Dzonsons appeared in OpenBSD 4.6.