man.7 (17815B)
- .\" $Id: man.7,v 1.148 2021/08/05 14:31:14 schwarze Exp $
- .\"
- .\" Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
- .\" Copyright (c) 2011-2015, 2017-2020 Ingo Schwarze <schwarze@openbsd.org>
- .\" Copyright (c) 2017 Anthony Bentley <bentley@openbsd.org>
- .\" Copyright (c) 2010 Joerg Sonnenberger <joerg@netbsd.org>
- .\"
- .\" Permission to use, copy, modify, and distribute this software for any
- .\" purpose with or without fee is hereby granted, provided that the above
- .\" copyright notice and this permission notice appear in all copies.
- .\"
- .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
- .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
- .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
- .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
- .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
- .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
- .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
- .\"
- .Dd $Mdocdate: August 5 2021 $
- .Dt MAN 7
- .Os
- .Sh NAME
- .Nm man
- .Nd legacy formatting language for manual pages
- .Sh DESCRIPTION
- The
- .Nm man
- language was the standard formatting language for
- .At
- manual pages from 1979 to 1989.
- Do not use it to write new manual pages: it is a purely presentational
- language and lacks support for semantic markup.
- Use the
- .Xr mdoc 7
- language, instead.
- .Pp
- In a
- .Nm
- document, lines beginning with the control character
- .Sq \&.
- are called
- .Dq macro lines .
- The first word is the macro name.
- It usually consists of two capital letters.
- For a list of portable macros, see
- .Sx MACRO OVERVIEW .
- The words following the macro name are arguments to the macro.
- .Pp
- Lines not beginning with the control character are called
- .Dq text lines .
- They provide free-form text to be printed; the formatting of the text
- depends on the respective processing context:
- .Bd -literal -offset indent
- \&.SH Macro lines change control state.
- Text lines are interpreted within the current state.
- .Ed
- .Pp
- Many aspects of the basic syntax of the
- .Nm
- language are based on the
- .Xr roff 7
- language; see the
- .Em LANGUAGE SYNTAX
- and
- .Em MACRO SYNTAX
- sections in the
- .Xr roff 7
- manual for details, in particular regarding
- comments, escape sequences, whitespace, and quoting.
- .Pp
- Each
- .Nm
- document starts with the
- .Ic TH
- macro specifying the document's name and section, followed by the
- .Sx NAME
- section formatted as follows:
- .Bd -literal -offset indent
- \&.TH PROGNAME 1 1979-01-10
- \&.SH NAME
- \efBprogname\efR \e(en one line about what it does
- .Ed
- .Sh MACRO OVERVIEW
- This overview is sorted such that macros of similar purpose are listed
- together.
- Deprecated and non-portable macros are not included in the overview,
- but can be found in the alphabetical reference below.
- .Ss Page header and footer meta-data
- .Bl -column "RS, RE" description
- .It Ic TH Ta set the title: Ar name section date Op Ar source Op Ar volume
- .It Ic AT Ta display AT&T UNIX version in the page footer (<= 1 argument)
- .It Ic UC Ta display BSD version in the page footer (<= 1 argument)
- .El
- .Ss Sections and paragraphs
- .Bl -column "RS, RE" description
- .It Ic SH Ta section header (one line)
- .It Ic SS Ta subsection header (one line)
- .It Ic PP Ta start an undecorated paragraph (no arguments)
- .It Ic RS , RE Ta reset the left margin: Op Ar width
- .It Ic IP Ta indented paragraph: Op Ar head Op Ar width
- .It Ic TP Ta tagged paragraph: Op Ar width
- .It Ic PD Ta set vertical paragraph distance: Op Ar height
- .It Ic in Ta additional indent: Op Ar width
- .El
- .Ss Physical markup
- .Bl -column "RS, RE" description
- .It Ic B Ta boldface font
- .It Ic I Ta italic font
- .It Ic SB Ta small boldface font
- .It Ic SM Ta small roman font
- .It Ic BI Ta alternate between boldface and italic fonts
- .It Ic BR Ta alternate between boldface and roman fonts
- .It Ic IB Ta alternate between italic and boldface fonts
- .It Ic IR Ta alternate between italic and roman fonts
- .It Ic RB Ta alternate between roman and boldface fonts
- .It Ic RI Ta alternate between roman and italic fonts
- .El
- .Sh MACRO REFERENCE
- This section is a canonical reference to all macros, arranged
- alphabetically.
- For the scoping of individual macros, see
- .Sx MACRO SYNTAX .
- .Bl -tag -width 3n
- .It Ic AT
- Sets the volume for the footer for compatibility with man pages from
- .At
- releases.
- The optional arguments specify which release it is from.
- This macro is an extension that first appeared in
- .Bx 4.3 .
- .It Ic B
- Text is rendered in bold face.
- .It Ic BI
- Text is rendered alternately in bold face and italic.
- Thus,
- .Sq .BI this word and that
- causes
- .Sq this
- and
- .Sq and
- to render in bold face, while
- .Sq word
- and
- .Sq that
- render in italics.
- Whitespace between arguments is omitted in output.
- .Pp
- Example:
- .Pp
- .Dl \&.BI bold italic bold italic
- .It Ic BR
- Text is rendered alternately in bold face and roman (the default font).
- Whitespace between arguments is omitted in output.
- See also
- .Ic BI .
- .It Ic DT
- Restore the default tabulator positions.
- They are at intervals of 0.5 inches.
- This has no effect unless the tabulator positions were changed with the
- .Xr roff 7
- .Ic ta
- request.
- .It Ic EE
- This is a non-standard Version 9
- .At
- extension later adopted by GNU.
- In
- .Xr mandoc 1 ,
- it does the same as the
- .Xr roff 7
- .Ic fi
- request (switch to fill mode).
- .It Ic EX
- This is a non-standard Version 9
- .At
- extension later adopted by GNU.
- In
- .Xr mandoc 1 ,
- it does the same as the
- .Xr roff 7
- .Ic nf
- request (switch to no-fill mode).
- .It Ic HP
- Begin a paragraph whose initial output line is left-justified, but
- subsequent output lines are indented, with the following syntax:
- .Pp
- .D1 Pf . Ic HP Op Ar width
- .Pp
- The
- .Ar width
- argument is a
- .Xr roff 7
- scaling width.
- If specified, it's saved for later paragraph left margins;
- if unspecified, the saved or default width is used.
- .Pp
- This macro is portable, but deprecated
- because it has no good representation in HTML output,
- usually ending up indistinguishable from
- .Ic PP .
- .It Ic I
- Text is rendered in italics.
- .It Ic IB
- Text is rendered alternately in italics and bold face.
- Whitespace between arguments is omitted in output.
- See also
- .Ic BI .
- .It Ic IP
- Begin an indented paragraph with the following syntax:
- .Pp
- .D1 Pf . Ic IP Op Ar head Op Ar width
- .Pp
- The
- .Ar width
- argument is a
- .Xr 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.
- .Pp
- The
- .Ar head
- argument is used as a leading term, flushed to the left margin.
- This is useful for bulleted paragraphs and so on.
- .It Ic IR
- Text is rendered alternately in italics and roman (the default font).
- Whitespace between arguments is omitted in output.
- See also
- .Ic BI .
- .It Ic LP
- A synonym for
- .Ic PP .
- .It Ic ME
- End a mailto block started with
- .Ic MT .
- This is a non-standard GNU extension.
- .It Ic MT
- Begin a mailto block.
- This is a non-standard GNU extension.
- It has the following syntax:
- .Bd -unfilled -offset indent
- .Pf . Ic MT Ar address
- link description to be shown
- .Pf . Ic ME
- .Ed
- .It Ic OP
- Optional command-line argument.
- This is a non-standard DWB extension.
- It has the following syntax:
- .Pp
- .D1 Pf . Ic OP Ar key Op Ar value
- .Pp
- The
- .Ar key
- is usually a command-line flag and
- .Ar value
- its argument.
- .It Ic P
- This synonym for
- .Ic PP
- is an
- .At III
- extension later adopted by
- .Bx 4.3 .
- .It Ic PD
- Specify the vertical space to be inserted before each new paragraph.
- .br
- The syntax is as follows:
- .Pp
- .D1 Pf . Ic PD Op Ar height
- .Pp
- The
- .Ar height
- argument is a
- .Xr roff 7
- scaling width.
- It defaults to
- .Cm 1v .
- If the unit is omitted,
- .Cm v
- is assumed.
- .Pp
- This macro affects the spacing before any subsequent instances of
- .Ic HP ,
- .Ic IP ,
- .Ic LP ,
- .Ic P ,
- .Ic PP ,
- .Ic SH ,
- .Ic SS ,
- .Ic SY ,
- and
- .Ic TP .
- .It Ic PP
- Begin an undecorated paragraph.
- The scope of a paragraph is closed by a subsequent paragraph,
- sub-section, section, or end of file.
- The saved paragraph left-margin width is reset to the default.
- .It Ic RB
- Text is rendered alternately in roman (the default font) and bold face.
- Whitespace between arguments is omitted in output.
- See also
- .Ic BI .
- .It Ic RE
- Explicitly close out the scope of a prior
- .Ic RS .
- The default left margin is restored to the state before that
- .Ic RS
- invocation.
- .Pp
- The syntax is as follows:
- .Pp
- .D1 Pf . Ic RE Op Ar level
- .Pp
- Without an argument, the most recent
- .Ic RS
- block is closed out.
- If
- .Ar level
- is 1, all open
- .Ic RS
- blocks are closed out.
- Otherwise,
- .Ar level No \(mi 1
- nested
- .Ic RS
- blocks remain open.
- .It Ic RI
- Text is rendered alternately in roman (the default font) and italics.
- Whitespace between arguments is omitted in output.
- See also
- .Ic BI .
- .It Ic RS
- Temporarily reset the default left margin.
- This has the following syntax:
- .Pp
- .D1 Pf . Ic RS Op Ar width
- .Pp
- The
- .Ar width
- argument is a
- .Xr roff 7
- scaling width.
- If not specified, the saved or default width is used.
- .Pp
- See also
- .Ic RE .
- .It Ic SB
- Text is rendered in small size (one point smaller than the default font)
- bold face.
- This macro is an extension that probably first appeared in SunOS 4.0
- and was later adopted by GNU and by
- .Bx 4.4 .
- .It Ic SH
- Begin a section.
- The scope of a section is only closed by another section or the end of
- file.
- The paragraph left-margin width is reset to the default.
- .It Ic SM
- Text is rendered in small size (one point smaller than the default
- font).
- .It Ic SS
- Begin a sub-section.
- The scope of a sub-section is closed by a subsequent sub-section,
- section, or end of file.
- The paragraph left-margin width is reset to the default.
- .It Ic SY
- Begin a synopsis block with the following syntax:
- .Bd -unfilled -offset indent
- .Pf . Ic SY Ar command
- .Ar arguments
- .Pf . Ic YS
- .Ed
- .Pp
- This is a non-standard GNU extension
- and very rarely used even in GNU manual pages.
- Formatting is similar to
- .Ic IP .
- .It Ic TH
- Set the name of the manual page for use in the page header
- and footer with the following syntax:
- .Pp
- .D1 Pf . Ic TH Ar name section date Op Ar source Op Ar volume
- .Pp
- Conventionally, the document
- .Ar name
- is given in all caps.
- The
- .Ar section
- is usually a single digit, in a few cases followed by a letter.
- The recommended
- .Ar date
- format is
- .Sy YYYY-MM-DD
- as specified in the ISO-8601 standard;
- if the argument does not conform, it is printed verbatim.
- If the
- .Ar date
- is empty or not specified, the current date is used.
- The optional
- .Ar source
- string specifies the organisation providing the utility.
- When unspecified,
- .Xr mandoc 1
- uses its
- .Fl Ios
- argument.
- The
- .Ar volume
- string replaces the default volume title of the
- .Ar section .
- .Pp
- Examples:
- .Pp
- .Dl \&.TH CVS 5 "1992-02-12" GNU
- .It Ic TP
- Begin a paragraph where the head, if exceeding the indentation width, is
- followed by a newline; if not, the body follows on the same line after
- advancing to the indentation width.
- Subsequent output lines are indented.
- The syntax is as follows:
- .Bd -unfilled -offset indent
- .Pf . Ic TP Op Ar width
- .Ar head No \e" one line
- .Ar body
- .Ed
- .Pp
- The
- .Ar width
- argument is a
- .Xr roff 7
- scaling width.
- If specified, it's saved for later paragraph left-margins; if
- unspecified, the saved or default width is used.
- .It Ic TQ
- Like
- .Ic TP ,
- except that no vertical spacing is inserted before the paragraph.
- This is a non-standard GNU extension
- and very rarely used even in GNU manual pages.
- .It Ic UC
- Sets the volume for the footer for compatibility with man pages from
- .Bx
- releases.
- The optional first argument specifies which release it is from.
- This macro is an extension that first appeared in
- .Bx 3 .
- .It Ic UE
- End a uniform resource identifier block started with
- .Ic UR .
- This is a non-standard GNU extension.
- .It Ic UR
- Begin a uniform resource identifier block.
- This is a non-standard GNU extension.
- It has the following syntax:
- .Bd -unfilled -offset indent
- .Pf . Ic UR Ar uri
- link description to be shown
- .Pf . Ic UE
- .Ed
- .It Ic YS
- End a synopsis block started with
- .Ic SY .
- This is a non-standard GNU extension.
- .It Ic in
- Indent relative to the current indentation:
- .Pp
- .D1 Pf . Ic in Op Ar width
- .Pp
- If
- .Ar width
- is signed, the new offset is relative.
- Otherwise, it is absolute.
- This value is reset upon the next paragraph, section, or sub-section.
- .El
- .Sh MACRO SYNTAX
- The
- .Nm
- macros are classified by scope: line scope or block scope.
- Line macros are only scoped to the current line (and, in some
- situations, the subsequent line).
- Block macros are scoped to the current line and subsequent lines until
- closed by another block macro.
- .Ss Line Macros
- Line macros are generally scoped to the current line, with the body
- consisting of zero or more arguments.
- If a macro is scoped to the next line and the line arguments are empty,
- the next line, which must be text, is used instead.
- Thus:
- .Bd -literal -offset indent
- \&.I
- foo
- .Ed
- .Pp
- is equivalent to
- .Sq .I foo .
- If next-line macros are invoked consecutively, only the last is used.
- If a next-line macro is followed by a non-next-line macro, an error is
- raised.
- .Pp
- The syntax is as follows:
- .Bd -literal -offset indent
- \&.YO \(lBbody...\(rB
- \(lBbody...\(rB
- .Ed
- .Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent
- .It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes
- .It Ic AT Ta <=1 Ta current Ta \&
- .It Ic B Ta n Ta next-line Ta \&
- .It Ic BI Ta n Ta current Ta \&
- .It Ic BR Ta n Ta current Ta \&
- .It Ic DT Ta 0 Ta current Ta \&
- .It Ic EE Ta 0 Ta current Ta Version 9 At
- .It Ic EX Ta 0 Ta current Ta Version 9 At
- .It Ic I Ta n Ta next-line Ta \&
- .It Ic IB Ta n Ta current Ta \&
- .It Ic IR Ta n Ta current Ta \&
- .It Ic OP Ta >=1 Ta current Ta DWB
- .It Ic PD Ta 1 Ta current Ta \&
- .It Ic RB Ta n Ta current Ta \&
- .It Ic RI Ta n Ta current Ta \&
- .It Ic SB Ta n Ta next-line Ta \&
- .It Ic SM Ta n Ta next-line Ta \&
- .It Ic TH Ta >1, <6 Ta current Ta \&
- .It Ic UC Ta <=1 Ta current Ta \&
- .It Ic in Ta 1 Ta current Ta Xr roff 7
- .El
- .Ss Block Macros
- Block macros comprise a head and body.
- As with in-line macros, the head is scoped to the current line and, in
- one circumstance, the next line (the next-line stipulations as in
- .Sx Line Macros
- apply here as well).
- .Pp
- The syntax is as follows:
- .Bd -literal -offset indent
- \&.YO \(lBhead...\(rB
- \(lBhead...\(rB
- \(lBbody...\(rB
- .Ed
- .Pp
- The closure of body scope may be to the section, where a macro is closed
- by
- .Ic SH ;
- sub-section, closed by a section or
- .Ic SS ;
- or paragraph, closed by a section, sub-section,
- .Ic HP ,
- .Ic IP ,
- .Ic LP ,
- .Ic P ,
- .Ic PP ,
- .Ic RE ,
- .Ic SY ,
- or
- .Ic TP .
- No closure refers to an explicit block closing macro.
- .Pp
- 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.
- .Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent
- .It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes
- .It Ic HP Ta <2 Ta current Ta paragraph Ta \&
- .It Ic IP Ta <3 Ta current Ta paragraph Ta \&
- .It Ic LP Ta 0 Ta current Ta paragraph Ta \&
- .It Ic ME Ta 0 Ta none Ta none Ta GNU
- .It Ic MT Ta 1 Ta current Ta to \&ME Ta GNU
- .It Ic P Ta 0 Ta current Ta paragraph Ta \&
- .It Ic PP Ta 0 Ta current Ta paragraph Ta \&
- .It Ic RE Ta <=1 Ta current Ta none Ta \&
- .It Ic RS Ta 1 Ta current Ta to \&RE Ta \&
- .It Ic SH Ta >0 Ta next-line Ta section Ta \&
- .It Ic SS Ta >0 Ta next-line Ta sub-section Ta \&
- .It Ic SY Ta 1 Ta current Ta to \&YS Ta GNU
- .It Ic TP Ta n Ta next-line Ta paragraph Ta \&
- .It Ic TQ Ta n Ta next-line Ta paragraph Ta GNU
- .It Ic UE Ta 0 Ta current Ta none Ta GNU
- .It Ic UR Ta 1 Ta current Ta part Ta GNU
- .It Ic YS Ta 0 Ta none Ta none Ta GNU
- .El
- .Pp
- If a block macro is next-line scoped, it may only be followed by in-line
- macros for decorating text.
- .Ss Font handling
- In
- .Nm
- documents, both
- .Sx Physical markup
- macros and
- .Xr roff 7
- .Ql \ef
- 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
- .Ic BR
- open and close a font scope for each argument.
- .Sh SEE ALSO
- .Xr man 1 ,
- .Xr mandoc 1 ,
- .Xr eqn 7 ,
- .Xr mandoc_char 7 ,
- .Xr mdoc 7 ,
- .Xr roff 7 ,
- .Xr tbl 7
- .Sh HISTORY
- The
- .Nm
- language first appeared as a macro package for the roff typesetting
- system in
- .At v7 .
- .Pp
- The stand-alone implementation that is part of the
- .Xr mandoc 1
- utility first appeared in
- .Ox 4.6 .
- .Sh AUTHORS
- .An -nosplit
- .An Douglas McIlroy Aq Mt m.douglas.mcilroy@dartmouth.edu
- designed and implemented the original version of these macros,
- wrote the original version of this manual page,
- and was the first to use them when he edited volume 1 of the
- .At v7
- manual pages.
- .Pp
- .An James Clark
- later rewrote the macros for groff.
- .An Eric S. Raymond Aq Mt esr@thyrsus.com
- and
- .An Werner Lemberg Aq Mt wl@gnu.org
- added the extended
- .Nm
- macros to groff in 2007.
- .Pp
- The
- .Xr mandoc 1
- program and this
- .Nm
- reference were written by
- .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .