[BACK]Return to mdoc.7 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mdoc.7 between version 1.65 and 1.92

version 1.65, 2009/10/19 11:02:23 version 1.92, 2010/04/07 18:50:35
Line 131  and
Line 131  and
 .Ss Text Decoration  .Ss Text Decoration
 Terms may be text-decorated using the  Terms may be text-decorated using the
 .Sq \ef  .Sq \ef
 escape followed by an indicator: B (bold), I, (italic), or P and R  escape followed by an indicator: B (bold), I, (italic), R (Roman), or P
 (Roman, or reset).  This form is not recommended for  (revert to previous mode):
   .Pp
   .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 ,  .Nm ,
 which encourages semantic, not presentation, annotation.  which encourages semantic annotation.
 .  .
 .  .
 .Ss Predefined Strings  .Ss Predefined Strings
 Historically,  Historically,
 .Xr groff 1  .Xr groff 1
 also defined a set of package-specific  also defined a set of package-specific
 .Dq predefined strings ,  .Dq predefined strings ,
 which, like  which, like
 .Sx Special Characters ,  .Sx Special Characters ,
 demark special output characters and strings by way of input codes.  demark special output characters and strings by way of input codes.
 Predefined strings are escaped with the slash-asterisk,  Predefined strings are escaped with the slash-asterisk,
Line 210  considered literal text.  Thus, the following produces
Line 250  considered literal text.  Thus, the following produces
 In free-form mode, quotes are regarded as opaque text.  In free-form mode, quotes are regarded as opaque text.
 .  .
 .Ss Dates  .Ss Dates
 TODO.  There are several macros in
   .Nm
   that require a date argument.  The canonical form for dates is the
   American format:
   .Pp
   .D1 Cm Month Day , Year
   .Pp
   The
   .Cm Day
   value is an optionally zero-padded numeral.  The
   .Cm Month
   value is the full month name.  The
   .Cm Year
   value is the full four-digit year.
   .Pp
   Reduced form dates are broken-down canonical form dates:
   .Pp
   .D1 Cm Month , Year
   .D1 Cm Year
   .Pp
   Some examples of valid dates follow:
   .Pp
   .D1 "May, 2009" Pq reduced form
   .D1 "2009" Pq reduced form
   .D1 "May 20, 2009" Pq canonical form
 .  .
 .Ss Scaling Widths  .Ss Scaling Widths
 Many macros support scaled widths for their arguments, such as  Many macros support scaled widths for their arguments, such as
Line 267  is necessarily non-portable across output media.  See
Line 331  is necessarily non-portable across output media.  See
 .  .
 .  .
 .Sh MANUAL STRUCTURE  .Sh MANUAL STRUCTURE
 Each  A well-formed
 .Nm  .Nm
 document must begin with a document prologue, containing, in order,  document consists of a document prologue followed by one or more
   sections.
   .Pp
   The prologue, which consists of (in order) the
 .Sx \&Dd ,  .Sx \&Dd ,
 .Sx \&Dt ,  .Sx \&Dt ,
 and  and
 .Sx \&Os ,  .Sx \&Os
 then the NAME section containing at least one  macros, is required for every document.
   .Pp
   The first section (sections are denoted by
   .Sx \&Sh )
   must be the NAME section, consisting of at least one
 .Sx \&Nm  .Sx \&Nm
 followed by  followed by
 .Sx \&Nd :  .Sx \&Nd .
   .Pp
   Following that, convention dictates specifying at least the SYNOPSIS and
   DESCRIPTION sections, although this varies between manual sections.
   .Pp
   The following is a well-formed skeleton
   .Nm
   file:
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Dd $\&Mdocdate$  \&.Dd $\&Mdocdate$
 \&.Dt mdoc 7  \&.Dt mdoc 7
