-.\" $Id: mdoc.7,v 1.143 2010/08/06 17:07:11 schwarze Exp $
+.\" $Id: mdoc.7,v 1.174 2011/01/04 23:32:21 kristaps Exp $
.\"
.\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
.\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
.\" 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 6 2010 $
+.Dd $Mdocdate: January 4 2011 $
.Dt MDOC 7
.Os
.Sh NAME
.Bx
.Ux
manuals.
-In this reference document, we describe its syntax, structure, and
+This reference document describes its syntax, structure, and
usage.
-Our reference implementation is mandoc; the
+The reference implementation is
+.Xr mandoc 1 ;
+the
.Sx COMPATIBILITY
section describes compatibility with other troff \-mdoc implementations.
.Pp
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
+Macro lines with only a control character and optional 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.
+or a single one character sequence.
See
.Xr mandoc_char 7
for a complete list.
.Ss Text Decoration
Terms may be text-decorated using the
.Sq \ef
-escape followed by an indicator: B (bold), I, (italic), R (Roman), or P
+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.
which encourages semantic annotation.
.Ss Predefined Strings
Historically,
-.Xr groff 1
+troff
also defined a set of package-specific
.Dq predefined strings ,
which, like
.Pq vertical bar .
.Ss Whitespace
Whitespace consists of the space character.
-In free-form lines, whitespace is preserved within a line; un-escaped
+In free-form lines, whitespace is preserved within a line; unescaped
trailing spaces are stripped from input (unless in a literal context).
Blank free-form lines, which may include whitespace, are only permitted
within literal contexts.
Macro arguments may be quoted with double-quotes 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
+The next double-quote not pairwise adjacent to another double-quote
terminates the literal, regardless of surrounding whitespace.
.Pp
Note that any quoted text, even if it would cause a macro invocation
See
.Sx COMPATIBILITY .
.Ss Sentence Spacing
-When composing a manual, make sure that your sentences end at the end of
+When composing a manual, make sure that 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,
.Sq \&" ) .
.Pp
The proper spacing is also intelligently preserved if a sentence ends at
-the boundary of a macro line, e.g.,
+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 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 For sections 2, 3, & 9 only.
+\&.\e\*q Not used in OpenBSD.
\&.Sh SYNOPSIS
\&.Nm foo
\&.Op Fl options
\&.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 The next is for sections 1, 6, 7, & 8 only.
+\&.\e\*q For sections 2, 3, & 9 only.
\&.\e\*q .Sh ENVIRONMENT
+\&.\e\*q For sections 1, 6, 7, & 8 only.
\&.\e\*q .Sh FILES
-\&.\e\*q The next is for sections 1 & 8 only.
\&.\e\*q .Sh EXIT STATUS
+\&.\e\*q For sections 1, 6, & 8 only.
\&.\e\*q .Sh EXAMPLES
-\&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.
\&.\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 For sections 2, 3, & 9 only.
\&.\e\*q .Sh SEE ALSO
\&.\e\*q .Xr foobar 1
\&.\e\*q .Sh STANDARDS
\&.\e\*q .Sh CAVEATS
\&.\e\*q .Sh BUGS
\&.\e\*q .Sh SECURITY CONSIDERATIONS
+\&.\e\*q Not used in OpenBSD.
.Ed
.Pp
-The sections in a
+The sections in an
.Nm
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 one-line description of the documented material.
+The name(s) and a one line description of the documented material.
The syntax for this as follows:
.Bd -literal -offset indent
-\&.Nm name0
-\&.Nm name1
+\&.Nm name0 ,
+\&.Nm name1 ,
\&.Nm name2
-\&.Nd a one-line description
+\&.Nd a one line description
.Ed
.Pp
The
.Pp
For the second, function calls (sections 2, 3, 9):
.Bd -literal -offset indent
-\&.Vt extern const char *global;
\&.In header.h
+\&.Vt extern const char *global;
\&.Ft "char *"
\&.Fn foo "const char *src"
\&.Ft "char *"
and
.Sx \&Ft .
All of these macros are output on their own line.
-If two such dissimilar macros are pair-wise invoked (except for
+If two such dissimilar macros are pairwise invoked (except for
.Sx \&Ft
before
.Sx \&Fo
.Sx \&Ss
macro or the end of an enclosing block, whichever comes first.
.It Em DESCRIPTION
-This expands upon the brief, one-line description in
+This expands upon the brief, one line description in
.Em NAME .
-It usually contains a break-down of the options (if documenting a
+It usually contains a breakdown of the options (if documenting a
command), such as:
.Bd -literal -offset indent
The arguments are as follows:
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.
+This section documents the
+return values of functions in sections 2, 3, and 9.
.Pp
See
.Sx \&Rv .
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.
+This section documents the
+command exit status for section 1, 6, and 8 utilities.
Historically, this information was described in
.Em DIAGNOSTICS ,
a practise that is now discouraged.
.It Em EXAMPLES
Example usages.
This often contains snippets of well-formed, well-tested invocations.
-Make doubly sure that your examples work properly!
+Make sure that examples work properly!
.It Em DIAGNOSTICS
Documents error conditions.
This is most useful in section 4 manuals.
Common misuses and misunderstandings should be explained
in this section.
.It Em BUGS
-Known bugs, limitations and work-arounds should be described
+Known bugs, limitations, and work-arounds should be described
in this section.
.It Em SECURITY CONSIDERATIONS
Documents any security precautions that operators should consider.
.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
-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
.Pq n ,
then the macro accepts an arbitrary number of arguments.
.Bd -literal -offset indent
-\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb
+\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB
\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
Publication city or location of an
.Sx \&Rs
block.
-.Pp
-.Em Remarks :
-this macro is not implemented in
-.Xr groff 1 .
.Ss \&%D
Publication date of an
.Sx \&Rs
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:
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:
-.D1 \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac
+.Dl \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac
.Pp
See also
.Sx \&Aq .
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:
-.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
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:
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 ,
argument are equivalent, as are
.Fl symbolic
and
-.Cm \&Sy,
+.Cm \&Sy ,
and
.Fl literal
and
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:
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
Encloses its arguments in curly braces.
.Pp
Examples:
-.D1 \&.Brq 1 , ... , \&Va n
+.Dl \&.Brq 1 , ... , \&Va n
.Pp
See also
.Sx \&Bro .
no argument is provided.
.Pp
Examples:
-.D1 \&.Bsx 1.0
-.D1 \&.Bsx
+.Dl \&.Bsx 1.0
+.Dl \&.Bsx
.Pp
See also
.Sx \&At ,
.Sx \&Ux .
.Ss \&Bt
Prints
-.Dq is currently in beta test.
+.Dq is currently in beta test .
.Ss \&Bx
Format the BSD version provided as an argument, or a default value if no
argument is provided.
.Pp
Examples:
-.D1 \&.Bx 4.4
-.D1 \&.Bx
+.Dl \&.Bx 4.4
+.Dl \&.Bx
.Pp
See also
.Sx \&At ,
.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
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 .
It is followed by a newline.
.Pp
Examples:
-.D1 \&.D1 \&Fl abcdefgh
+.Dl \&.D1 \&Fl abcdefgh
.Pp
See also
.Sx \&Bd
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
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
.Ar luna88k ,
.Ar mac68k ,
.Ar macppc ,
+.Ar mips64 ,
.Ar mvme68k ,
.Ar mvme88k ,
.Ar mvmeppc ,
.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
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 .
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 ,
stylistically decorating technical terms.
.Pp
Examples:
-.D1 \&.Em Warnings!
-.D1 \&.Em Remarks :
+.Dl \&.Em Warnings!
+.Dl \&.Em Remarks :
.Pp
See also
.Sx \&Bf ,
Display error constants.
.Pp
Examples:
-.D1 \&.Er EPERM
-.D1 \&.Er ENOENT
+.Dl \&.Er EPERM
+.Dl \&.Er ENOENT
.Pp
See also
.Sx \&Dv .
.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:
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 .
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 .
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
+When referring to a function documented in another manual page, use
+.Sx \&Xr
+instead.
See also
.Sx MANUAL STRUCTURE
and
.D1 Pf \. Sx \&Ft Cm functype
.Pp
Examples:
-.D1 \&.Ft int
+.Dl \&.Ft int
.Bd -literal -offset indent -compact
\&.Ft functype
\&.Fn funcname
and
.Sx \&Fo .
.Ss \&Fx
-Format the FreeBSD version provided as an argument, or a default value
+Format the
+.Fx
+version provided as an argument, or a default value
if no argument is provided.
.Pp
Examples:
-.D1 \&.Fx 7.1
-.D1 \&.Fx
+.Dl \&.Fx 7.1
+.Dl \&.Fx
.Pp
See also
.Sx \&At ,
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 No Fl literal
+.Sx \&Bd Fl literal
or
.Sx \&D1
is preferred for displaying code; the
the arguments is enclosed in angle brackets.
.Pp
Examples:
-.D1 \&.In sys/types
+.Dl \&.In sys/types
.Pp
See also
.Sx MANUAL STRUCTURE .
.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
.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
.D1 Pf \. Sx \&Lk Cm uri Op Cm name
.Pp
Examples:
-.D1 \&.Lk http://bsd.lv "The BSD.lv Project"
-.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 .
.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:
.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.
+A one line description of the manual's content.
This may only be invoked in the
.Em SYNOPSIS
section subsequent the
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
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:
-.D1 \&.Fl o \&Ns \&Ar output
+.Dl \&.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
+Format the
+.Nx
+version provided as an argument, or a default value if
no argument is provided.
.Pp
Examples:
-.D1 \&.Nx 5.01
-.D1 \&.Nx
+.Dl \&.Nx 5.01
+.Dl \&.Nx
.Pp
See also
.Sx \&At ,
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 .
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
.Em Remarks :
this macro has been deprecated.
.Ss \&Ox
-Format the OpenBSD version provided as an argument, or a default value
+Format the
+.Ox
+version provided as an argument, or a default value
if no argument is provided.
.Pp
Examples:
-.D1 \&.Ox 4.5
-.D1 \&.Ox
+.Dl \&.Ox 4.5
+.Dl \&.Ox
.Pp
See also
.Sx \&At ,
.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:
-.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 .
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 .
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 .
Format a tradename.
.Pp
Examples:
-.D1 \&.Tn IBM
+.Dl \&.Tn IBM
.Ss \&Ud
Prints out
-.Dq currently under development.
+.Dq currently under development .
.Ss \&Ux
Format the UNIX name.
Accepts no argument.
.Pp
Examples:
-.D1 \&.Ux
+.Dl \&.Ux
.Pp
See also
.Sx \&At ,
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
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
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 .
.Sx \&Ns
is inserted into the token stream.
This behaviour is for compatibility with
-.Xr groff 1 .
+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
.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
-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
+The following problematic behaviour is found in groff:
+.ds hist (Historic groff only.)
+.Pp
.Bl -dash -compact
.It
-An empty
-.Sq \&Dd
-macro in groff prints
+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]
+Newer groff and mandoc print
+.Qq AT&T UNIX
+and the arguments.
+.It
+.Sx \&Bd Fl column
+does not recognize trailing punctuation characters when they immediately
+precede tabulator characters, but treats them as normal text and
+outputs a space before them.
+.It
+.Sx \&Bd Fl ragged compact
+does not start a new line.
+\*[hist]
+.It
+.Sx \&Dd
+without an argument prints
.Dq Epoch .
In mandoc, it resolves to the current date.
.It
-The \es (font size), \em (font colour), and \eM (font filling colour)
-font decoration escapes are all discarded in mandoc.
+.Sx \&Fl
+does not print a dash for an empty argument.
+\*[hist]
.It
-Old groff fails to assert a newline before
-.Sx \&Bd Fl ragged compact .
+.Sx \&Fn
+does not start a new line unless invoked as the line macro in the
+.Em SYNOPSIS
+section.
+\*[hist]
.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.
+with
+.Pf non- Sx \&Fa
+children causes inconsistent spacing between arguments.
+In mandoc, a single space is always inserted between arguments.
.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
+.Em SYNOPSIS
+causes inconsistent vertical spacing, 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.
+for the normalised behaviour in mandoc.
.It
-Historic groff formats the
.Sx \&In
-badly: trailing arguments are trashed and
-.Em SYNOPSIS
-is not specially treated.
+ignores additional arguments and is not treated specially in the
+.Em SYNOPSIS .
+\*[hist]
.It
-groff does not accept the
-.Sq \&Ta
-pseudo-macro as a line macro.
-mandoc does.
+.Sx \&It
+sometimes requires a
+.Fl nested
+flag.
+\*[hist]
+In new groff and mandoc, any list may be nested by default and
+.Fl enum
+lists will restart the sequence only for the sub-list.
+.It
+.Sx \&Li
+followed by a reserved character is incorrectly used in some manuals
+instead of properly quoting that character, which sometimes works with
+historic groff.
.It
-The comment syntax
-.Sq \e\."
-is no longer accepted.
+.Sx \&Lk
+only accepts a single link-name argument; the remainder is misformatted.
.It
-In groff, the
.Sx \&Pa
-macro does not format its arguments when used in the FILES section under
+does not format its arguments when used in the FILES section under
certain list types.
-mandoc does.
.It
-Historic groff does not print a dash for empty
-.Sx \&Fl
-arguments.
-mandoc and newer groff implementations do.
+.Sx \&Ta
+can only be called by other macros, but not at the beginning of a line.
.It
-groff behaves irregularly when specifying
+.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.
+.It
+.Sq \(ba
+(vertical bar) is not fully supported as a delimiter.
+\*[hist]
+.It
+.Sq \ef
+.Pq font face
+and
.Sq \ef
+.Pq font family face
.Sx Text Decoration
-within line-macro scopes.
-mandoc follows a consistent system.
+escapes behave irregularly when specified within line-macro scopes.
.It
-In mandoc, negative scaling units are truncated to zero; groff would
-move to prior lines.
-Furthermore, the
-.Sq f
-scaling unit, while accepted, is rendered as the default unit.
+Negative scaling units return to prior lines.
+Instead, mandoc truncates them to zero.
+.El
+.Pp
+The following features are unimplemented in mandoc:
+.Pp
+.Bl -dash -compact
.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.
+.Sx \&Bd
+.Fl file Ar file .
.It
-Display offsets
.Sx \&Bd
.Fl offset Ar center
and
-.Fl offset Ar right
-are disregarded in mandoc.
-Furthermore, troff specifies a
-.Fl file Ar file
-argument that is not supported in mandoc.
-Lastly, since text is not right-justified in mandoc (or even groff),
-.Fl ragged
-and
-.Fl filled
-are aliases, as are
-.Fl literal
-and
-.Fl unfilled .
-.It
-Historic groff has many un-callable macros.
-Most of these (excluding some block-level macros) are now callable.
-.It
-The vertical bar
-.Sq \(ba
-made historic groff
-.Qq go orbital
-but has been a proper delimiter since then.
-.It
-.Sx \&It Fl nested
-is assumed for all lists (it wasn't in historic groff): any list may be
-nested and
-.Fl enum
-lists will restart the sequence only for the sub-list.
-.It
-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.
+.Fl offset Ar right .
+Groff does not implement centered and flush-right rendering either,
+but produces large indentations.
.It
-In groff, the
-.Sx \&Cd ,
-.Sx \&Er ,
-.Sx \&Ex ,
+The
+.Sq \eh
+.Pq horizontal position ,
+.Sq \ev
+.Pq vertical position ,
+.Sq \em
+.Pq text colour ,
+.Sq \eM
+.Pq text filling colour ,
+.Sq \ez
+.Pq zero-length character ,
+.Sq \ew
+.Pq string length ,
+.Sq \ek
+.Pq horizontal position marker ,
+.Sq \eo
+.Pq text overstrike ,
and
-.Sx \&Rv
-macros were stipulated only to occur in certain manual sections.
-mandoc does not have these restrictions.
+.Sq \es
+.Pq text size
+escape sequences are all discarded in mandoc.
.It
-Newer groff and mandoc print
-.Qq AT&T UNIX
-prior to unknown arguments of
-.Sx \&At ;
-older groff did nothing.
+The
+.Sq \ef
+scaling unit is accepted by mandoc, but rendered as the default unit.
+.It
+In quoted literals, groff allows pairwise double-quotes to produce a
+standalone double-quote in formatted output.
+This is not supported by mandoc.
.El
.Sh SEE ALSO
+.Xr man 1 ,
.Xr mandoc 1 ,
+.Xr man 7 ,
.Xr mandoc_char 7
+.Xr roff 7 ,
+.Xr tbl 7
+.Sh HISTORY
+The
+.Nm
+language first appeared as a troff macro package in
+.Bx 4.4 .
+It was later significantly updated by Werner Lemberg and Ruslan Ermilov
+in groff-1.17.
+The standalone implementation that is part of the
+.Xr mandoc 1
+utility written by Kristaps Dzonsons appeared in
+.Ox 4.6 .
.Sh AUTHORS
The
.Nm
git.ckatri.com / mandoc.git / blobdiff