In the SYNOPSIS, .Nm at the beginning of an input line starts

[mandoc.git] / mdoc.7

diff --git a/mdoc.7 b/mdoc.7
index 0f7e551d5693225c2d8bdd199e3d1541ea10b0df..f1f57a98d690a5681f8c424834598bac625d4b00 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"    $Id: mdoc.7,v 1.138 2010/07/19 15:28:11 kristaps Exp $
+.\"    $Id: mdoc.7,v 1.140 2010/07/19 21:59:48 kristaps Exp $

 .\"
 .\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>


@@ -948,7 +948,8 @@ Examples:
 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
+.Pp
+.Bl -tag -width "-nosplitX" -offset indent -compact

 .It Fl split
 Renders a line break before each author listing.
 .It Fl nosplit
 .It Fl split
 Renders a line break before each author listing.
 .It Fl nosplit


@@ -956,13 +957,17 @@ The opposite of
 .Fl split .
 .El
 .Pp
 .Fl split .
 .El
 .Pp

-In the AUTHORS section, the default is not to split the first author
+In the
+.Em 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
 .Fl split
 will cause the first listing also to be split.
 listing, but all subsequent author listings, whether or not they're
 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.
+If not in the
+.Em AUTHORS
+section, the default is not to split.

 .Pp
 Examples:
 .D1 \&.An -nosplit
 .Pp
 Examples:
 .D1 \&.An -nosplit


@@ -973,9 +978,12 @@ the effects of
 .Fl split
 or
 .Fl nosplit
 .Fl split
 or
 .Fl nosplit

-are re-set when entering the AUTHORS section, so if one specifies
+are re-set when entering the
+.Em AUTHORS
+section, so if one specifies

 .Sx \&An Fl nosplit
 .Sx \&An Fl nosplit

-in the general document body, it must be re-specified in the AUTHORS
+in the general document body, it must be re-specified in the
+.Em AUTHORS

 section.
 .Ss \&Ao
 Begins a block enclosed by angled brackets.
 section.
 .Ss \&Ao
 Begins a block enclosed by angled brackets.


@@ -989,10 +997,10 @@ See also
 .Ss \&Ap
 Inserts an apostrophe without any surrounding whitespace.
 This is generally used as a grammatical device when referring to the verb
 .Ss \&Ap
 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
-\&.Fn execve Ap d
-.Ed
+form of a function.
+.Pp
+Examples:
+.D1 \&.Fn execve \&Ap d

 .Ss \&Aq
 Encloses its arguments in angled brackets.
 .Pp
 .Ss \&Aq
 Encloses its arguments in angled brackets.
 .Pp


@@ -1024,7 +1032,8 @@ Examples:
 .Ss \&At
 Formats an AT&T version.
 Accepts at most one parameter:
 .Ss \&At
 Formats an AT&T version.
 Accepts at most one parameter:

-.Bl -tag -width 12n -offset indent
+.Pp
+.Bl -tag -width "v[1-7] | 32vX" -offset indent -compact

 .It Cm v[1-7] | 32v
 A version of
 .At .
 .It Cm v[1-7] | 32v
 A version of
 .At .


@@ -1314,7 +1323,7 @@ Begins a block enclosed by square brackets.
 Does not have any head arguments.
 .Pp
 Examples:
 Does not have any head arguments.
 .Pp
 Examples:

-.Bd -literal -offset indent
+.Bd -literal -offset indent -compact

 \&.Bo 1 ,
 \&.Dv BUFSIZ \&Bc
 .Ed
 \&.Bo 1 ,
 \&.Dv BUFSIZ \&Bc
 .Ed


@@ -1347,7 +1356,7 @@ Begins a block enclosed by curly braces.
 Does not have any head arguments.
 .Pp
 Examples:
 Does not have any head arguments.
 .Pp
 Examples:

-.Bd -literal -offset indent
+.Bd -literal -offset indent -compact

 \&.Bro 1 , ... ,
 \&.Va n \&Brc
 .Ed
 \&.Bro 1 , ... ,
 \&.Va n \&Brc
 .Ed


@@ -1482,7 +1491,7 @@ invocations.
 It is followed by a newline.
 .Pp
 Examples:
 It is followed by a newline.
 .Pp
 Examples:

