-.\" $Id: mdoc.7,v 1.144 2010/08/06 17:09:58 schwarze Exp $
+.\" $Id: mdoc.7,v 1.179 2011/02/07 00:05:40 schwarze Exp $
.\"
-.\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
+.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
.\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" 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: February 7 2011 $
.Dt MDOC 7
.Os
.Sh NAME
.Nm
documents may contain only graphable 7-bit ASCII characters, the space
character, and, in certain circumstances, the tab character.
-All manuals must have
-.Ux
-line terminators.
+.Pp
+If the first character of a line is a space, that line is printed
+with a leading newline.
.Ss Comments
Text following a
.Sq \e\*q ,
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
By doing so, front-ends will be able to apply the proper amount of
spacing after the end of sentence (unescaped) period, exclamation mark,
or question mark followed by zero or more non-sentence closing
-delimiters (
-.Ns Sq \&) ,
+delimiters
+.Po
+.Sq \&) ,
.Sq \&] ,
.Sq \&' ,
-.Sq \&" ) .
+.Sq \&"
+.Pc .
.Pp
The proper spacing is also intelligently preserved if a sentence ends at
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 an
.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 *"
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
.It Sx \&%T Ta \&No Ta \&No Ta >0
.It Sx \&%U Ta \&No Ta \&No Ta >0
.It Sx \&%V Ta \&No Ta \&No Ta >0
-.It Sx \&Ad Ta Yes Ta Yes Ta n
-.It Sx \&An Ta Yes Ta Yes Ta n
+.It Sx \&Ad Ta Yes Ta Yes Ta >0
+.It Sx \&An Ta Yes Ta Yes Ta >0
.It Sx \&Ap Ta Yes Ta Yes Ta 0
.It Sx \&Ar Ta Yes Ta Yes Ta n
.It Sx \&At Ta Yes Ta Yes Ta 1
.It Sx \&Bt Ta \&No Ta \&No Ta 0
.It Sx \&Bx Ta Yes Ta Yes Ta n
.It Sx \&Cd Ta Yes Ta Yes Ta >0
-.It Sx \&Cm Ta Yes Ta Yes Ta n
+.It Sx \&Cm Ta Yes Ta Yes Ta >0
.It Sx \&Db Ta \&No Ta \&No Ta 1
.It Sx \&Dd Ta \&No Ta \&No Ta n
.It Sx \&Dt Ta \&No Ta \&No Ta n
-.It Sx \&Dv Ta Yes Ta Yes Ta n
+.It Sx \&Dv Ta Yes Ta Yes Ta >0
.It Sx \&Dx Ta Yes Ta Yes Ta n
.It Sx \&Em Ta Yes Ta Yes Ta >0
.It Sx \&En Ta \&No Ta \&No Ta 0
.It Sx \&Er Ta Yes Ta Yes Ta >0
.It Sx \&Es Ta \&No Ta \&No Ta 0
-.It Sx \&Ev Ta Yes Ta Yes Ta n
+.It Sx \&Ev Ta Yes Ta Yes Ta >0
.It Sx \&Ex Ta \&No Ta \&No Ta n
-.It Sx \&Fa Ta Yes Ta Yes Ta n
+.It Sx \&Fa Ta Yes Ta Yes Ta >0
.It Sx \&Fd Ta \&No Ta \&No Ta >0
.It Sx \&Fl Ta Yes Ta Yes Ta n
.It Sx \&Fn Ta Yes Ta Yes Ta >0
.It Sx \&Fr Ta \&No Ta \&No Ta n
-.It Sx \&Ft Ta Yes Ta Yes Ta n
+.It Sx \&Ft Ta Yes Ta Yes Ta >0
.It Sx \&Fx Ta Yes Ta Yes Ta n
.It Sx \&Hf Ta \&No Ta \&No Ta n
.It Sx \&Ic Ta Yes Ta Yes Ta >0
.It Sx \&In Ta \&No Ta \&No Ta n
.It Sx \&Lb Ta \&No Ta \&No Ta 1
-.It Sx \&Li Ta Yes Ta Yes Ta n
-.It Sx \&Lk Ta Yes Ta Yes Ta n
+.It Sx \&Li Ta Yes Ta Yes Ta >0
+.It Sx \&Lk Ta Yes Ta Yes Ta >0
.It Sx \&Lp Ta \&No Ta \&No Ta 0
.It Sx \&Ms Ta Yes Ta Yes Ta >0
.It Sx \&Mt Ta Yes Ta Yes Ta >0
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 ,
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 ,
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
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 Fl literal
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.
This may only be invoked in 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
+This has no effect when invoked at the start of a macro line.
+.Pp
Examples:
-.D1 \&.Fl o \&Ns \&Ar output
+.Dl \&.Fl o \&Ns \&Ar output
.Pp
See also
.Sx \&No
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
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 .
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.
+for the normalised behaviour in mandoc.
.It
-Historic groff does not break before an
-.Sx \&Fn
-when not invoked as the line macro in the
-.Em SYNOPSIS
-section.
-.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
-The comment syntax
-.Sq \e\."
-is no longer accepted.
+.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
+.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
+.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
-groff behaves irregularly when specifying
+.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 pairwise 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