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

Diff for /mandoc/mdoc.7 between version 1.79 and 1.93

version 1.79, 2010/01/01 13:35:30 version 1.93, 2010/04/07 19:37:54
Line 31  language is used to format
Line 31  language is used to format
 .Bx  .Bx
 .Ux  .Ux
 manuals.  In this reference document, we describe its syntax, structure,  manuals.  In this reference document, we describe its syntax, structure,
 and usage.  Our reference implementation is  and usage.  Our reference implementation is mandoc; the
 .Xr mandoc 1 .  
 The  
 .Sx COMPATIBILITY  .Sx COMPATIBILITY
 section describes compatibility with  section describes compatibility with other troff \-mdoc implementations.
 .Xr groff 1 .  
 .  .
 .Pp  .Pp
 An  An
Line 132  and
Line 129  and
 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), R (Roman), or P  escape followed by an indicator: B (bold), I, (italic), R (Roman), or P
 (revert to previous mode):  (revert to previous mode):
 .Pp  .Pp
 .D1 \efBbold\efR \efIitalic\efP  .D1 \efBbold\efR \efIitalic\efP
 .Pp  .Pp
Line 170  for arbitrary-digit numerals:
Line 167  for arbitrary-digit numerals:
 .D1 \es+(10much bigger\es-(10  .D1 \es+(10much bigger\es-(10
 .D1 \es+'100'much much bigger\es-'100'  .D1 \es+'100'much much bigger\es-'100'
 .Pp  .Pp
 Note these forms are  Note these forms are
 .Em not  .Em not
 recommended for  recommended for
 .Nm ,  .Nm ,
 which encourages semantic 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 343  and
Line 340  and
 .Sx \&Os  .Sx \&Os
 macros, is required for every document.  macros, is required for every document.
 .Pp  .Pp
 The first section (sections are denoted by  The first section (sections are denoted by
 .Sx \&Sh )  .Sx \&Sh )
 must be the NAME section, consisting of at least one  must be the NAME section, consisting of at least one
 .Sx \&Nm  .Sx \&Nm
Line 419  The
Line 416  The
 macro(s) must precede the  macro(s) must precede the
 .Sx \&Nd  .Sx \&Nd
 macro.  macro.
   .Pp
   See
   .Sx \&Nm
   and
   .Sx \&Nd .
 .  .
 .It Em LIBRARY  .It Em LIBRARY
 The name of the library containing the documented material, which is  The name of the library containing the documented material, which is
Line 429  this is as follows:
Line 431  this is as follows:
 .Ed  .Ed
 .Pp  .Pp
 See  See
 .Sx \&Lb  .Sx \&Lb .
 for details.  
 .  .
 .It Em SYNOPSIS  .It Em SYNOPSIS
 Documents the utility invocation syntax, function call syntax, or device  Documents the utility invocation syntax, function call syntax, or device
 configuration.  configuration.
 .Pp  .Pp
 For the first, utilities (sections 1, 6, and 8), this is  For the first, utilities (sections 1, 6, and 8), this is
 generally structured as follows:  generally structured as follows:
Line 465  And for the third, configurations (section 4):
Line 466  And for the third, configurations (section 4):
 \&.Cd \*qit* at isa? port 0x4e\*q  \&.Cd \*qit* at isa? port 0x4e\*q
 .Ed  .Ed
 .Pp  .Pp
 Manuals not in these sections generally don't need a  Manuals not in these sections generally don't need a
 .Em SYNOPSIS .  .Em SYNOPSIS .
   .Pp
   See
   .Sx \&Op ,
   .Sx \&Cd ,
   .Sx \&Fn ,
   .Sx \&Ft ,
   and
   .Sx \&Vt .
 .  .
 .It Em DESCRIPTION  .It Em DESCRIPTION
 This expands upon the brief, one-line description in  This expands upon the brief, one-line description in
 .Em NAME .  .Em NAME .
 It usually contains a break-down of the options (if documenting a  It usually contains a break-down of the options (if documenting a
 command), such as:  command), such as:
Line 480  The arguments are as follows:
Line 489  The arguments are as follows:
 Print verbose information.  Print verbose information.
 \&.El  \&.El
 .Ed  .Ed
   .Pp
 Manuals not documenting a command won't include the above fragment.  Manuals not documenting a command won't include the above fragment.
 .  .
 .It Em IMPLEMENTATION NOTES  .It Em IMPLEMENTATION NOTES
Line 535  for manuals in sections 1, 6, and 8; however, this pra
Line 545  for manuals in sections 1, 6, and 8; however, this pra
 discouraged.  discouraged.
 .Pp  .Pp
 See  See
 .Sx \&Bl No \-diag .  .Sx \&Bl
   .Fl diag .
 .  .
 .It Em ERRORS  .It Em ERRORS
 Documents error handling in sections 2, 3, and 9.  Documents error handling in sections 2, 3, and 9.
Line 669  All macros have bodies; some
Line 680  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 756  or end of line.
Line 767  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 837  then the macro accepts an arbitrary number of argument
Line 857  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 849  then the macro accepts an arbitrary number of argument
Line 869  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 951  Address construct: usually in the context of an comput
Line 971  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
Line 975  will cause the first listing also to be split.  If not
Line 993  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 996  Begins a block enclosed by angled brackets.  Does not 
Line 1011  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 1012  a function:
Line 1025  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 1038  Command arguments.  If an argument is not provided, th
Line 1049  Command arguments.  If an argument is not provided, th
 is 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 1058  A system version of
Line 1067  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 \&Bsx ,  .Sx \&Bsx ,
Line 1160  and
Line 1167  and
 .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 1168  arguments.
Line 1228  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 1205  arguments.
Line 1263  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 1215  See also
Line 1273  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 1227  Format the BSD/OS version provided as an argument, or 
Line 1283  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 ,
Line 1251  Format the BSD version provided as an argument, or a d
Line 1305  Format the BSD version provided as an argument, or a d
 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 ,
Line 1267  and
Line 1319  and
 .Sx \&Ux .  .Sx \&Ux .
 .  .
 .Ss \&Cd  .Ss \&Cd
 Configuration declaration (suggested for use only in section four  Configuration declaration.  This denotes strings accepted by
 manuals).  This denotes strings accepted by  
 .Xr config 8 .  .Xr config 8 .
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .D1 \&.Cd device le0 at scode?
 \&.Cd device le0 at scode?  
 .Ed  
 .Pp  .Pp
 .Em Remarks :  .Em Remarks :
 this macro is commonly abused by using quoted literals to retain  this macro is commonly abused by using quoted literals to retain
Line 1287  Command modifiers.  Useful when specifying configurati
Line 1336  Command modifiers.  Useful when specifying configurati
 keys.  keys.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .D1 \&.Cm ControlPath
 \&.Cm ControlPath  .D1 \&.Cm ControlMaster
 \&.Cm ControlMaster  
 .Ed  
 .Pp  .Pp
 See also  See also
 .Sx \&Fl .  .Sx \&Fl .
Line 1300  One-line indented display.  This is formatted by the d
Line 1347  One-line indented display.  This is formatted by the d
 is useful for simple indented statements.  It is followed by a newline.  is useful for simple indented statements.  It is followed by a newline.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .D1 \&.D1 \&Fl abcdefgh
 \&.D1 Fl abcdefgh  
 .Ed  
 .Pp  .Pp
 See also  See also
 .Sx \&Bd  .Sx \&Bd
Line 1322  manual.  Its calling syntax is as follows:
Line 1367  manual.  Its calling syntax is as follows:
 .Pp  .Pp
 .D1 \. Ns Sx \&Dd Cm date  .D1 \. Ns Sx \&Dd Cm date
 .Pp  .Pp
 The  The
 .Cm date  .Cm date
 field may be either  field may be either
 .Ar $\&Mdocdate$ ,  .Ar $\&Mdocdate$ ,
Line 1333  or instead a valid canonical date as specified by
Line 1378  or instead a valid canonical date as specified by
 If a date does not conform, the current date is used instead.  If a date does not conform, the current date is used instead.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .D1 \&.Dd $\&Mdocdate$
 \&.Dd $\&Mdocdate$  .D1 \&.Dd $\&Mdocdate: July 21 2007$
 \&.Dd $\&Mdocdate: July 21 2007$  .D1 \&.Dd July 21, 2007
 \&.Dd July 21, 2007  
 .Ed  
 .Pp  .Pp
 See also  See also
 .Sx \&Dt  .Sx \&Dt
Line 1349  One-line intended display.  This is formatted as liter
Line 1392  One-line intended display.  This is formatted as liter
 useful for commands and invocations.  It is followed by a newline.  useful for commands and invocations.  It is followed by a newline.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .D1 \&.Dl % mandoc mdoc.7 | less
 \&.Dl % mandoc mdoc.7 | less  
 .Ed  
 .Pp  .Pp
 See also  See also
 .Sx \&Bd  .Sx \&Bd
Line 1363  Begins a block enclosed by double quotes.  Does not ha
Line 1404  Begins a block enclosed by double quotes.  Does not ha
 arguments.  arguments.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .D1 \&.D1 \&Do April is the cruellest month \&Dc \e(em T.S. Eliot
 \&.D1 Do April is the cruellest month Dc \e(em T.S. Eliot  
 .Ed  
 .Pp  .Pp
 See also  See also
 .Sx \&Dq .  .Sx \&Dq .
 .  .
 .Ss \&Dq  .Ss \&Dq
 Encloses its arguments in double quotes.  Encloses its arguments in double quotes.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .Bd -literal -offset indent -compact
 \&.Dq April is the cruellest month  \&.Dq April is the cruellest month
 \e(em T.S. Eliot  \e(em T.S. Eliot
 .Ed  .Ed
Line 1477  subsequent that.  It, too, is optional.  It must be on
Line 1516  subsequent that.  It, too, is optional.  It must be on
 .Ar hppa64 ,  .Ar hppa64 ,
 .Ar i386 ,  .Ar i386 ,
 .Ar landisk ,  .Ar landisk ,
   .Ar loongson ,
 .Ar luna88k ,  .Ar luna88k ,
 .Ar mac68k ,  .Ar mac68k ,
 .Ar macppc ,  .Ar macppc ,
Line 1495  or
Line 1535  or
 .El  .El
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .D1 \&.Dt FOO 1
 \&.Dt FOO 1  .D1 \&.Dt FOO 4 KM
 \&.Dt FOO 4 KM  .D1 \&.Dt FOO 9 i386
 \&.Dt FOO 9 i386  .D1 \&.Dt FOO 9 KM i386
 \&.Dt FOO 9 KM i386  
 .Ed  
 .Pp  .Pp
 See also  See also
 .Sx \&Dd  .Sx \&Dd
Line 1511  and
Line 1549  and
 Defined variables such as preprocessor constants.  Defined variables such as preprocessor constants.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .D1 \&.Dv BUFSIZ
 \&.Dv BUFSIZ  .D1 \&.Dv STDOUT_FILENO
 \&.Dv STDOUT_FILENO  
 .Ed  
 .Pp  .Pp
 See also  See also
 .Sx \&Er .  .Sx \&Er .
Line 1524  Format the DragonFly BSD version provided as an argume
Line 1560  Format the DragonFly BSD version provided as an argume
 value if no argument is provided.  value if no argument is provided.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .D1 \&.Dx 2.4.1
 \&.Dx 2.4.1  .D1 \&.Dx
 \&.Dx  
 .Ed  
 .Pp  .Pp
 See also  See also
 .Sx \&At ,  .Sx \&At ,
Line 1544  and
Line 1578  and
 .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  Denotes text that should be emphasised.  Note that this is a
 presentation term and should not be used for stylistically decorating  presentation term and should not be used for stylistically decorating
 technical terms.  technical terms.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .D1 \&.Em Warnings!
 \&.Ed Warnings!  .D1 \&.Em Remarks :
 \&.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).  Display error constants.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .D1 \&.Er EPERM
 \&.Er EPERM  .D1 \&.Er ENOENT
 \&.Er ENOENT  
 .Ed  
 .Pp  .Pp
 See also  See also
 .Sx \&Dv .  .Sx \&Dv .
Line 1576  Environmental variables such as those specified in
Line 1607  Environmental variables such as those specified in
 .Xr environ 7 .  .Xr environ 7 .
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .D1 \&.Ev DISPLAY
 \&.Ev DISPLAY  .D1 \&.Ev PATH
 \&.Ev PATH  
 .Ed  
 .  .
 .Ss \&Ex  .Ss \&Ex
 Inserts text regarding a utility's exit values.  This macro must have  Inserts text regarding a utility's exit values.  This macro must have
Line 1599  is provided.
Line 1628  is provided.
 Command-line flag.  Used when listing arguments to command-line  Command-line flag.  Used when listing arguments to command-line
 utilities.  Prints a fixed-width hyphen  utilities.  Prints a fixed-width hyphen
 .Sq \-  .Sq \-
 before each delimited argument.  If no arguments are provided, a hyphen  directly followed by each argument.  If no arguments are provided, a hyphen is
 is still printed.  printed followed by a space.  If the argument is a macro, a hyphen is
   prefixed to the subsequent macro output.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .D1 \&.Fl a b c
 \&.Fl a b c  .D1 \&.Fl \&Pf a b
 \&.Fl  .D1 \&.Fl
 \&.Op Fl o Ns Ar file  .D1 \&.Op \&Fl o \&Ns \&Ar file
 .Ed  
 .Pp  .Pp
 See also  See also
 .Sx \&Cm .  .Sx \&Cm .
Line 1621  Format the FreeBSD version provided as an argument, or
Line 1650  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 ,
Line 1648  Format a hyperlink.  The calling syntax is as follows:
Line 1675  Format a hyperlink.  The calling syntax is as follows:
 .D1 \. Ns Sx \&Lk Cm uri Op Cm name  .D1 \. Ns Sx \&Lk Cm uri Op Cm name
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .D1 \&.Lk http://bsd.lv "The BSD.lv Project"
 \&.Lk http://bsd.lv "The BSD.lv Project"  .D1 \&.Lk http://bsd.lv
 \&.Lk http://bsd.lv  
 .Ed  
 .Pp  .Pp
 See also  See also
 .Sx \&Mt .  .Sx \&Mt .
Line 1668  Format the NetBSD version provided as an argument, or 
Line 1693  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 ,
Line 1701  unspecified, it defaults to the local operating system
Line 1724  unspecified, it defaults to the local operating system
 the suggested form.  the suggested form.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .D1 \&.Os
 \&.Os  .D1 \&.Os KTH/CSC/TCS
 \&.Os KTH/CSC/TCS  .D1 \&.Os BSD 4.3
 \&.Os BSD 4.3  
 .Ed  
 .Pp  .Pp
 See also  See also
 .Sx \&Dd  .Sx \&Dd
Line 1723  Format the OpenBSD version provided as an argument, or
Line 1744  Format the OpenBSD 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 \&.Ox 4.5
 \&.Ox 4.5  .D1 \&.Ox
 \&.Ox  
 .Ed  
 .Pp  .Pp
 See also  See also
 .Sx \&At ,  .Sx \&At ,
Line 1776  and
Line 1795  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 1809  line.
Line 1828  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 ,
Line 1825  and
Line 1842  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
 .  .
 .  .
 .Sh COMPATIBILITY  .Sh COMPATIBILITY
 This section documents compatibility with other roff implementations, at  This section documents compatibility between mandoc and other other
 this time limited to  troff implementations, at this time limited to GNU troff
 .Xr groff 1 .  .Pq Qq groff .
 The term  The term
 .Qq historic groff  .Qq historic groff
 refers to those versions before the  refers to groff versions before the
 .Pa doc.tmac  .Pa doc.tmac
 file re-write  file re-write
 .Pq somewhere between 1.15 and 1.19 .  .Pq somewhere between 1.15 and 1.19 .
 .  .
 .Pp  .Pp
   Heirloom troff, the other significant troff implementation accepting
   \-mdoc, is similar to historic groff.
   .
   .Pp
 .Bl -dash -compact  .Bl -dash -compact
 .It  .It
 Historic  The comment syntax
 .Xr groff 1  .Sq \e."
 does not print a dash for empty  is no longer accepted.
   .
   .It
   In groff, the
   .Sx \&Pa
   macro 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  .Sx \&Fl
 arguments.  This behaviour has been discontinued.  arguments.  mandoc and newer groff implementations do.
 .It  .It
 .Xr groff 1  groff behaves irregularly when specifying
 behaves strangely (even between versions) when specifying  
 .Sq \ef  .Sq \ef
 escapes within line-macro scopes.  These aberrations have been  .Sx Text Decoration
 normalised.  within line-macro scopes.  mandoc follows a consistent system.
   .
 .It  .It
 Negative scaling units are now truncated to zero instead of creating  In mandoc, negative scaling units are truncated to zero; groff would
 interesting conditions, such as with  move to prior lines.  Furthermore, the
 .Sx \&sp  
 .Cm \-1i .  
 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.
   .
 .It  .It
 In quoted literals, groff allowed pair-wise double-quotes to produce a  In quoted literals, groff allowed pair-wise double-quotes to produce a
 standalone double-quote in formatted output.  This idiosyncratic  standalone double-quote in formatted output.  This idiosyncratic
 behaviour is no longer applicable.  behaviour is not applicable in mandoc.
   .
 .It  .It
 Display types  Display types
 .Sx \&Bd  .Sx \&Bd
Line 1876  Display types
Line 1957  Display types
 and  and
 .Fl right  .Fl right
 are aliases for  are aliases for
 .Fl left .  .Fl left
 The  in manodc.  Furthermore, the
 .Fl file Ar file  .Fl file Ar file
 argument is ignored.  Since text is not right-justified,  argument is ignored.  Lastly, since text is not right-justified in
   mandoc (or even groff),
 .Fl ragged  .Fl ragged
 and  and
 .Fl filled  .Fl filled
Line 1887  are aliases, as are
Line 1969  are aliases, as are
 .Fl literal  .Fl literal
 and  and
 .Fl unfilled .  .Fl unfilled .
   .
 .It  .It
 Blocks of whitespace are stripped from both macro and free-form text  In mandoc, blocks of whitespace are stripped from both macro and
 lines (except when in literal mode), while groff would retain whitespace  free-form text lines (except when in literal mode); groff would retain
 in free-form text lines.  whitespace in free-form text lines.
   .
 .It  .It
 Historic groff has many un-callable macros.  Most of these (excluding  Historic groff has many un-callable macros.  Most of these (excluding
 some block-level macros) are now callable, conforming to the  some block-level macros) are now callable.
 non-historic groff version.  .
 .It  .It
 The vertical bar  The vertical bar
 .Sq \(ba  .Sq \(ba
 made historic groff  made historic groff
 .Qq go orbital  .Qq go orbital
 but is a proper delimiter in this implementation.  but has been a proper delimiter since then.
   .
 .It  .It
 .Sx \&It  .Sx \&It Fl nested
 .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
 lists will restart the sequence only for the sub-list.  lists will restart the sequence only for the sub-list.
   .
 .It  .It
 Some manuals use  Some manuals use
 .Sx \&Li  .Sx \&Li
 incorrectly by following it with a reserved character and expecting the  incorrectly by following it with a reserved character and expecting the
 delimiter to render.  This is not supported.  delimiter to render.  This is not supported in mandoc.
   .
 .It  .It
 In groff, the  In groff, the
 .Sx \&Fo  .Sx \&Fo
 macro only produces the first parameter.  This is no longer the case.  macro only produces the first parameter.  This is not the case in
   mandoc.
   .
   .It
   In groff, the
   .Sx \&Cd ,
   .Sx \&Er ,
   and
   .Sx \&Ex
   macros were stipulated only to occur in certain manual sections.  mandoc
   does not have these restrictions.
 .El  .El
 .  .
 .  .
Legend:
Removed from v.1.79  
changed lines
  Added in v.1.93
CVSweb