summaryrefslogtreecommitdiffstats
path: root/mdoc.7
diff options
context:
space:
mode:
Diffstat (limited to 'mdoc.7')
-rw-r--r--mdoc.7279
1 files changed, 170 insertions, 109 deletions
diff --git a/mdoc.7 b/mdoc.7
index f7bc161e..8bfb58d0 100644
--- a/mdoc.7
+++ b/mdoc.7
@@ -27,8 +27,10 @@ The
language is used to format
.Bx
.Ux
-manuals. In this reference document, we describe its syntax, structure,
-and usage. Our reference implementation is mandoc; the
+manuals.
+In this reference document, we describe its syntax, structure, and
+usage.
+Our reference implementation is mandoc; the
.Sx COMPATIBILITY
section describes compatibility with other troff \-mdoc implementations.
.Pp
@@ -37,7 +39,8 @@ An
document follows simple rules: lines beginning with the control
character
.Sq \.
-are parsed for macros. Other lines are interpreted within the scope of
+are parsed for macros.
+Other lines are interpreted within the scope of
prior macros:
.Bd -literal -offset indent
\&.Sh Macro lines change control state.
@@ -46,18 +49,20 @@ Other lines are interpreted within the current state.
.Sh LANGUAGE SYNTAX
.Nm
documents may contain only graphable 7-bit ASCII characters, the space
-character, and, in certain circumstances, the tab character. All
-manuals must have
+character, and, in certain circumstances, the tab character.
+All manuals must have
.Ux
line terminators.
.Ss Comments
Text following a
.Sq \e\*q ,
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,
+line.
+A macro line with only a control character and comment escape,
.Sq \&.\e\*q ,
-is also ignored. Macro lines with only a control character and optionally
-whitespace are stripped from input.
+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:
.Pp
@@ -445,8 +450,8 @@ section, particularly
.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
+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
@@ -858,14 +863,17 @@ For the scoping of individual macros, see
.Ss \&%A
Author name of an
.Sx \&Rs
-block. Multiple authors should each be accorded their own
+block.
+Multiple authors should each be accorded their own
.Sx \%%A
-line. Author names should be ordered with full or abbreviated
-forename(s) first, then full surname.
+line.
+Author names should be ordered with full or abbreviated forename(s)
+first, then full surname.
.Ss \&%B
Book title of an
.Sx \&Rs
-block. This macro may also be used in a non-bibliographic context when
+block.
+This macro may also be used in a non-bibliographic context when
referring to book titles.
.Ss \&%C
Publication city or location of an
@@ -878,8 +886,8 @@ this macro is not implemented in
.Ss \&%D
Publication date of an
.Sx \&Rs
-block. This should follow the reduced or canonical form syntax
-described in
+block.
+This should follow the reduced or canonical form syntax described in
.Sx Dates .
.Ss \&%I
Publisher or issuer name of an
@@ -904,7 +912,8 @@ block.
.Ss \&%Q
Institutional author (school, government, etc.) of an
.Sx \&Rs
-block. Multiple institutional authors should each be accorded their own
+block.
+Multiple institutional authors should each be accorded their own
.Sx \&%Q
line.
.Ss \&%R
@@ -914,8 +923,9 @@ block.
.Ss \&%T
Article title of an
.Sx \&Rs
-block. This macro may also be used in a non-bibliographical context
-when referring to article titles.
+block.
+This macro may also be used in a non-bibliographical context when
+referring to article titles.
.Ss \&%U
URI of reference document.
.Ss \&%V
@@ -925,7 +935,8 @@ block.
.Ss \&Ac
Closes an
.Sx \&Ao
-block. Does not have any tail arguments.
+block.
+Does not have any tail arguments.
.Ss \&Ad
Address construct: usually in the context of an computational address in
memory, not a physical (post) address.
@@ -976,7 +987,7 @@ Examples:
See also
.Sx \&Aq .
.Ss \&Ap
-Inserts an apostrophe without any surrounding white-space.
+Inserts an apostrophe without any surrounding whitespace.
This is generally used as a grammatical device when referring to the verb
form of a function:
.Bd -literal -offset indent
@@ -1040,7 +1051,8 @@ and
.Ss \&Bc
Closes a
.Sx \&Bo
-block. Does not have any tail arguments.
+block.
+Does not have any tail arguments.
.Ss \&Bd
Begins a display block.
Its syntax is as follows:
@@ -1289,8 +1301,8 @@ 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
+A list offset by list entry heads.
+List entry bodies are positioned after the head as specified by the
.Fl width
argument.
.El
@@ -1328,7 +1340,8 @@ See also
.Ss \&Brc
Closes a
.Sx \&Bro
-block. Does not have any tail arguments.
+block.
+Does not have any tail arguments.
.Ss \&Bro
Begins a block enclosed by curly braces.
Does not have any head arguments.
@@ -1396,7 +1409,7 @@ Examples:
.Pp
.Em Remarks :
this macro is commonly abused by using quoted literals to retain
-white-space and align consecutive
+whitespace and align consecutive
.Sx \&Cd
declarations.
This practise is discouraged.
@@ -1432,7 +1445,8 @@ Its syntax is as follows:
.Ss \&Dc
Closes a
.Sx \&Do
-block. Does not have any tail arguments.
+block.
+Does not have any tail arguments.
.Ss \&Dd
Document date.
This is the mandatory first macro of any
@@ -1475,8 +1489,8 @@ See also
and
.Sx \&D1 .
.Ss \&Do
-Begins a block enclosed by double quotes. Does not have any head
-arguments.
+Begins a block enclosed by double quotes.
+Does not have any head arguments.
.Pp
Examples:
.D1 \&.D1 \&Do April is the cruellest month \&Dc \e(em T.S. Eliot
@@ -1484,7 +1498,9 @@ Examples:
See also
.Sx \&Dq .
.Ss \&Dq
-Encloses its arguments in double quotes.
+Encloses its arguments in
+.Dq typographic
+double-quotes.
.Pp
Examples:
.Bd -literal -offset indent -compact
@@ -1493,8 +1509,10 @@ Examples:
.Ed
.Pp
See also
+.Ss \&Qq ,
+.Ss \&Sq ,
+and
.Sx \&Do .
-.Ss \&Dt
Document title.
This is the mandatory second macro of any
.Nm
@@ -1515,7 +1533,7 @@ Its arguments are as follows:
.Bl -tag -width Ds -offset Ds
.It Cm title
The document's title (name), defaulting to
-.Qq UNKNOWN
+.Dq UNKNOWN
if unspecified.
It should be capitalised.
.It Cm section
@@ -1555,7 +1573,7 @@ or
.Ar paper
.Pq paper .
It should correspond to the manual's filename suffix and defaults to
-.Qq 1
+.Dq 1
if unspecified.
.It Cm volume
This overrides the volume inferred from
@@ -1696,6 +1714,12 @@ stylistically decorating technical terms.
Examples:
.D1 \&.Em Warnings!
.D1 \&.Em Remarks :
+.Pp
+See also
+.Sx \&Bf ,
+.Sx \&Sy ,
+and
+.Sx \&Li .
.Ss \&En
This macro is obsolete and not implemented.
.Ss \&Eo
@@ -1913,13 +1937,13 @@ is preferred for displaying code; the
macro is used when referring to specific instructions.
.Ss \&In
An
-.Qq include
+.Dq include
file.
In the
.Em SYNOPSIS
section (only if invoked as the line macro), the first argument is
preceded by
-.Qq #include ,
+.Dq #include ,
the arguments is enclosed in angled braces.
.Pp
Examples:
@@ -1991,8 +2015,8 @@ 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
+interpreted as a macro).
+Note that the tab phrase delimiter may only be used within the
.Sx \&It
line itself.
Subsequent this, only the
@@ -2036,6 +2060,12 @@ Examples:
Denotes text that should be in a literal font mode.
Note that this is a presentation term and should not be used for
stylistically decorating technical terms.
+.Pp
+See also
+.Sx \&Bf ,
+.Sx \&Sy ,
+and
+.Sx \&Em .
.Ss \&Lk
Format a hyperlink.
Its syntax is as follows:
@@ -2052,9 +2082,14 @@ See also
Synonym for
.Sx \&Pp .
.Ss \&Ms
+Display a mathematical symbol.
+.Pp
+Examples:
+.D1 \&.Ms sigma
+.D1 \&.Ms aleph
.Ss \&Mt
Format a
-.Qq mailto:
+.Dq mailto:
hyperlink.
Its syntax is as follows:
.Pp
@@ -2125,12 +2160,23 @@ macro rather than
to mark up the name of the manual page.
.Ss \&No
A
-.Qq noop
+.Dq noop
macro used to terminate prior macro contexts.
.Pp
Examples:
.D1 \&.Sx \&Fl ab \&No cd \&Fl ef
.Ss \&Ns
+Suppress a space.
+Following invocation, text is interpreted as free-form text until a
+macro is encountered.
+.Pp
+Examples:
+.D1 \&.Fl o \&Ns \&Ar output
+.Pp
+See also
+.Sx \&No
+and
+.Sx \&Sm .
.Ss \&Nx
Format the NetBSD version provided as an argument, or a default value if
no argument is provided.
@@ -2157,7 +2203,7 @@ Multi-line version of
.Sx \&Op .
.Pp
Examples:
-.Bd -literal -offset indent
+.Bd -literal -offset indent -compact
\&.Oo
\&.Op Fl flag Ns Ar value
\&.Oc
@@ -2234,7 +2280,7 @@ Close parenthesised context opened by
.Sx \&Po .
.Ss \&Pf
Removes the space
-.Pq Qq prefix
+.Pq Dq prefix
between its arguments.
Its syntax is as follows:
.Pp
@@ -2259,9 +2305,29 @@ Parenthesised enclosure.
See also
.Sx \&Po .
.Ss \&Qc
+Close quoted context opened by
+.Sx \&Qo .
.Ss \&Ql
+Format a single-quoted literal.
+See also
+.Sx \&Qq
+and
+.Sx \&Sq .
.Ss \&Qo
+Multi-line version of
+.Sx \&Qq .
.Ss \&Qq
+Encloses its arguments in
+.Dq typewriter
+double-quotes.
+Consider using
+.Sx \&Dq .
+.Pp
+See also
+.Sx \&Dq ,
+.Sx \&Sq ,
+and
+.Sx \&Qo .
.Ss \&Re
Closes a
.Sx \&Rs
@@ -2309,7 +2375,23 @@ before the rendered output, else the block continues on the current
line.
.Ss \&Rv
.Ss \&Sc
+Close single-quoted context opened by
+.Sx \&So .
.Ss \&Sh
+Begin a new section.
+For a list of conventional manual sections, see
+.Sx MANUAL STRUCTURE .
+These sections should be used unless it's absolutely necessary that
+custom sections be used.
+.Pp
+Section names should be unique so that they may be keyed by
+.Sx \&Sx .
+.Pp
+See also
+.Sx \&Pp ,
+.Sx \&Ss ,
+and
+.Sx \&Sx .
.Ss \&Sm
Switches the spacing mode for output generated from macros.
Its syntax is as follows:
@@ -2324,12 +2406,59 @@ no white space is inserted between macro arguments and between the
output generated from adjacent macros, but free-form text lines
still get normal spacing between words and sentences.
.Ss \&So
+Multi-line version of
+.Sx \&Sq .
.Ss \&Sq
+Encloses its arguments in
+.Dq typewriter
+single-quotes.
+.Pp
+See also
+.Sx \&Dq ,
+.Sx \&Qq ,
+and
+.Sx \&So .
.Ss \&Ss
+Begin a new sub-section.
+Unlike with
+.Sx \&Sh ,
+there's no convention for sub-sections.
+Conventional sections, as described in
+.Sx MANUAL STRUCTURE ,
+rarely have sub-sections.
+.Pp
+Sub-section names should be unique so that they may be keyed by
+.Sx \&Sx .
+.Pp
+See also
+.Sx \&Pp ,
+.Sx \&Sh ,
+and
+.Sx \&Sx .
.Ss \&St
.Ss \&Sx
+Reference a section or sub-section.
+The referenced section or sub-section name must be identical to the
+enclosed argument, including whitespace.
+.Pp
+Examples:
+.D1 \&.Sx MANUAL STRUCTURE
.Ss \&Sy
+Format enclosed arguments in symbolic
+.Pq Dq boldface .
+Note that this is a presentation term and should not be used for
+stylistically decorating technical terms.
+.Pp
+See also
+.Sx \&Bf ,
+.Sx \&Li ,
+and
+.Sx \&Em .
.Ss \&Tn
+Format a tradename.
+.Pp
+Examples:
+.D1 \&.Tn IBM .
.Ss \&Ud
Prints out
.Dq currently under development.
@@ -2571,71 +2700,3 @@ The
.Nm
reference was written by
.An Kristaps Dzonsons Aq kristaps@bsd.lv .
-.\"
-.\" XXX: this really isn't the place for these caveats.
-.\" .
-.\" .
-.\" .Sh CAVEATS
-.\" There are many ambiguous parts of mdoc.
-.\" .
-.\" .Pp
-.\" .Bl -dash -compact
-.\" .It
-.\" .Sq \&Fa
-.\" should be
-.\" .Sq \&Va
-.\" as function arguments are variables.
-.\" .It
-.\" .Sq \&Ft
-.\" should be
-.\" .Sq \&Vt
-.\" as function return types are still types. Furthermore, the
-.\" .Sq \&Ft
-.\" should be removed and
-.\" .Sq \&Fo ,
-.\" which ostensibly follows it, should follow the same convention as
-.\" .Sq \&Va .
-.\" .It
-.\" .Sq \&Va
-.\" should formalise that only one or two arguments are acceptable: a
-.\" variable name and optional, preceding type.
-.\" .It
-.\" .Sq \&Fd
-.\" is ambiguous. It's commonly used to indicate an include file in the
-.\" synopsis section.
-.\" .Sq \&In
-.\" should be used, instead.
-.\" .It
-.\" Only the
-.\" .Sq \-literal
-.\" argument to
-.\" .Sq \&Bd
-.\" makes sense. The remaining ones should be removed.
-.\" .It
-.\" The
-.\" .Sq \&Xo
-.\" and
-.\" .Sq \&Xc
-.\" macros should be deprecated.
-.\" .It
-.\" The
-.\" .Sq \&Dt
-.\" macro lacks clarity. It should be absolutely clear which title will
-.\" render when formatting the manual page.
-.\" .It
-.\" A
-.\" .Sq \&Lx
-.\" should be provided for Linux (\(`a la
-.\" .Sq \&Ox ,
-.\" .Sq \&Nx
-.\" etc.).
-.\" .It
-.\" There's no way to refer to references in
-.\" .Sq \&Rs/Re
-.\" blocks.
-.\" .It
-.\" The \-split and \-nosplit dictates via
-.\" .Sq \&An
-.\" are re-set when entering and leaving the AUTHORS section.
-.\" .El
-.\" .