Plug in the "head" concept for tables. A tbl_head specifies the full

[mandoc.git] / mdoc.7

diff --git a/mdoc.7 b/mdoc.7
index d7bd066d58bd7698ee917a29ed6d321113645b9d..3689a5ca2fa1ec24624814c6b04b0518f05d1f14 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"    $Id: mdoc.7,v 1.155 2010/08/24 14:03:46 kristaps Exp $
+.\"    $Id: mdoc.7,v 1.173 2010/12/29 16:16:50 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>


@@ -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: August 24 2010 $
+.Dd $Mdocdate: December 29 2010 $

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


@@ -125,7 +125,7 @@ Terms may be text-decorated using the
 escape followed by an indicator: B (bold), I (italic), R (Roman), or P
 (revert to previous mode):
 .Pp
 escape followed by an indicator: B (bold), I (italic), R (Roman), or P
 (revert to previous mode):
 .Pp

-.D1 \efBbold\efR \efIitalic\efP
+.Dl \efBbold\efR \efIitalic\efP

 .Pp
 A numerical representation 3, 2, or 1 (bold, italic, and Roman,
 respectively) may be used instead.
 .Pp
 A numerical representation 3, 2, or 1 (bold, italic, and Roman,
 respectively) may be used instead.


@@ -293,8 +293,8 @@ The proper spacing is also intelligently preserved if a sentence ends at
 the boundary of a macro line.
 For example:
 .Pp
 the boundary of a macro line.
 For example:
 .Pp

-.D1 \&Xr mandoc 1 \.
-.D1 \&Fl T \&Ns \&Cm ascii \.
+.Dl \&Xr mandoc 1 \.
+.Dl \&Fl T \&Ns \&Cm ascii \.

 .Sh MANUAL STRUCTURE
 A well-formed
 .Nm
 .Sh MANUAL STRUCTURE
 A well-formed
 .Nm


@@ -331,8 +331,9 @@ file:
 \&.Sh NAME
 \&.Nm foo
 \&.Nd a description goes here
 \&.Sh NAME
 \&.Nm foo
 \&.Nd a description goes here

-\&.\e\*q The next is for sections 2, 3, & 9 only.

 \&.\e\*q .Sh LIBRARY
 \&.\e\*q .Sh LIBRARY

+\&.\e\*q For sections 2, 3, & 9 only.
+\&.\e\*q Not used in OpenBSD.

 \&.Sh SYNOPSIS
 \&.Nm foo
 \&.Op Fl options
 \&.Sh SYNOPSIS
 \&.Nm foo
 \&.Op Fl options


@@ -342,18 +343,19 @@ The
 \&.Nm
 utility processes files ...
 \&.\e\*q .Sh IMPLEMENTATION NOTES
 \&.Nm
 utility processes files ...
 \&.\e\*q .Sh IMPLEMENTATION NOTES

-\&.\e\*q The next is for sections 2, 3, & 9 only.
+\&.\e\*q Not used in OpenBSD.

 \&.\e\*q .Sh RETURN VALUES
 \&.\e\*q .Sh RETURN VALUES

-\&.\e\*q The next is for sections 1, 6, 7, & 8 only.
+\&.\e\*q For sections 2, 3, & 9 only.

 \&.\e\*q .Sh ENVIRONMENT
 \&.\e\*q .Sh ENVIRONMENT

+\&.\e\*q For sections 1, 6, 7, & 8 only.

 \&.\e\*q .Sh FILES
 \&.\e\*q .Sh FILES

-\&.\e\*q The next is for sections 1 & 8 only.

 \&.\e\*q .Sh EXIT STATUS
 \&.\e\*q .Sh EXIT STATUS

+\&.\e\*q For sections 1, 6, & 8 only.

 \&.\e\*q .Sh EXAMPLES
 \&.\e\*q .Sh EXAMPLES

-\&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.

 \&.\e\*q .Sh DIAGNOSTICS
 \&.\e\*q .Sh DIAGNOSTICS

-\&.\e\*q The next is for sections 2, 3, & 9 only.
+\&.\e\*q For sections 1, 4, 6, 7, & 8 only.

 \&.\e\*q .Sh ERRORS
 \&.\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 SEE ALSO
 \&.\e\*q .Xr foobar 1
 \&.\e\*q .Sh STANDARDS


