The "value" argument to the roff(7) .nr requests ends right before

[mandoc.git] / mdoc.7

diff --git a/mdoc.7 b/mdoc.7
index 515485d1d7eeef05157fa05ee10a55ec6570d5b0..b7ff7676b1c9a4529df0495888233cb72dd4a434 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"    $Id: mdoc.7,v 1.212 2011/09/27 21:49:23 schwarze Exp $
+.\"    $Id: mdoc.7,v 1.222 2013/11/02 20:39:49 schwarze Exp $

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


@@ -15,7 +15,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"

-.Dd $Mdocdate: September 27 2011 $
+.Dd $Mdocdate: November 2 2013 $

 .Dt MDOC 7
 .Os
 .Sh NAME
 .Dt MDOC 7
 .Os
 .Sh NAME


@@ -477,6 +477,7 @@ in the alphabetical
 .Bl -column "Brq, Bro, Brc" description
 .It Sx \&Lb Ta function library (one argument)
 .It Sx \&In Ta include file (one argument)
 .Bl -column "Brq, Bro, Brc" description
 .It Sx \&Lb Ta function library (one argument)
 .It Sx \&In Ta include file (one argument)

+.It Sx \&Fd Ta other preprocessor directive (>0 arguments)

 .It Sx \&Ft Ta function type (>0 arguments)
 .It Sx \&Fo , \&Fc Ta function block: Ar funcname
 .It Sx \&Fn Ta function name:
 .It Sx \&Ft Ta function type (>0 arguments)
 .It Sx \&Fo , \&Fc Ta function block: Ar funcname
 .It Sx \&Fn Ta function name:


@@ -657,7 +658,7 @@ for all other author listings.
 .Pp
 Examples:
 .Dl \&.An -nosplit
 .Pp
 Examples:
 .Dl \&.An -nosplit

-.Dl \&.An Kristaps Dzonsons \&Aq kristaps@bsd.lv
+.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv

 .Ss \&Ao
 Begin a block enclosed by angle brackets.
 Does not have any head arguments.
 .Ss \&Ao
 Begin a block enclosed by angle brackets.
 Does not have any head arguments.


@@ -711,7 +712,9 @@ for fixed strings to be passed verbatim as arguments, use
 or
 .Sx \&Cm .
 .Ss \&At
 or
 .Sx \&Cm .
 .Ss \&At

-Formats an AT&T version.
+Formats an
+.At
+version.

 Accepts one optional argument:
 .Pp
 .Bl -tag -width "v[1-7] | 32vX" -offset indent -compact
 Accepts one optional argument:
 .Pp
 .Bl -tag -width "v[1-7] | 32vX" -offset indent -compact


@@ -820,8 +823,8 @@ The most popular is the imaginary macro
 which resolves to
 .Sy 6n .
 .It
 which resolves to
 .Sy 6n .
 .It

-A width using the syntax described in
-.Sx Scaling Widths .
+A scaling width as described in
+.Xr roff 7 .

 .It
 An arbitrary string, which indents by the length of this string.
 .El
 .It
 An arbitrary string, which indents by the length of this string.
 .El


@@ -926,8 +929,8 @@ The
 .Fl width
 and
 .Fl offset
 .Fl width
 and
 .Fl offset

-arguments accept
-.Sx Scaling Widths
+arguments accept scaling widths as described in
+.Xr roff 7

 or use the length of the given string.
 The
 .Fl offset
 or use the length of the given string.
 The
 .Fl offset


@@ -956,9 +959,9 @@ A columnated list.
 The
 .Fl width
 argument has no effect; instead, each argument specifies the width
 The
 .Fl width
 argument has no effect; instead, each argument specifies the width

-of one column, using either the
-.Sx Scaling Widths
-syntax or the string length of the argument.
+of one column, using either the scaling width syntax described in
+.Xr roff 7
+or the string length of the argument.

 If the first line of the body of a
 .Fl column
 list is not an
 If the first line of the body of a
 .Fl column
 list is not an


@@ -1089,7 +1092,9 @@ Examples:
 See also
 .Sx \&Bro .
 .Ss \&Bsx
 See also
 .Sx \&Bro .
 .Ss \&Bsx

-Format the BSD/OS version provided as an argument, or a default value if
+Format the
+.Bsx
+version provided as an argument, or a default value if

 no argument is provided.
 .Pp
 Examples:
 no argument is provided.
 .Pp
 Examples:


@@ -1109,7 +1114,9 @@ and
 Prints
 .Dq is currently in beta test.
 .Ss \&Bx
 Prints
 .Dq is currently in beta test.
 .Ss \&Bx

-Format the BSD version provided as an argument, or a default value if no
+Format the
+.Bx
+version provided as an argument, or a default value if no

 argument is provided.
 .Pp
 Examples:
 argument is provided.
 .Pp
 Examples:


@@ -1282,7 +1289,8 @@ Its syntax is as follows:
 .Ar title
 .Oo
 .Ar section
 .Ar title
 .Oo
 .Ar section

-.Op Ar volume | arch
+.Op Ar volume
+.Op Ar arch

 .Oc
 .Oc
 .Ed
 .Oc
 .Oc
 .Ed


@@ -1363,42 +1371,19 @@ or
 .Ar CON
 .Pq contributed manuals .
 .It Ar arch
 .Ar CON
 .Pq contributed manuals .
 .It Ar arch

-This specifies a specific relevant architecture.
-If
-.Ar 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
-.Ar alpha ,
-.Ar amd64 ,
-.Ar amiga ,
-.Ar arc ,
-.Ar arm ,
-.Ar armish ,
-.Ar aviion ,
-.Ar hp300 ,
-.Ar hppa ,
-.Ar hppa64 ,
-.Ar i386 ,
-.Ar landisk ,
-.Ar loongson ,
-.Ar luna88k ,
-.Ar mac68k ,
-.Ar macppc ,
-.Ar mips64 ,
-.Ar mvme68k ,
-.Ar mvme88k ,
-.Ar mvmeppc ,
-.Ar pmax ,
-.Ar sgi ,
-.Ar socppc ,
-.Ar sparc ,
-.Ar sparc64 ,
-.Ar sun3 ,
-.Ar vax ,
+This specifies the machine architecture a manual page applies to,
+where relevant, for example
+.Cm alpha ,
+.Cm amd64 ,
+.Cm i386 ,

 or
 or

-.Ar zaurus .
+.Cm sparc64 .
+The list of supported architectures varies by operating system.
+For the full list of all architectures recognized by
+.Xr mandoc 1 ,
+see the file
+.Pa arch.in
+in the source distribution.

 .El
 .Pp
 Examples:
 .El
 .Pp
 Examples:


@@ -1423,11 +1408,16 @@ See also
 .Sx \&Er
 and
 .Sx \&Ev
 .Sx \&Er
 and
 .Sx \&Ev

-for special-purpose constants and
+for special-purpose constants,

 .Sx \&Va
 .Sx \&Va

-for variable symbols.
+for variable symbols, and
+.Sx \&Fd
+for listing preprocessor variable definitions in the
+.Em SYNOPSIS .

 .Ss \&Dx
 .Ss \&Dx

-Format the DragonFly BSD version provided as an argument, or a default
+Format the
+.Dx
+version provided as an argument, or a default

 value if no argument is provided.
 .Pp
 Examples:
 value if no argument is provided.
 .Pp
 Examples:


@@ -1584,15 +1574,32 @@ See also
 End a function context started by
 .Sx \&Fo .
 .Ss \&Fd
 End a function context started by
 .Sx \&Fo .
 .Ss \&Fd

-Historically used to document include files.
-This usage has been deprecated in favour of
+Preprocessor directive, in particular for listing it in the
+.Em SYNOPSIS .
+Historically, it was also used to document include files.
+The latter usage has been deprecated in favour of

 .Sx \&In .
 .Sx \&In .

