913 lines
23 KiB
Groff
913 lines
23 KiB
Groff
.\" $Vendor-Id: man.7,v 1.113 2012/01/03 15:16:24 kristaps Exp $
|
|
.\"
|
|
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
|
|
.\" Copyright (c) 2011 Ingo Schwarze <schwarze@openbsd.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 January 3, 2012
|
|
.Dt MAN 7
|
|
.Os
|
|
.Sh NAME
|
|
.Nm man
|
|
.Nd legacy formatting language for manual pages
|
|
.Sh DESCRIPTION
|
|
Traditionally, the
|
|
.Nm man
|
|
language has been used to write
|
|
.Ux
|
|
manuals for the
|
|
.Xr 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.
|
|
.Pp
|
|
.Bf -emphasis
|
|
Do not use
|
|
.Nm
|
|
to write your manuals:
|
|
.Ef
|
|
It 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 available 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.
|
|
.Sh MANUAL STRUCTURE
|
|
Each
|
|
.Nm
|
|
document must contain the
|
|
.Sx \&TH
|
|
macro describing the document's section and title.
|
|
It may occur anywhere in the document, although conventionally it
|
|
appears as the first macro.
|
|
.Pp
|
|
Beyond
|
|
.Sx \&TH ,
|
|
at least one macro or text line must appear in the document.
|
|
.Pp
|
|
The following is a well-formed skeleton
|
|
.Nm
|
|
file for a utility
|
|
.Qq progname :
|
|
.Bd -literal -offset indent
|
|
\&.TH PROGNAME 1 2009-10-10
|
|
\&.SH NAME
|
|
\efBprogname\efR \e(en a description goes here
|
|
\&.\e\(dq .SH LIBRARY
|
|
\&.\e\(dq For sections 2 & 3 only.
|
|
\&.\e\(dq Not used in OpenBSD.
|
|
\&.SH SYNOPSIS
|
|
\efBprogname\efR [\efB\e-options\efR] arguments...
|
|
\&.SH DESCRIPTION
|
|
The \efBfoo\efR utility processes files...
|
|
\&.\e\(dq .SH IMPLEMENTATION NOTES
|
|
\&.\e\(dq Not used in OpenBSD.
|
|
\&.\e\(dq .SH RETURN VALUES
|
|
\&.\e\(dq For sections 2, 3, & 9 only.
|
|
\&.\e\(dq .SH ENVIRONMENT
|
|
\&.\e\(dq For sections 1, 6, 7, & 8 only.
|
|
\&.\e\(dq .SH FILES
|
|
\&.\e\(dq .SH EXIT STATUS
|
|
\&.\e\(dq For sections 1, 6, & 8 only.
|
|
\&.\e\(dq .SH EXAMPLES
|
|
\&.\e\(dq .SH DIAGNOSTICS
|
|
\&.\e\(dq For sections 1, 4, 6, 7, & 8 only.
|
|
\&.\e\(dq .SH ERRORS
|
|
\&.\e\(dq For sections 2, 3, & 9 only.
|
|
\&.\e\(dq .SH SEE ALSO
|
|
\&.\e\(dq .BR foo ( 1 )
|
|
\&.\e\(dq .SH STANDARDS
|
|
\&.\e\(dq .SH HISTORY
|
|
\&.\e\(dq .SH AUTHORS
|
|
\&.\e\(dq .SH CAVEATS
|
|
\&.\e\(dq .SH BUGS
|
|
\&.\e\(dq .SH SECURITY CONSIDERATIONS
|
|
\&.\e\(dq Not used in OpenBSD.
|
|
.Ed
|
|
.Pp
|
|
The sections in a
|
|
.Nm
|
|
document are conventionally ordered as they appear above.
|
|
Sections should be composed as follows:
|
|
.Bl -ohang -offset indent
|
|
.It Em NAME
|
|
The name(s) and a short description of the documented material.
|
|
The syntax for this is generally as follows:
|
|
.Pp
|
|
.D1 \efBname\efR \e(en description
|
|
.It Em LIBRARY
|
|
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:
|
|
.Pp
|
|
.D1 Standard C Library (libc, -lc)
|
|
.It Em SYNOPSIS
|
|
Documents the utility invocation syntax, function call syntax, or device
|
|
configuration.
|
|
.Pp
|
|
For the first, utilities (sections 1, 6, and 8), this is
|
|
generally structured as follows:
|
|
.Pp
|
|
.D1 \efBname\efR [-\efBab\efR] [-\efBc\efR\efIarg\efR] \efBpath\efR...
|
|
.Pp
|
|
For the second, function calls (sections 2, 3, 9):
|
|
.Pp
|
|
.D1 \&.B char *name(char *\efIarg\efR);
|
|
.Pp
|
|
And for the third, configurations (section 4):
|
|
.Pp
|
|
.D1 \&.B name* at cardbus ? function ?
|
|
.Pp
|
|
Manuals not in these sections generally don't need a
|
|
.Em SYNOPSIS .
|
|
.It Em DESCRIPTION
|
|
This expands upon the brief, one-line description in
|
|
.Em NAME .
|
|
It usually contains a break-down of the options (if documenting a
|
|
command).
|
|
.It Em 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.
|
|
.It Em RETURN VALUES
|
|
This section documents the return values of functions in sections 2, 3, and 9.
|
|
.It Em ENVIRONMENT
|
|
Documents any usages of environment variables, e.g.,
|
|
.Xr environ 7 .
|
|
.It Em FILES
|
|
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.).
|
|
.It Em EXIT STATUS
|
|
This section documents the command exit status for
|
|
section 1, 6, and 8 utilities.
|
|
Historically, this information was described in
|
|
.Em DIAGNOSTICS ,
|
|
a practise that is now discouraged.
|
|
.It Em EXAMPLES
|
|
Example usages.
|
|
This often contains snippets of well-formed,
|
|
well-tested invocations.
|
|
Make sure that examples work properly!
|
|
.It Em DIAGNOSTICS
|
|
Documents error conditions.
|
|
This is most useful in section 4 manuals.
|
|
Historically, this section was used in place of
|
|
.Em EXIT STATUS
|
|
for manuals in sections 1, 6, and 8; however, this practise is
|
|
discouraged.
|
|
.It Em ERRORS
|
|
Documents error handling in sections 2, 3, and 9.
|
|
.It Em SEE ALSO
|
|
References other manuals with related topics.
|
|
This section should exist for most manuals.
|
|
.Pp
|
|
.D1 \&.BR bar \&( 1 \&),
|
|
.Pp
|
|
Cross-references should conventionally be ordered
|
|
first by section, then alphabetically.
|
|
.It Em STANDARDS
|
|
References any standards implemented or used, such as
|
|
.Pp
|
|
.D1 IEEE Std 1003.2 (\e(lqPOSIX.2\e(rq)
|
|
.Pp
|
|
If not adhering to any standards, the
|
|
.Em HISTORY
|
|
section should be used.
|
|
.It Em HISTORY
|
|
A brief history of the subject, including where support first appeared.
|
|
.It Em AUTHORS
|
|
Credits to the person or persons who wrote the code and/or documentation.
|
|
Authors should generally be noted by both name and email address.
|
|
.It Em CAVEATS
|
|
Common misuses and misunderstandings should be explained
|
|
in this section.
|
|
.It Em BUGS
|
|
Known bugs, limitations, and work-arounds should be described
|
|
in this section.
|
|
.It Em SECURITY CONSIDERATIONS
|
|
Documents any security precautions that operators should consider.
|
|
.El
|
|
.Sh MACRO OVERVIEW
|
|
This overview is sorted such that macros of similar purpose are listed
|
|
together, to help find the best macro for any given purpose.
|
|
Deprecated 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 "PP, LP, P" description
|
|
.It Sx TH Ta set the title: Ar title section date Op Ar source Op Ar volume
|
|
.It Sx AT Ta display AT&T UNIX version in the page footer (<= 1 argument)
|
|
.It Sx UC Ta display BSD version in the page footer (<= 1 argument)
|
|
.El
|
|
.Ss Sections and paragraphs
|
|
.Bl -column "PP, LP, P" description
|
|
.It Sx SH Ta section header (one line)
|
|
.It Sx SS Ta subsection header (one line)
|
|
.It Sx PP , LP , P Ta start an undecorated paragraph (no arguments)
|
|
.It Sx RS , RE Ta reset the left margin: Op Ar width
|
|
.It Sx IP Ta indented paragraph: Op Ar head Op Ar width
|
|
.It Sx TP Ta tagged paragraph: Op Ar width
|
|
.It Sx HP Ta hanged paragraph: Op Ar width
|
|
.It Sx \&br Ta force output line break in text mode (no arguments)
|
|
.It Sx \&sp Ta force vertical space: Op Ar height
|
|
.It Sx fi , nf Ta fill mode and no-fill mode (no arguments)
|
|
.It Sx in Ta additional indent: Op Ar width
|
|
.El
|
|
.Ss Physical markup
|
|
.Bl -column "PP, LP, P" description
|
|
.It Sx B Ta boldface font
|
|
.It Sx I Ta italic font
|
|
.It Sx R Ta roman (default) font
|
|
.It Sx SB Ta small boldface font
|
|
.It Sx SM Ta small roman font
|
|
.It Sx BI Ta alternate between boldface and italic fonts
|
|
.It Sx BR Ta alternate between boldface and roman fonts
|
|
.It Sx IB Ta alternate between italic and boldface fonts
|
|
.It Sx IR Ta alternate between italic and roman fonts
|
|
.It Sx RB Ta alternate between roman and boldface fonts
|
|
.It Sx RI Ta alternate between roman and italic fonts
|
|
.El
|
|
.Ss Semantic markup
|
|
.Bl -column "PP, LP, P" description
|
|
.It Sx OP Ta optional arguments
|
|
.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 .
|
|
.Ss \&AT
|
|
Sets the volume for the footer for compatibility with man pages from
|
|
.Tn AT&T UNIX
|
|
releases.
|
|
The optional arguments specify which release it is from.
|
|
.Ss \&B
|
|
Text is rendered in bold face.
|
|
.Pp
|
|
See also
|
|
.Sx \&I
|
|
and
|
|
.Sx \&R .
|
|
.Ss \&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
|
|
Examples:
|
|
.Pp
|
|
.Dl \&.BI bold italic bold italic
|
|
.Pp
|
|
The output of this example will be emboldened
|
|
.Dq bold
|
|
and italicised
|
|
.Dq italic ,
|
|
with spaces stripped between arguments.
|
|
.Pp
|
|
See also
|
|
.Sx \&IB ,
|
|
.Sx \&BR ,
|
|
.Sx \&RB ,
|
|
.Sx \&RI ,
|
|
and
|
|
.Sx \&IR .
|
|
.Ss \&BR
|
|
Text is rendered alternately in bold face and roman (the default font).
|
|
Whitespace between arguments is omitted in output.
|
|
.Pp
|
|
See
|
|
.Sx \&BI
|
|
for an equivalent example.
|
|
.Pp
|
|
See also
|
|
.Sx \&BI ,
|
|
.Sx \&IB ,
|
|
.Sx \&RB ,
|
|
.Sx \&RI ,
|
|
and
|
|
.Sx \&IR .
|
|
.Ss \&DT
|
|
Has no effect.
|
|
Included for compatibility.
|
|
.Ss \&HP
|
|
Begin a paragraph whose initial output line is left-justified, but
|
|
subsequent output lines are indented, with the following syntax:
|
|
.Bd -filled -offset indent
|
|
.Pf \. Sx \&HP
|
|
.Op Cm width
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Cm width
|
|
argument must conform to
|
|
.Sx Scaling Widths .
|
|
If specified, it's saved for later paragraph left-margins; if unspecified, the
|
|
saved or default width is used.
|
|
.Pp
|
|
See also
|
|
.Sx \&IP ,
|
|
.Sx \&LP ,
|
|
.Sx \&P ,
|
|
.Sx \&PP ,
|
|
and
|
|
.Sx \&TP .
|
|
.Ss \&I
|
|
Text is rendered in italics.
|
|
.Pp
|
|
See also
|
|
.Sx \&B
|
|
and
|
|
.Sx \&R .
|
|
.Ss \&IB
|
|
Text is rendered alternately in italics and bold face.
|
|
Whitespace between arguments is omitted in output.
|
|
.Pp
|
|
See
|
|
.Sx \&BI
|
|
for an equivalent example.
|
|
.Pp
|
|
See also
|
|
.Sx \&BI ,
|
|
.Sx \&BR ,
|
|
.Sx \&RB ,
|
|
.Sx \&RI ,
|
|
and
|
|
.Sx \&IR .
|
|
.Ss \&IP
|
|
Begin an indented paragraph with the following syntax:
|
|
.Bd -filled -offset indent
|
|
.Pf \. Sx \&IP
|
|
.Op Cm head Op Cm width
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Cm width
|
|
argument defines the width of the left margin and is defined by
|
|
.Sx Scaling Widths .
|
|
It's saved for later paragraph left-margins; if unspecified, the saved or
|
|
default width is used.
|
|
.Pp
|
|
The
|
|
.Cm head
|
|
argument is used as a leading term, flushed to the left margin.
|
|
This is useful for bulleted paragraphs and so on.
|
|
.Pp
|
|
See also
|
|
.Sx \&HP ,
|
|
.Sx \&LP ,
|
|
.Sx \&P ,
|
|
.Sx \&PP ,
|
|
and
|
|
.Sx \&TP .
|
|
.Ss \&IR
|
|
Text is rendered alternately in italics and roman (the default font).
|
|
Whitespace between arguments is omitted in output.
|
|
.Pp
|
|
See
|
|
.Sx \&BI
|
|
for an equivalent example.
|
|
.Pp
|
|
See also
|
|
.Sx \&BI ,
|
|
.Sx \&IB ,
|
|
.Sx \&BR ,
|
|
.Sx \&RB ,
|
|
and
|
|
.Sx \&RI .
|
|
.Ss \&LP
|
|
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.
|
|
.Pp
|
|
See also
|
|
.Sx \&HP ,
|
|
.Sx \&IP ,
|
|
.Sx \&P ,
|
|
.Sx \&PP ,
|
|
and
|
|
.Sx \&TP .
|
|
.Ss \&OP
|
|
Optional command-line argument.
|
|
This has the following syntax:
|
|
.Bd -filled -offset indent
|
|
.Pf \. Sx \&OP
|
|
.Cm key Op Cm value
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Cm key
|
|
is usually a command-line flag and
|
|
.Cm value
|
|
its argument.
|
|
.Ss \&P
|
|
Synonym for
|
|
.Sx \&LP .
|
|
.Pp
|
|
See also
|
|
.Sx \&HP ,
|
|
.Sx \&IP ,
|
|
.Sx \&LP ,
|
|
.Sx \&PP ,
|
|
and
|
|
.Sx \&TP .
|
|
.Ss \&PP
|
|
Synonym for
|
|
.Sx \&LP .
|
|
.Pp
|
|
See also
|
|
.Sx \&HP ,
|
|
.Sx \&IP ,
|
|
.Sx \&LP ,
|
|
.Sx \&P ,
|
|
and
|
|
.Sx \&TP .
|
|
.Ss \&R
|
|
Text is rendered in roman (the default font).
|
|
.Pp
|
|
See also
|
|
.Sx \&I
|
|
and
|
|
.Sx \&B .
|
|
.Ss \&RB
|
|
Text is rendered alternately in roman (the default font) and bold face.
|
|
Whitespace between arguments is omitted in output.
|
|
.Pp
|
|
See
|
|
.Sx \&BI
|
|
for an equivalent example.
|
|
.Pp
|
|
See also
|
|
.Sx \&BI ,
|
|
.Sx \&IB ,
|
|
.Sx \&BR ,
|
|
.Sx \&RI ,
|
|
and
|
|
.Sx \&IR .
|
|
.Ss \&RE
|
|
Explicitly close out the scope of a prior
|
|
.Sx \&RS .
|
|
The default left margin is restored to the state of the original
|
|
.Sx \&RS
|
|
invocation.
|
|
.Ss \&RI
|
|
Text is rendered alternately in roman (the default font) and italics.
|
|
Whitespace between arguments is omitted in output.
|
|
.Pp
|
|
See
|
|
.Sx \&BI
|
|
for an equivalent example.
|
|
.Pp
|
|
See also
|
|
.Sx \&BI ,
|
|
.Sx \&IB ,
|
|
.Sx \&BR ,
|
|
.Sx \&RB ,
|
|
and
|
|
.Sx \&IR .
|
|
.Ss \&RS
|
|
Temporarily reset the default left margin.
|
|
This has the following syntax:
|
|
.Bd -filled -offset indent
|
|
.Pf \. Sx \&RS
|
|
.Op Cm width
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Cm width
|
|
argument must conform to
|
|
.Sx Scaling Widths .
|
|
If not specified, the saved or default width is used.
|
|
.Pp
|
|
See also
|
|
.Sx \&RE .
|
|
.Ss \&SB
|
|
Text is rendered in small size (one point smaller than the default font)
|
|
bold face.
|
|
.Ss \&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.
|
|
.Ss \&SM
|
|
Text is rendered in small size (one point smaller than the default
|
|
font).
|
|
.Ss \&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.
|
|
.Ss \&TH
|
|
Sets the title of the manual page with the following syntax:
|
|
.Bd -filled -offset indent
|
|
.Pf \. Sx \&TH
|
|
.Ar title section date
|
|
.Op Ar source Op Ar volume
|
|
.Ed
|
|
.Pp
|
|
Conventionally, the document
|
|
.Ar title
|
|
is given in all caps.
|
|
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.
|
|
The
|
|
.Ar volume
|
|
string replaces the default rendered volume, which is dictated by the
|
|
manual section.
|
|
.Pp
|
|
Examples:
|
|
.Pp
|
|
.Dl \&.TH CVS 5 "1992-02-12" GNU
|
|
.Ss \&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 a
|
|
buffer to the indentation width.
|
|
Subsequent output lines are indented.
|
|
The syntax is as follows:
|
|
.Bd -filled -offset indent
|
|
.Pf \. Sx \&TP
|
|
.Op Cm width
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Cm width
|
|
argument must conform to
|
|
.Sx Scaling Widths .
|
|
If specified, it's saved for later paragraph left-margins; if
|
|
unspecified, the saved or default width is used.
|
|
.Pp
|
|
See also
|
|
.Sx \&HP ,
|
|
.Sx \&IP ,
|
|
.Sx \&LP ,
|
|
.Sx \&P ,
|
|
and
|
|
.Sx \&PP .
|
|
.Ss \&UC
|
|
Sets the volume for the footer for compatibility with man pages from
|
|
BSD releases.
|
|
The optional first argument specifies which release it is from.
|
|
.Ss \&br
|
|
Breaks the current line.
|
|
Consecutive invocations have no further effect.
|
|
.Pp
|
|
See also
|
|
.Sx \&sp .
|
|
.Ss \&fi
|
|
End literal mode begun by
|
|
.Sx \&nf .
|
|
.Ss \&ft
|
|
Change the current font mode.
|
|
See
|
|
.Sx Text Decoration
|
|
for a listing of available font modes.
|
|
.Ss \&in
|
|
Indent relative to the current indentation:
|
|
.Pp
|
|
.D1 Pf \. Sx \&in Op Cm width
|
|
.Pp
|
|
If
|
|
.Cm width
|
|
is signed, the new offset is relative.
|
|
Otherwise, it is absolute.
|
|
This value is reset upon the next paragraph, section, or sub-section.
|
|
.Ss \&na
|
|
Don't align to the right margin.
|
|
.Ss \&nf
|
|
Begin literal mode: all subsequent free-form lines have their end of
|
|
line boundaries preserved.
|
|
May be ended by
|
|
.Sx \&fi .
|
|
Literal mode is implicitly ended by
|
|
.Sx \&SH
|
|
or
|
|
.Sx \&SS .
|
|
.Ss \&sp
|
|
Insert vertical spaces into output with the following syntax:
|
|
.Bd -filled -offset indent
|
|
.Pf \. Sx \&sp
|
|
.Op Cm height
|
|
.Ed
|
|
.Pp
|
|
Insert
|
|
.Cm height
|
|
spaces, which must conform to
|
|
.Sx Scaling Widths .
|
|
If 0, this is equivalent to the
|
|
.Sx \&br
|
|
macro.
|
|
Defaults to 1, if unspecified.
|
|
.Pp
|
|
See also
|
|
.Sx \&br .
|
|
.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, except for
|
|
.Sx \&br ,
|
|
.Sx \&sp ,
|
|
and
|
|
.Sx \&na .
|
|
.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 Sx \&AT Ta <=1 Ta current Ta \&
|
|
.It Sx \&B Ta n Ta next-line Ta \&
|
|
.It Sx \&BI Ta n Ta current Ta \&
|
|
.It Sx \&BR Ta n Ta current Ta \&
|
|
.It Sx \&DT Ta 0 Ta current Ta \&
|
|
.It Sx \&I Ta n Ta next-line Ta \&
|
|
.It Sx \&IB Ta n Ta current Ta \&
|
|
.It Sx \&IR Ta n Ta current Ta \&
|
|
.It Sx \&OP Ta 0, 1 Ta current Ta compat
|
|
.It Sx \&R Ta n Ta next-line Ta \&
|
|
.It Sx \&RB Ta n Ta current Ta \&
|
|
.It Sx \&RI Ta n Ta current Ta \&
|
|
.It Sx \&SB Ta n Ta next-line Ta \&
|
|
.It Sx \&SM Ta n Ta next-line Ta \&
|
|
.It Sx \&TH Ta >1, <6 Ta current Ta \&
|
|
.It Sx \&UC Ta <=1 Ta current Ta \&
|
|
.It Sx \&br Ta 0 Ta current Ta compat
|
|
.It Sx \&fi Ta 0 Ta current Ta compat
|
|
.It Sx \&ft Ta 1 Ta current Ta compat
|
|
.It Sx \&in Ta 1 Ta current Ta compat
|
|
.It Sx \&na Ta 0 Ta current Ta compat
|
|
.It Sx \&nf Ta 0 Ta current Ta compat
|
|
.It Sx \&sp Ta 1 Ta current Ta compat
|
|
.El
|
|
.Pp
|
|
Macros marked as
|
|
.Qq compat
|
|
are included for compatibility with the significant corpus of existing
|
|
manuals that mix dialects of roff.
|
|
These macros should not be used for portable
|
|
.Nm
|
|
manuals.
|
|
.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
|
|
.Sx \&SH ;
|
|
sub-section, closed by a section or
|
|
.Sx \&SS ;
|
|
part, closed by a section, sub-section, or
|
|
.Sx \&RE ;
|
|
or paragraph, closed by a section, sub-section, part,
|
|
.Sx \&HP ,
|
|
.Sx \&IP ,
|
|
.Sx \&LP ,
|
|
.Sx \&P ,
|
|
.Sx \&PP ,
|
|
or
|
|
.Sx \&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 Sx \&HP Ta <2 Ta current Ta paragraph Ta \&
|
|
.It Sx \&IP Ta <3 Ta current Ta paragraph Ta \&
|
|
.It Sx \&LP Ta 0 Ta current Ta paragraph Ta \&
|
|
.It Sx \&P Ta 0 Ta current Ta paragraph Ta \&
|
|
.It Sx \&PP Ta 0 Ta current Ta paragraph Ta \&
|
|
.It Sx \&RE Ta 0 Ta current Ta none Ta compat
|
|
.It Sx \&RS Ta 1 Ta current Ta part Ta compat
|
|
.It Sx \&SH Ta >0 Ta next-line Ta section Ta \&
|
|
.It Sx \&SS Ta >0 Ta next-line Ta sub-section Ta \&
|
|
.It Sx \&TP Ta n Ta next-line Ta paragraph Ta \&
|
|
.El
|
|
.Pp
|
|
Macros marked
|
|
.Qq compat
|
|
are as mentioned in
|
|
.Sx Line Macros .
|
|
.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
|
|
.Sx \&BR
|
|
open and close a font scope for each argument.
|
|
.Sh COMPATIBILITY
|
|
This section documents areas of questionable portability between
|
|
implementations of the
|
|
.Nm
|
|
language.
|
|
.Pp
|
|
.Bl -dash -compact
|
|
.It
|
|
Do not depend on
|
|
.Sx \&SH
|
|
or
|
|
.Sx \&SS
|
|
to close out a literal context opened with
|
|
.Sx \&nf .
|
|
This behaviour may not be portable.
|
|
.It
|
|
In quoted literals, GNU troff allowed pair-wise double-quotes to produce
|
|
a standalone double-quote in formatted output.
|
|
It is not known whether this behaviour is exhibited by other formatters.
|
|
.It
|
|
troff suppresses a newline before
|
|
.Sq \(aq
|
|
macro output; in mandoc, it is an alias for the standard
|
|
.Sq \&.
|
|
control character.
|
|
.It
|
|
The
|
|
.Sq \eh
|
|
.Pq horizontal position ,
|
|
.Sq \ev
|
|
.Pq vertical position ,
|
|
.Sq \em
|
|
.Pq text colour ,
|
|
.Sq \eM
|
|
.Pq text filling colour ,
|
|
.Sq \ez
|
|
.Pq zero-length character ,
|
|
.Sq \ew
|
|
.Pq string length ,
|
|
.Sq \ek
|
|
.Pq horizontal position marker ,
|
|
.Sq \eo
|
|
.Pq text overstrike ,
|
|
and
|
|
.Sq \es
|
|
.Pq text size
|
|
escape sequences are all discarded in mandoc.
|
|
.It
|
|
The
|
|
.Sq \ef
|
|
scaling unit is accepted by mandoc, but rendered as the default unit.
|
|
.It
|
|
The
|
|
.Sx \&sp
|
|
macro does not accept negative values in mandoc.
|
|
In GNU troff, this would result in strange behaviour.
|
|
.It
|
|
In page header lines, GNU troff versions up to and including 1.21
|
|
only print
|
|
.Ar volume
|
|
names explicitly specified in the
|
|
.Sx \&TH
|
|
macro; mandoc and newer groff print the default volume name
|
|
corresponding to the
|
|
.Ar section
|
|
number when no
|
|
.Ar volume
|
|
is given, like in
|
|
.Xr mdoc 7 .
|
|
.El
|
|
.Pp
|
|
The
|
|
.Sx OP
|
|
macro is part of the extended
|
|
.Nm
|
|
macro set, and may not be portable to non-GNU troff implementations.
|
|
.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 .
|
|
It was later rewritten by James Clark as a macro package for groff.
|
|
Eric S. Raymond wrote the extended
|
|
.Nm
|
|
macros for groff in 2007.
|
|
The stand-alone implementation that is part of the
|
|
.Xr mandoc 1
|
|
utility written by Kristaps Dzonsons appeared in
|
|
.Ox 4.6 .
|
|
.Sh AUTHORS
|
|
This
|
|
.Nm
|
|
reference was written by
|
|
.An Kristaps Dzonsons ,
|
|
.Mt kristaps@bsd.lv .
|
|
.Sh CAVEATS
|
|
Do not use this language.
|
|
Use
|
|
.Xr mdoc 7 ,
|
|
instead.
|