-.D1 \&.Dl % mandoc mdoc.7 | less
+.D1 \&.Dl % mandoc mdoc.7 \e(ba less

 .Pp
 See also
 .Sx \&Bd
 .Pp
 See also
 .Sx \&Bd


@@ -1493,7 +1502,12 @@ Begins a block enclosed by double quotes.
 Does not have any head arguments.
 .Pp
 Examples:
 Does not have any head arguments.
 .Pp
 Examples:

-.D1 \&.D1 \&Do April is the cruellest month \&Dc \e(em T.S. Eliot
+.Bd -literal -offset indent -compact
+\&.Do
+April is the cruellest month
+\&.Dc
+\e(em T.S. Eliot
+.Ed

 .Pp
 See also
 .Sx \&Dq .
 .Pp
 See also
 .Sx \&Dq .


@@ -1509,10 +1523,11 @@ Examples:
 .Ed
 .Pp
 See also
 .Ed
 .Pp
 See also

-.Ss \&Qq ,
-.Ss \&Sq ,
+.Sx \&Qq ,
+.Sx \&Sq ,

 and
 .Sx \&Do .
 and
 .Sx \&Do .

+.Ss \&Dt

 Document title.
 This is the mandatory second macro of any
 .Nm
 Document title.
 This is the mandatory second macro of any
 .Nm


@@ -1752,16 +1767,19 @@ Examples:
 .D1 \&.Ev DISPLAY
 .D1 \&.Ev PATH
 .Ss \&Ex
 .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 value.
+This macro must consist of the

 .Fl std
 .Fl std

-argument specified, then an optional
+argument followed by an optional

 .Ar utility .
 If
 .Ar utility
 is not provided, the document's name as stipulated in
 .Sx \&Nm
 is provided.
 .Ar utility .
 If
 .Ar utility
 is not provided, the document's name as stipulated in
 .Sx \&Nm
 is provided.

+.Pp
+See also
+.Sx \&Rv .

 .Ss \&Fa
 Function argument.
 Its syntax is as follows:
 .Ss \&Fa
 Function argument.
 Its syntax is as follows:


@@ -1881,6 +1899,7 @@ See also
 .Sx \&Fa ,
 .Sx \&Fc ,
 and
 .Sx \&Fa ,
 .Sx \&Fc ,
 and

+.Sx \&Ft .

 .Ss \&Ft
 A function type.
 Its syntax is as follows:
 .Ss \&Ft
 A function type.
 Its syntax is as follows:


@@ -2083,6 +2102,9 @@ Synonym for
 .Sx \&Pp .
 .Ss \&Ms
 Display a mathematical symbol.
 .Sx \&Pp .
 .Ss \&Ms
 Display a mathematical symbol.

+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&Ms Cm symbol

 .Pp
 Examples:
 .D1 \&.Ms sigma
 .Pp
 Examples:
 .D1 \&.Ms sigma


@@ -2374,6 +2396,19 @@ block is used within a SEE ALSO section, a vertical space is asserted
 before the rendered output, else the block continues on the current
 line.
 .Ss \&Rv
 before the rendered output, else the block continues on the current
 line.
 .Ss \&Rv

+Inserts text regarding a function call's return value.
+This macro must consist of the
+.Fl std
+argument followed by an optional
+.Ar function .
+If
+.Ar function
+is not provided, the document's name as stipulated by the first
+.Sx \&Nm
+is provided.
+.Pp
+See also
+.Sx \&Ex .

 .Ss \&Sc
 Close single-quoted context opened by
 .Sx \&So .
 .Ss \&Sc
 Close single-quoted context opened by
 .Sx \&So .


@@ -2436,6 +2471,102 @@ See also
 and
 .Sx \&Sx .
 .Ss \&St
 and
 .Sx \&Sx .
 .Ss \&St

+Replace an abbreviation for a standard with the full form.
+The following standards are recognised:
+.Pp
+.Bl -tag -width "-p1003.1g-2000X" -compact
+.It \-p1003.1-88
+.St -p1003.1-88
+.It \-p1003.1-90
+.St -p1003.1-90
+.It \-p1003.1-96
+.St -p1003.1-96
+.It \-p1003.1-2001
+.St -p1003.1-2001
+.It \-p1003.1-2004
+.St -p1003.1-2004
+.It \-p1003.1-2008
+.St -p1003.1-2008
+.It \-p1003.1
+.St -p1003.1
+.It \-p1003.1b
+.St -p1003.1b
+.It \-p1003.1b-93
+.St -p1003.1b-93
+.It \-p1003.1c-95
+.St -p1003.1c-95
+.It \-p1003.1g-2000
+.St -p1003.1g-2000
+.It \-p1003.1i-95
+.St -p1003.1i-95
+.It \-p1003.2-92
+.St -p1003.2-92
+.It \-p1003.2a-92
+.St -p1003.2a-92
+.It \-p1387.2-95
+.St -p1387.2-95
+.It \-p1003.2
+.St -p1003.2
+.It \-p1387.2
+.St -p1387.2
+.It \-isoC
+.St -isoC
+.It \-isoC-90
+.St -isoC-90
+.It \-isoC-amd1
+.St -isoC-amd1
+.It \-isoC-tcor1
+.St -isoC-tcor1
+.It \-isoC-tcor2
+.St -isoC-tcor2
+.It \-isoC-99
+.St -isoC-99
+.It \-iso9945-1-90
+.St -iso9945-1-90
+.It \-iso9945-1-96
+.St -iso9945-1-96
+.It \-iso9945-2-93
+.St -iso9945-2-93
+.It \-ansiC
+.St -ansiC
+.It \-ansiC-89
+.St -ansiC-89
+.It \-ansiC-99
+.St -ansiC-99
+.It \-ieee754
+.St -ieee754
+.It \-iso8802-3
+.St -iso8802-3
+.It \-ieee1275-94
+.St -ieee1275-94
+.It \-xpg3
+.St -xpg3
+.It \-xpg4
+.St -xpg4
+.It \-xpg4.2
+.St -xpg4.2
+.St -xpg4.3
+.It \-xbd5
+.St -xbd5
+.It \-xcu5
+.St -xcu5
+.It \-xsh5
+.St -xsh5
+.It \-xns5
+.St -xns5
+.It \-xns5.2
+.St -xns5.2
+.It \-xns5.2d2.0
+.St -xns5.2d2.0
+.It \-xcurses4.2
+.St -xcurses4.2
+.It \-susv2
+.St -susv2
+.It \-susv3
+.St -susv3
+.It \-svid4
+.St -svid4
+.El

 .Ss \&Sx
 Reference a section or sub-section.
 The referenced section or sub-section name must be identical to the
 .Ss \&Sx
 Reference a section or sub-section.
 The referenced section or sub-section name must be identical to the


@@ -2458,7 +2589,7 @@ and
 Format a tradename.
 .Pp
 Examples:
 Format a tradename.
 .Pp
 Examples:

-.D1 \&.Tn IBM .
+.D1 \&.Tn IBM

 .Ss \&Ud
 Prints out
 .Dq currently under development.
 .Ss \&Ud
 Prints out
 .Dq currently under development.


@@ -2541,7 +2672,28 @@ Examples:
 .D1 \&.Xr mandoc 1 \&;
 .D1 \&.Xr mandoc 1 \&Ns s behaviour
 .Ss \&br
 .D1 \&.Xr mandoc 1 \&;
 .D1 \&.Xr mandoc 1 \&Ns s behaviour
 .Ss \&br

+Emits a line-break.
+This macro should not be used; it is implemented for compatibility with
+historical manuals.
+.Pp
+Consider using
+.Sx \&Pp
+in the event of natural paragraph breaks.

 .Ss \&sp
 .Ss \&sp

+Emits vertical space.
+This macro should not be used; it is implemented for compatibility with
+historical manuals.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&sp Op Cm height
+.Pp
+The
+.Cm height
+argument must be formatted as described in
+.Sx Scaling Widths .
+If unspecified,
+.Sx \&sp
+asserts a single vertical space.

 .Sh COMPATIBILITY
 This section documents compatibility between mandoc and other other
 troff implementations, at this time limited to GNU troff
 .Sh COMPATIBILITY
 This section documents compatibility between mandoc and other other
 troff implementations, at this time limited to GNU troff