@@ -362,6 +364,7 @@ utility processes files ...
 \&.\e\*q .Sh CAVEATS
 \&.\e\*q .Sh BUGS
 \&.\e\*q .Sh SECURITY CONSIDERATIONS
 \&.\e\*q .Sh CAVEATS
 \&.\e\*q .Sh BUGS
 \&.\e\*q .Sh SECURITY CONSIDERATIONS

+\&.\e\*q Not used in OpenBSD.

 .Ed
 .Pp
 The sections in an
 .Ed
 .Pp
 The sections in an


@@ -601,20 +604,21 @@ closes it out.
 .Pp
 The
 .Em Callable
 .Pp
 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
+column indicates that the macro may also be called by passing its name
+as an argument to another macro.
+If a macro is not callable but its name appears as an argument
+to another macro, it is interpreted as opaque text.
+For example,

 .Sq \&.Fl \&Sh
 produces
 .Sq Fl \&Sh .
 .Pp
 The
 .Em Parsed
 .Sq \&.Fl \&Sh
 produces
 .Sq Fl \&Sh .
 .Pp
 The
 .Em Parsed

-column indicates whether the macro may be followed by further
-(ostensibly callable) macros.
-If a macro is not parsed, subsequent macro invocations on the line
-will be interpreted as opaque text.
+column indicates whether the macro may call other macros by receiving
+their names as arguments.
+If a macro is not parsed but the name of another macro appears
+as an argument, it is interpreted as opaque text.

 .Pp
 The
 .Em Scope
 .Pp
 The
 .Em Scope


@@ -935,8 +939,8 @@ Memory address.
 Do not use this for postal addresses.
 .Pp
 Examples:
 Do not use this for postal addresses.
 .Pp
 Examples:

-.D1 \&.Ad [0,$]
-.D1 \&.Ad 0x00000000
+.Dl \&.Ad [0,$]
+.Dl \&.Ad 0x00000000

 .Ss \&An
 Author name.
 Requires either the name of an author or one of the following arguments:
 .Ss \&An
 Author name.
 Requires either the name of an author or one of the following arguments:


@@ -966,14 +970,14 @@ for the first author listing and
 for all other author listings.
 .Pp
 Examples:
 for all other author listings.
 .Pp
 Examples:

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

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

-.D1 \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac
+.Dl \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac

 .Pp
 See also
 .Sx \&Aq .
 .Pp
 See also
 .Sx \&Aq .


@@ -983,12 +987,12 @@ This is generally used as a grammatical device when referring to the verb
 form of a function.
 .Pp
 Examples:
 form of a function.
 .Pp
 Examples:

-.D1 \&.Fn execve \&Ap d
+.Dl \&.Fn execve \&Ap d

 .Ss \&Aq
 Encloses its arguments in angle brackets.
 .Pp
 Examples:
 .Ss \&Aq
 Encloses its arguments in angle brackets.
 .Pp
 Examples:

-.D1 \&.Fl -key= \&Ns \&Aq \&Ar val
+.Dl \&.Fl -key= \&Ns \&Aq \&Ar val

 .Pp
 .Em Remarks :
 this macro is often abused for rendering URIs, which should instead use
 .Pp
 .Em Remarks :
 this macro is often abused for rendering URIs, which should instead use


@@ -1009,9 +1013,9 @@ If an argument is not provided, the string
 is used as a default.
 .Pp
 Examples:
 is used as a default.
 .Pp
 Examples:

-.D1 \&.Fl o \&Ns \&Ar file1
-.D1 \&.Ar
-.D1 \&.Ar arg1 , arg2 .
+.Dl \&.Fl o \&Ns \&Ar file1
+.Dl \&.Ar
+.Dl \&.Ar arg1 , arg2 .

 .Ss \&At
 Formats an AT&T version.
 Accepts one optional argument:
 .Ss \&At
 Formats an AT&T version.
 Accepts one optional argument:


@@ -1028,8 +1032,8 @@ A version of
 Note that these arguments do not begin with a hyphen.
 .Pp
 Examples:
 Note that these arguments do not begin with a hyphen.
 .Pp
 Examples:

-.D1 \&.At
-.D1 \&.At V.1
+.Dl \&.At
+.Dl \&.At V.1

 .Pp
 See also
 .Sx \&Bsx ,
 .Pp
 See also
 .Sx \&Bsx ,


@@ -1197,7 +1201,7 @@ Be careful in using over-long lines within a keep block!
 Doing so will clobber the right margin.
 .Ss \&Bl
 Begin a list.
 Doing so will clobber the right margin.
 .Ss \&Bl
 Begin a list.

-Lists consist of items started by the
+Lists consist of items specified using the

 .Sx \&It
 macro, containing a head or a body or both.
 The list syntax is as follows:
 .Sx \&It
 macro, containing a head or a body or both.
 The list syntax is as follows:


@@ -1332,7 +1336,7 @@ See also
 Encloses its arguments in square brackets.
 .Pp
 Examples:
 Encloses its arguments in square brackets.
 .Pp
 Examples:

-.D1 \&.Bq 1 , \&Dv BUFSIZ
+.Dl \&.Bq 1 , \&Dv BUFSIZ

 .Pp
 .Em Remarks :
 this macro is sometimes abused to emulate optional arguments for
 .Pp
 .Em Remarks :
 this macro is sometimes abused to emulate optional arguments for


@@ -1365,7 +1369,7 @@ See also
 Encloses its arguments in curly braces.
 .Pp
 Examples:
 Encloses its arguments in curly braces.
 .Pp
 Examples:

-.D1 \&.Brq 1 , ... , \&Va n
+.Dl \&.Brq 1 , ... , \&Va n

 .Pp
 See also
 .Sx \&Bro .
 .Pp
 See also
 .Sx \&Bro .


@@ -1374,8 +1378,8 @@ Format the BSD/OS version provided as an argument, or a default value if
 no argument is provided.
 .Pp
 Examples:
 no argument is provided.
 .Pp
 Examples:

-.D1 \&.Bsx 1.0
-.D1 \&.Bsx
+.Dl \&.Bsx 1.0
+.Dl \&.Bsx

 .Pp
 See also
 .Sx \&At ,
 .Pp
 See also
 .Sx \&At ,


@@ -1394,8 +1398,8 @@ Format the BSD version provided as an argument, or a default value if no
 argument is provided.
 .Pp
 Examples:
 argument is provided.
 .Pp
 Examples:

-.D1 \&.Bx 4.4
-.D1 \&.Bx
+.Dl \&.Bx 4.4
+.Dl \&.Bx

 .Pp
 See also
 .Sx \&At ,
 .Pp
 See also
 .Sx \&At ,


@@ -1412,7 +1416,7 @@ This denotes strings accepted by
 .Xr config 8 .
 .Pp
 Examples:
 .Xr config 8 .
 .Pp
 Examples:

-.D1 \&.Cd device le0 at scode?
+.Dl \&.Cd device le0 at scode?

 .Pp
 .Em Remarks :
 this macro is commonly abused by using quoted literals to retain
 .Pp
 .Em Remarks :
 this macro is commonly abused by using quoted literals to retain


@@ -1425,8 +1429,8 @@ Command modifiers.
 Useful when specifying configuration options or keys.
 .Pp
 Examples:
 Useful when specifying configuration options or keys.
 .Pp
 Examples:

-.D1 \&.Cm ControlPath
-.D1 \&.Cm ControlMaster
+.Dl \&.Cm ControlPath
+.Dl \&.Cm ControlMaster

 .Pp
 See also
 .Sx \&Fl .
 .Pp
 See also
 .Sx \&Fl .


@@ -1437,7 +1441,7 @@ statements.
 It is followed by a newline.
 .Pp
 Examples:
 It is followed by a newline.
 .Pp
 Examples:

-.D1 \&.D1 \&Fl abcdefgh
+.Dl \&.D1 \&Fl abcdefgh

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


@@ -1476,9 +1480,9 @@ or instead a valid canonical date as specified by
 If a date does not conform or is empty, the current date is used.
 .Pp
 Examples:
 If a date does not conform or is empty, the current date is used.
 .Pp
 Examples:

-.D1 \&.Dd $\&Mdocdate$
-.D1 \&.Dd $\&Mdocdate: July 21 2007$
-.D1 \&.Dd July 21, 2007
+.Dl \&.Dd $\&Mdocdate$
+.Dl \&.Dd $\&Mdocdate: July 21 2007$
+.Dl \&.Dd July 21, 2007

 .Pp
 See also
 .Sx \&Dt
 .Pp
 See also
 .Sx \&Dt


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

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

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


@@ -1643,6 +1647,7 @@ It must be one of
 .Ar luna88k ,
 .Ar mac68k ,
 .Ar macppc ,
 .Ar luna88k ,
 .Ar mac68k ,
 .Ar macppc ,

+.Ar mips64 ,

 .Ar mvme68k ,
 .Ar mvme88k ,
 .Ar mvmeppc ,
 .Ar mvme68k ,
 .Ar mvme88k ,
 .Ar mvmeppc ,


@@ -1658,9 +1663,9 @@ or
 .El
 .Pp
 Examples:
 .El
 .Pp
 Examples:

-.D1 \&.Dt FOO 1
-.D1 \&.Dt FOO 4 KM
-.D1 \&.Dt FOO 9 i386
+.Dl \&.Dt FOO 1
+.Dl \&.Dt FOO 4 KM
+.Dl \&.Dt FOO 9 i386

 .Pp
 See also
 .Sx \&Dd
 .Pp
 See also
 .Sx \&Dd


@@ -1670,8 +1675,8 @@ and
 Defined variables such as preprocessor constants.
 .Pp
 Examples:
 Defined variables such as preprocessor constants.
 .Pp
 Examples:

-.D1 \&.Dv BUFSIZ
-.D1 \&.Dv STDOUT_FILENO
+.Dl \&.Dv BUFSIZ
+.Dl \&.Dv STDOUT_FILENO

 .Pp
 See also
 .Sx \&Er .
 .Pp
 See also
 .Sx \&Er .


@@ -1680,8 +1685,8 @@ Format the DragonFly BSD version provided as an argument, or a default
 value if no argument is provided.
 .Pp
 Examples:
 value if no argument is provided.
 .Pp
 Examples:

-.D1 \&.Dx 2.4.1
-.D1 \&.Dx
+.Dl \&.Dx 2.4.1
+.Dl \&.Dx

 .Pp
 See also
 .Sx \&At ,
 .Pp
 See also
 .Sx \&At ,


@@ -1727,8 +1732,8 @@ Note that this is a presentation term and should not be used for
 stylistically decorating technical terms.
 .Pp
 Examples:
 stylistically decorating technical terms.
 .Pp
 Examples:

-.D1 \&.Em Warnings!
-.D1 \&.Em Remarks :
+.Dl \&.Em Warnings!
+.Dl \&.Em Remarks :

 .Pp
 See also
 .Sx \&Bf ,
 .Pp
 See also
 .Sx \&Bf ,


@@ -1753,8 +1758,8 @@ will emulate
 Display error constants.
 .Pp
 Examples:
 Display error constants.
 .Pp
 Examples:

-.D1 \&.Er EPERM
-.D1 \&.Er ENOENT
+.Dl \&.Er EPERM
+.Dl \&.Er ENOENT

 .Pp
 See also
 .Sx \&Dv .
 .Pp
 See also
 .Sx \&Dv .


@@ -1765,8 +1770,8 @@ Environmental variables such as those specified in
 .Xr environ 7 .
 .Pp
 Examples:
 .Xr environ 7 .
 .Pp
 Examples:

-.D1 \&.Ev DISPLAY
-.D1 \&.Ev PATH
+.Dl \&.Ev DISPLAY
+.Dl \&.Ev PATH

 .Ss \&Ex
 Insert a standard sentence regarding exit values.
 Its syntax is as follows:
 .Ss \&Ex
 Insert a standard sentence regarding exit values.
 Its syntax is as follows:


@@ -1806,9 +1811,9 @@ Furthermore, if the following macro is another
 the last argument will also have a trailing comma.
 .Pp
 Examples:
 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
+.Dl \&.Fa \(dqconst char *p\(dq
+.Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq
+.Dl \&.Fa foo

 .Pp
 See also
 .Sx \&Fo .
 .Pp
 See also
 .Sx \&Fo .


@@ -1836,10 +1841,10 @@ If the argument is a macro, a hyphen is prefixed to the subsequent macro
 output.
 .Pp
 Examples:
 output.
 .Pp
 Examples:

-.D1 \&.Fl a b c
-.D1 \&.Fl \&Pf a b
-.D1 \&.Fl
-.D1 \&.Op \&Fl o \&Ns \&Ar file
+.Dl \&.Fl a b c
+.Dl \&.Fl \&Pf a b
+.Dl \&.Fl
+.Dl \&.Op \&Fl o \&Ns \&Ar file

 .Pp
 See also
 .Sx \&Cm .
 .Pp
 See also
 .Sx \&Cm .


@@ -1858,14 +1863,17 @@ are delimited by commas.
 If no arguments are specified, blank parenthesis are output.
 .Pp
 Examples:
 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
+.Dl \&.Fn "int funcname" "int arg0" "int arg1"
+.Dl \&.Fn funcname "int arg0"
+.Dl \&.Fn funcname arg0

 .Bd -literal -offset indent -compact
 \&.Ft functype
 \&.Fn funcname
 .Ed
 .Pp
 .Bd -literal -offset indent -compact
 \&.Ft functype
 \&.Fn funcname
 .Ed
 .Pp

+When referring to a function documented in another manual page, use
+.Sx \&Xr
+instead.

 See also
 .Sx MANUAL STRUCTURE
 and
 See also
 .Sx MANUAL STRUCTURE
 and


@@ -1908,7 +1916,7 @@ Its syntax is as follows:
 .D1 Pf \. Sx \&Ft Cm functype
 .Pp
 Examples:
 .D1 Pf \. Sx \&Ft Cm functype
 .Pp
 Examples:

-.D1 \&.Ft int
+.Dl \&.Ft int

 .Bd -literal -offset indent -compact
 \&.Ft functype
 \&.Fn funcname
 .Bd -literal -offset indent -compact
 \&.Ft functype
 \&.Fn funcname


@@ -1926,8 +1934,8 @@ version provided as an argument, or a default value
 if no argument is provided.
 .Pp
 Examples:
 if no argument is provided.
 .Pp
 Examples:

-.D1 \&.Fx 7.1
-.D1 \&.Fx
+.Dl \&.Fx 7.1
+.Dl \&.Fx

 .Pp
 See also
 .Sx \&At ,
 .Pp
 See also
 .Sx \&At ,


@@ -1947,8 +1955,8 @@ This is similar to
 but used for instructions rather than values.
 .Pp
 Examples:
 but used for instructions rather than values.
 .Pp
 Examples:

-.D1 \&.Ic hash
-.D1 \&.Ic alias
+.Dl \&.Ic hash
+.Dl \&.Ic alias

 .Pp
 Note that using
 .Sx \&Bd Fl literal
 .Pp
 Note that using
 .Sx \&Bd Fl literal


@@ -1969,7 +1977,7 @@ preceded by
 the arguments is enclosed in angle brackets.
 .Pp
 Examples:
 the arguments is enclosed in angle brackets.
 .Pp
 Examples:

-.D1 \&.In sys/types
+.Dl \&.In sys/types

 .Pp
 See also
 .Sx MANUAL STRUCTURE .
 .Pp
 See also
 .Sx MANUAL STRUCTURE .


@@ -2049,7 +2057,7 @@ phrases on an
 .Sx \&It ,
 for example,
 .Pp
 .Sx \&It ,
 for example,
 .Pp

-.D1 .It \(dqcol1 ; <TAB> col2 ;\(dq \&;
+.Dl .It \(dqcol1 ; <TAB> col2 ;\(dq \&;

 .Pp
 will preserve the semicolon whitespace except for the last.
 .Pp
 .Pp
 will preserve the semicolon whitespace except for the last.
 .Pp


@@ -2076,8 +2084,8 @@ section as described in
 .Sx MANUAL STRUCTURE .
 .Pp
 Examples:
 .Sx MANUAL STRUCTURE .
 .Pp
 Examples:

-.D1 \&.Lb libz
-.D1 \&.Lb mdoc
+.Dl \&.Lb libz
+.Dl \&.Lb mdoc

 .Ss \&Li
 Denotes text that should be in a literal font mode.
 Note that this is a presentation term and should not be used for
 .Ss \&Li
 Denotes text that should be in a literal font mode.
 Note that this is a presentation term and should not be used for


@@ -2095,8 +2103,8 @@ Its syntax is as follows:
 .D1 Pf \. Sx \&Lk Cm uri Op Cm name
 .Pp
 Examples:
 .D1 Pf \. Sx \&Lk Cm uri Op Cm name
 .Pp
 Examples:

-.D1 \&.Lk http://bsd.lv \*qThe BSD.lv Project\*q
-.D1 \&.Lk http://bsd.lv
+.Dl \&.Lk http://bsd.lv \*qThe BSD.lv Project\*q
+.Dl \&.Lk http://bsd.lv

 .Pp
 See also
 .Sx \&Mt .
 .Pp
 See also
 .Sx \&Mt .


@@ -2110,8 +2118,8 @@ Its syntax is as follows:
 .D1 Pf \. Sx \&Ms Cm symbol
 .Pp
 Examples:
 .D1 Pf \. Sx \&Ms Cm symbol
 .Pp
 Examples:

-.D1 \&.Ms sigma
-.D1 \&.Ms aleph
+.Dl \&.Ms sigma
+.Dl \&.Ms aleph

 .Ss \&Mt
 Format a
 .Dq mailto:
 .Ss \&Mt
 Format a
 .Dq mailto:


@@ -2121,7 +2129,7 @@ Its syntax is as follows:
 .D1 Pf \. Sx \&Mt Cm address
 .Pp
 Examples:
 .D1 Pf \. Sx \&Mt Cm address
 .Pp
 Examples:

-.D1 \&.Mt discuss@manpages.bsd.lv
+.Dl \&.Mt discuss@manpages.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


@@ -2131,8 +2139,8 @@ section subsequent the
 macro.
 .Pp
 Examples:
 macro.
 .Pp
 Examples:

-.D1 \&.Sx \&Nd mdoc language reference
-.D1 \&.Sx \&Nd format and display UNIX manuals
+.Dl \&.Sx \&Nd mdoc language reference
+.Dl \&.Sx \&Nd format and display UNIX manuals

 .Pp
 The
 .Sx \&Nd
 .Pp
 The
 .Sx \&Nd


@@ -2189,14 +2197,14 @@ A
 macro used to terminate prior macro contexts.
 .Pp
 Examples:
 macro used to terminate prior macro contexts.
 .Pp
 Examples:

-.D1 \&.Sx \&Fl ab \&No cd \&Fl ef
+.Dl \&.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:
 .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
+.Dl \&.Fl o \&Ns \&Ar output

 .Pp
 See also
 .Sx \&No
 .Pp
 See also
 .Sx \&No


@@ -2209,8 +2217,8 @@ version provided as an argument, or a default value if
 no argument is provided.
 .Pp
 Examples:
 no argument is provided.
 .Pp
 Examples:

-.D1 \&.Nx 5.01
-.D1 \&.Nx
+.Dl \&.Nx 5.01
+.Dl \&.Nx

 .Pp
 See also
 .Sx \&At ,
 .Pp
 See also
 .Sx \&At ,


@@ -2241,8 +2249,8 @@ Used when listing options to command-line utilities.
 Prints the argument(s) in brackets.
 .Pp
 Examples:
 Prints the argument(s) in brackets.
 .Pp
 Examples:

-.D1 \&.Op \&Fl a \&Ar b
-.D1 \&.Op \&Ar a | b
+.Dl \&.Op \&Fl a \&Ar b
+.Dl \&.Op \&Ar a | b

 .Pp
 See also
 .Sx \&Oo .
 .Pp
 See also
 .Sx \&Oo .


@@ -2263,9 +2271,9 @@ Left unspecified, it defaults to the local operating system version.
 This is the suggested form.
 .Pp
 Examples:
 This is the suggested form.
 .Pp
 Examples:

-.D1 \&.Os
-.D1 \&.Os KTH/CSC/TCS
-.D1 \&.Os BSD 4.3
+.Dl \&.Os
+.Dl \&.Os KTH/CSC/TCS
+.Dl \&.Os BSD 4.3

 .Pp
 See also
 .Sx \&Dd
 .Pp
 See also
 .Sx \&Dd


@@ -2283,8 +2291,8 @@ version provided as an argument, or a default value
 if no argument is provided.
 .Pp
 Examples:
 if no argument is provided.
 .Pp
 Examples:

-.D1 \&.Ox 4.5
-.D1 \&.Ox
+.Dl \&.Ox 4.5
+.Dl \&.Ox

 .Pp
 See also
 .Sx \&At ,
 .Pp
 See also
 .Sx \&At ,


@@ -2297,10 +2305,13 @@ and
 .Sx \&Ux .
 .Ss \&Pa
 A file-system path.
 .Sx \&Ux .
 .Ss \&Pa
 A file-system path.

+If an argument is not provided, the string
+.Dq \(ti
+is used as a default.

 .Pp
 Examples:
 .Pp
 Examples:

-.D1 \&.Pa /usr/bin/mandoc
-.D1 \&.Pa /usr/share/man/man7/mdoc.7
+.Dl \&.Pa /usr/bin/mandoc
+.Dl \&.Pa /usr/share/man/man7/mdoc.7

 .Pp
 See also
 .Sx \&Lk .
 .Pp
 See also
 .Sx \&Lk .


@@ -2320,7 +2331,7 @@ The
 argument may be a macro.
 .Pp
 Examples:
 argument may be a macro.
 .Pp
 Examples:

-.D1 \&.Pf \e. \&Sx \&Pf \&Cm prefix suffix
+.Dl \&.Pf \e. \&Sx \&Pf \&Cm prefix suffix

 .Ss \&Po
 Multi-line version of
 .Sx \&Pq .
 .Ss \&Po
 Multi-line version of
 .Sx \&Pq .


@@ -2580,7 +2591,12 @@ The referenced section or sub-section name must be identical to the
 enclosed argument, including whitespace.
 .Pp
 Examples:
 enclosed argument, including whitespace.
 .Pp
 Examples:

-.D1 \&.Sx MANUAL STRUCTURE
+.Dl \&.Sx MANUAL STRUCTURE
+.Pp
+See also
+.Sx \&Sh
+and
+.Sx \&Ss .

 .Ss \&Sy
 Format enclosed arguments in symbolic
 .Pq Dq boldface .
 .Ss \&Sy
 Format enclosed arguments in symbolic
 .Pq Dq boldface .


@@ -2596,7 +2612,7 @@ and
 Format a tradename.
 .Pp
 Examples:
 Format a tradename.
 .Pp
 Examples:

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

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


@@ -2605,7 +2621,7 @@ Format the UNIX name.
 Accepts no argument.
 .Pp
 Examples:
 Accepts no argument.
 .Pp
 Examples:

-.D1 \&.Ux
+.Dl \&.Ux

 .Pp
 See also
 .Sx \&At ,
 .Pp
 See also
 .Sx \&At ,


@@ -2620,8 +2636,8 @@ and
 A variable name.
 .Pp
 Examples:
 A variable name.
 .Pp
 Examples:

-.D1 \&.Va foo
-.D1 \&.Va const char *bar ;
+.Dl \&.Va foo
+.Dl \&.Va const char *bar ;

 .Ss \&Vt
 A variable type.
 This is also used for indicating global variables in the
 .Ss \&Vt
 A variable type.
 This is also used for indicating global variables in the


@@ -2640,8 +2656,8 @@ Note that this should not be confused with
 which is used for function return types.
 .Pp
 Examples:
 which is used for function return types.
 .Pp
 Examples:

-.D1 \&.Vt unsigned char
-.D1 \&.Vt extern const char * const sys_signame[] \&;
+.Dl \&.Vt unsigned char
+.Dl \&.Vt extern const char * const sys_signame[] \&;

 .Pp
 See also
 .Sx MANUAL STRUCTURE
 .Pp
 See also
 .Sx MANUAL STRUCTURE


@@ -2651,9 +2667,13 @@ and
 Close a scope opened by
 .Sx \&Xo .
 .Ss \&Xo
 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.
+Extend the header of an
+.Sx \&It
+macro or the body of a partial-implicit block macro
+beyond the end of the input line.
+This macro originally existed to work around the 9-argument limit
+of historic
+.Xr roff 7 .

 .Ss \&Xr
 Link to another manual
 .Pq Qq cross-reference .
 .Ss \&Xr
 Link to another manual
 .Pq Qq cross-reference .


@@ -2675,9 +2695,9 @@ This behaviour is for compatibility with
 GNU troff.
 .Pp
 Examples:
 GNU troff.
 .Pp
 Examples:

-.D1 \&.Xr mandoc 1
-.D1 \&.Xr mandoc 1 \&;
-.D1 \&.Xr mandoc 1 \&Ns s behaviour
+.Dl \&.Xr mandoc 1
+.Dl \&.Xr mandoc 1 \&;
+.Dl \&.Xr mandoc 1 \&Ns s behaviour

 .Ss \&br
 Emits a line-break.
 This macro should not be used; it is implemented for compatibility with
 .Ss \&br
 Emits a line-break.
 This macro should not be used; it is implemented for compatibility with


@@ -2707,10 +2727,10 @@ troff implementations, at this time limited to GNU troff
 .Pq Qq groff .
 The term
 .Qq historic groff
 .Pq Qq groff .
 The term
 .Qq historic groff

-refers to groff versions before the
+refers to groff versions before 1.17,
+which featured a significant update of the

 .Pa doc.tmac
 .Pa doc.tmac

-file re-write
-.Pq somewhere between 1.15 and 1.19 .
+file.

 .Pp
 Heirloom troff, the other significant troff implementation accepting
 \-mdoc, is similar to historic groff.
 .Pp
 Heirloom troff, the other significant troff implementation accepting
 \-mdoc, is similar to historic groff.


@@ -2720,6 +2740,16 @@ The following problematic behaviour is found in groff:
 .Pp
 .Bl -dash -compact
 .It
 .Pp
 .Bl -dash -compact
 .It

+Display macros
+.Po
+.Sx \&Bd ,
+.Sx \&Dl ,
+and
+.Sx \&D1
+.Pc
+may not be nested.
+\*[hist]
+.It

 .Sx \&At
 with unknown arguments produces no output at all.
 \*[hist]
 .Sx \&At
 with unknown arguments produces no output at all.
 \*[hist]


@@ -2801,6 +2831,11 @@ can only be called by other macros, but not at the beginning of a line.
 .Sx \&%C
 is not implemented.
 .It
 .Sx \&%C
 is not implemented.
 .It

+Historic groff only allows up to eight or nine arguments per macro input
+line, depending on the exact situation.
+Providing more arguments causes garbled output.
+The number of arguments on one input line is not limited with mandoc.
+.It

 Historic groff has many un-callable macros.
 Most of these (excluding some block-level macros) are callable
 in new groff and mandoc.
 Historic groff has many un-callable macros.
 Most of these (excluding some block-level macros) are callable
 in new groff and mandoc.


@@ -2850,6 +2885,8 @@ The
 .Pq string length ,
 .Sq \ek
 .Pq horizontal position marker ,
 .Pq string length ,
 .Sq \ek
 .Pq horizontal position marker ,

+.Sq \eo
+.Pq text overstrike ,

 and
 .Sq \es
 .Pq text size
 and
 .Sq \es
 .Pq text size


@@ -2864,6 +2901,7 @@ standalone double-quote in formatted output.
 This is not supported by mandoc.
 .El
 .Sh SEE ALSO
 This is not supported by mandoc.
 .El
 .Sh SEE ALSO

+.Xr man 1 ,

 .Xr mandoc 1 ,
 .Xr mandoc_char 7
 .Sh HISTORY
 .Xr mandoc 1 ,
 .Xr mandoc_char 7
 .Sh HISTORY