Line 320  utility processes files ...
Line 398  utility processes files ...
 \&.\e\*q .Sh BUGS  \&.\e\*q .Sh BUGS
 \&.\e\*q .Sh SECURITY CONSIDERATIONS  \&.\e\*q .Sh SECURITY CONSIDERATIONS
 .Ed  .Ed
   .Pp
   The sections in a
   .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 short description of the documented material.  The
   syntax for this as follows:
   .Bd -literal -offset indent
   \&.Nm name0
   \&.Nm name1
   \&.Nm name2
   \&.Nd a short description
   .Ed
   .Pp
   The
   .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
   assumed to be a function in a section 2 or 3 manual.  The syntax for
   this is as follows:
   .Bd -literal -offset indent
   \&.Lb libarm
   .Ed
 .Pp  .Pp
 Subsequent SYNOPSIS and DESCRIPTION sections are strongly encouraged,  See
 but non-compulsory.  .Sx \&Lb .
 .  .
   .It Em SYNOPSIS
   Documents the utility invocation syntax, function call syntax, or device
   configuration.
   .Pp
   For the first, utilities (sections 1, 6, and 8), this is
   generally structured as follows:
   .Bd -literal -offset indent
   \&.Nm foo
   \&.Op Fl v
   \&.Op Fl o Ar file
   \&.Op Ar
   \&.Nm bar
   \&.Op Fl v
   \&.Op Fl o Ar file
   \&.Op Ar
   .Ed
   .Pp
   For the second, function calls (sections 2, 3, 9):
   .Bd -literal -offset indent
   \&.Vt extern const char *global;
   \&.In header.h
   \&.Ft "char *"
   \&.Fn foo "const char *src"
   \&.Ft "char *"
   \&.Fn bar "const char *src"
   .Ed
   .Pp
   And for the third, configurations (section 4):
   .Bd -literal -offset indent
   \&.Cd \*qit* at isa? port 0x2e\*q
   \&.Cd \*qit* at isa? port 0x4e\*q
   .Ed
   .Pp
   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
   .Em NAME .
   It usually contains a break-down of the options (if documenting a
   command), such as:
   .Bd -literal -offset indent
   The arguments are as follows:
   \&.Bl \-tag \-width Ds
   \&.It Fl v
   Print verbose information.
   \&.El
   .Ed
   .Pp
   Manuals not documenting a command won't include the above fragment.
   .
   .It Em IMPLEMENTATION NOTES
   Implementation-specific notes should be kept here.  This is useful when
   implementing standard functions that may have side effects or notable
   algorithmic implications.
   .
   .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.  Historically, this information was
   described in
   .Em DIAGNOSTICS ,
   a practise that is now discouraged.
   .Pp
   See
   .Sx \&Ex .
   .
   .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.
   .Pp
   See
   .Sx \&Rv .
   .
   .It Em ENVIRONMENT
   Documents any usages of environment variables, e.g.,
   .Xr environ 7 .
   .Pp
   See
   .Sx \&Ev .
   .
   .It Em FILES
   Documents files used.  It's helpful to document both the file and a
   short description of how the file is used (created, modified, etc.).
   .Pp
   See
   .Sx \&Pa .
   .
   .It Em EXAMPLES
   Example usages.  This often contains snippets of well-formed,
   well-tested invocations.  Make doubly sure that your examples work
   properly!
   .
   .It Em DIAGNOSTICS
   Documents error conditions.  This is most useful in section 4 manuals.
   Historically, this section was used in place of
   .Em EXIT STATUS
   for manuals in sections 1, 6, and 8; however, this practise is
   discouraged.
   .Pp
   See
   .Sx \&Bl
   .Fl diag .
   .
   .It Em ERRORS
   Documents error handling in sections 2, 3, and 9.
   .Pp
   See
   .Sx \&Er .
   .
   .It Em SEE ALSO
   References other manuals with related topics.  This section should exist
   for most manuals.  Cross-references should conventionally be ordered
   first by section, then alphabetically.
   .Pp
   See
   .Sx \&Xr .
   .
   .It Em STANDARDS
   References any standards implemented or used.  If not adhering to any
   standards, the
   .Em HISTORY
   section should be used instead.
   .Pp
   See
   .Sx \&St .
   .
   .It Em HISTORY
   The history of any manual without a
   .Em STANDARDS
   section should be described in this section.
   .
   .It Em AUTHORS
   Credits to authors, if applicable, should appear in this section.
   Authors should generally be noted by both name and an e-mail address.
   .Pp
   See
   .Sx \&An .
   .
   .It Em CAVEATS
   Explanations of common misuses and misunderstandings should be explained
   in this section.
   .
   .It Em BUGS
   Extant bugs should be described in this section.
   .
   .It Em SECURITY CONSIDERATIONS
   Documents any security precautions that operators should consider.
   .
   .El
   .
   .
 .Sh MACRO SYNTAX  .Sh MACRO SYNTAX
 Macros are one to three three characters in length and begin with a  Macros are one to three three characters in length and begin with a
 control character ,  control character ,
Line 410  All macros have bodies; some
Line 683  All macros have bodies; some
 don't have heads; only one  don't have heads; only one
 .Po  .Po
 .Sx \&It Fl column  .Sx \&It Fl column
 .Pc  .Pc
 has multiple heads.  has multiple heads.
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB  \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
Line 497  or end of line.
Line 770  or end of line.
 .It Sx \&Ql  Ta    Yes      Ta    Yes  .It Sx \&Ql  Ta    Yes      Ta    Yes
 .It Sx \&Qq  Ta    Yes      Ta    Yes  .It Sx \&Qq  Ta    Yes      Ta    Yes
 .It Sx \&Sq  Ta    Yes      Ta    Yes  .It Sx \&Sq  Ta    Yes      Ta    Yes
   .It Sx \&Vt  Ta    Yes      Ta    Yes
 .El  .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  .Ss In-line
Line 528  then the macro accepts an arbitrary number of argument
Line 810  then the macro accepts an arbitrary number of argument
 .It Sx \&%N  Ta    \&No     Ta    \&No     Ta    >0  .It Sx \&%N  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&%O  Ta    \&No     Ta    \&No     Ta    >0  .It Sx \&%O  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&%P  Ta    \&No     Ta    \&No     Ta    >0  .It Sx \&%P  Ta    \&No     Ta    \&No     Ta    >0
   .It Sx \&%Q  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&%R  Ta    \&No     Ta    \&No     Ta    >0  .It Sx \&%R  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&%T  Ta    \&No     Ta    \&No     Ta    >0  .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 \&%V  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&Ad  Ta    Yes      Ta    Yes      Ta    n  .It Sx \&Ad  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&An  Ta    Yes      Ta    Yes      Ta    n  .It Sx \&An  Ta    Yes      Ta    Yes      Ta    n
Line 576  then the macro accepts an arbitrary number of argument
Line 860  then the macro accepts an arbitrary number of argument
 .It Sx \&Ot  Ta    \&No     Ta    \&No     Ta    n  .It Sx \&Ot  Ta    \&No     Ta    \&No     Ta    n
 .It Sx \&Ox  Ta    Yes      Ta    Yes      Ta    n  .It Sx \&Ox  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Pa  Ta    Yes      Ta    Yes      Ta    n  .It Sx \&Pa  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Pf  Ta    \&No     Ta    Yes      Ta    1  .It Sx \&Pf  Ta    Yes      Ta    Yes      Ta    1
 .It Sx \&Pp  Ta    \&No     Ta    \&No     Ta    0  .It Sx \&Pp  Ta    \&No     Ta    \&No     Ta    0
 .It Sx \&Rv  Ta    \&No     Ta    \&No     Ta    n  .It Sx \&Rv  Ta    \&No     Ta    \&No     Ta    n
 .It Sx \&Sm  Ta    \&No     Ta    \&No     Ta    1  .It Sx \&Sm  Ta    \&No     Ta    \&No     Ta    1
Line 588  then the macro accepts an arbitrary number of argument
Line 872  then the macro accepts an arbitrary number of argument
 .It Sx \&Ux  Ta    Yes      Ta    Yes      Ta    n  .It Sx \&Ux  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Va  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 \&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 \&br  Ta    \&No     Ta    \&No     Ta    0
 .It Sx \&sp  Ta    \&No     Ta    \&No     Ta    1  .It Sx \&sp  Ta    \&No     Ta    \&No     Ta    1
 .El  .El
 .  .
 .  .
 .Sh REFERENCE  .Sh REFERENCE
Line 604  Author name of an
Line 888  Author name of an
 .Sx \&Rs  .Sx \&Rs
 block.  Multiple authors should each be accorded their own  block.  Multiple authors should each be accorded their own
 .Sx \%%A  .Sx \%%A
 line.  line.  Author names should be ordered with full or abbreviated
 .Pp  forename(s) first, then full surname.
 Author names should be ordered with full or abbreviated forename(s)  
 first, then full surname.  
 .  .
 .Ss \&%B  .Ss \&%B
 Book title of an  Book title of an
Line 627  this macro is not implemented in
Line 909  this macro is not implemented in
 .Ss \&%D  .Ss \&%D
 Publication date of an  Publication date of an
 .Sx \&Rs  .Sx \&Rs
 block.  This should follow the canonical syntax for  block.  This should follow the reduced or canonical form syntax
   described in
 .Sx Dates .  .Sx Dates .
 .  .
 .Ss \&%I  .Ss \&%I
Line 673  Article title of an
Line 956  Article title of an
 block.  This macro may also be used in a non-bibliographical context  block.  This macro may also be used in a non-bibliographical context
 when referring to article titles.  when referring to article titles.
 .  .
   .Ss \&%U
   URI of reference document.
   .
 .Ss \&%V  .Ss \&%V
 Volume number of an  Volume number of an
 .Sx \&Rs  .Sx \&Rs
Line 688  Address construct: usually in the context of an comput
Line 974  Address construct: usually in the context of an comput
 memory, not a physical (post) address.  memory, not a physical (post) address.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .D1 \&.Ad [0,$]
 \&.Ad [0,$]  .D1 \&.Ad 0x00000000
 \&.Ad 0x00000000  
 .Ed  
 .  .
 .Ss \&An  .Ss \&An
 Author name.  This macro may alternatively accepts the following  Author name.  This macro may alternatively accepts the following
 arguments, although these may not be specified along with a parameter:  arguments, although these may not be specified along with a parameter:
 .Bl -tag -width 12n -offset indent  .Bl -tag -width 12n -offset indent
 .It Fl split  .It Fl split
 Renders a line break is rendered before each author listing.  Renders a line break before each author listing.
 .It Fl nosplit  .It Fl nosplit
 The opposite of  The opposite of
 .Fl split .  .Fl split .
Line 712  will cause the first listing also to be split.  If not
Line 996  will cause the first listing also to be split.  If not
 section, the default is not to split.  section, the default is not to split.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .D1 \&.An -nosplit
 \&.An -nosplit  .D1 \&.An J. D. Ullman .
 \&.An J. E. Hopcraft ,  
 \&.An J. D. Ullman .  
 .Ed  
 .Pp  .Pp
 .Em Remarks :  .Em Remarks :
 the effects of  the effects of
Line 733  Begins a block enclosed by angled brackets.  Does not 
Line 1014  Begins a block enclosed by angled brackets.  Does not 
 arguments.  arguments.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .D1 \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac
 \&.Fl -key= Ns Ao Ar val Ac  
 .Ed  
 .Pp  .Pp
 See also  See also
 .Sx \&Aq .  .Sx \&Aq .
Line 749  a function:
Line 1028  a function:
 .Ed  .Ed
 .  .
 .Ss \&Aq  .Ss \&Aq
 Encloses its arguments in angled brackets.  Encloses its arguments in angled brackets.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .D1 \&.Fl -key= \&Ns \&Aq \&Ar val
 \&.Fl -key= Ns Aq Ar val  
 .Ed  
 .Pp  .Pp
 .Em Remarks :  .Em Remarks :
 this macro is often abused for rendering URIs, which should instead use  this macro is often abused for rendering URIs, which should instead use
Line 770  See also
Line 1047  See also
 .Sx \&Ao .  .Sx \&Ao .
 .  .
 .Ss \&Ar  .Ss \&Ar
 Command arguments.  If an argument is not provided, the strings  Command arguments.  If an argument is not provided, the string
 .Dq file ...  .Dq file ...
 are used as a default.  is used as a default.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .D1 \&.Fl o \&Ns \&Ar file1
 \&.Fl o Ns Ar file1  .D1 \&.Ar
 \&.Ar  .D1 \&.Ar arg1 , arg2 .
 \&.Ar arg1 , arg2 .  
 .Ed  
 .  .
 .Ss \&At  .Ss \&At
 Formats an AT&T version.  Accepts at most one parameter:  Formats an AT&T version.  Accepts at most one parameter:
Line 795  A system version of
Line 1070  A system version of
 Note that these parameters do not begin with a hyphen.  Note that these parameters do not begin with a hyphen.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .D1 \&.At
 \&.At  .D1 \&.At V.1
 \&.At V.1  
 .Ed  
 .Pp  .Pp
 See also  See also
 .Sx \&Bx ,  
 .Sx \&Bsx ,  .Sx \&Bsx ,
   .Sx \&Bx ,
   .Sx \&Dx ,
 .Sx \&Fx ,  .Sx \&Fx ,
 .Sx \&Nx ,  .Sx \&Nx ,
 .Sx \&Ox ,  .Sx \&Ox ,
Line 859  which aligns around an imagined centre axis.
Line 1133  which aligns around an imagined centre axis.
 .It  .It
 As a precalculated width for a named macro.  The most popular is the  As a precalculated width for a named macro.  The most popular is the
 imaginary macro  imaginary macro
 .Ar Ds ,  .Ar \&Ds ,
 which resolves to  which resolves to
 .Ar 6n .  .Ar 6n .
 .It  .It
Line 887  Examples:
Line 1161  Examples:
    Hello       world.     Hello       world.
 \&.Ed  \&.Ed
 .Ed  .Ed
   .Pp
   See also
   .Sx \&D1
   and
   .Sx \&Dl .
 .  .
 .Ss \&Bf  .Ss \&Bf
 .Ss \&Bk  .Ss \&Bk
 .Ss \&Bl  .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  .Ss \&Bo
 Begins a block enclosed by square brackets.  Does not have any head  Begins a block enclosed by square brackets.  Does not have any head
 arguments.  arguments.
Line 899  arguments.
Line 1231  arguments.
 Examples:  Examples:
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Bo 1 ,  \&.Bo 1 ,
 \&.Dv BUFSIZ Bc  \&.Dv BUFSIZ \&Bc
 .Ed  .Ed
 .Pp  .Pp
 See also  See also
 .Sx \&Bq .  .Sx \&Bq .
 .  .
 .Ss \&Bq  .Ss \&Bq
 Encloses its arguments in square brackets.  Encloses its arguments in square brackets.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .D1 \&.Bq 1 , \&Dv BUFSIZ
 \&.Bq 1 , Dv BUFSIZ  
 .Ed  
 .Pp  .Pp
 .Em Remarks :  .Em Remarks :
 this macro is sometimes abused to emulate optional arguments for  this macro is sometimes abused to emulate optional arguments for
Line 936  arguments.
Line 1266  arguments.
 Examples:  Examples:
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Bro 1 , ... ,  \&.Bro 1 , ... ,
 \&.Va n Brc  \&.Va n \&Brc
 .Ed  .Ed
 .Pp  .Pp
 See also  See also
Line 946  See also
Line 1276  See also
 Encloses its arguments in curly braces.  Encloses its arguments in curly braces.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .D1 \&.Brq 1 , ... , \&Va n
 \&.Brq 1 , ... , Va n  
 .Ed  
 .Pp  .Pp
 See also  See also
 .Sx \&Bro .  .Sx \&Bro .
Line 958  Format the BSD/OS version provided as an argument, or 
Line 1286  Format the BSD/OS version provided as an argument, or 
 no argument is provided.  no argument is provided.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .D1 \&.Bsx 1.0
 \&.Bsx 1.0  .D1 \&.Bsx
 \&.Bsx  
 .Ed  
 .Pp  .Pp
 See also  See also
 .Sx \&At ,  .Sx \&At ,
 .Sx \&Bx ,  .Sx \&Bx ,
   .Sx \&Dx ,
 .Sx \&Fx ,  .Sx \&Fx ,
 .Sx \&Nx ,  .Sx \&Nx ,
 .Sx \&Ox ,  .Sx \&Ox ,
Line 973  and
Line 1300  and
 .Sx \&Ux .  .Sx \&Ux .
 .  .
 .Ss \&Bt  .Ss \&Bt
   Prints
   .Dq is currently in beta test.
   .
 .Ss \&Bx  .Ss \&Bx
 Format the BSD version provided as an argument, or a default value if no  Format the BSD version provided as an argument, or a default value if no
 argument is provided.  argument is provided.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .D1 \&.Bx 4.4
 \&.Bx 4.4  .D1 \&.Bx
 \&.Bx  
 .Ed  
 .Pp  .Pp
 See also  See also
 .Sx \&At ,  .Sx \&At ,
 .Sx \&Bsx ,  .Sx \&Bsx ,
   .Sx \&Dx ,
 .Sx \&Fx ,  .Sx \&Fx ,
 .Sx \&Nx ,  .Sx \&Nx ,
 .Sx \&Ox ,  .Sx \&Ox ,
Line 993  and
Line 1322  and
 .Sx \&Ux .  .Sx \&Ux .
 .  .
 .Ss \&Cd  .Ss \&Cd
   Configuration declaration (suggested for use in section four and nine
   manuals).  This denotes strings accepted by
   .Xr config 8 .
   .Pp
   Examples:
   .D1 \&.Cd device le0 at scode?
   .Pp
   .Em Remarks :
   this macro is commonly abused by using quoted literals to retain
   white-space and align consecutive
   .Sx \&Cd
   declarations.  This practise is discouraged.
   .
 .Ss \&Cm  .Ss \&Cm
   Command modifiers.  Useful when specifying configuration options or
   keys.
   .Pp
   Examples:
   .D1 \&.Cm ControlPath
   .D1 \&.Cm ControlMaster
   .Pp
   See also
   .Sx \&Fl .
   .
 .Ss \&D1  .Ss \&D1
   One-line indented display.  This is formatted by the default rules and
   is useful for simple indented statements.  It is followed by a newline.
   .Pp
   Examples:
   .D1 \&.D1 \&Fl abcdefgh
   .Pp
   See also
   .Sx \&Bd
   and
   .Sx \&Dl .
   .
 .Ss \&Db  .Ss \&Db
 .Ss \&Dc  .Ss \&Dc
   Closes a
   .Sx \&Do
   block.  Does not have any tail arguments.
   .
 .Ss \&Dd  .Ss \&Dd
   Document date.  This is the mandatory first macro of any
   .Nm
   manual.  Its calling syntax is as follows:
   .Pp
   .D1 \. Ns Sx \&Dd Cm date
   .Pp
   The
   .Cm date
   field may be either
   .Ar $\&Mdocdate$ ,
   which signifies the current manual revision date dictated by
   .Xr cvs 1 ,
   or instead a valid canonical date as specified by
   .Sx Dates .
   If a date does not conform, the current date is used instead.
   .Pp
   Examples:
   .D1 \&.Dd $\&Mdocdate$
   .D1 \&.Dd $\&Mdocdate: July 21 2007$
   .D1 \&.Dd July 21, 2007
   .Pp
   See also
   .Sx \&Dt
   and
   .Sx \&Os .
   .
 .Ss \&Dl  .Ss \&Dl
   One-line intended display.  This is formatted as literal text and is
   useful for commands and invocations.  It is followed by a newline.
   .Pp
   Examples:
   .D1 \&.Dl % mandoc mdoc.7 | less
   .Pp
   See also
   .Sx \&Bd
   and
   .Sx \&D1 .
   .
 .Ss \&Do  .Ss \&Do
   Begins a block enclosed by double quotes.  Does not have any head
   arguments.
   .Pp
   Examples:
   .D1 \&.D1 \&Do April is the cruellest month \&Dc \e(em T.S. Eliot
   .Pp
   See also
   .Sx \&Dq .
   .
 .Ss \&Dq  .Ss \&Dq
   Encloses its arguments in double quotes.
   .Pp
   Examples:
   .Bd -literal -offset indent -compact
   \&.Dq April is the cruellest month
   \e(em T.S. Eliot
   .Ed
   .Pp
   See also
   .Sx \&Do .
   .
 .Ss \&Dt  .Ss \&Dt
   Document title.  This is the mandatory second macro of any
   .Nm
   file.  Its calling syntax is as follows:
   .Pp
   .D1 \. Ns Sx \&Dt Cm title section Op Cm volume | arch
   .Pp
   Its arguments are as follows:
   .Bl -tag -width Ds -offset Ds
   .It Cm title
   The document's title (name).  This should be capitalised and is
   required.
   .It Cm section
   The manual section.  This may be one of
   .Ar 1
   .Pq utilities ,
   .Ar 2
   .Pq system calls ,
   .Ar 3
   .Pq libraries ,
   .Ar 3p
   .Pq Perl libraries ,
   .Ar 4
   .Pq devices ,
   .Ar 5
   .Pq file formats ,
   .Ar 6
   .Pq games ,
   .Ar 7
   .Pq miscellaneous ,
   .Ar 8
   .Pq system utilities ,
   .Ar 9
   .Pq kernel functions ,
   .Ar X11
   .Pq X Window System ,
   .Ar X11R6
   .Pq X Window System ,
   .Ar unass
   .Pq unassociated ,
   .Ar local
   .Pq local system ,
   .Ar draft
   .Pq draft manual ,
   or
   .Ar paper
   .Pq paper .
   It is also required and should correspond to the manual's filename
   suffix.
   .It Cm volume
   This overrides the volume inferred from
   .Ar section .
   This field is optional, and if specified, must be one of
   .Ar USD
   .Pq users' supplementary documents ,
   .Ar PS1
   .Pq programmers' supplementary documents ,
   .Ar AMD
   .Pq administrators' supplementary documents ,
   .Ar SMM
   .Pq system managers' manuals ,
   .Ar URM
   .Pq users' reference manuals ,
   .Ar PRM
   .Pq programmers' reference manuals ,
   .Ar KM
   .Pq kernel manuals ,
   .Ar IND
   .Pq master index ,
   .Ar MMI
   .Pq master index ,
   .Ar LOCAL
   .Pq local manuals ,
   .Ar LOC
   .Pq local manuals ,
   or
   .Ar CON
   .Pq contributed manuals .
   .It Cm arch
   This specifies a specific relevant architecture.  If
   .Cm volume
   is not provided, it may be used in its place, else it may be used
   subsequent that.  It, too, is optional.  It must be one of
   .Ar alpha ,
   .Ar amd64 ,
   .Ar amiga ,
   .Ar arc ,
   .Ar arm ,
   .Ar armish ,
   .Ar aviion ,
   .Ar hp300 ,
   .Ar hppa ,
   .Ar hppa64 ,
   .Ar i386 ,
   .Ar landisk ,
   .Ar loongson ,
   .Ar luna88k ,
   .Ar mac68k ,
   .Ar macppc ,
   .Ar mvme68k ,
   .Ar mvme88k ,
   .Ar mvmeppc ,
   .Ar pmax ,
   .Ar sgi ,
   .Ar socppc ,
   .Ar sparc ,
   .Ar sparc64 ,
   .Ar sun3 ,
   .Ar vax ,
   or
   .Ar zaurus .
   .El
   .Pp
   Examples:
   .D1 \&.Dt FOO 1
   .D1 \&.Dt FOO 4 KM
   .D1 \&.Dt FOO 9 i386
   .D1 \&.Dt FOO 9 KM i386
   .Pp
   See also
   .Sx \&Dd
   and
   .Sx \&Os .
   .
 .Ss \&Dv  .Ss \&Dv
   Defined variables such as preprocessor constants.
   .Pp
   Examples:
   .D1 \&.Dv BUFSIZ
   .D1 \&.Dv STDOUT_FILENO
   .Pp
   See also
   .Sx \&Er .
   .
 .Ss \&Dx  .Ss \&Dx
   Format the DragonFly BSD version provided as an argument, or a default
   value if no argument is provided.
   .Pp
   Examples:
   .D1 \&.Dx 2.4.1
   .D1 \&.Dx
   .Pp
   See also
   .Sx \&At ,
   .Sx \&Bsx ,
   .Sx \&Bx ,
   .Sx \&Fx ,
   .Sx \&Nx ,
   .Sx \&Ox ,
   and
   .Sx \&Ux .
   .
 .Ss \&Ec  .Ss \&Ec
 .Ss \&Ed  .Ss \&Ed
 .Ss \&Ef  .Ss \&Ef
 .Ss \&Ek  .Ss \&Ek
 .Ss \&El  .Ss \&El
   .
 .Ss \&Em  .Ss \&Em
   Denotes text that should be emphasised.  Note that this is a
   presentation term and should not be used for stylistically decorating
   technical terms.
   .Pp
   Examples:
   .D1 \&.Em Warnings!
   .D1 \&.Em Remarks :
   .
 .Ss \&En  .Ss \&En
 .Ss \&Eo  .Ss \&Eo
 .Ss \&Er  .Ss \&Er
   Display error constants.
   .Pp
   Examples:
   .D1 \&.Er EPERM
   .D1 \&.Er ENOENT
   .Pp
   See also
   .Sx \&Dv .
   .
 .Ss \&Es  .Ss \&Es
   .
 .Ss \&Ev  .Ss \&Ev
   Environmental variables such as those specified in
   .Xr environ 7 .
   .Pp
   Examples:
   .D1 \&.Ev DISPLAY
   .D1 \&.Ev PATH
   .
 .Ss \&Ex  .Ss \&Ex
   Inserts text regarding a utility's exit values.  This macro must have
   first the
   .Fl std
   argument specified, then an optional
   .Ar utility .
   If
   .Ar utility
   is not provided, the document's name as stipulated in
   .Sx \&Nm
   is provided.
 .Ss \&Fa  .Ss \&Fa
 .Ss \&Fc  .Ss \&Fc
 .Ss \&Fd  .Ss \&Fd
 .Ss \&Fl  .Ss \&Fl
   Command-line flag.  Used when listing arguments to command-line
   utilities.  Prints a fixed-width hyphen
   .Sq \-
   directly followed by each argument.  If no arguments are provided, a hyphen is
   printed followed by a space.  If the argument is a macro, a hyphen is
   prefixed to the subsequent macro output.
   .Pp
   Examples:
   .D1 \&.Fl a b c
   .D1 \&.Fl \&Pf a b
   .D1 \&.Fl
   .D1 \&.Op \&Fl o \&Ns \&Ar file
   .Pp
   See also
   .Sx \&Cm .
   .
 .Ss \&Fn  .Ss \&Fn
 .Ss \&Fo  .Ss \&Fo
 .Ss \&Fr  .Ss \&Fr
Line 1029  Format the FreeBSD version provided as an argument, or
Line 1654  Format the FreeBSD version provided as an argument, or
 if no argument is provided.  if no argument is provided.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .D1 \&.Fx 7.1
 \&.Fx 7.1  .D1 \&.Fx
 \&.Fx  
 .Ed  
 .Pp  .Pp
 See also  See also
 .Sx \&At ,  .Sx \&At ,
 .Sx \&Bx ,  
 .Sx \&Bsx ,  .Sx \&Bsx ,
   .Sx \&Bx ,
   .Sx \&Dx ,
 .Sx \&Nx ,  .Sx \&Nx ,
 .Sx \&Ox ,  .Sx \&Ox ,
 and  and
Line 1050  and
Line 1674  and
 .Ss \&Lb  .Ss \&Lb
 .Ss \&Li  .Ss \&Li
 .Ss \&Lk  .Ss \&Lk
   Format a hyperlink.  The calling syntax is as follows:
   .Pp
   .D1 \. Ns Sx \&Lk Cm uri Op Cm name
   .Pp
   Examples:
   .D1 \&.Lk http://bsd.lv "The BSD.lv Project"
   .D1 \&.Lk http://bsd.lv
   .Pp
   See also
   .Sx \&Mt .
   .
 .Ss \&Lp  .Ss \&Lp
 .Ss \&Ms  .Ss \&Ms
 .Ss \&Mt  .Ss \&Mt
Line 1062  Format the NetBSD version provided as an argument, or 
Line 1697  Format the NetBSD version provided as an argument, or 
 no argument is provided.  no argument is provided.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .D1 \&.Nx 5.01
 \&.Nx 5.01  .D1 \&.Nx
 \&.Nx  
 .Ed  
 .Pp  .Pp
 See also  See also
 .Sx \&At ,  .Sx \&At ,
 .Sx \&Bx ,  
 .Sx \&Bsx ,  .Sx \&Bsx ,
   .Sx \&Bx ,
   .Sx \&Dx ,
 .Sx \&Fx ,  .Sx \&Fx ,
 .Sx \&Ox ,  .Sx \&Ox ,
 and  and
Line 1080  and
Line 1714  and
 .Ss \&Oo  .Ss \&Oo
 .Ss \&Op  .Ss \&Op
 .Ss \&Os  .Ss \&Os
   Document operating system version.  This is the mandatory third macro of
   any
   .Nm
   file.  Its calling syntax is as follows:
   .Pp
   .D1 \. Ns Sx \&Os Op Cm system
   .Pp
   The optional
   .Cm system
   parameter specifies the relevant operating system or environment.  Left
   unspecified, it defaults to the local operating system version.  This is
   the suggested form.
   .Pp
   Examples:
   .D1 \&.Os
   .D1 \&.Os KTH/CSC/TCS
   .D1 \&.Os BSD 4.3
   .Pp
   See also
   .Sx \&Dd
   and
   .Sx \&Dt .
   .
 .Ss \&Ot  .Ss \&Ot
   Unknown usage.
   .Pp
   .Em Remarks :
   this macro has been deprecated.
   .
 .Ss \&Ox  .Ss \&Ox
 Format the OpenBSD version provided as an argument, or a default value  Format the OpenBSD version provided as an argument, or a default value
 if no argument is provided.  if no argument is provided.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .D1 \&.Ox 4.5
 \&.Ox 4.5  .D1 \&.Ox
 \&.Ox  
 .Ed  
 .Pp  .Pp
 See also  See also
 .Sx \&At ,  .Sx \&At ,
 .Sx \&Bsx ,  .Sx \&Bsx ,
 .Sx \&Bx ,  .Sx \&Bx ,
   .Sx \&Dx ,
 .Sx \&Fx ,  .Sx \&Fx ,
 .Sx \&Nx ,  .Sx \&Nx ,
 and  and
Line 1119  block.  Does not have any tail arguments.
Line 1780  block.  Does not have any tail arguments.
 .Ss \&Rs  .Ss \&Rs
 Begins a bibliographic  Begins a bibliographic
 .Pq Dq reference  .Pq Dq reference
 block.  Does not have any head arguments.  The block macro and may only  block.  Does not have any head arguments.  The block macro may only
 contain  contain
 .Sx \&%A ,  .Sx \&%A ,
 .Sx \&%B ,  .Sx \&%B ,
Line 1138  and
Line 1799  and
 child macros (at least one must be specified).  child macros (at least one must be specified).
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .Bd -literal -offset indent -compact
 \&.Rs  \&.Rs
 \&.%A J. E. Hopcroft  \&.%A J. E. Hopcroft
 \&.%A J. D. Ullman  \&.%A J. D. Ullman
Line 1171  line.
Line 1832  line.
 Format the UNIX name.  Accepts no argument.  Format the UNIX name.  Accepts no argument.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .D1 \&.Ux
 \&.Ux  
 .Ed  
 .Pp  .Pp
 See also  See also
 .Sx \&At ,  .Sx \&At ,
 .Sx \&Bx ,  
 .Sx \&Bsx ,  .Sx \&Bsx ,
   .Sx \&Bx ,
   .Sx \&Dx ,
 .Sx \&Fx ,  .Sx \&Fx ,
 .Sx \&Nx ,  .Sx \&Nx ,
 and  and
Line 1186  and
Line 1846  and
 .  .
 .Ss \&Va  .Ss \&Va
 .Ss \&Vt  .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:
   .D1 \&.Vt unsigned char
   .D1 \&.Vt extern const char * const sys_signame[] ;
   .Pp
   See also
   .Sx \&Ft
   and
   .Sx \&Va .
   .
 .Ss \&Xc  .Ss \&Xc
   Close a scope opened by
   .Sx \&Xo .
   .
 .Ss \&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.
   .
 .Ss \&Xr  .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:
   .D1 \&.Xr mandoc 1
   .D1 \&.Xr mandoc 1 ;
   .D1 \&.Xr mandoc 1 \&Ns s behaviour
   .
 .Ss \&br  .Ss \&br
 .Ss \&sp  .Ss \&sp
 .  .
Line 1207  file re-write
Line 1919  file re-write
 .Pp  .Pp
 .Bl -dash -compact  .Bl -dash -compact
 .It  .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  Negative scaling units are now truncated to zero instead of creating
 interesting conditions, such as with  interesting conditions, such as with
 .Sq \&sp -1i .  .Sx \&sp
   .Fl 1i .
 Furthermore, the  Furthermore, the
 .Sq f  .Sq f
 scaling unit, while accepted, is rendered as the default unit.  scaling unit, while accepted, is rendered as the default unit.
Line 1219  standalone double-quote in formatted output.  This idi
Line 1955  standalone double-quote in formatted output.  This idi
 behaviour is no longer applicable.  behaviour is no longer applicable.
 .It  .It
 Display types  Display types
 .Sx \&Bd Fl center  .Sx \&Bd
   .Fl center
 and  and
 .Fl right  .Fl right
 are aliases for  are aliases for
Line 1249  made historic groff
Line 1986  made historic groff
 .Qq go orbital  .Qq go orbital
 but is a proper delimiter in this implementation.  but is a proper delimiter in this implementation.
 .It  .It
 .Sx \&It Fl nested  .Sx \&It
   .Fl nested
 is assumed for all lists (it wasn't in historic groff): any list may be  is assumed for all lists (it wasn't in historic groff): any list may be
 nested and  nested and
 .Fl enum  .Fl enum
Legend:
Removed from v.1.65  
changed lines
  Added in v.1.92
CVSweb