-.\" $Id: mdoc.7,v 1.96 2010/05/08 08:36:44 kristaps Exp $
+.\" $Id: mdoc.7,v 1.127 2010/06/27 13:30:51 schwarze Exp $
.\"
.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
.\"
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: May 8 2010 $
+.Dd $Mdocdate: June 27 2010 $
.Dt MDOC 7
.Os
.Sh NAME
.Pp
An
.Nm
-document follows simple rules: lines beginning with the control
+document follows simple rules: lines beginning with the control
character
.Sq \.
are parsed for macros. Other lines are interpreted within the scope of
whether in a macro or free-form text line, is ignored to the end of
line. A macro line with only a control character and comment escape,
.Sq \&.\e" ,
-is also ignored. Macro lines with only a control charater and optionally
+is also ignored. Macro lines with only a control character and optionally
whitespace are stripped from input.
.Ss Reserved Characters
Within a macro line, the following characters are reserved:
.Sq \&[
for n-character sequences (terminated at a close-bracket
.Sq \&] ) ;
-or a single one-character sequence. See
+or a single one-character sequence.
+See
.Xr mandoc_char 7
-for a complete list. Examples include
+for a complete list.
+Examples include
.Sq \e(em
.Pq em-dash
and
.D1 \efBbold\efR \efIitalic\efP
.Pp
A numerical representation 3, 2, or 1 (bold, italic, and Roman,
-respectively) may be used instead. A text decoration is valid within
-the current font scope only: if a macro opens a font scope alongside
+respectively) may be used instead.
+A text decoration is valid within
+the current font scope only: if a macro opens a font scope alongside
its own scope, such as
.Sx \&Bf
.Cm \&Sy ,
in-scope invocations of
.Sq \ef
-are only valid within the font scope of the macro. If
+are only valid within the font scope of the macro.
+If
.Sq \ef
is specified outside of any font scope, such as in unenclosed, free-form
text, it will affect the remainder of the document.
.Dq predefined strings ,
which, like
.Sx Special Characters ,
-demark special output characters and strings by way of input codes.
+mark special output characters and strings by way of input codes.
Predefined strings are escaped with the slash-asterisk,
.Sq \e* :
single-character
.Sq \e*[N] .
See
.Xr mandoc_char 7
-for a complete list. Examples include
+for a complete list.
+Examples include
.Sq \e*(Am
.Pq ampersand
and
.Sq \e*(Ba
.Pq vertical bar .
.Ss Whitespace
+Whitespace consists of the space character.
In free-form lines, whitespace is preserved within a line; un-escaped
trailing spaces are stripped from input (unless in a literal context).
-Blank free-form lines, which may include spaces, are only permitted
+Blank free-form lines, which may include whitespace, are only permitted
within literal contexts.
.Pp
-In macro lines, whitespace delimits arguments and is discarded. If
-arguments are quoted, whitespace within the quotes is retained.
+In macro lines, whitespace delimits arguments and is discarded.
+If arguments are quoted, whitespace within the quotes is retained.
.Ss Quotation
Macro arguments may be quoted with a double-quote to group
-space-delimited terms or to retain blocks of whitespace. A quoted
-argument begins with a double-quote preceded by whitespace. The next
-double-quote not pair-wise adjacent to another double-quote terminates
-the literal, regardless of surrounding whitespace.
+space-delimited terms or to retain blocks of whitespace.
+A quoted argument begins with a double-quote preceded by whitespace.
+The next double-quote not pair-wise adjacent to another double-quote
+terminates the literal, regardless of surrounding whitespace.
.Pp
This produces tokens
.Sq a" ,
and
.Sq fg" .
Note that any quoted term, be it argument or macro, is indiscriminately
-considered literal text. Thus, the following produces
+considered literal text.
+Thus, the following produces
.Sq \&Em a :
.Bd -literal -offset indent
\&.Em "Em a"
.Ss Dates
There are several macros in
.Nm
-that require a date argument. The canonical form for dates is the
-American format:
+that require a date argument.
+The canonical form for dates is the American format:
.Pp
.D1 Cm Month Day , Year
.Pp
The
.Cm Day
-value is an optionally zero-padded numeral. The
+value is an optionally zero-padded numeral.
+The
.Cm Month
-value is the full month name. The
+value is the full month name.
+The
.Cm Year
value is the full four-digit year.
.Pp
The syntax for scaled widths 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. The following
-scaling units are accepted:
+Negative numbers, while accepted, are truncated to zero.
+The following scaling units are accepted:
.Pp
.Bl -tag -width Ds -offset indent -compact
.It c
.Sq u ,
or
.Sq v
-is necessarily non-portable across output media. See
+is necessarily non-portable across output media.
+See
.Sx COMPATIBILITY .
+.Ss Sentence Spacing
+When composing a manual, make sure that your sentences end at the end of
+a line.
+By doing so, front-ends 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 (
+.Ns Sq \&) ,
+.Sq \&] ,
+.Sq \&' ,
+.Sq \&" ) .
+.Pp
+The proper spacing is also intelligently preserved if a sentence ends at
+the boundary of a macro line, e.g.,
+.Pp
+.D1 \&Xr mandoc 1 \.
+.D1 \&Fl T \&Ns \&Cm ascii \.
.Sh MANUAL STRUCTURE
A well-formed
.Nm
followed by
.Sx \&Nd .
.Pp
-Following that, convention dictates specifying at least the SYNOPSIS and
-DESCRIPTION sections, although this varies between manual sections.
+Following that, convention dictates specifying at least the
+.Em SYNOPSIS
+and
+.Em DESCRIPTION
+sections, although this varies between manual sections.
.Pp
The following is a well-formed skeleton
.Nm
\&.Dd $\&Mdocdate$
\&.Dt mdoc 7
\&.Os
-\&.
\&.Sh NAME
\&.Nm foo
\&.Nd a description goes here
-\&.\e\*q The next is for sections 2 & 3 only.
+\&.\e\*q The next is for sections 2, 3, & 9 only.
\&.\e\*q .Sh LIBRARY
-\&.
\&.Sh SYNOPSIS
\&.Nm foo
\&.Op Fl options
\&.Ar
-\&.
\&.Sh DESCRIPTION
The
\&.Nm
utility processes files ...
\&.\e\*q .Sh IMPLEMENTATION NOTES
-\&.\e\*q The next is for sections 1 & 8 only.
-\&.\e\*q .Sh EXIT STATUS
\&.\e\*q The next is for sections 2, 3, & 9 only.
\&.\e\*q .Sh RETURN VALUES
\&.\e\*q The next is for sections 1, 6, 7, & 8 only.
\&.\e\*q .Sh ENVIRONMENT
\&.\e\*q .Sh FILES
+\&.\e\*q The next is for sections 1 & 8 only.
+\&.\e\*q .Sh EXIT STATUS
\&.\e\*q .Sh EXAMPLES
\&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.
\&.\e\*q .Sh DIAGNOSTICS
.Pp
The sections in a
.Nm
-document are conventionally ordered as they appear above. Sections
-should be composed as follows:
+document are conventionally ordered as they appear above.
+Sections should be composed as follows:
.Bl -ohang -offset Ds
.It Em NAME
-The name(s) and a short description of the documented material. The
-syntax for this as follows:
+The name(s) and a short description of the documented material.
+The syntax for this as follows:
.Bd -literal -offset indent
\&.Nm name0
\&.Nm name1
.Sx \&Nd .
.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. The syntax for
-this is as follows:
+assumed to be a function in a section 2, 3, or 9 manual.
+The syntax for this is as follows:
.Bd -literal -offset indent
\&.Lb libarm
.Ed
Manuals not in these sections generally don't need a
.Em SYNOPSIS .
.Pp
-See
-.Sx \&Op ,
+Some macros are displayed differently in the
+.Em SYNOPSIS
+section, particularly
+.Sx \&Nm ,
.Sx \&Cd ,
+.Sx \&Fd ,
+.Sx \&Fn ,
+.Sx \&Fo ,
+.Sx \&In ,
+.Sx \&Vt ,
+and
+.Sx \&Ft .
+All of these macros are output on their own line. If two such
+dissimilar macros are pair-wise invoked (except for
+.Sx \&Ft
+before
+.Sx \&Fo
+or
+.Sx \&Fn ) ,
+they are separated by a vertical space, unless in the case of
+.Sx \&Fo ,
.Sx \&Fn ,
-.Sx \&Ft ,
and
-.Sx \&Vt .
+.Sx \&Ft ,
+which are always separated by vertical space.
.It Em DESCRIPTION
This expands upon the brief, one-line description in
.Em NAME .
.Pp
Manuals not documenting a command won't include the above fragment.
.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 EXIT STATUS
-Command exit status for section 1, 6, and 8 manuals. This section is
-the dual of
-.Em RETURN VALUES ,
-which is used for functions. Historically, this information was
-described in
-.Em DIAGNOSTICS ,
-a practise that is now discouraged.
-.Pp
-See
-.Sx \&Ex .
+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 is the dual of
.Em EXIT STATUS ,
-which is used for commands. It documents the return values of functions
-in sections 2, 3, and 9.
+which is used for commands.
+It documents the return values of functions in sections 2, 3, and 9.
.Pp
See
.Sx \&Rv .
See
.Sx \&Ev .
.It Em FILES
-Documents files used. It's helpful to document both the file and a
-short description of how the file is used (created, modified, etc.).
+Documents files used.
+It's helpful to document both the file and a short description of how
+the file is used (created, modified, etc.).
.Pp
See
.Sx \&Pa .
+.It Em EXIT STATUS
+Command exit status for section 1, 6, and 8 manuals.
+This section is the dual of
+.Em RETURN VALUES ,
+which is used for functions.
+Historically, this information was described in
+.Em DIAGNOSTICS ,
+a practise that is now discouraged.
+.Pp
+See
+.Sx \&Ex .
.It Em EXAMPLES
-Example usages. This often contains snippets of well-formed,
-well-tested invocations. Make doubly sure that your examples work
-properly!
+Example usages.
+This often contains snippets of well-formed, well-tested invocations.
+Make doubly sure that your examples work properly!
.It Em DIAGNOSTICS
-Documents error conditions. This is most useful in section 4 manuals.
+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
See
.Sx \&Er .
.It Em SEE ALSO
-References other manuals with related topics. This section should exist
-for most manuals. Cross-references should conventionally be ordered
-first by section, then alphabetically.
+References other manuals with related topics.
+This section should exist for most manuals.
+Cross-references should conventionally be ordered first by section, then
+alphabetically.
.Pp
See
.Sx \&Xr .
.It Em STANDARDS
-References any standards implemented or used. If not adhering to any
-standards, the
+References any standards implemented or used.
+If not adhering to any standards, the
.Em HISTORY
section should be used instead.
.Pp
Macros are one to three three characters in length and begin with a
control character ,
.Sq \&. ,
-at the beginning of the line. An arbitrary amount of whitespace may
-sit between the control character and the macro name. Thus, the
-following are equivalent:
+at the beginning of the line.
+An arbitrary amount of whitespace may sit between the control character
+and the macro name.
+Thus, the following are equivalent:
.Bd -literal -offset indent
\&.Pp
\&.\ \ \ \&Pp
.Ed
.Pp
-The syntax of a macro depends on its classification. In this section,
+The syntax of a macro depends on its classification.
+In this section,
.Sq \-arg
refers to macro arguments, which may be followed by zero or more
.Sq parm
The
.Em Callable
column indicates that the macro may be called subsequent to the initial
-line-macro. If a macro is not callable, then its invocation after the
-initial line macro is interpreted as opaque text, such that
+line-macro.
+If a macro is not callable, then its invocation after the initial line
+macro is interpreted as opaque text, such that
.Sq \&.Fl \&Sh
produces
.Sq Fl \&Sh .
The
.Em Parsable
column indicates whether the macro may be followed by further
-(ostensibly callable) macros. If a macro is not parsable, subsequent
-macro invocations on the line will be interpreted as opaque text.
+(ostensibly callable) macros.
+If a macro is not parsable, subsequent macro invocations on the line
+will be interpreted as opaque text.
.Pp
The
.Em Scope
column, if applicable, describes closure rules.
.Ss Block full-explicit
-Multi-line scope closed by an explicit closing macro. All macros
-contains bodies; only
+Multi-line scope closed by an explicit closing macro.
+All macros contains bodies; only
.Sx \&Bf
contains a head.
.Bd -literal -offset indent
.It Sx \&Ss Ta \&No Ta \&No Ta closed by Sx \&Sh , Sx \&Ss
.El
.Ss Block partial-explicit
-Like block full-explicit, but also with single-line scope. Each
-has at least a body and, in limited circumstances, a head
+Like block full-explicit, but also with single-line scope.
+Each has at least a body and, in limited circumstances, a head
.Po
.Sx \&Fo ,
.Sx \&Eo
macro is a
.Sx Block partial-implicit
only when invoked as the first macro
-in a SYNOPSIS section line, else it is
+in a
+.Em SYNOPSIS
+section line, else it is
.Sx In-line .
.Ss In-line
Closed by
.Sx Reserved Characters ,
-end of line, fixed argument lengths, and/or subsequent macros. In-line
-macros have only text children. If a number (or inequality) of
-arguments is
+end of line, fixed argument lengths, and/or subsequent macros.
+In-line macros have only text children.
+If a number (or inequality) of arguments is
.Pq n ,
then the macro accepts an arbitrary number of arguments.
.Bd -literal -offset indent
.El
.Sh REFERENCE
This section is a canonical reference of all macros, arranged
-alphabetically. For the scoping of individual macros, see
+alphabetically.
+For the scoping of individual macros, see
.Sx MACRO SYNTAX .
.Ss \&%A
Author name of an
.D1 \&.Ad [0,$]
.D1 \&.Ad 0x00000000
.Ss \&An
-Author name. This macro may alternatively accepts the following
-arguments, although these may not be specified along with a parameter:
+Author name.
+This macro may alternatively accepts the following arguments, although
+these may not be specified along with a parameter:
.Bl -tag -width 12n -offset indent
.It Fl split
Renders a line break before each author listing.
.Pp
In the AUTHORS section, the default is not to split the first author
listing, but all subsequent author listings, whether or not they're
-interspersed by other macros or text, are split. Thus, specifying
+interspersed by other macros or text, are split.
+Thus, specifying
.Fl split
-will cause the first listing also to be split. If not in the AUTHORS
-section, the default is not to split.
+will cause the first listing also to be split.
+If not in the AUTHORS section, the default is not to split.
.Pp
Examples:
.D1 \&.An -nosplit
in the general document body, it must be re-specified in the AUTHORS
section.
.Ss \&Ao
-Begins a block enclosed by angled brackets. Does not have any head
-arguments.
+Begins a block enclosed by angled brackets.
+Does not have any head arguments.
.Pp
Examples:
.D1 \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac
See also
.Sx \&Aq .
.Ss \&Ap
-Inserts an apostrophe without any surrounding white-space. This is
-generally used as a grammatic device when referring to the verb form of
-a function:
+Inserts an apostrophe without any surrounding white-space.
+This is generally used as a grammatical device when referring to the verb
+form of a function:
.Bd -literal -offset indent
\&.Fn execve Ap d
.Ed
See also
.Sx \&Ao .
.Ss \&Ar
-Command arguments. If an argument is not provided, the string
+Command arguments.
+If an argument is not provided, the string
.Dq file ...
is used as a default.
.Pp
.D1 \&.Ar
.D1 \&.Ar arg1 , arg2 .
.Ss \&At
-Formats an AT&T version. Accepts at most one parameter:
+Formats an AT&T version.
+Accepts at most one parameter:
.Bl -tag -width 12n -offset indent
.It Cm v[1-7] | 32v
A version of
.Sx \&Bo
block. Does not have any tail arguments.
.Ss \&Bd
-Begins a display block. A display is collection of macros or text which
-may be collectively offset or justified in a manner different from that
-of the enclosing context. By default, the block is preceded by a
-vertical space.
+Begins a display block.
+A display is collection of macros or text which may be collectively
+offset or justified in a manner different from that
+of the enclosing context.
+By default, the block is preceded by a vertical space.
.Pp
Each display is associated with a type, which must be one of the
following arguments:
Centre-justify each line.
.El
.Pp
-The type must be provided first. Secondary arguments are as follows:
+The type must be provided first.
+Secondary arguments are as follows:
.Bl -tag -width 12n -offset indent
.It Fl offset Ar width
Offset by the value of
.Ar center ,
which aligns around an imagined centre axis.
.It
-As a precalculated width for a named macro. The most popular is the
-imaginary macro
+As a precalculated width for a named macro.
+The most popular is the imaginary macro
.Ar \&Ds ,
which resolves to
.Ar 6n .
As the calculated string length of the opaque string.
.El
.Pp
-If unset, it will revert to the value of
-.Ar 8n
-as described in
-.Sx Scaling Widths .
+If not provided an argument, it will be ignored.
.It Fl compact
Do not assert a vertical space before the block.
.It Fl file Ar file
.Sx \&Dl .
.Ss \&Bf
.Ss \&Bk
+Begins a keep block, containing a collection of macros or text
+to be kept together in the output.
+One argument is required; additional arguments are ignored.
+Currently, the only argument implemented is
+.Fl words ,
+requesting to keep together all words of the contained text
+on the same output line.
+A
+.Fl lines
+argument to keep together all lines of the contained text
+on the same page has been desired for a long time,
+but has never been implemented.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Bk \-words
+\&.Op o Ar output_file
+\&.Ek
+.Ed
.Ss \&Bl
-.\" Begins a list composed of one or more list entries. A list entry is
-.\" specified by the
-.\" .Sx \&It
-.\" macro, which consists of a head and optional body. By default, a list
-.\" is preceded by a blank line. A list must specify one of the following
-.\" list types:
-.\" .Bl -tag -width 12n
-.\" .It Fl bullet
-.\" A list offset by a bullet. The head of list entries must be empty.
-.\" List entry bodies are justified after the bullet.
-.\" .It Fl column
-.\" A columnated list. The number of columns is specified as arguments to
-.\" the
-.\" .Sx \&Bl
-.\" macro (the deprecated form of following the invocation of
-.\" .Fl column
-.\" is also accepted). Arguments dictate the width of columns specified in
-.\" list entries. List entry bodies must be left empty. Columns specified
-.\" in the list entry head are justified to their position in the sequence
-.\" of columns.
-.\" .It Fl dash
-.\" A list offset by a dash (hyphen). The head of list entries must be
-.\" empty. List entry bodies are justified past the dash.
-.\" .It Fl diag
-.\" Like
-.\" .Fl inset
-.\" lists, but with additional formatting to the head.
-.\" .It Fl enum
-.\" A list offset by a number indicating list entry position. The head of
-.\" list entries must be empty. List entry bodies are justified past the
-.\" enumeration.
-.\" .It Fl hang
-.\" Like
-.\" .Fl tag ,
-.\" but instead of list bodies justifying to the head on the first line,
-.\" they trail the head text.
-.\" .It Fl hyphen
-.\" Synonym for
-.\" .Fl dash .
-.\" .It Fl inset
-.\" Like
-.\" .Fl tag ,
-.\" but list entry bodies aren't justified.
-.\" .It Fl item
-.\" An un-justified list. This produces blocks of text.
-.\" .It Fl ohang
-.\" List bodies are placed on the line following the head.
-.\" .It Fl tag
-.\" A list offset by list entry heads. List entry bodies are justified
-.\" after the head.
-.\" .El
-.\" .Pp
-.\" More...
-.\" .
+Begins a list composed of one or more list entries.
+A list is associated with a type, which is a required argument.
+Other arguments are
+.Fl width ,
+defined per-type as accepting a literal or
+.Sx Scaling Widths
+value;
+.Fl offset ,
+also accepting a literal or
+.Sx Scaling Widths
+value setting the list's global offset; and
+.Fl compact ,
+suppressing the default vertical space printed before each list entry.
+A list entry is specified by the
+.Sx \&It
+macro, which consists of a head and optional body (depending on the list
+type).
+A list must specify one of the following list types:
+.Bl -tag -width 12n -offset indent
+.It Fl bullet
+A list offset by a bullet.
+The head of list entries must be empty.
+List entry bodies are positioned after the bullet.
+The
+.Fl width
+argument varies the width of list bodies' left-margins.
+.It Fl column
+A columnated list.
+The
+.Fl width
+argument has no effect.
+The number of columns is specified as parameters to the
+.Sx \&Bl
+macro.
+These dictate the width of columns either as
+.Sx Scaling Widths
+or literal text.
+If the initial macro of a
+.Fl column
+list is not an
+.Sx \&It ,
+an
+.Sx \&It
+context spanning each line is implied until an
+.Sx \&It
+line macro is encountered, at which point list bodies are interpreted as
+described in the
+.Sx \&It
+documentation.
+.It Fl dash
+A list offset by a dash (hyphen).
+The head of list entries must be empty.
+List entry bodies are positioned past the dash.
+The
+.Fl width
+argument varies the width of list bodies' left-margins.
+.It Fl diag
+Like
+.Fl inset ,
+but with additional formatting to the head.
+The
+.Fl width
+argument varies the width of list bodies' left-margins.
+.It Fl enum
+An enumerated list offset by the enumeration from 1.
+The head of list entries must be empty.
+List entry bodies are positioned after the enumeration.
+The
+.Fl width
+argument varies the width of list bodies' left-margins.
+.It Fl hang
+Like
+.Fl tag ,
+but instead of list bodies positioned after the head, they trail the
+head text.
+The
+.Fl width
+argument varies the width of list bodies' left-margins.
+.It Fl hyphen
+Synonym for
+.Fl dash .
+.It Fl inset
+List bodies follow the list head.
+The
+.Fl width
+argument is ignored.
+.It Fl item
+This produces blocks of text.
+The head of list entries must be empty.
+The
+.Fl width
+argument is ignored.
+.It Fl ohang
+List bodies are positioned on the line following the head.
+The
+.Fl width
+argument is ignored.
+.It Fl tag
+A list offset by list entry heads. List entry bodies are positioned
+after the head as specified by the
+.Fl width
+argument.
+.El
+.Pp
+See also
+.Sx \&It .
.Ss \&Bo
-Begins a block enclosed by square brackets. Does not have any head
-arguments.
+Begins a block enclosed by square brackets.
+Does not have any head arguments.
.Pp
Examples:
.Bd -literal -offset indent
.Sx \&Bro
block. Does not have any tail arguments.
.Ss \&Bro
-Begins a block enclosed by curly braces. Does not have any head
-arguments.
+Begins a block enclosed by curly braces.
+Does not have any head arguments.
.Pp
Examples:
.Bd -literal -offset indent
and
.Sx \&Ux .
.Ss \&Cd
-Configuration declaration. This denotes strings accepted by
+Configuration declaration.
+This denotes strings accepted by
.Xr config 8 .
.Pp
Examples:
this macro is commonly abused by using quoted literals to retain
white-space and align consecutive
.Sx \&Cd
-declarations. This practise is discouraged.
+declarations.
+This practise is discouraged.
.Ss \&Cm
-Command modifiers. Useful when specifying configuration options or
-keys.
+Command modifiers.
+Useful when specifying configuration options or keys.
.Pp
Examples:
.D1 \&.Cm ControlPath
See also
.Sx \&Fl .
.Ss \&D1
-One-line indented display. This is formatted by the default rules and
-is useful for simple indented statements. It is followed by a newline.
+One-line indented display.
+This is formatted by the default rules and is useful for simple indented
+statements.
+It is followed by a newline.
.Pp
Examples:
.D1 \&.D1 \&Fl abcdefgh
and
.Sx \&Dl .
.Ss \&Db
+Start a debugging context.
+This macro is parsed, but generally ignored.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&Db Cm on | off
.Ss \&Dc
Closes a
.Sx \&Do
block. Does not have any tail arguments.
.Ss \&Dd
-Document date. This is the mandatory first macro of any
+Document date.
+This is the mandatory first macro of any
.Nm
-manual. Its calling syntax is as follows:
+manual.
+Its syntax is as follows:
.Pp
-.D1 \. Ns Sx \&Dd Cm date
+.D1 Pf \. Sx \&Dd Cm date
.Pp
The
.Cm date
and
.Sx \&Os .
.Ss \&Dl
-One-line intended display. This is formatted as literal text and is
-useful for commands and invocations. It is followed by a newline.
+One-line intended display.
+This is formatted as literal text and is useful for commands and
+invocations.
+It is followed by a newline.
.Pp
Examples:
.D1 \&.Dl % mandoc mdoc.7 | less
See also
.Sx \&Do .
.Ss \&Dt
-Document title. This is the mandatory second macro of any
+Document title.
+This is the mandatory second macro of any
.Nm
-file. Its calling syntax is as follows:
-.Pp
-.D1 \. Ns Sx \&Dt Cm title section Op Cm volume | arch
+file.
+Its syntax is as follows:
+.Bd -ragged -offset indent
+.Pf \. Sx \&Dt
+.Oo
+.Cm title
+.Oo
+.Cm section
+.Op Cm volume | arch
+.Oc
+.Oc
+.Ed
.Pp
Its arguments are as follows:
.Bl -tag -width Ds -offset Ds
.It Cm title
-The document's title (name). This should be capitalised and is
-required.
+The document's title (name), defaulting to
+.Qq UNKNOWN
+if unspecified.
+It should be capitalised.
.It Cm section
-The manual section. This may be one of
+The manual section.
+This may be one of
.Ar 1
.Pq utilities ,
.Ar 2
or
.Ar paper
.Pq paper .
-It is also required and should correspond to the manual's filename
-suffix.
+It should correspond to the manual's filename suffix and defaults to
+.Qq 1
+if unspecified.
.It Cm volume
This overrides the volume inferred from
.Ar section .
.Ar CON
.Pq contributed manuals .
.It Cm arch
-This specifies a specific relevant architecture. If
+This specifies a specific relevant architecture.
+If
.Cm volume
is not provided, it may be used in its place, else it may be used
-subsequent that. It, too, is optional. It must be one of
+subsequent that.
+It, too, is optional.
+It must be one of
.Ar alpha ,
.Ar amd64 ,
.Ar amiga ,
.D1 \&.Dt FOO 1
.D1 \&.Dt FOO 4 KM
.D1 \&.Dt FOO 9 i386
-.D1 \&.Dt FOO 9 KM i386
.Pp
See also
.Sx \&Dd
.Ss \&Ed
.Ss \&Ef
.Ss \&Ek
+Ends a keep context started by
+.Sx \&Bk .
.Ss \&El
+Ends a list context started by
+.Sx \&Bl .
+.Pp
+See also
+.Sx \&Bl
+and
+.Sx \&It .
.Ss \&Em
-Denotes text that should be emphasised. Note that this is a
-presentation term and should not be used for stylistically decorating
-technical terms.
+Denotes text that should be emphasised.
+Note that this is a presentation term and should not be used for
+stylistically decorating technical terms.
.Pp
Examples:
.D1 \&.Em Warnings!
.D1 \&.Ev DISPLAY
.D1 \&.Ev PATH
.Ss \&Ex
-Inserts text regarding a utility's exit values. This macro must have
-first the
+Inserts text regarding a utility's exit values.
+This macro must have first the
.Fl std
argument specified, then an optional
.Ar utility .
.Sx \&Nm
is provided.
.Ss \&Fa
+Function argument.
+Its syntax is as follows:
+.Bd -ragged -offset indent
+.Pf \. Sx \&Fa
+.Op Cm argtype
+.Cm argname
+.Ed
+.Pp
+This may be invoked for names with or without the corresponding type.
+It is also used to specify the field name of a structure.
+Most often, the
+.Sx \&Fa
+macro is used in the
+.Em SYNOPSIS
+within
+.Sx \&Fo
+section when documenting multi-line function prototypes.
+If invoked with multiple arguments, the arguments are separated by a
+comma.
+Furthermore, if the following macro is another
+.Sx \&Fa ,
+the last argument will also have a trailing comma.
+.Pp
+Examples:
+.D1 \&.Fa \(dqconst char *p\(dq
+.D1 \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq
+.D1 \&.Fa foo
+.Pp
+See also
+.Sx \&Fo .
.Ss \&Fc
.Ss \&Fd
+Historically used to document include files.
+This usage has been deprecated in favour of
+.Sx \&In .
+Do not use this macro.
+.Pp
+See also
+.Sx MANUAL STRUCTURE
+and
+.Sx \&In .
.Ss \&Fl
-Command-line flag. Used when listing arguments to command-line
-utilities. Prints a fixed-width hyphen
+Command-line flag.
+Used when listing arguments to command-line utilities.
+Prints a fixed-width hyphen
.Sq \-
-directly followed by each argument. If no arguments are provided, a hyphen is
-printed followed by a space. If the argument is a macro, a hyphen is
-prefixed to the subsequent macro output.
+directly followed by each argument.
+If no arguments are provided, a hyphen is printed followed by a space.
+If the argument is a macro, a hyphen is prefixed to the subsequent macro
+output.
.Pp
Examples:
.D1 \&.Fl a b c
See also
.Sx \&Cm .
.Ss \&Fn
+A function name.
+Its syntax is as follows:
+.Bd -ragged -offset indent
+.Pf \. Ns Sx \&Fn
+.Op Cm functype
+.Cm funcname
+.Op Oo Cm argtype Oc Cm argname
+.Ed
+.Pp
+Function arguments are surrounded in parenthesis and
+are delimited by commas.
+If no arguments are specified, blank parenthesis are output.
+.Pp
+Examples:
+.D1 \&.Fn "int funcname" "int arg0" "int arg1"
+.D1 \&.Fn funcname "int arg0"
+.D1 \&.Fn funcname arg0
+.Bd -literal -offset indent -compact
+\&.Ft functype
+\&.Fn funcname
+.Ed
+.Pp
+See also
+.Sx MANUAL STRUCTURE
+and
+.Sx \&Ft .
.Ss \&Fo
-.Ss \&Fr
+Begin a function block.
+This is a multi-line version of
+.Sx \&Fn .
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&Fo Cm funcname
+.Pp
+Invocations usually occur in the following context:
+.Bd -ragged -offset indent
+.Pf \. Sx \&Ft Cm functype
+.br
+.Pf \. Sx \&Fo Cm funcname
+.br
+.Pf \. Sx \&Fa Oo Cm argtype Oc Cm argname
+.br
+\.\.\.
+.br
+.Pf \. Sx \&Fc
+.Ed
+.Pp
+A
+.Sx \&Fo
+scope is closed by
+.Pp
+See also
+.Sx MANUAL STRUCTURE ,
+.Sx \&Fa ,
+.Sx \&Fc ,
+and
.Ss \&Ft
+A function type.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&Ft Cm functype
+.Pp
+Examples:
+.D1 \&.Ft int
+.Bd -literal -offset indent -compact
+\&.Ft functype
+\&.Fn funcname
+.Ed
+.Pp
+See also
+.Sx MANUAL STRUCTURE ,
+.Sx \&Fn ,
+and
+.Sx \&Fo .
.Ss \&Fx
Format the FreeBSD version provided as an argument, or a default value
if no argument is provided.
.Ss \&Hf
.Ss \&Ic
.Ss \&In
+An
+.Qq include
+file.
+In the
+.Em SYNOPSIS
+section (only if invoked as the line macro), the first argument is
+preceded by
+.Qq #include ,
+the arguments is enclosed in angled braces.
+.Pp
+Examples:
+.D1 \&.In sys/types
+.Pp
+See also
+.Sx MANUAL STRUCTURE .
.Ss \&It
+A list item.
+The syntax of this macro depends on the list type.
+.Pp
+Lists
+of type
+.Fl hang ,
+.Fl ohang ,
+.Fl inset ,
+and
+.Fl diag
+have the following syntax:
+.Pp
+.D1 Pf \. Sx \&It Cm args
+.Pp
+Lists of type
+.Fl bullet ,
+.Fl dash ,
+.Fl enum ,
+.Fl hyphen
+and
+.Fl item
+have the following syntax:
+.Pp
+.D1 Pf \. Sx \&It
+.Pp
+with subsequent lines interpreted within the scope of the
+.Sx \&It
+until either a closing
+.Sx \&El
+or another
+.Sx \&It .
+.Pp
+The
+.Fl tag
+list has the following syntax:
+.Pp
+.D1 Pf \. Sx \&It Op Cm args
+.Pp
+Subsequent lines are interpreted as with
+.Fl bullet
+and family.
+The line arguments correspond to the list's left-hand side; body
+arguments correspond to the list's contents.
+.Pp
+The
+.Fl column
+list is the most complicated.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&It Op Cm args
+.Pp
+The
+.Cm args
+are phrases, a mix of macros and text corresponding to a line column,
+delimited by tabs or the special
+.Sq \&Ta
+pseudo-macro.
+Lines subsequent the
+.Sx \&It
+are interpreted within the scope of the last phrase.
+Calling the pseudo-macro
+.Sq \&Ta
+will open a new phrase scope (this must occur on a macro line to be
+interpreted as a macro). Note that the tab phrase delimiter may only be
+used within the
+.Sx \&It
+line itself.
+Subsequent this, only the
+.Sq \&Ta
+pseudo-macro may be used to delimit phrases.
+Furthermore, note that quoted sections propagate over tab-delimited
+phrases on an
+.Sx \&It ,
+for example,
+.Pp
+.D1 .It \(dqcol1 ; <TAB> col2 ;\(dq \&;
+.Pp
+will preserve the semicolon whitespace except for the last.
+.Pp
+See also
+.Sx \&Bl .
.Ss \&Lb
+Specify a library.
+The syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&Lb Cm library
+.Pp
+The
+.Cm library
+parameter may be a system library, such as
+.Cm libz
+or
+.Cm libpam ,
+in which case a small library description is printed next to the linker
+invocation; or a custom library, in which case the library name is
+printed in quotes.
+This is most commonly used in the
+.Em SYNOPSIS
+section as described in
+.Sx MANUAL STRUCTURE .
+.Pp
+Examples:
+.D1 \&.Lb libz
+.D1 \&.Lb mdoc
.Ss \&Li
.Ss \&Lk
-Format a hyperlink. The calling syntax is as follows:
+Format a hyperlink.
+Its syntax is as follows:
.Pp
-.D1 \. Ns Sx \&Lk Cm uri Op Cm name
+.D1 Pf \. Sx \&Lk Cm uri Op Cm name
.Pp
Examples:
.D1 \&.Lk http://bsd.lv "The BSD.lv Project"
.Ss \&Lp
.Ss \&Ms
.Ss \&Mt
+Format a
+.Qq mailto:
+hyperlink.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&Mt Cm address
+.Pp
+Examples:
+.D1 \&.Mt discuss@manpages.bsd.lv
.Ss \&Nd
.Ss \&Nm
.Ss \&No
.Ss \&Oo
.Ss \&Op
.Ss \&Os
-Document operating system version. This is the mandatory third macro of
+Document operating system version.
+This is the mandatory third macro of
any
.Nm
-file. Its calling syntax is as follows:
+file.
+Its syntax is as follows:
.Pp
-.D1 \. Ns Sx \&Os Op Cm system
+.D1 Pf \. Sx \&Os Op Cm system
.Pp
The optional
.Cm system
-parameter specifies the relevant operating system or environment. Left
-unspecified, it defaults to the local operating system version. This is
-the suggested form.
+parameter specifies the relevant operating system or environment.
+Left unspecified, it defaults to the local operating system version.
+This is the suggested form.
.Pp
Examples:
.D1 \&.Os
.Ss \&Re
Closes a
.Sx \&Rs
-block. Does not have any tail arguments.
+block.
+Does not have any tail arguments.
.Ss \&Rs
Begins a bibliographic
.Pq Dq reference
-block. Does not have any head arguments. The block macro may only
-contain
+block.
+Does not have any head arguments.
+The block macro may only contain
.Sx \&%A ,
.Sx \&%B ,
.Sx \&%C ,
.Sx \&%Q ,
.Sx \&%R ,
.Sx \&%T ,
+.Sx \&%U ,
and
.Sx \&%V
child macros (at least one must be specified).
.Ss \&Sy
.Ss \&Tn
.Ss \&Ud
+Prints out
+.Dq currently under development.
.Ss \&Ux
-Format the UNIX name. Accepts no argument.
+Format the UNIX name.
+Accepts no argument.
.Pp
Examples:
.D1 \&.Ux
.Sx \&Ox .
.Ss \&Va
.Ss \&Vt
-A variable type. This is also used for indicating global variables in the
-SYNOPSIS section, in which case a variable name is also specified. Note that
-it accepts
+A variable type.
+This is also used for indicating global variables in the
+.Em SYNOPSIS
+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 SYNOPSIS section, else it
-accepts ordinary
+syntax when invoked as the first macro in the
+.Em SYNOPSIS
+section, else it accepts ordinary
.Sx In-line
syntax.
.Pp
.Pp
Examples:
.D1 \&.Vt unsigned char
-.D1 \&.Vt extern const char * const sys_signame[] ;
+.D1 \&.Vt extern const char * const sys_signame[] \&;
.Pp
See also
-.Sx \&Ft
+.Sx MANUAL STRUCTURE
and
.Sx \&Va .
.Ss \&Xc
Close a scope opened by
.Sx \&Xo .
.Ss \&Xo
-Open an extension scope. This macro originally existed to extend the
-9-argument limit of troff; since this limit has been lifted, the macro
-has been deprecated.
+Open an extension scope.
+This macro originally existed to extend the 9-argument limit of troff;
+since this limit has been lifted, the macro has been deprecated.
.Ss \&Xr
Link to another manual
.Pq Qq cross-reference .
-Its calling syntax is
+Its syntax is as follows:
.Pp
-.D1 \. Ns Sx \&Xr Cm name section
+.D1 Pf \. Sx \&Xr Cm name section
.Pp
The
.Cm name
and
.Cm section
-are the name and section of the linked manual. If
+are the name and section of the linked manual.
+If
.Cm section
is followed by non-punctuation, an
.Sx \&Ns
-is inserted into the token stream. This behaviour is for compatibility
-with
+is inserted into the token stream.
+This behaviour is for compatibility with
.Xr groff 1 .
.Pp
Examples:
.D1 \&.Xr mandoc 1
-.D1 \&.Xr mandoc 1 ;
+.D1 \&.Xr mandoc 1 \&;
.D1 \&.Xr mandoc 1 \&Ns s behaviour
.Ss \&br
.Ss \&sp
.Pp
.Bl -dash -compact
.It
+Old groff fails to assert a newline before
+.Sx \&Bd Fl ragged compact .
+.It
+groff behaves inconsistently when encountering
+.Pf non- Sx \&Fa
+children of
+.Sx \&Fo
+regarding spacing between arguments.
+In mandoc, this is not the case: each argument is consistently followed
+by a single space and the trailing
+.Sq \&)
+suppresses prior spacing.
+.It
+groff behaves inconsistently when encountering
+.Sx \&Ft
+and
+.Sx \&Fn
+in the
+.Em SYNOPSIS :
+at times newline(s) are suppressed depending on whether a prior
+.Sx \&Fn
+has been invoked.
+In mandoc, this is not the case.
+See
+.Sx \&Ft
+and
+.Sx \&Fn
+for the normalised behaviour.
+.It
+Historic groff does not break before an
+.Sx \&Fn
+when not invoked as the line macro in the
+.Em SYNOPSIS
+section.
+.It
+Historic groff formats the
+.Sx \&In
+badly: trailing arguments are trashed and
+.Em SYNOPSIS
+is not specially treated.
+.It
+groff does not accept the
+.Sq \&Ta
+pseudo-macro as a line macro.
+mandoc does.
+.It
The comment syntax
.Sq \e."
is no longer accepted.
In groff, the
.Sx \&Pa
macro does not format its arguments when used in the FILES section under
-certain list types. mandoc does.
+certain list types.
+mandoc does.
.It
Historic groff does not print a dash for empty
.Sx \&Fl
-arguments. mandoc and newer groff implementations do.
+arguments.
+mandoc and newer groff implementations do.
.It
groff behaves irregularly when specifying
.Sq \ef
.Sx Text Decoration
-within line-macro scopes. mandoc follows a consistent system.
+within line-macro scopes.
+mandoc follows a consistent system.
.It
In mandoc, negative scaling units are truncated to zero; groff would
-move to prior lines. Furthermore, the
+move to prior lines.
+Furthermore, the
.Sq f
scaling unit, while accepted, is rendered as the default unit.
.It
In quoted literals, groff allowed pair-wise double-quotes to produce a
-standalone double-quote in formatted output. This idiosyncratic
-behaviour is not applicable in mandoc.
+standalone double-quote in formatted output.
+This idiosyncratic behaviour is not applicable in mandoc.
.It
-Display types
+Display offsets
.Sx \&Bd
-.Fl center
+.Fl offset Ar center
and
-.Fl right
-are aliases for
-.Fl left
-in manodc. Furthermore, the
+.Fl offset Ar right
+are disregarded in mandoc.
+Furthermore, the
.Fl file Ar file
-argument is ignored. Lastly, since text is not right-justified in
-mandoc (or even groff),
+argument is not supported in mandoc.
+Lastly, since text is not right-justified in mandoc (or even groff),
.Fl ragged
and
.Fl filled
and
.Fl unfilled .
.It
-Historic groff has many un-callable macros. Most of these (excluding
-some block-level macros) are now callable.
+Historic groff has many un-callable macros.
+Most of these (excluding some block-level macros) are now callable.
.It
The vertical bar
.Sq \(ba
Some manuals use
.Sx \&Li
incorrectly by following it with a reserved character and expecting the
-delimiter to render. This is not supported in mandoc.
-.It
-In groff, the
-.Sx \&Fo
-macro only produces the first parameter. This is not the case in
-mandoc.
+delimiter to render.
+This is not supported in mandoc.
.It
In groff, the
.Sx \&Cd ,
.Sx \&Er ,
+.Sx \&Ex ,
and
-.Sx \&Ex
-macros were stipulated only to occur in certain manual sections. mandoc
-does not have these restrictions.
+.Sx \&Rv
+macros were stipulated only to occur in certain manual sections.
+mandoc does not have these restrictions.
+.It
+Newer groff and mandoc print
+.Qq AT&T UNIX
+prior to unknown arguments of
+.Sx \&At ;
+older groff did nothing.
.El
.Sh SEE ALSO
.Xr mandoc 1 ,
git.ckatri.com / mandoc.git / blobdiff