-.\" $Id: mdoc.7,v 1.75 2009/11/06 10:31:31 kristaps Exp $
+.\" $Id: mdoc.7,v 1.84 2010/02/17 19:22:50 kristaps Exp $
.\"
.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
.\"
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: November 6 2009 $
+.Dd $Mdocdate: February 17 2010 $
.Dt MDOC 7
.Os
.
Terms may be text-decorated using the
.Sq \ef
escape followed by an indicator: B (bold), I, (italic), R (Roman), or P
-(revert to previous mode). A numerical representation 3, 2, or 1
-(bold, italic, and Roman, respectively) may be used instead.
+(revert to previous mode):
.Pp
-These form is not recommended for
+.D1 \efBbold\efR \efIitalic\efP
+.Pp
+A numerical representation 3, 2, or 1 (bold, italic, and Roman,
+respectively) may be used instead. A text decoration is valid within
+the current font scope only: if a macro opens a font scope alongside
+its own scope, such as
+.Sx \&Bf
+.Cm \&Sy ,
+in-scope invocations of
+.Sq \ef
+are only valid within the font scope of the macro. If
+.Sq \ef
+is specified outside of any font scope, such as in unenclosed, free-form
+text, it will affect the remainder of the document.
+.Pp
+Text may also be sized with the
+.Sq \es
+escape, whose syntax is one of
+.Sq \es+-n
+for one-digit numerals;
+.Sq \es(+-nn
+or
+.Sq \es+-(nn
+for two-digit numerals; and
+.Sq \es[+-N] ,
+.Sq \es+-[N] ,
+.Sq \es'+-N' ,
+or
+.Sq \es+-'N'
+for arbitrary-digit numerals:
+.Pp
+.D1 \es+1bigger\es-1
+.D1 \es[+10]much bigger\es[-10]
+.D1 \es+(10much bigger\es-(10
+.D1 \es+'100'much much bigger\es-'100'
+.Pp
+Note these forms are
+.Em not
+recommended for
.Nm ,
which encourages semantic annotation.
.
.
.Ss Predefined Strings
-Historically,
+Historically,
.Xr groff 1
-also defined a set of package-specific
+also defined a set of package-specific
.Dq predefined strings ,
-which, like
+which, like
.Sx Special Characters ,
demark special output characters and strings by way of input codes.
Predefined strings are escaped with the slash-asterisk,
.Sx \&Os
macros, is required for every document.
.Pp
-The first section (sections are denoted by
+The first section (sections are denoted by
.Sx \&Sh )
must be the NAME section, consisting of at least one
.Sx \&Nm
macro(s) must precede the
.Sx \&Nd
macro.
+.Pp
+See
+.Sx \&Nm
+and
+.Sx \&Nd .
.
.It Em LIBRARY
The name of the library containing the documented material, which is
.Ed
.Pp
See
-.Sx \&Lb
-for details.
+.Sx \&Lb .
.
.It Em SYNOPSIS
Documents the utility invocation syntax, function call syntax, or device
-configuration.
+configuration.
.Pp
For the first, utilities (sections 1, 6, and 8), this is
generally structured as follows:
\&.Cd \*qit* at isa? port 0x4e\*q
.Ed
.Pp
-Manuals not in these sections generally don't need a
+Manuals not in these sections generally don't need a
.Em SYNOPSIS .
+.Pp
+See
+.Sx \&Op ,
+.Sx \&Cd ,
+.Sx \&Fn ,
+.Sx \&Ft ,
+and
+.Sx \&Vt .
.
.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
command), such as:
Print verbose information.
\&.El
.Ed
+.Pp
Manuals not documenting a command won't include the above fragment.
.
.It Em IMPLEMENTATION NOTES
discouraged.
.Pp
See
-.Sx \&Bl No \-diag .
+.Sx \&Bl
+.Fl diag .
.
.It Em ERRORS
Documents error handling in sections 2, 3, and 9.
don't have heads; only one
.Po
.Sx \&It Fl column
-.Pc
+.Pc
has multiple heads.
.Bd -literal -offset indent
\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
.It Sx \&Ql Ta Yes Ta Yes
.It Sx \&Qq Ta Yes Ta Yes
.It Sx \&Sq Ta Yes Ta Yes
+.It Sx \&Vt Ta Yes Ta Yes
.El
+.Pp
+Note that the
+.Sx \&Vt
+macro is a
+.Sx Block partial-implicit
+only when invoked as the first macro
+in a SYNOPSIS section line, else it is
+.Sx In-line .
.
.
.Ss In-line
.It Sx \&Ux Ta Yes Ta Yes Ta n
.It Sx \&Va Ta Yes Ta Yes Ta n
.It Sx \&Vt Ta Yes Ta Yes Ta >0
-.It Sx \&Xr Ta Yes Ta Yes Ta >0, <3
+.It Sx \&Xr Ta Yes Ta Yes Ta >0
.It Sx \&br Ta \&No Ta \&No Ta 0
.It Sx \&sp Ta \&No Ta \&No Ta 1
-.El
+.El
.
.
.Sh REFERENCE
.Ed
.
.Ss \&Aq
-Encloses its arguments in angled brackets.
+Encloses its arguments in angled brackets.
.Pp
Examples:
.Bd -literal -offset indent
.Pp
Examples:
.Bd -literal -offset indent
-\&.At
+\&.At
\&.At V.1
.Ed
.Pp
.Ss \&Bf
.Ss \&Bk
.Ss \&Bl
-.
+.\" Begins a list composed of one or more list entries. A list entry is
+.\" specified by the
+.\" .Sx \&It
+.\" macro, which consists of a head and optional body. By default, a list
+.\" is preceded by a blank line. A list must specify one of the following
+.\" list types:
+.\" .Bl -tag -width 12n
+.\" .It Fl bullet
+.\" A list offset by a bullet. The head of list entries must be empty.
+.\" List entry bodies are justified after the bullet.
+.\" .It Fl column
+.\" A columnated list. The number of columns is specified as arguments to
+.\" the
+.\" .Sx \&Bl
+.\" macro (the deprecated form of following the invocation of
+.\" .Fl column
+.\" is also accepted). Arguments dictate the width of columns specified in
+.\" list entries. List entry bodies must be left empty. Columns specified
+.\" in the list entry head are justified to their position in the sequence
+.\" of columns.
+.\" .It Fl dash
+.\" A list offset by a dash (hyphen). The head of list entries must be
+.\" empty. List entry bodies are justified past the dash.
+.\" .It Fl diag
+.\" Like
+.\" .Fl inset
+.\" lists, but with additional formatting to the head.
+.\" .It Fl enum
+.\" A list offset by a number indicating list entry position. The head of
+.\" list entries must be empty. List entry bodies are justified past the
+.\" enumeration.
+.\" .It Fl hang
+.\" Like
+.\" .Fl tag ,
+.\" but instead of list bodies justifying to the head on the first line,
+.\" they trail the head text.
+.\" .It Fl hyphen
+.\" Synonym for
+.\" .Fl dash .
+.\" .It Fl inset
+.\" Like
+.\" .Fl tag ,
+.\" but list entry bodies aren't justified.
+.\" .It Fl item
+.\" An un-justified list. This produces blocks of text.
+.\" .It Fl ohang
+.\" List bodies are placed on the line following the head.
+.\" .It Fl tag
+.\" A list offset by list entry heads. List entry bodies are justified
+.\" after the head.
+.\" .El
+.\" .Pp
+.\" More...
+.\" .
.Ss \&Bo
Begins a block enclosed by square brackets. Does not have any head
arguments.
.Sx \&Bq .
.
.Ss \&Bq
-Encloses its arguments in square brackets.
+Encloses its arguments in square brackets.
.Pp
Examples:
.Bd -literal -offset indent
.Pp
.D1 \. Ns Sx \&Dd Cm date
.Pp
-The
+The
.Cm date
field may be either
.Ar $\&Mdocdate$ ,
.Sx \&Dq .
.
.Ss \&Dq
-Encloses its arguments in double quotes.
+Encloses its arguments in double quotes.
.Pp
Examples:
.Bd -literal -offset indent
.Ss \&Fc
.Ss \&Fd
.Ss \&Fl
+Command-line flag. Used when listing arguments to command-line
+utilities. Prints a fixed-width hyphen
+.Sq \-
+before each delimited argument. If no arguments are provided, a hyphen
+is still printed.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Fl a b c
+\&.Fl
+\&.Op Fl o Ns Ar file
+.Ed
+.Pp
+See also
+.Sx \&Cm .
+.
.Ss \&Fn
.Ss \&Fo
.Ss \&Fr
.
.Ss \&Va
.Ss \&Vt
+A variable type. This is also used for indicating global variables in the
+SYNOPSIS section, in which case a variable name is also specified. Note that
+it accepts
+.Sx Block partial-implicit
+syntax when invoked as the first macro in the SYNOPSIS section, else it
+accepts ordinary
+.Sx In-line
+syntax.
+.Pp
+Note that this should not be confused with
+.Sx \&Ft ,
+which is used for function return types.
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Vt unsigned char
+\&.Vt extern const char * const sys_signame[] ;
+.Ed
+.Pp
+See also
+.Sx \&Ft
+and
+.Sx \&Va .
+.
.Ss \&Xc
.Ss \&Xo
.Ss \&Xr
+Link to another manual
+.Pq Qq cross-reference .
+Its calling syntax is
+.Pp
+.D1 \. Ns Sx \&Xr Cm name section
+.Pp
+The
+.Cm name
+and
+.Cm section
+are the name and section of the linked manual. If
+.Cm section
+is followed by non-punctuation, an
+.Sx \&Ns
+is inserted into the token stream. This behaviour is for compatibility
+with
+.Xr groff 1 .
+.Pp
+Examples:
+.Bd -literal -offset indent
+\&.Xr mandoc 1
+\&.Xr mandoc 1 ;
+\&.Xr mandoc 1 s behaviour
+.Ed
+.
.Ss \&br
.Ss \&sp
.
.Pp
.Bl -dash -compact
.It
+The comment syntax
+.Sq \e."
+is no longer accepted.
+.It
+In
+.Xr groff 1 ,
+the
+.Sx \&Pa
+macro does not format its arguments when used in the FILES section under
+certain list types. This irregular behaviour has been discontinued.
+.It
+Historic
+.Xr groff 1
+does not print a dash for empty
+.Sx \&Fl
+arguments. This behaviour has been discontinued.
+.It
+.Xr groff 1
+behaves strangely (even between versions) when specifying
+.Sq \ef
+escapes within line-macro scopes. These aberrations have been
+normalised.
+.It
Negative scaling units are now truncated to zero instead of creating
interesting conditions, such as with
-.Sq \&sp -1i .
+.Sx \&sp
+.Fl 1i .
Furthermore, the
.Sq f
scaling unit, while accepted, is rendered as the default unit.
behaviour is no longer applicable.
.It
Display types
-.Sx \&Bd Fl center
+.Sx \&Bd
+.Fl center
and
.Fl right
are aliases for
.Qq go orbital
but is a proper delimiter in this implementation.
.It
-.Sx \&It Fl nested
+.Sx \&It
+.Fl nested
is assumed for all lists (it wasn't in historic groff): any list may be
nested and
.Fl enum
git.ckatri.com / mandoc.git / blobdiff