-Do not use this macro.
+.Pp
+Its syntax is as follows:
+.Bd -ragged -offset indent
+.Pf \. Sx \&Fd
+.Li # Ns Ar directive
+.Op Ar argument ...
+.Ed
+.Pp
+Examples:
+.Dl \&.Fd #define sa_handler __sigaction_u.__sa_handler
+.Dl \&.Fd #define SIO_MAXNFDS
+.Dl \&.Fd #ifdef FS_DEBUG
+.Dl \&.Ft void
+.Dl \&.Fn dbg_open \(dqconst char *\(dq
+.Dl \&.Fd #endif

 .Pp
 See also
 .Pp
 See also

-.Sx MANUAL STRUCTURE
+.Sx MANUAL STRUCTURE ,
+.Sx \&In ,

 and
 and

-.Sx \&In .
+.Sx \&Dv .

 .Ss \&Fl
 Command-line flag or option.
 Used when listing arguments to command-line utilities.
 .Ss \&Fl
 Command-line flag or option.
 Used when listing arguments to command-line utilities.


@@ -1873,7 +1880,7 @@ section as described in
 .Pp
 Examples:
 .Dl \&.Lb libz
 .Pp
 Examples:
 .Dl \&.Lb libz

-.Dl \&.Lb mdoc
+.Dl \&.Lb libmandoc

 .Ss \&Li
 Denotes text that should be in a
 .Li literal
 .Ss \&Li
 Denotes text that should be in a
 .Li literal


@@ -1924,6 +1931,7 @@ Its syntax is as follows:
 .Pp
 Examples:
 .Dl \&.Mt discuss@manpages.bsd.lv
 .Pp
 Examples:
 .Dl \&.Mt discuss@manpages.bsd.lv

+.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv

 .Ss \&Nd
 A one line description of the manual's content.
 This may only be invoked in the
 .Ss \&Nd
 A one line description of the manual's content.
 This may only be invoked in the


@@ -2105,7 +2113,7 @@ This macro is obsolete and not implemented in
 .Xr mandoc 1 .
 .Pp
 Historical
 .Xr mandoc 1 .
 .Pp
 Historical

-.Xr mdoc 7
+.Nm

 packages described it as
 .Dq "old function type (FORTRAN)" .
 .Ss \&Ox
 packages described it as
 .Dq "old function type (FORTRAN)" .
 .Ss \&Ox


@@ -2369,20 +2377,26 @@ The following standards are recognised:
 .St -p1003.1b-93
 .It \-p1003.1c-95
 .St -p1003.1c-95
 .St -p1003.1b-93
 .It \-p1003.1c-95
 .St -p1003.1c-95

+.It \-p1003.1d-99
+.St -p1003.1d-99

 .It \-p1003.1g-2000
 .St -p1003.1g-2000
 .It \-p1003.1i-95
 .St -p1003.1i-95
 .It \-p1003.1g-2000
 .St -p1003.1g-2000
 .It \-p1003.1i-95
 .St -p1003.1i-95

+.It \-p1003.1j-2000
+.St -p1003.1j-2000
+.It \-p1003.1q-2000
+.St -p1003.1q-2000
+.It \-p1003.2
+.St -p1003.2

 .It \-p1003.2-92
 .St -p1003.2-92
 .It \-p1003.2a-92
 .St -p1003.2a-92
 .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 \-p1387.2
 .St -p1387.2

+.It \-p1387.2-95
+.St -p1387.2-95

 .It \-isoC
 .St -isoC
 .It \-isoC-90
 .It \-isoC
 .St -isoC
 .It \-isoC-90


@@ -2395,6 +2409,8 @@ The following standards are recognised:
 .St -isoC-tcor2
 .It \-isoC-99
 .St -isoC-99
 .St -isoC-tcor2
 .It \-isoC-99
 .St -isoC-99

+.It \-isoC-2011
+.St -isoC-2011

 .It \-iso9945-1-90
 .St -iso9945-1-90
 .It \-iso9945-1-96
 .It \-iso9945-1-90
 .St -iso9945-1-90
 .It \-iso9945-1-96


@@ -2487,7 +2503,9 @@ Examples:
 Prints out
 .Dq currently under development.
 .Ss \&Ux
 Prints out
 .Dq currently under development.
 .Ss \&Ux

-Format the UNIX name.
+Format the
+.Ux
+name.

 Accepts no argument.
 .Pp
 Examples:
 Accepts no argument.
 .Pp
 Examples:


@@ -2552,20 +2570,14 @@ Link to another manual
 .Pq Qq cross-reference .
 Its syntax is as follows:
 .Pp
 .Pq Qq cross-reference .
 Its syntax is as follows:
 .Pp

-.D1 Pf \. Sx \&Xr Ar name section
+.D1 Pf \. Sx \&Xr Ar name Op section

 .Pp
 .Pp

-The
+Cross reference the

 .Ar name
 and
 .Ar section
 .Ar name
 and
 .Ar section

-are the name and section of the linked manual.
-If
-.Ar section
-is followed by non-punctuation, an
-.Sx \&Ns
-is inserted into the token stream.
-This behaviour is for compatibility with
-GNU troff.
+number of another man page;
+omitting the section number is rarely useful.

 .Pp
 Examples:
 .Dl \&.Xr mandoc 1
 .Pp
 Examples:
 .Dl \&.Xr mandoc 1


@@ -2589,8 +2601,8 @@ Its syntax is as follows:
 .Pp
 The
 .Ar height
 .Pp
 The
 .Ar height

-argument must be formatted as described in
-.Sx Scaling Widths .
+argument is a scaling width as described in
+.Xr roff 7 .

 If unspecified,
 .Sx \&sp
 asserts a single vertical space.
 If unspecified,
 .Sx \&sp
 asserts a single vertical space.


@@ -2984,7 +2996,7 @@ Manually switching the font using the
 .Ql \ef
 font escape sequences is never required.
 .Sh COMPATIBILITY
 .Ql \ef
 font escape sequences is never required.
 .Sh COMPATIBILITY

-This section documents compatibility between mandoc and other other
+This section documents compatibility between mandoc and other

 troff implementations, at this time limited to GNU troff
 .Pq Qq groff .
 The term
 troff implementations, at this time limited to GNU troff
 .Pq Qq groff .
 The term


@@ -3188,5 +3200,4 @@ utility written by Kristaps Dzonsons appeared in
 The
 .Nm
 reference was written by
 The
 .Nm
 reference was written by

-.An Kristaps Dzonsons ,
-.Mt kristaps@bsd.lv .
+.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .