-.\" $Id: mdoc.7,v 1.195 2011/08/02 01:07:26 schwarze Exp $
+.\" $Id: mdoc.7,v 1.210 2011/09/18 07:57:16 schwarze Exp $
.\"
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
.\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
.\" 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 2 2011 $
+.Dd $Mdocdate: September 18 2011 $
.Dt MDOC 7
.Os
.Sh NAME
manuals.
This reference document describes its syntax, structure, and
usage.
-The reference implementation is
+The reference implementation for
+.Nm
+formatting is
.Xr mandoc 1 ;
the
.Sx COMPATIBILITY
-section describes compatibility with other troff \-mdoc implementations.
+section describes compatibility with other implementations.
.Pp
An
.Nm
character
.Sq \&.
are parsed for macros.
-Text lines, those not beginning with the control character, are
+Lines not beginning with the control character are
interpreted within the scope of prior macros:
.Bd -literal -offset indent
\&.Sh Macro lines change control state.
.Nm
documents may contain only graphable 7-bit ASCII characters, the space
character, and, in certain circumstances, the tab character.
-.Pp
-If the first character of a text line is a space, that line is printed
-with a leading newline.
+The back-space character
+.Sq \e
+indicates the start of an escape sequence for
+.Sx Comments ,
+.Sx Predefined Strings ,
+and
+.Sx Special Characters .
.Ss Comments
-Text following a
-.Sq \e\*q ,
+Text following an escaped double-quote
+.Sq \e\(dq ,
whether in a macro or text line, is ignored to the end of
line.
-A macro line with only a control character and comment escape,
-.Sq \&.\e\*q ,
+A macro line beginning with a control character and comment escape
+.Sq \&.\e\(dq
is also ignored.
-Macro lines with only a control character and optional whitespace are
+Furthermore,
+macro lines with only a control character and optional trailing
+whitespace are
stripped from input.
+.Pp
+Examples:
+.Bd -literal -offset indent -compact
+\&.\e\(dq This is a comment line.
+\&.\e\(dq The next line is ignored:
+\&.
+\&.Em Emphasis \e\(dq This is also a comment.
+.Ed
.Ss Special Characters
-Special characters may occur in both macro and text lines.
+Special characters are used to encode special glyphs and are rendered
+differently across output media.
+They may occur in both macro and text lines.
Sequences begin with the escape character
.Sq \e
followed by either an open-parenthesis
for n-character sequences (terminated at a close-bracket
.Sq \&] ) ;
or a single one character sequence.
+.Pp
+Examples:
+.Bl -tag -width Ds -offset indent -compact
+.It Li \e(em
+Two-letter em dash escape.
+.It Li \ee
+One-letter backslash escape.
+.El
+.Pp
See
.Xr mandoc_char 7
for a complete list.
-Examples include
-.Sq \e(em
-.Pq em-dash
-and
-.Sq \ee
-.Pq back-slash .
.Ss Text Decoration
Terms may be text-decorated using the
.Sq \ef
-escape followed by an indicator: B (bold), I (italic), R (Roman), or P
-(revert to previous mode):
-.Pp
-.Dl \efBbold\efR \efIitalic\efP
-.Pp
-A numerical representation 3, 2, or 1 (bold, italic, and Roman,
+escape followed by an indicator: B (bold), I (italic), R (regular), or P
+(revert to previous mode).
+A numerical representation 3, 2, or 1 (bold, italic, and regular,
respectively) may be used instead.
If a macro opens a font scope after calling
.Sq \ef ,
.Sx \&Bf
scope.
.Pp
-Note this form is
+Examples:
+.Bl -tag -width Ds -offset indent -compact
+.It Li \efBbold\efR
+Write in bold, then switch to regular font mode.
+.It Li \efIitalic\efP
+Write in italic, then return to previous font mode.
+.El
+.Pp
+Text decoration is
.Em not
recommended for
.Nm ,
which encourages semantic annotation.
.Ss Predefined Strings
-Historically,
-troff
-also defined a set of package-specific
-.Dq predefined strings ,
-which, like
+Predefined strings, like
.Sx Special Characters ,
-mark special output characters and strings by way of input codes.
+mark special output glyphs.
Predefined strings are escaped with the slash-asterisk,
.Sq \e* :
single-character
.Sq \e*(XX ,
and N-character
.Sq \e*[N] .
-See
-.Xr mandoc_char 7
-for a complete list.
-Examples include
-.Sq \e*(Am
-.Pq ampersand
-and
-.Sq \e*(Ba
-.Pq vertical bar .
+.Pp
+Examples:
+.Bl -tag -width Ds -offset indent -compact
+.It Li \e*(Am
+Two-letter ampersand predefined string.
+.It Li \e*q
+One-letter double-quote predefined string.
+.El
+.Pp
+These strings are set using
+.Xr roff 7 ,
+although
+.Nm
+consists of several pre-set escapes listed in
+.Xr mandoc_char 7 .
.Ss Whitespace
Whitespace consists of the space character.
-In text lines, whitespace is preserved within a line; unescaped
-trailing spaces are stripped from input (unless in a literal context).
-Blank text lines, which may include whitespace, are only permitted
-within literal contexts.
+In text lines, whitespace is preserved within a line.
+In macro lines, whitespace delimits arguments and is discarded.
.Pp
-In general, trailing whitespace on input lines is discouraged
-for reasons of clarity and portability.
+Unescaped trailing spaces are stripped from text line input unless in a
+literal context.
+In general, trailing whitespace on any input line is discouraged for
+reasons of portability.
In the rare case that a blank character is needed at the end of an
input line, it may be forced by
.Sq \e\ \e& .
.Pp
-In macro lines, whitespace delimits arguments and is discarded.
-.Ss Quotation
-Macro arguments may be quoted with double-quotes; in this case,
-whitespace within the quotes is retained as part of the argument.
-For example,
-.Pp
-.D1 Pf \. \&Fn strlen "\(dqconst char *s\(dq"
+In general, space characters can be rendered as literal
+characters by using non-breaking space escapes or
+.Sx Quotation .
.Pp
-renders as
-.Sq Fn strlen "const char *s" ,
-while
-.Pp
-.D1 Pf \. \&Fn strlen "const char *s"
-.Pp
-would produce
-.Sq Fn strlen const char *s .
+Blank text lines, which may include whitespace, are only permitted
+within literal contexts.
+If the first character of a text line is a space, that line is printed
+with a leading newline.
+.Ss Quotation
+Macro arguments may be quoted with double-quotes to so that the
+enclosed text is one literal term.
+Quoted text, even if whitespace or if it would cause a macro invocation
+when unquoted, is considered literal text.
.Pp
A quoted argument begins with a double-quote preceded by whitespace.
The next double-quote not pairwise adjacent to another double-quote
terminates the literal, regardless of surrounding whitespace.
.Pp
-In unquoted arguments, space characters can alternatively be included
-by preceding them with a backslash
-.Pq Sq \e\~ ,
-but quoting is usually better for clarity.
-.Pp
-Note that any quoted text, even if it would cause a macro invocation
-when unquoted, is considered literal text.
-Thus, the following produces
-.Sq Op "Fl a" :
-.Bd -literal -offset indent
-\&.Op "Fl a"
-.Ed
-.Pp
-In text lines, quotes are regarded as opaque text.
+Examples:
+.Bl -tag -width Ds -offset indent -compact
+.It Li .Fn strlen \(dqconst char *s\(dq
+Group arguments
+.Qq const char *s
+into one function argument.
+If unspecified,
+.Qq const ,
+.Qq char ,
+and
+.Qq *s
+would be considered separate arguments.
+.Pq See Sx \&Fn .
+.It Li .Op \(dqFl a\(dq
+Consider
+.Qq \&Fl a
+as literal text instead of a flag macro.
+.Pq Aee Sx \&Op , \&Fl .
+.El
.Ss Scaling Widths
-Many macros support scaled widths for their arguments, such as
-stipulating a two-inch list indentation with the following:
-.Bd -literal -offset indent
-\&.Bl -tag -width 2i
-.Ed
-.Pp
-The syntax for scaled widths is
+Many macros support scaled widths for their arguments.
+The syntax for a scaled width is
.Sq Li [+-]?[0-9]*.[0-9]*[:unit:] ,
where a decimal must be preceded or proceeded by at least one digit.
Negative numbers, while accepted, are truncated to zero.
+.Pp
The following scaling units are accepted:
.Pp
.Bl -tag -width Ds -offset indent -compact
is necessarily non-portable across output media.
See
.Sx COMPATIBILITY .
+.Pp
+Examples:
+.Bl -tag -width Ds -offset indent -compact
+.It Li \&.Bl -tag -width 2i
+two-inch tagged list indentation
+.Pq see Sx \&Bl
+.It Li \&.sp 2v
+two vertical spaces
+.Pq see Sx \&sp
+.El
.Ss Sentence Spacing
-When composing a manual, make sure that sentences end at the end of
-a line.
-By doing so, front-ends will be able to apply the proper amount of
+Sentences should terminate at the end of an input line.
+By doing this, a formatter will be able to apply the proper amount of
spacing after the end of sentence (unescaped) period, exclamation mark,
or question mark followed by zero or more non-sentence closing
delimiters
.Pp
The proper spacing is also intelligently preserved if a sentence ends at
the boundary of a macro line.
-For example:
.Pp
-.Dl \&.Xr mandoc 1 \&.
-.Dl \&.Fl T \&Ns \&Cm ascii \&.
+Examples:
+.Bd -literal -offset indent -compact
+Do not end sentences mid-line like this. Instead,
+end a sentence like this.
+A macro would end like this:
+\&.Xr mandoc 1 \&.
+.Ed
.Sh MANUAL STRUCTURE
A well-formed
.Nm
\&.Sh NAME
\&.Nm progname
\&.Nd one line about what it does
-\&.\e\*q .Sh LIBRARY
-\&.\e\*q For sections 2, 3, & 9 only.
-\&.\e\*q Not used in OpenBSD.
+\&.\e\(dq .Sh LIBRARY
+\&.\e\(dq For sections 2, 3, & 9 only.
+\&.\e\(dq Not used in OpenBSD.
\&.Sh SYNOPSIS
\&.Nm progname
\&.Op Fl options
The
\&.Nm
utility processes files ...
-\&.\e\*q .Sh IMPLEMENTATION NOTES
-\&.\e\*q Not used in OpenBSD.
-\&.\e\*q .Sh RETURN VALUES
-\&.\e\*q For sections 2, 3, & 9 only.
-\&.\e\*q .Sh ENVIRONMENT
-\&.\e\*q For sections 1, 6, 7, & 8 only.
-\&.\e\*q .Sh FILES
-\&.\e\*q .Sh EXIT STATUS
-\&.\e\*q For sections 1, 6, & 8 only.
-\&.\e\*q .Sh EXAMPLES
-\&.\e\*q .Sh DIAGNOSTICS
-\&.\e\*q For sections 1, 4, 6, 7, & 8 only.
-\&.\e\*q .Sh ERRORS
-\&.\e\*q For sections 2, 3, & 9 only.
-\&.\e\*q .Sh SEE ALSO
-\&.\e\*q .Xr foobar 1
-\&.\e\*q .Sh STANDARDS
-\&.\e\*q .Sh HISTORY
-\&.\e\*q .Sh AUTHORS
-\&.\e\*q .Sh CAVEATS
-\&.\e\*q .Sh BUGS
-\&.\e\*q .Sh SECURITY CONSIDERATIONS
-\&.\e\*q Not used in OpenBSD.
+\&.\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 .Xr foobar 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 an
.Pp
And for the third, configurations (section 4):
.Bd -literal -offset indent
-\&.Cd \*qit* at isa? port 0x2e\*q
-\&.Cd \*qit* at isa? port 0x4e\*q
+\&.Cd \(dqit* at isa? port 0x2e\(dq
+\&.Cd \(dqit* at isa? port 0x4e\(dq
.Ed
.Pp
Manuals not in these sections generally don't need a
.Ed
.Pp
Manuals not documenting a command won't include the above fragment.
+.Pp
+Since the
+.Em DESCRIPTION
+section usually contains most of the text of a manual, longer manuals
+often use the
+.Sx \&Ss
+macro to form subsections.
+In very long manuals, the
+.Em DESCRIPTION
+may be split into multiple sections, each started by an
+.Sx \&Sh
+macro followed by a non-standard section name, and each having
+several subsections, like in the present
+.Nm
+manual.
.It Em IMPLEMENTATION NOTES
Implementation-specific notes should be kept here.
This is useful when implementing standard functions that may have side
Cross-references should conventionally be ordered first by section, then
alphabetically.
.Pp
+References to other documentation concerning the topic of the manual page,
+for example authoritative books or journal articles, may also be
+provided in this section.
+.Pp
See
+.Sx \&Rs
+and
.Sx \&Xr .
.It Em STANDARDS
References any standards implemented or used.
See
.Sx \&St .
.It Em HISTORY
-A brief history of the subject, including where support first appeared.
+A brief history of the subject, including where it was first implemented,
+and when it was ported to or reimplemented for the operating system at hand.
.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.
\(lBbody...\(rB
\&.Yc
.Ed
-.Pp
-.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsedX" "closed by XXX"
+.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXX" -offset indent
.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
.It Sx \&Bd Ta \&No Ta \&No Ta closed by Sx \&Ed
.It Sx \&Bf Ta \&No Ta \&No Ta closed by Sx \&Ef
\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
\(lBbody...\(rB
.Ed
-.Pp
-.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX"
+.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" -offset indent
.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
-.It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El
-.It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh
-.It Sx \&Nm Ta \&No Ta Yes Ta closed by Sx \&Nm , Sx \&Sh , Sx \&Ss
-.It Sx \&Sh Ta \&No Ta \&No Ta closed by Sx \&Sh
-.It Sx \&Ss Ta \&No Ta \&No Ta closed by Sx \&Sh , Sx \&Ss
+.It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El
+.It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh
+.It Sx \&Nm Ta \&No Ta Yes Ta closed by Sx \&Nm , Sx \&Sh , Sx \&Ss
+.It Sx \&Sh Ta \&No Ta Yes Ta closed by Sx \&Sh
+.It Sx \&Ss Ta \&No Ta Yes Ta closed by Sx \&Sh , Sx \&Ss
.El
.Pp
Note that the
\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
\(lBbody...\(rB \&Yc \(lBtail...\(rB
.Ed
-.Pp
-.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -compact -offset indent
+.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent
.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
.It Sx \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao
.It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac
.Bd -literal -offset indent
\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
.Ed
-.Pp
-.Bl -column "MacroX" "CallableX" "ParsedX" -compact -offset indent
+.Bl -column "MacroX" "CallableX" "ParsedX" -offset indent
.It Em Macro Ta Em Callable Ta Em Parsed
.It Sx \&Aq Ta Yes Ta Yes
.It Sx \&Bq Ta Yes Ta Yes
lists.
It delimits blocks representing table cells;
these blocks have bodies, but no heads.
-.Pp
-.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -compact -offset indent
+.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent
.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
.It Sx \&Ta Ta Yes Ta Yes Ta closed by Sx \&Ta , Sx \&It
.El
\&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
.Ed
-.Pp
-.Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -compact -offset indent
+.Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -offset indent
.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments
.It Sx \&%A Ta \&No Ta \&No Ta >0
.It Sx \&%B Ta \&No Ta \&No Ta >0
.Sq \&|
character.
Using this predefined string is not recommended in new manuals.
+.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 Document preamble and NAME section macros
+.Bl -column "Brq, Bro, Brc" description
+.It Sx \&Dd Ta document date: Cm $Mdocdate: September 18 2011 $ | Ar month day , year
+.It Sx \&Dt Ta document title: Ar TITLE section Op Ar volume | arch
+.It Sx \&Os Ta operating system version: Op Ar system Op Ar version
+.It Sx \&Nm Ta document name (one argument)
+.It Sx \&Nd Ta document description (one line)
+.El
+.Ss Sections and cross references
+.Bl -column "Brq, Bro, Brc" description
+.It Sx \&Sh Ta section header (one line)
+.It Sx \&Ss Ta subsection header (one line)
+.It Sx \&Sx Ta internal cross reference to a section or subsection
+.It Sx \&Xr Ta cross reference to another manual page: Ar name section
+.It Sx \&Pp , \&Lp Ta start a text paragraph (no arguments)
+.El
+.Ss Displays and lists
+.Bl -column "Brq, Bro, Brc" description
+.It Sx \&Bd , \&Ed Ta display block:
+.Fl Ar type
+.Op Fl offset Ar width
+.Op Fl compact
+.It Sx \&D1 Ta indented display (one line)
+.It Sx \&Dl Ta indented literal display (one line)
+.It Sx \&Bl , \&El Ta list block:
+.Fl Ar type
+.Op Fl width Ar val
+.Op Fl offset Ar val
+.Op Fl compact
+.It Sx \&It Ta list item (syntax depends on Fl Ar type )
+.It Sx \&Ta Ta table cell separator in Sx Bl Fl column No lists
+.It Sx \&Rs , \&%* , \&Re Ta bibliographic block (references)
+.El
+.Ss Spacing control
+.Bl -column "Brq, Bro, Brc" description
+.It Sx \&Pf Ta prefix, no following horizontal space (one argument)
+.It Sx \&Ns Ta roman font, no preceding horizontal space (no arguments)
+.It Sx \&Ap Ta apostrophe without surrounding whitespace (no arguments)
+.It Sx \&Sm Ta switch horizontal spacing mode: Cm on | off
+.It Sx \&Bk , \&Ek Ta keep block: Fl words
+.It Sx \&br Ta force output line break in text mode (no arguments)
+.It Sx \&sp Ta force vertical space: Op Ar height
+.El
+.Ss Semantic markup for command line utilities:
+.Bl -column "Brq, Bro, Brc" description
+.It Sx \&Nm Ta start a SYNOPSIS block with the name of a utility
+.It Sx \&Fl Ta command line options (flags) (>=0 arguments)
+.It Sx \&Cm Ta command modifier (>0 arguments)
+.It Sx \&Ar Ta command arguments (>=0 arguments)
+.It Sx \&Op , \&Oo , \&Oc Ta optional syntax elements (enclosure)
+.It Sx \&Ic Ta internal or interactive command (>0 arguments)
+.It Sx \&Ev Ta environmental variable (>0 arguments)
+.It Sx \&Pa Ta file system path (>=0 arguments)
+.El
+.Ss Semantic markup for function libraries:
+.Bl -column "Brq, Bro, Brc" description
+.It Sx \&Lb Ta function library (one argument)
+.It Sx \&In Ta include file (one argument)
+.It Sx \&Ft Ta function type (>0 arguments)
+.It Sx \&Fo , \&Fc Ta function block: Ar funcname
+.It Sx \&Fn Ta function name:
+.Op Ar functype
+.Ar funcname
+.Oo
+.Op Ar argtype
+.Ar argname
+.Oc
+.It Sx \&Fa Ta function argument (>0 arguments)
+.It Sx \&Vt Ta variable type (>0 arguments)
+.It Sx \&Va Ta variable name (>0 arguments)
+.It Sx \&Dv Ta defined variable or preprocessor constant (>0 arguments)
+.It Sx \&Er Ta error constant (>0 arguments)
+.It Sx \&Ev Ta environmental variable (>0 arguments)
+.El
+.Ss Various semantic markup:
+.Bl -column "Brq, Bro, Brc" description
+.It Sx \&An Ta author name (>0 arguments)
+.It Sx \&Lk Ta hyperlink: Ar uri Op Ar name
+.It Sx \&Mt Ta Do mailto Dc hyperlink: Ar address
+.It Sx \&Cd Ta kernel configuration declaration (>0 arguments)
+.It Sx \&Ad Ta memory address (>0 arguments)
+.It Sx \&Ms Ta mathematical symbol (>0 arguments)
+.It Sx \&Tn Ta tradename (>0 arguments)
+.El
+.Ss Physical markup
+.Bl -column "Brq, Bro, Brc" description
+.It Sx \&Em Ta italic font or underline (emphasis) (>0 arguments)
+.It Sx \&Sy Ta boldface font (symbolic) (>0 arguments)
+.It Sx \&Li Ta typewriter font (literal) (>0 arguments)
+.It Sx \&No Ta return to roman font (normal) (no arguments)
+.It Sx \&Bf , \&Ef Ta font block:
+.Op Fl Ar type | Cm \&Em | \&Li | \&Sy
+.El
+.Ss Physical enclosures
+.Bl -column "Brq, Bro, Brc" description
+.It Sx \&Dq , \&Do , \&Dc Ta enclose in typographic double quotes: Dq text
+.It Sx \&Qq , \&Qo , \&Qc Ta enclose in typewriter double quotes: Qq text
+.It Sx \&Sq , \&So , \&Sc Ta enclose in single quotes: Sq text
+.It Sx \&Ql Ta single-quoted literal text: Ql text
+.It Sx \&Pq , \&Po , \&Pc Ta enclose in parentheses: Pq text
+.It Sx \&Bq , \&Bo , \&Bc Ta enclose in square brackets: Bq text
+.It Sx \&Brq , \&Bro , \&Brc Ta enclose in curly braces: Brq text
+.It Sx \&Aq , \&Ao , \&Ac Ta enclose in angle brackets: Aq text
+.It Sx \&Eo , \&Ec Ta generic enclosure
+.El
+.Ss Text production
+.Bl -column "Brq, Bro, Brc" description
+.It Sx \&Ex Fl std Ta standard command exit values: Op Ar utility ...
+.It Sx \&Rv Fl std Ta standard function return values: Op Ar function ...
+.It Sx \&St Ta reference to a standards document (one argument)
+.It Sx \&Ux Ta Ux
+.It Sx \&At Ta At
+.It Sx \&Bx Ta Bx
+.It Sx \&Bsx Ta Bsx
+.It Sx \&Nx Ta Nx
+.It Sx \&Fx Ta Fx
+.It Sx \&Ox Ta Ox
+.It Sx \&Dx Ta Dx
+.El
.Sh REFERENCE
This section is a canonical reference of all macros, arranged
alphabetically.
.Dl \&.Ad 0x00000000
.Ss \&An
Author name.
+Can be used both for the authors of the program, function, or driver
+documented in the manual, or for the authors of the manual itself.
Requires either the name of an author or one of the following arguments:
.Pp
.Bl -tag -width "-nosplitX" -offset indent -compact
is used as a default.
.Pp
Examples:
-.Dl \&.Fl o \&Ns \&Ar file1
-.Dl \&.Ar
-.Dl \&.Ar arg1 , arg2 .
+.Dl ".Fl o Ar file"
+.Dl ".Ar"
+.Dl ".Ar arg1 , arg2 ."
+.Pp
+The arguments to the
+.Sx \&Ar
+macro are names and placeholders for command arguments;
+for fixed strings to be passed verbatim as arguments, use
+.Sx \&Fl
+or
+.Sx \&Cm .
.Ss \&At
Formats an AT&T version.
Accepts one optional argument:
must be one of the following:
.Bl -tag -width 13n -offset indent
.It Fl centered
-Centre-justify each line.
+Produce one output line from each input line, and centre-justify each line.
Using this display type is not recommended; many
.Nm
implementations render it poorly.
.It Fl filled
-Left- and right-justify the block.
+Change the positions of line breaks to fill each line, and left- and
+right-justify the resulting block.
.It Fl literal
-Do not justify the block at all.
+Produce one output line from each input line,
+and do not justify the block at all.
Preserve white space as it appears in the input.
+Always use a constant-width font.
+Use this for displaying source code.
.It Fl ragged
-Only left-justify the block.
+Change the positions of line breaks to fill each line, and left-justify
+the resulting block.
.It Fl unfilled
-An alias for
-.Fl literal .
+The same as
+.Fl literal ,
+but using the same font as for normal text, which is a variable width font
+if supported by the output device.
.El
.Pp
The
.It
One of the pre-defined strings
.Cm indent ,
-the width of standard indentation;
+the width of a standard indentation (six constant width characters);
.Cm indent-two ,
twice
.Cm indent ;
Like
.Fl inset ,
except that item heads are not parsed for macro invocations.
-.\" but with additional formatting to the head.
+Most often used in the
+.Em DIAGNOSTICS
+section with error constants in the item heads.
.It Fl enum
A numbered list.
+No item heads can be specified.
Formatted like
.Fl bullet ,
except that cardinal numbers are used in place of bullets,
Otherwise, the body starts on the output line following the head.
.El
.Pp
+Lists may be nested within lists and displays.
+Nesting of
+.Fl column
+and
+.Fl enum
+lists may not be portable.
+.Pp
See also
.Sx \&El
and
.Sx \&Ux .
.Ss \&Bt
Prints
-.Dq is currently in beta test .
+.Dq is currently in beta test.
.Ss \&Bx
Format the BSD version provided as an argument, or a default value if no
argument is provided.
.Pp
Examples:
+.Dl \&.Bx 4.3 Tahoe
.Dl \&.Bx 4.4
.Dl \&.Bx
.Pp
Kernel configuration declaration.
This denotes strings accepted by
.Xr config 8 .
+It is most often used in section 4 manual pages.
.Pp
Examples:
.Dl \&.Cd device le0 at scode?
This practise is discouraged.
.Ss \&Cm
Command modifiers.
-Useful when specifying configuration options or keys.
+Typically used for fixed strings passed as arguments, unless
+.Sx \&Fl
+is more appropriate.
+Also useful when specifying configuration options or keys.
.Pp
Examples:
-.Dl \&.Cm ControlPath
-.Dl \&.Cm ControlMaster
-.Pp
-See also
-.Sx \&Fl .
+.Dl ".Nm mt Fl f Ar device Cm rewind"
+.Dl ".Nm ps Fl o Cm pid , Ns Cm command"
+.Dl ".Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2"
+.Dl ".Cm IdentityFile Pa ~/.ssh/id_rsa"
+.Dl ".Cm LogLevel Dv DEBUG"
.Ss \&D1
One-line indented display.
This is formatted by the default rules and is useful for simple indented
and
.Sx \&It .
.Ss \&Em
-Denotes text that should be emphasised.
+Denotes text that should be
+.Em emphasised .
Note that this is a presentation term and should not be used for
stylistically decorating technical terms.
+Depending on the output device, this is usually represented
+using an italic font or underlined characters.
.Pp
Examples:
.Dl \&.Em Warnings!
.Pp
See also
.Sx \&Bf ,
-.Sx \&Sy ,
+.Sx \&Li ,
+.Sx \&No ,
and
-.Sx \&Li .
+.Sx \&Sy .
.Ss \&En
This macro is obsolete and not implemented in
.Xr mandoc 1 .
Error constants for definitions of the
.Va errno
libc global variable.
+This is most often used in section 2 and 3 manual pages.
.Pp
Examples:
.Dl \&.Er EPERM
.Ss \&Ex
Insert a standard sentence regarding command exit values of 0 on success
and >0 on failure.
+This is most often used in section 1, 6, and 8 manual pages.
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&Ex Fl std Op Ar utility ...
and
.Sx \&In .
.Ss \&Fl
-Command-line flag.
+Command-line flag or option.
Used when listing arguments to command-line utilities.
Prints a fixed-width hyphen
.Sq \-
output.
.Pp
Examples:
-.Dl \&.Fl a b c
-.Dl \&.Fl \&Pf a b
-.Dl \&.Fl
-.Dl \&.Op \&Fl o \&Ns \&Ar file
+.Dl ".Fl R Op Fl H | L | P"
+.Dl ".Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux"
+.Dl ".Fl type Cm d Fl name Pa CVS"
+.Dl ".Fl Ar signal_number"
+.Dl ".Fl o Fl"
.Pp
See also
.Sx \&Cm .
Function arguments are surrounded in parenthesis and
are delimited by commas.
If no arguments are specified, blank parenthesis are output.
+In the
+.Em SYNOPSIS
+section, this macro starts a new output line,
+and a blank line is automatically inserted between function definitions.
.Pp
Examples:
-.Dl \&.Fn \*qint funcname\*q \*qint arg0\*q \*qint arg1\*q
-.Dl \&.Fn funcname \*qint arg0\*q
+.Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq
+.Dl \&.Fn funcname \(dqint arg0\(dq
.Dl \&.Fn funcname arg0
+.Pp
.Bd -literal -offset indent -compact
\&.Ft functype
\&.Fn funcname
.Sx \&Xr
instead.
See also
-.Sx MANUAL STRUCTURE
+.Sx MANUAL STRUCTURE ,
+.Sx \&Fo ,
and
.Sx \&Ft .
.Ss \&Fo
A
.Sx \&Fo
scope is closed by
+.Sx \&Fc .
.Pp
See also
.Sx MANUAL STRUCTURE ,
and
.Sx \&Ft .
.Ss \&Fr
-This macro is obsolete and not implemented.
+This macro is obsolete and not implemented in
+.Xr mandoc 1 .
+.Pp
+It was used to show function return values.
+The syntax was:
+.Pp
+.Dl Pf . Sx \&Fr Ar value
.Ss \&Ft
A function type.
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&Ft Ar functype
.Pp
+In the
+.Em SYNOPSIS
+section, a new output line is started after this macro.
+.Pp
Examples:
.Dl \&.Ft int
.Bd -literal -offset indent -compact
and
.Sx \&Ux .
.Ss \&Hf
-This macro is obsolete and not implemented.
+This macro is not implemented in
+.Xr mandoc 1 .
+.Pp
+It was used to include the contents of a (header) file literally.
+The syntax was:
+.Pp
+.Dl Pf . Sx \&Hf Ar filename
.Ss \&Ic
Designate an internal or interactive command.
This is similar to
but used for instructions rather than values.
.Pp
Examples:
+.Dl \&.Ic :wq
.Dl \&.Ic hash
.Dl \&.Ic alias
.Pp
An
.Dq include
file.
-In the
+When invoked as the first macro on an input line in the
.Em SYNOPSIS
-section (only if invoked as the line macro), the first argument is
-preceded by
+section, the argument is displayed in angle brackets
+and preceded by
.Dq #include ,
-the arguments is enclosed in angle brackets.
+and a blank line is inserted in front if there is a preceding
+function declaration.
+This is most often used in section 2, 3, and 9 manual pages.
.Pp
Examples:
-.Dl \&.In sys/types
+.Dl \&.In sys/types.h
.Pp
See also
.Sx MANUAL STRUCTURE .
.Sx \&Ta
macro can be used to delimit cells, and
.Sx \&Ta
-is only recognized as a macro when called by other macros,
+is only recognised as a macro when called by other macros,
not as the first macro on a line.
.Pp
Note that quoted strings may span tab-delimited cells on an
.Dl \&.Lb libz
.Dl \&.Lb mdoc
.Ss \&Li
-Denotes text that should be in a literal font mode.
+Denotes text that should be in a
+.Li literal
+font mode.
Note that this is a presentation term and should not be used for
stylistically decorating technical terms.
.Pp
+On terminal output devices, this is often indistinguishable from
+normal text.
+.Pp
See also
.Sx \&Bf ,
-.Sx \&Sy ,
+.Sx \&Em ,
+.Sx \&No ,
and
-.Sx \&Em .
+.Sx \&Sy .
.Ss \&Lk
Format a hyperlink.
Its syntax is as follows:
.D1 Pf \. Sx \&Lk Ar uri Op Ar name
.Pp
Examples:
-.Dl \&.Lk http://bsd.lv \*qThe BSD.lv Project\*q
+.Dl \&.Lk http://bsd.lv \(dqThe BSD.lv Project\(dq
.Dl \&.Lk http://bsd.lv
.Pp
See also
macro.
.Pp
Examples:
-.Dl \&.Sx \&Nd mdoc language reference
-.Dl \&.Sx \&Nd format and display UNIX manuals
+.Dl Pf . Sx \&Nd mdoc language reference
+.Dl Pf . Sx \&Nd format and display UNIX manuals
.Pp
The
.Sx \&Nd
.Sx \&Nm
to mark up the name of the manual page.
.Ss \&No
-A
-.Dq noop
-macro used to terminate prior macro contexts.
+Normal text.
+Closes the scope of any preceding in-line macro.
+When used after physical formatting macros like
+.Sx \&Em
+or
+.Sx \&Sy ,
+switches back to the standard font face and weight.
+Can also be used to embed plain text strings in macro lines
+using semantic annotation macros.
.Pp
Examples:
-.Dl \&.Sx \&Fl ab \&No cd \&Fl ef
+.Dl ".Em italic , Sy bold , No and roman"
+.Pp
+.Bd -literal -offset indent -compact
+\&.Sm off
+\&.Cm :C No / Ar pattern No / Ar replacement No /
+\&.Sm on
+.Ed
+.Pp
+See also
+.Sx \&Em ,
+.Sx \&Li ,
+and
+.Sx \&Sy .
.Ss \&Ns
-Suppress a space.
-Following invocation, text is interpreted as free-form text until a
-macro is encountered.
+Suppress a space between the output of the preceding macro
+and the following text or macro.
+Following invocation, input is interpreted as normal text
+just like after an
+.Sx \&No
+macro.
.Pp
This has no effect when invoked at the start of a macro line.
.Pp
Examples:
-.Dl \&.Fl o \&Ns \&Ar output
+.Dl ".Ar name Ns = Ns Ar value"
+.Dl ".Cm :M Ns Ar pattern"
+.Dl ".Fl o Ns Ar output"
.Pp
See also
.Sx \&No
\&.Oc
.Ed
.Ss \&Op
-Command-line option.
-Used when listing options to command-line utilities.
+Optional part of a command line.
Prints the argument(s) in brackets.
+This is most often used in the
+.Em SYNOPSIS
+section of section 1 and 8 manual pages.
.Pp
Examples:
.Dl \&.Op \&Fl a \&Ar b
and
.Sx \&Dt .
.Ss \&Ot
-Unknown usage.
+This macro is obsolete and not implemented in
+.Xr mandoc 1 .
.Pp
-.Em Remarks :
-this macro has been deprecated.
+Historical
+.Xr mdoc 7
+packages described it as
+.Dq "old function type (FORTRAN)" .
.Ss \&Ox
Format the
.Ox
and
.Sx \&Ux .
.Ss \&Pa
-A file-system path.
-If an argument is not provided, the string
-.Dq \(ti
+An absolute or relative file system path, or a file or directory name.
+If an argument is not provided, the character
+.Sq \(ti
is used as a default.
.Pp
Examples:
Close parenthesised context opened by
.Sx \&Po .
.Ss \&Pf
-Removes the space
+Removes the space between its argument
.Pq Dq prefix
-between its arguments.
+and the following macro.
Its syntax is as follows:
.Pp
-.D1 Pf \. \&Pf Ar prefix suffix
+.D1 .Pf Ar prefix macro arguments ...
.Pp
-The
-.Ar suffix
-argument may be a macro.
+This is equivalent to:
+.Pp
+.D1 .No Ar prefix No \&Ns Ar macro arguments ...
.Pp
Examples:
-.Dl \&.Pf \e. \&Sx \&Pf \&Ar prefix suffix
+.Dl ".Pf $ Ar variable_name"
+.Dl ".Pf 0x Ar hex_digits"
+.Pp
+See also
+.Sx \&Ns
+and
+.Sx \&Sm .
.Ss \&Po
Multi-line version of
.Sx \&Pq .
Break a paragraph.
This will assert vertical space between prior and subsequent macros
and/or text.
+.Pp
+Paragraph breaks are not needed before or after
+.Sx \&Sh
+or
+.Sx \&Ss
+macros or before displays
+.Pq Sx \&Bd
+or lists
+.Pq Sx \&Bl
+unless the
+.Fl compact
+flag is given.
.Ss \&Pq
Parenthesised enclosure.
.Pp
.Sx \&Qq .
.Ss \&Qq
Encloses its arguments in
-.Dq typewriter
+.Qq typewriter
double-quotes.
Consider using
.Sx \&Dq .
.Pp
Section names should be unique so that they may be keyed by
.Sx \&Sx .
+Although this macro is parsed, it should not consist of child node or it
+may not be linked with
+.Sx \&Sx .
.Pp
See also
.Sx \&Pp ,
.Sx \&Sq .
.Ss \&Sq
Encloses its arguments in
-.Dq typewriter
+.Sq typewriter
single-quotes.
.Pp
See also
and
.Sx \&So .
.Ss \&Ss
-Begin a new sub-section.
+Begin a new subsection.
Unlike with
.Sx \&Sh ,
-there's no convention for sub-sections.
-Conventional sections, as described in
-.Sx MANUAL STRUCTURE ,
-rarely have sub-sections.
+there is no convention for the naming of subsections.
+Except
+.Em DESCRIPTION ,
+the conventional sections described in
+.Sx MANUAL STRUCTURE
+rarely have subsections.
.Pp
Sub-section names should be unique so that they may be keyed by
.Sx \&Sx .
+Although this macro is parsed, it should not consist of child node or it
+may not be linked with
+.Sx \&Sx .
.Pp
See also
.Sx \&Pp ,
.St -ieee754
.It \-iso8802-3
.St -iso8802-3
+.It \-iso8601
+.St -iso8601
.It \-ieee1275-94
.St -ieee1275-94
.It \-xpg3
.St -xpg4
.It \-xpg4.2
.St -xpg4.2
+.It \-xpg4.3
.St -xpg4.3
.It \-xbd5
.St -xbd5
.St -svid4
.El
.Ss \&Sx
-Reference a section or sub-section.
-The referenced section or sub-section name must be identical to the
+Reference a section or subsection in the same manual page.
+The referenced section or subsection name must be identical to the
enclosed argument, including whitespace.
.Pp
Examples:
.Pp
See also
.Sx \&Bf ,
+.Sx \&Em ,
.Sx \&Li ,
and
-.Sx \&Em .
+.Sx \&No .
.Ss \&Ta
Table cell separator in
.Sx \&Bl Fl column
.Ss \&Tn
Format a tradename.
.Pp
+Since this macro is often implemented to use a small caps font,
+it has historically been used for acronyms (like ASCII) as well.
+Such usage is not recommended because it would use the same macro
+sometimes for semantical annotation, sometimes for physical formatting.
+.Pp
Examples:
.Dl \&.Tn IBM
.Ss \&Ud
Prints out
-.Dq currently under development .
+.Dq currently under development.
.Ss \&Ux
Format the UNIX name.
Accepts no argument.
section, in which case a variable name is also specified.
Note that it accepts
.Sx Block partial-implicit
-syntax when invoked as the first macro in the
+syntax when invoked as the first macro on an input line in the
.Em SYNOPSIS
section, else it accepts ordinary
.Sx In-line
syntax.
+In the former case, this macro starts a new output line,
+and a blank line is inserted in front if there is a preceding
+function definition or include directive.
.Pp
Note that this should not be confused with
.Sx \&Ft ,
and the arguments.
.It
.Sx \&Bl Fl column
-does not recognize trailing punctuation characters when they immediately
+does not recognise trailing punctuation characters when they immediately
precede tabulator characters, but treats them as normal text and
outputs a space before them.
.It
.Fl offset Ar center
and
.Fl offset Ar right .
-Groff does not implement centered and flush-right rendering either,
+Groff does not implement centred and flush-right rendering either,
but produces large indentations.
.It
The
.Xr mandoc 1 ,
.Xr eqn 7 ,
.Xr man 7 ,
-.Xr mandoc_char 7
+.Xr mandoc_char 7 ,
.Xr roff 7 ,
.Xr tbl 7
.Sh HISTORY
The
.Nm
reference was written by
-.An Kristaps Dzonsons Aq kristaps@bsd.lv .
+.An Kristaps Dzonsons ,
+.Mt kristaps@bsd.lv .
git.ckatri.com / mandoc.git / blobdiff