-.\" $Id: mdoc.7,v 1.142 2010/07/26 13:45:49 kristaps Exp $
+.\" $Id: mdoc.7,v 1.169 2010/12/06 16:37:32 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: July 26 2010 $
+.Dd $Mdocdate: December 6 2010 $
.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
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 \.
\&.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.
See
.Sx \&St .
.It Em HISTORY
-The history of any manual without a
-.Em STANDARDS
-section should be described in this section.
+A brief history of the subject, including where support first appeared.
.It Em AUTHORS
-Credits to authors, if applicable, should appear in this section.
+Credits to the person or persons who wrote the code and/or documentation.
Authors should generally be noted by both name and email address.
.Pp
See
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
argument are equivalent, as are
.Fl symbolic
and
-.Cm \&Sy,
+.Cm \&Sy ,
and
.Fl literal
and
.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.
.Ar luna88k ,
.Ar mac68k ,
.Ar macppc ,
+.Ar mips64 ,
.Ar mvme68k ,
.Ar mvme88k ,
.Ar mvmeppc ,
\&.Fn funcname
.Ed
.Pp
+When referring to a function documented in another manual page, use
+.Sx \&Xr
+instead.
See also
.Sx MANUAL STRUCTURE
and
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 \&.Ic alias
.Pp
Note that using
-.Sx \&Bd No Fl literal
+.Sx \&Bd Fl literal
or
.Sx \&D1
is preferred for displaying code; the
.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 \*qThe BSD.lv Project\*q
.D1 \&.Lk http://bsd.lv
.Pp
See also
Format a
.Dq mailto:
hyperlink.
+If an argument is not provided, the string
+.Dq \(ti
+is used as a default.
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&Mt Cm address
Examples:
.D1 \&.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
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:
file.
Its syntax is as follows:
.Pp
-.D1 Pf \. Sx \&Os Op Cm system
+.D1 Pf \. Sx \&Os Op Cm system Op Cm version
.Pp
The optional
.Cm system
.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:
.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 \&.Tn IBM
.Ss \&Ud
Prints out
-.Dq currently under development.
+.Dq currently under development .
.Ss \&Ux
Format the UNIX name.
Accepts no argument.
.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
.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
+.Pq Sx \&Bd , Sx \&Dl , and Sx \&D1
+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
+.Sq \(ba
+(vertical bar) is not fully supported as a delimiter.
+\*[hist]
.It
-groff behaves irregularly when specifying
.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 .
+.Fl offset Ar right .
+Groff does not implement centered and flush-right rendering either,
+but produces large indentations.
.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.
-.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 mandoc_char 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