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

Diff for /mandoc/mdoc.7 between version 1.64 and 1.88

version 1.64, 2009/10/19 10:18:05 version 1.88, 2010/04/06 07:17:51
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 620  Publication city or location of an
Line 902  Publication city or location of an
 .Sx \&Rs  .Sx \&Rs
 block.  block.
 .Pp  .Pp
 .Em Compatibility remark :  .Em Remarks :
 this macro is not implemented in  this macro is not implemented in
 .Xr groff 1 .  .Xr groff 1 .
 .  .
 .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 698  Author name.  This macro may alternatively accepts the
Line 984  Author name.  This macro may alternatively accepts the
 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 749  a function:
Line 1035  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  .Bd -literal -offset indent
Line 770  See also
Line 1056  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  .Bd -literal -offset indent
Line 796  Note that these parameters do not begin with a hyphen.
Line 1082  Note that these parameters do not begin with a hyphen.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.At  \&.At
 \&.At V.1  \&.At V.1
 .Ed  .Ed
   .Pp
   See also
   .Sx \&Bsx ,
   .Sx \&Bx ,
   .Sx \&Dx ,
   .Sx \&Fx ,
   .Sx \&Nx ,
   .Sx \&Ox ,
   and
   .Sx \&Ux .
 .  .
 .Ss \&Bc  .Ss \&Bc
 Closes a  Closes a
Line 850  which aligns around an imagined centre axis.
Line 1146  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 874  before any text or macros within the block.
Line 1170  before any text or macros within the block.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Bd \-literal \-offset indent  
 int  
 main(void)  
 {  
         printf("Hello, world!\en");  
 }  
 \&.Ed  
   
 \&.Bd \-unfilled \-offset two-indent \-compact  \&.Bd \-unfilled \-offset two-indent \-compact
 Hello     Hello       world.
       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
   arguments.
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.Bo 1 ,
   \&.Dv BUFSIZ Bc
   .Ed
   .Pp
   See also
   .Sx \&Bq .
   .
 .Ss \&Bq  .Ss \&Bq
   Encloses its arguments in square brackets.
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.Bq 1 , Dv BUFSIZ
   .Ed
   .Pp
   .Em Remarks :
   this macro is sometimes abused to emulate optional arguments for
   commands; the correct macros to use for this purpose are
   .Sx \&Op ,
   .Sx \&Oo ,
   and
   .Sx \&Oc .
   .Pp
   See also
   .Sx \&Bo .
   .
 .Ss \&Brc  .Ss \&Brc
   Closes a
   .Sx \&Bro
   block.  Does not have any tail arguments.
   .
 .Ss \&Bro  .Ss \&Bro
   Begins a block enclosed by curly braces.  Does not have any head
   arguments.
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.Bro 1 , ... ,
   \&.Va n Brc
   .Ed
   .Pp
   See also
   .Sx \&Brq .
   .
 .Ss \&Brq  .Ss \&Brq
   Encloses its arguments in curly braces.
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.Brq 1 , ... , Va n
   .Ed
   .Pp
   See also
   .Sx \&Bro .
   .
 .Ss \&Bsx  .Ss \&Bsx
   Format the BSD/OS version provided as an argument, or a default value if
   no argument is provided.
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.Bsx 1.0
   \&.Bsx
   .Ed
   .Pp
   See also
   .Sx \&At ,
   .Sx \&Bx ,
   .Sx \&Dx ,
   .Sx \&Fx ,
   .Sx \&Nx ,
   .Sx \&Ox ,
   and
   .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
   argument is provided.
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.Bx 4.4
   \&.Bx
   .Ed
   .Pp
   See also
   .Sx \&At ,
   .Sx \&Bsx ,
   .Sx \&Dx ,
   .Sx \&Fx ,
   .Sx \&Nx ,
   .Sx \&Ox ,
   and
   .Sx \&Ux .
   .
 .Ss \&Cd  .Ss \&Cd
   Configuration declaration (suggested for use only in section four
   manuals).  This denotes strings accepted by
   .Xr config 8 .
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.Cd device le0 at scode?
   .Ed
   .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:
   .Bd -literal -offset indent
   \&.Cm ControlPath
   \&.Cm ControlMaster
   .Ed
   .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:
   .Bd -literal -offset indent
   \&.D1 Fl abcdefgh
   .Ed
   .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:
   .Bd -literal -offset indent
   \&.Dd $\&Mdocdate$
   \&.Dd $\&Mdocdate: July 21 2007$
   \&.Dd July 21, 2007
   .Ed
   .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:
   .Bd -literal -offset indent
   \&.Dl % mandoc mdoc.7 | less
   .Ed
   .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:
   .Bd -literal -offset indent
   \&.D1 Do April is the cruellest month Dc \e(em T.S. Eliot
   .Ed
   .Pp
   See also
   .Sx \&Dq .
   .
 .Ss \&Dq  .Ss \&Dq
   Encloses its arguments in double quotes.
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.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:
   .Bd -literal -offset indent
   \&.Dt FOO 1
   \&.Dt FOO 4 KM
   \&.Dt FOO 9 i386
   \&.Dt FOO 9 KM i386
   .Ed
   .Pp
   See also
   .Sx \&Dd
   and
   .Sx \&Os .
   .
 .Ss \&Dv  .Ss \&Dv
   Defined variables such as preprocessor constants.
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.Dv BUFSIZ
   \&.Dv STDOUT_FILENO
   .Ed
   .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:
   .Bd -literal -offset indent
   \&.Dx 2.4.1
   \&.Dx
   .Ed
   .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:
   .Bd -literal -offset indent
   \&.Ed Warnings!
   \&.Ed Remarks :
   .Ed
   .
 .Ss \&En  .Ss \&En
 .Ss \&Eo  .Ss \&Eo
 .Ss \&Er  .Ss \&Er
   Error constants (suggested for use only in section two manuals).
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.Er EPERM
   \&.Er ENOENT
   .Ed
   .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:
   .Bd -literal -offset indent
   \&.Ev DISPLAY
   \&.Ev PATH
   .Ed
   .
 .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 \-
   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 \&Fn
 .Ss \&Fo  .Ss \&Fo
 .Ss \&Fr  .Ss \&Fr
 .Ss \&Ft  .Ss \&Ft
 .Ss \&Fx  .Ss \&Fx
   Format the FreeBSD version provided as an argument, or a default value
   if no argument is provided.
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.Fx 7.1
   \&.Fx
   .Ed
   .Pp
   See also
   .Sx \&At ,
   .Sx \&Bsx ,
   .Sx \&Bx ,
   .Sx \&Dx ,
   .Sx \&Nx ,
   .Sx \&Ox ,
   and
   .Sx \&Ux .
   .
 .Ss \&Hf  .Ss \&Hf
 .Ss \&Ic  .Ss \&Ic
 .Ss \&In  .Ss \&In
Line 939  Hello
Line 1720  Hello
 .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:
   .Bd -literal -offset indent
   \&.Lk http://bsd.lv "The BSD.lv Project"
   \&.Lk http://bsd.lv
   .Ed
   .Pp
   See also
   .Sx \&Mt .
   .
 .Ss \&Lp  .Ss \&Lp
 .Ss \&Ms  .Ss \&Ms
 .Ss \&Mt  .Ss \&Mt
Line 947  Hello
Line 1741  Hello
 .Ss \&No  .Ss \&No
 .Ss \&Ns  .Ss \&Ns
 .Ss \&Nx  .Ss \&Nx
   Format the NetBSD version provided as an argument, or a default value if
   no argument is provided.
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.Nx 5.01
   \&.Nx
   .Ed
   .Pp
   See also
   .Sx \&At ,
   .Sx \&Bsx ,
   .Sx \&Bx ,
   .Sx \&Dx ,
   .Sx \&Fx ,
   .Sx \&Ox ,
   and
   .Sx \&Ux .
   .
 .Ss \&Oc  .Ss \&Oc
 .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:
   .Bd -literal -offset indent
   \&.Os
   \&.Os KTH/CSC/TCS
   \&.Os BSD 4.3
   .Ed
   .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
   if no argument is provided.
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.Ox 4.5
   \&.Ox
   .Ed
   .Pp
   See also
   .Sx \&At ,
   .Sx \&Bsx ,
   .Sx \&Bx ,
   .Sx \&Dx ,
   .Sx \&Fx ,
   .Sx \&Nx ,
   and
   .Sx \&Ux .
   .
 .Ss \&Pa  .Ss \&Pa
 .Ss \&Pc  .Ss \&Pc
 .Ss \&Pf  .Ss \&Pf
Line 972  block.  Does not have any tail arguments.
Line 1834  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 1021  line.
Line 1883  line.
 .Ss \&Tn  .Ss \&Tn
 .Ss \&Ud  .Ss \&Ud
 .Ss \&Ux  .Ss \&Ux
   Format the UNIX name.  Accepts no argument.
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.Ux
   .Ed
   .Pp
   See also
   .Sx \&At ,
   .Sx \&Bsx ,
   .Sx \&Bx ,
   .Sx \&Dx ,
   .Sx \&Fx ,
   .Sx \&Nx ,
   and
   .Sx \&Ox .
   .
 .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:
   .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 \&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:
   .Bd -literal -offset indent
   \&.Xr mandoc 1
   \&.Xr mandoc 1 ;
   \&.Xr mandoc 1 s behaviour
   .Ed
   .
 .Ss \&br  .Ss \&br
 .Ss \&sp  .Ss \&sp
 .  .
Line 1044  file re-write
Line 1979  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 1056  standalone double-quote in formatted output.  This idi
Line 2015  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 1086  made historic groff
Line 2046  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.64  
changed lines
  Added in v.1.88
CVSweb