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

Diff for /mandoc/mdoc.7 between version 1.82 and 1.114

version 1.82, 2010/01/07 19:10:10 version 1.114, 2010/06/03 14:29:52
Line 1 
Line 1 
 .\"     $Id$  .\"     $Id$
 .\"  .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>  .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"  .\"
 .\" Permission to use, copy, modify, and distribute this software for any  .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above  .\" purpose with or without fee is hereby granted, provided that the above
Line 17 
Line 17 
 .Dd $Mdocdate$  .Dd $Mdocdate$
 .Dt MDOC 7  .Dt MDOC 7
 .Os  .Os
 .  
 .  
 .Sh NAME  .Sh NAME
 .Nm mdoc  .Nm mdoc
 .Nd mdoc language reference  .Nd mdoc language reference
 .  
 .  
 .Sh DESCRIPTION  .Sh DESCRIPTION
 The  The
 .Nm mdoc  .Nm mdoc
Line 31  language is used to format
Line 27  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
 .Nm  .Nm
Line 50  prior macros:
Line 42  prior macros:
 \&.Sh Macro lines change control state.  \&.Sh Macro lines change control state.
 Other lines are interpreted within the current state.  Other lines are interpreted within the current state.
 .Ed  .Ed
 .  
 .  
 .Sh LANGUAGE SYNTAX  .Sh LANGUAGE SYNTAX
 .Nm  .Nm
 documents may contain only graphable 7-bit ASCII characters, the space  documents may contain only graphable 7-bit ASCII characters, the space
Line 59  character, and, in certain circumstances, the tab char
Line 49  character, and, in certain circumstances, the tab char
 manuals must have  manuals must have
 .Ux  .Ux
 line terminators.  line terminators.
 .  
 .  
 .Ss Comments  .Ss Comments
 Text following a  Text following a
 .Sq \e" ,  .Sq \e" ,
Line 69  line.  A macro line with only a control character and 
Line 57  line.  A macro line with only a control character and 
 .Sq \&.\e" ,  .Sq \&.\e" ,
 is also ignored.  Macro lines with only a control charater and optionally  is also ignored.  Macro lines with only a control charater and optionally
 whitespace are stripped from input.  whitespace are stripped from input.
 .  
 .  
 .Ss Reserved Characters  .Ss Reserved Characters
 Within a macro line, the following characters are reserved:  Within a macro line, the following characters are reserved:
 .Pp  .Pp
Line 98  Within a macro line, the following characters are rese
Line 84  Within a macro line, the following characters are rese
 .It \&|  .It \&|
 .Pq vertical bar  .Pq vertical bar
 .El  .El
 .  
 .Pp  .Pp
 Use of reserved characters is described in  Use of reserved characters is described in
 .Sx MACRO SYNTAX .  .Sx MACRO SYNTAX .
Line 106  For general use in macro lines, these characters must 
Line 91  For general use in macro lines, these characters must 
 with a non-breaking space  with a non-breaking space
 .Pq Sq \e&  .Pq Sq \e&
 or, if applicable, an appropriate escape sequence used.  or, if applicable, an appropriate escape sequence used.
 .  
 .  
 .Ss Special Characters  .Ss Special Characters
 Special characters may occur in both macro and free-form lines.  Special characters may occur in both macro and free-form lines.
 Sequences begin with the escape character  Sequences begin with the escape character
Line 118  for two-character sequences; an open-bracket
Line 101  for two-character sequences; an open-bracket
 .Sq \&[  .Sq \&[
 for n-character sequences (terminated at a close-bracket  for n-character sequences (terminated at a close-bracket
 .Sq \&] ) ;  .Sq \&] ) ;
 or a single one-character sequence.  See  or a single one-character sequence.
   See
 .Xr mandoc_char 7  .Xr mandoc_char 7
 for a complete list.  Examples include  for a complete list.
   Examples include
 .Sq \e(em  .Sq \e(em
 .Pq em-dash  .Pq em-dash
 and  and
 .Sq \ee  .Sq \ee
 .Pq back-slash .  .Pq back-slash .
 .  
 .  
 .Ss Text Decoration  .Ss Text Decoration
 Terms may be text-decorated using the  Terms may be text-decorated using the
 .Sq \ef  .Sq \ef
Line 137  escape followed by an indicator: B (bold), I, (italic)
Line 120  escape followed by an indicator: B (bold), I, (italic)
 .D1 \efBbold\efR \efIitalic\efP  .D1 \efBbold\efR \efIitalic\efP
 .Pp  .Pp
 A numerical representation 3, 2, or 1 (bold, italic, and Roman,  A numerical representation 3, 2, or 1 (bold, italic, and Roman,
 respectively) may be used instead.  A text decoration is valid within  respectively) may be used instead.
   A text decoration is valid within
 the current font scope only:  if a macro opens a font scope alongside  the current font scope only:  if a macro opens a font scope alongside
 its own scope, such as  its own scope, such as
 .Sx \&Bf  .Sx \&Bf
 .Cm \&Sy ,  .Cm \&Sy ,
 in-scope invocations of  in-scope invocations of
 .Sq \ef  .Sq \ef
 are only valid within the font scope of the macro.  If  are only valid within the font scope of the macro.
   If
 .Sq \ef  .Sq \ef
 is specified outside of any font scope, such as in unenclosed, free-form  is specified outside of any font scope, such as in unenclosed, free-form
 text, it will affect the remainder of the document.  text, it will affect the remainder of the document.
Line 175  Note these forms are
Line 160  Note these forms are
 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
Line 195  and N-character
Line 178  and N-character
 .Sq \e*[N] .  .Sq \e*[N] .
 See  See
 .Xr mandoc_char 7  .Xr mandoc_char 7
 for a complete list.  Examples include  for a complete list.
   Examples include
 .Sq \e*(Am  .Sq \e*(Am
 .Pq ampersand  .Pq ampersand
 and  and
 .Sq \e*(Ba  .Sq \e*(Ba
 .Pq vertical bar .  .Pq vertical bar .
 .  
 .  
 .Ss Whitespace  .Ss Whitespace
 In non-literal free-form lines, consecutive blocks of whitespace are  Whitespace consists of the space character.
 pruned from input and added later in the output filter, if applicable:  In free-form lines, whitespace is preserved within a line; un-escaped
 .Bd -literal -offset indent  trailing spaces are stripped from input (unless in a literal context).
 These     spaces   are    pruned       from    input.  Blank free-form lines, which may include whitespace, are only permitted
 \&.Bd \-literal  within literal contexts.
 These         are              not.  
 \&.Ed  
 .Ed  
 .  
 .Pp  .Pp
 In macro lines, whitespace delimits arguments and is discarded.  If  In macro lines, whitespace delimits arguments and is discarded.
 arguments are quoted, whitespace within the quotes is retained.  If arguments are quoted, whitespace within the quotes is retained.
 .  
 .Pp  
 Blank lines are only permitted within literal contexts, as are lines  
 containing only whitespace.  Tab characters are only acceptable when  
 delimiting  
 .Sq \&Bl \-column  
 or when in a literal context.  
 .  
 .  
 .Ss Quotation  .Ss Quotation
 Macro arguments may be quoted with a double-quote to group  Macro arguments may be quoted with a double-quote to group
 space-delimited terms or to retain blocks of whitespace.  A quoted  space-delimited terms or to retain blocks of whitespace.
 argument begins with a double-quote preceded by whitespace.  The next  A quoted argument begins with a double-quote preceded by whitespace.
 double-quote not pair-wise adjacent to another double-quote terminates  The next double-quote not pair-wise adjacent to another double-quote
 the literal, regardless of surrounding whitespace.  terminates the literal, regardless of surrounding whitespace.
 .  
 .Pp  .Pp
 This produces tokens  This produces tokens
 .Sq a" ,  .Sq a" ,
Line 240  This produces tokens
Line 208  This produces tokens
 and  and
 .Sq fg" .  .Sq fg" .
 Note that any quoted term, be it argument or macro, is indiscriminately  Note that any quoted term, be it argument or macro, is indiscriminately
 considered literal text.  Thus, the following produces  considered literal text.
   Thus, the following produces
 .Sq \&Em a :  .Sq \&Em a :
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Em "Em a"  \&.Em "Em a"
 .Ed  .Ed
 .  
 .Pp  .Pp
 In free-form mode, quotes are regarded as opaque text.  In free-form mode, quotes are regarded as opaque text.
 .  
 .Ss Dates  .Ss Dates
 There are several macros in  There are several macros in
 .Nm  .Nm
 that require a date argument.  The canonical form for dates is the  that require a date argument.
 American format:  The canonical form for dates is the American format:
 .Pp  .Pp
 .D1 Cm Month Day , Year  .D1 Cm Month Day , Year
 .Pp  .Pp
 The  The
 .Cm Day  .Cm Day
 value is an optionally zero-padded numeral.  The  value is an optionally zero-padded numeral.
   The
 .Cm Month  .Cm Month
 value is the full month name.  The  value is the full month name.
   The
 .Cm Year  .Cm Year
 value is the full four-digit year.  value is the full four-digit year.
 .Pp  .Pp
Line 275  Some examples of valid dates follow:
Line 244  Some examples of valid dates follow:
 .D1 "May, 2009" Pq reduced form  .D1 "May, 2009" Pq reduced form
 .D1 "2009" Pq reduced form  .D1 "2009" Pq reduced form
 .D1 "May 20, 2009" Pq canonical 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
 stipulating a two-inch list indentation with the following:  stipulating a two-inch list indentation with the following:
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Bl -tag -width 2i  \&.Bl -tag -width 2i
 .Ed  .Ed
 .  
 .Pp  .Pp
 The syntax for scaled widths is  The syntax for scaled widths is
 .Sq Li [+-]?[0-9]*.[0-9]*[:unit:] ,  .Sq Li [+-]?[0-9]*.[0-9]*[:unit:] ,
 where a decimal must be preceded or proceeded by at least one digit.  where a decimal must be preceded or proceeded by at least one digit.
 Negative numbers, while accepted, are truncated to zero.  The following  Negative numbers, while accepted, are truncated to zero.
 scaling units are accepted:  The following scaling units are accepted:
 .Pp  .Pp
 .Bl -tag -width Ds -offset indent -compact  .Bl -tag -width Ds -offset indent -compact
 .It c  .It c
Line 326  Using anything other than
Line 293  Using anything other than
 .Sq u ,  .Sq u ,
 or  or
 .Sq v  .Sq v
 is necessarily non-portable across output media.  See  is necessarily non-portable across output media.
   See
 .Sx COMPATIBILITY .  .Sx COMPATIBILITY .
 .  .Ss Sentence Spacing
 .  When composing a manual, make sure that your sentences end at the end of
   a line.
   By doing so, front-ends will be able to apply the proper amount of
   spacing after the end of sentence (unescaped) period, exclamation mark,
   or question mark followed by zero or more non-sentence closing
   delimiters (
   .Ns Sq \&) ,
   .Sq \&] ,
   .Sq \&' ,
   .Sq \&" ) .
   .Pp
   The proper spacing is also intelligently preserved if a sentence ends at
   the boundary of a macro line, e.g.,
   .Pp
   .D1 \&Xr mandoc 1 \.
   .D1 \&Fl T \&Ns \&Cm ascii \.
 .Sh MANUAL STRUCTURE  .Sh MANUAL STRUCTURE
 A well-formed  A well-formed
 .Nm  .Nm
Line 360  file:
Line 343  file:
 \&.Dd $\&Mdocdate$  \&.Dd $\&Mdocdate$
 \&.Dt mdoc 7  \&.Dt mdoc 7
 \&.Os  \&.Os
 \&.  
 \&.Sh NAME  \&.Sh NAME
 \&.Nm foo  \&.Nm foo
 \&.Nd a description goes here  \&.Nd a description goes here
 \&.\e\*q The next is for sections 2 & 3 only.  \&.\e\*q The next is for sections 2, 3, & 9 only.
 \&.\e\*q .Sh LIBRARY  \&.\e\*q .Sh LIBRARY
 \&.  
 \&.Sh SYNOPSIS  \&.Sh SYNOPSIS
 \&.Nm foo  \&.Nm foo
 \&.Op Fl options  \&.Op Fl options
 \&.Ar  \&.Ar
 \&.  
 \&.Sh DESCRIPTION  \&.Sh DESCRIPTION
 The  The
 \&.Nm  \&.Nm
 utility processes files ...  utility processes files ...
 \&.\e\*q .Sh IMPLEMENTATION NOTES  \&.\e\*q .Sh IMPLEMENTATION NOTES
 \&.\e\*q The next is for sections 1 & 8 only.  
 \&.\e\*q .Sh EXIT STATUS  
 \&.\e\*q The next is for sections 2, 3, & 9 only.  \&.\e\*q The next is for sections 2, 3, & 9 only.
 \&.\e\*q .Sh RETURN VALUES  \&.\e\*q .Sh RETURN VALUES
 \&.\e\*q The next is for sections 1, 6, 7, & 8 only.  \&.\e\*q The next is for sections 1, 6, 7, & 8 only.
 \&.\e\*q .Sh ENVIRONMENT  \&.\e\*q .Sh ENVIRONMENT
 \&.\e\*q .Sh FILES  \&.\e\*q .Sh FILES
   \&.\e\*q The next is for sections 1 & 8 only.
   \&.\e\*q .Sh EXIT STATUS
 \&.\e\*q .Sh EXAMPLES  \&.\e\*q .Sh EXAMPLES
 \&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.  \&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.
 \&.\e\*q .Sh DIAGNOSTICS  \&.\e\*q .Sh DIAGNOSTICS
Line 401  utility processes files ...
Line 381  utility processes files ...
 .Pp  .Pp
 The sections in a  The sections in a
 .Nm  .Nm
 document are conventionally ordered as they appear above.  Sections  document are conventionally ordered as they appear above.
 should be composed as follows:  Sections should be composed as follows:
 .Bl -ohang -offset Ds  .Bl -ohang -offset Ds
 .It Em NAME  .It Em NAME
 The name(s) and a short description of the documented material.  The  The name(s) and a short description of the documented material.
 syntax for this as follows:  The syntax for this as follows:
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Nm name0  \&.Nm name0
 \&.Nm name1  \&.Nm name1
Line 424  See
Line 404  See
 .Sx \&Nm  .Sx \&Nm
 and  and
 .Sx \&Nd .  .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
 assumed to be a function in a section 2 or 3 manual.  The syntax for  assumed to be a function in a section 2, 3, or 9 manual.
 this is as follows:  The syntax for this is as follows:
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Lb libarm  \&.Lb libarm
 .Ed  .Ed
 .Pp  .Pp
 See  See
 .Sx \&Lb .  .Sx \&Lb .
 .  
 .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.
Line 479  See
Line 457  See
 .Sx \&Ft ,  .Sx \&Ft ,
 and  and
 .Sx \&Vt .  .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 .
Line 494  Print verbose information.
Line 471  Print verbose information.
 .Ed  .Ed
 .Pp  .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
 Implementation-specific notes should be kept here.  This is useful when  Implementation-specific notes should be kept here.
 implementing standard functions that may have side effects or notable  This is useful when implementing standard functions that may have side
 algorithmic implications.  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  .It Em RETURN VALUES
 This section is the dual of  This section is the dual of
 .Em EXIT STATUS ,  .Em EXIT STATUS ,
 which is used for commands.  It documents the return values of functions  which is used for commands.
 in sections 2, 3, and 9.  It documents the return values of functions in sections 2, 3, and 9.
 .Pp  .Pp
 See  See
 .Sx \&Rv .  .Sx \&Rv .
 .  
 .It Em ENVIRONMENT  .It Em ENVIRONMENT
 Documents any usages of environment variables, e.g.,  Documents any usages of environment variables, e.g.,
 .Xr environ 7 .  .Xr environ 7 .
 .Pp  .Pp
 See  See
 .Sx \&Ev .  .Sx \&Ev .
 .  
 .It Em FILES  .It Em FILES
 Documents files used.  It's helpful to document both the file and a  Documents files used.
 short description of how the file is used (created, modified, etc.).  It's helpful to document both the file and a short description of how
   the file is used (created, modified, etc.).
 .Pp  .Pp
 See  See
 .Sx \&Pa .  .Sx \&Pa .
 .  .It Em EXIT STATUS
   Command exit status for section 1, 6, and 8 manuals.
   This section is the dual of
   .Em RETURN VALUES ,
   which is used for functions.
   Historically, this information was described in
   .Em DIAGNOSTICS ,
   a practise that is now discouraged.
   .Pp
   See
   .Sx \&Ex .
 .It Em EXAMPLES  .It Em EXAMPLES
 Example usages.  This often contains snippets of well-formed,  Example usages.
 well-tested invocations.  Make doubly sure that your examples work  This often contains snippets of well-formed, well-tested invocations.
 properly!  Make doubly sure that your examples work properly!
 .  
 .It Em DIAGNOSTICS  .It Em DIAGNOSTICS
 Documents error conditions.  This is most useful in section 4 manuals.  Documents error conditions.
   This is most useful in section 4 manuals.
 Historically, this section was used in place of  Historically, this section was used in place of
 .Em EXIT STATUS  .Em EXIT STATUS
 for manuals in sections 1, 6, and 8; however, this practise is  for manuals in sections 1, 6, and 8; however, this practise is
Line 550  discouraged.
Line 522  discouraged.
 See  See
 .Sx \&Bl  .Sx \&Bl
 .Fl diag .  .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.
 .Pp  .Pp
 See  See
 .Sx \&Er .  .Sx \&Er .
 .  
 .It Em SEE ALSO  .It Em SEE ALSO
 References other manuals with related topics.  This section should exist  References other manuals with related topics.
 for most manuals.  Cross-references should conventionally be ordered  This section should exist for most manuals.
 first by section, then alphabetically.  Cross-references should conventionally be ordered first by section, then
   alphabetically.
 .Pp  .Pp
 See  See
 .Sx \&Xr .  .Sx \&Xr .
 .  
 .It Em STANDARDS  .It Em STANDARDS
 References any standards implemented or used.  If not adhering to any  References any standards implemented or used.
 standards, the  If not adhering to any standards, the
 .Em HISTORY  .Em HISTORY
 section should be used instead.  section should be used instead.
 .Pp  .Pp
 See  See
 .Sx \&St .  .Sx \&St .
 .  
 .It Em HISTORY  .It Em HISTORY
 The history of any manual without a  The history of any manual without a
 .Em STANDARDS  .Em STANDARDS
 section should be described in this section.  section should be described in this section.
 .  
 .It Em AUTHORS  .It Em AUTHORS
 Credits to authors, if applicable, should appear in this section.  Credits to authors, if applicable, should appear in this section.
 Authors should generally be noted by both name and an e-mail address.  Authors should generally be noted by both name and an e-mail address.
 .Pp  .Pp
 See  See
 .Sx \&An .  .Sx \&An .
 .  
 .It Em CAVEATS  .It Em CAVEATS
 Explanations of common misuses and misunderstandings should be explained  Explanations of common misuses and misunderstandings should be explained
 in this section.  in this section.
 .  
 .It Em BUGS  .It Em BUGS
 Extant bugs should be described in this section.  Extant bugs should be described in this section.
 .  
 .It Em SECURITY CONSIDERATIONS  .It Em SECURITY CONSIDERATIONS
 Documents any security precautions that operators should consider.  Documents any security precautions that operators should consider.
 .  
 .El  .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 ,
 .Sq \&. ,  .Sq \&. ,
 at the beginning of the line.  An arbitrary amount of whitespace may  at the beginning of the line.
 sit between the control character and the macro name.  Thus, the  An arbitrary amount of whitespace may sit between the control character
 following are equivalent:  and the macro name.
   Thus, the following are equivalent:
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Pp  \&.Pp
 \&.\ \ \ \&Pp  \&.\ \ \ \&Pp
 .Ed  .Ed
 .  
 .Pp  .Pp
 The syntax of a macro depends on its classification.  In this section,  The syntax of a macro depends on its classification.
   In this section,
 .Sq \-arg  .Sq \-arg
 refers to macro arguments, which may be followed by zero or more  refers to macro arguments, which may be followed by zero or more
 .Sq parm  .Sq parm
Line 621  parameters;
Line 584  parameters;
 opens the scope of a macro; and if specified,  opens the scope of a macro; and if specified,
 .Sq \&Yc  .Sq \&Yc
 closes it out.  closes it out.
 .  
 .Pp  .Pp
 The  The
 .Em Callable  .Em Callable
 column indicates that the macro may be called subsequent to the initial  column indicates that the macro may be called subsequent to the initial
 line-macro.  If a macro is not callable, then its invocation after the  line-macro.
 initial line macro is interpreted as opaque text, such that  If a macro is not callable, then its invocation after the initial line
   macro is interpreted as opaque text, such that
 .Sq \&.Fl \&Sh  .Sq \&.Fl \&Sh
 produces  produces
 .Sq Fl \&Sh .  .Sq Fl \&Sh .
 .  
 .Pp  .Pp
 The  The
 .Em Parsable  .Em Parsable
 column indicates whether the macro may be followed by further  column indicates whether the macro may be followed by further
 (ostensibly callable) macros.  If a macro is not parsable, subsequent  (ostensibly callable) macros.
 macro invocations on the line will be interpreted as opaque text.  If a macro is not parsable, subsequent macro invocations on the line
 .  will be interpreted as opaque text.
 .Pp  .Pp
 The  The
 .Em Scope  .Em Scope
 column, if applicable, describes closure rules.  column, if applicable, describes closure rules.
 .  
 .  
 .Ss Block full-explicit  .Ss Block full-explicit
 Multi-line scope closed by an explicit closing macro.  All macros  Multi-line scope closed by an explicit closing macro.
 contains bodies; only  All macros contains bodies; only
 .Sx \&Bf  .Sx \&Bf
 contains a head.  contains a head.
 .Bd -literal -offset indent  .Bd -literal -offset indent
Line 655  contains a head.
Line 615  contains a head.
 \(lBbody...\(rB  \(lBbody...\(rB
 \&.Yc  \&.Yc
 .Ed  .Ed
 .  
 .Pp  .Pp
 .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXX"  .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXX"
 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope  .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
Line 668  contains a head.
Line 627  contains a head.
 .It Sx \&Ek  Ta    \&No     Ta    \&No     Ta    opened by Sx \&Bk  .It Sx \&Ek  Ta    \&No     Ta    \&No     Ta    opened by Sx \&Bk
 .It Sx \&El  Ta    \&No     Ta    \&No     Ta    opened by Sx \&Bl  .It Sx \&El  Ta    \&No     Ta    \&No     Ta    opened by Sx \&Bl
 .El  .El
 .  
 .  
 .Ss Block full-implicit  .Ss Block full-implicit
 Multi-line scope closed by end-of-file or implicitly by another macro.  Multi-line scope closed by end-of-file or implicitly by another macro.
 All macros have bodies; some  All macros have bodies; some
Line 689  has multiple heads.
Line 646  has multiple heads.
 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB  \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
 \(lBbody...\(rB  \(lBbody...\(rB
 .Ed  .Ed
 .  
 .Pp  .Pp
 .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXXXXXXXXXX"  .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXXXXXXXXXX"
 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope  .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
Line 698  has multiple heads.
Line 654  has multiple heads.
 .It Sx \&Sh  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Sh  .It Sx \&Sh  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Sh
 .It Sx \&Ss  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Sh , Sx \&Ss  .It Sx \&Ss  Ta    \&No     Ta    \&No     Ta    closed by Sx \&Sh , Sx \&Ss
 .El  .El
 .  
 .  
 .Ss Block partial-explicit  .Ss Block partial-explicit
 Like block full-explicit, but also with single-line scope.  Each  Like block full-explicit, but also with single-line scope.
 has at least a body and, in limited circumstances, a head  Each has at least a body and, in limited circumstances, a head
 .Po  .Po
 .Sx \&Fo ,  .Sx \&Fo ,
 .Sx \&Eo  .Sx \&Eo
Line 717  and/or tail
Line 671  and/or tail
 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \  \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
 \(lBbody...\(rB \&Yc \(lBtail...\(rB  \(lBbody...\(rB \&Yc \(lBtail...\(rB
 .Ed  .Ed
 .  
 .Pp  .Pp
 .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent  .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent
 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope  .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope
Line 746  and/or tail
Line 699  and/or tail
 .It Sx \&Xc  Ta    Yes      Ta    Yes      Ta    opened by Sx \&Xo  .It Sx \&Xc  Ta    Yes      Ta    Yes      Ta    opened by Sx \&Xo
 .It Sx \&Xo  Ta    Yes      Ta    Yes      Ta    closed by Sx \&Xc  .It Sx \&Xo  Ta    Yes      Ta    Yes      Ta    closed by Sx \&Xc
 .El  .El
 .  
 .  
 .Ss Block partial-implicit  .Ss Block partial-implicit
 Like block full-implicit, but with single-line scope closed by  Like block full-implicit, but with single-line scope closed by
 .Sx Reserved Characters  .Sx Reserved Characters
Line 755  or end of line.
Line 706  or end of line.
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB  \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
 .Ed  .Ed
 .  
 .Pp  .Pp
 .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent  .Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent
 .It Em Macro Ta Em Callable Ta Em Parsable  .It Em Macro Ta Em Callable Ta Em Parsable
Line 770  or end of line.
Line 720  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
   .Em SYNOPSIS
   section line, else it is
   .Sx In-line .
 .Ss In-line  .Ss In-line
 Closed by  Closed by
 .Sx Reserved Characters ,  .Sx Reserved Characters ,
 end of line, fixed argument lengths, and/or subsequent macros.  In-line  end of line, fixed argument lengths, and/or subsequent macros.
 macros have only text children.  If a number (or inequality) of  In-line macros have only text children.
 arguments is  If a number (or inequality) of arguments is
 .Pq n ,  .Pq n ,
 then the macro accepts an arbitrary number of arguments.  then the macro accepts an arbitrary number of arguments.
 .Bd -literal -offset indent  .Bd -literal -offset indent
Line 788  then the macro accepts an arbitrary number of argument
Line 747  then the macro accepts an arbitrary number of argument
   
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN  \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
 .Ed  .Ed
 .  
 .Pp  .Pp
 .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent  .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent
 .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments  .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments
Line 851  then the macro accepts an arbitrary number of argument
Line 809  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 863  then the macro accepts an arbitrary number of argument
Line 821  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
 This section is a canonical reference of all macros, arranged  This section is a canonical reference of all macros, arranged
 alphabetically.  For the scoping of individual macros, see  alphabetically.
   For the scoping of individual macros, see
 .Sx MACRO SYNTAX .  .Sx MACRO SYNTAX .
 .  
 .Ss \&%A  .Ss \&%A
 Author name of an  Author name of an
 .Sx \&Rs  .Sx \&Rs
Line 881  block.  Multiple authors should each be accorded their
Line 837  block.  Multiple authors should each be accorded their
 .Sx \%%A  .Sx \%%A
 line.  Author names should be ordered with full or abbreviated  line.  Author names should be ordered with full or abbreviated
 forename(s) first, then full surname.  forename(s) first, then full surname.
 .  
 .Ss \&%B  .Ss \&%B
 Book title of an  Book title of an
 .Sx \&Rs  .Sx \&Rs
 block.  This macro may also be used in a non-bibliographic context when  block.  This macro may also be used in a non-bibliographic context when
 referring to book titles.  referring to book titles.
 .  
 .Ss \&%C  .Ss \&%C
 Publication city or location of an  Publication city or location of an
 .Sx \&Rs  .Sx \&Rs
Line 896  block.
Line 850  block.
 .Em Remarks :  .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 reduced or canonical form syntax  block.  This should follow the reduced or canonical form syntax
 described in  described in
 .Sx Dates .  .Sx Dates .
 .  
 .Ss \&%I  .Ss \&%I
 Publisher or issuer name of an  Publisher or issuer name of an
 .Sx \&Rs  .Sx \&Rs
 block.  block.
 .  
 .Ss \&%J  .Ss \&%J
 Journal name of an  Journal name of an
 .Sx \&Rs  .Sx \&Rs
 block.  block.
 .  
 .Ss \&%N  .Ss \&%N
 Issue number (usually for journals) of an  Issue number (usually for journals) of an
 .Sx \&Rs  .Sx \&Rs
 block.  block.
 .  
 .Ss \&%O  .Ss \&%O
 Optional information of an  Optional information of an
 .Sx \&Rs  .Sx \&Rs
 block.  block.
 .  
 .Ss \&%P  .Ss \&%P
 Book or journal page number of an  Book or journal page number of an
 .Sx \&Rs  .Sx \&Rs
 block.  block.
 .  
 .Ss \&%Q  .Ss \&%Q
 Institutional author (school, government, etc.) of an  Institutional author (school, government, etc.) of an
 .Sx \&Rs  .Sx \&Rs
 block.  Multiple institutional authors should each be accorded their own  block.  Multiple institutional authors should each be accorded their own
 .Sx \&%Q  .Sx \&%Q
 line.  line.
 .  
 .Ss \&%R  .Ss \&%R
 Technical report name of an  Technical report name of an
 .Sx \&Rs  .Sx \&Rs
 block.  block.
 .  
 .Ss \&%T  .Ss \&%T
 Article title of an  Article title of an
 .Sx \&Rs  .Sx \&Rs
 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  .Ss \&%U
 URI of reference document.  URI of reference document.
 .  
 .Ss \&%V  .Ss \&%V
 Volume number of an  Volume number of an
 .Sx \&Rs  .Sx \&Rs
 block.  block.
 .  
 .Ss \&Ac  .Ss \&Ac
 Closes an  Closes an
 .Sx \&Ao  .Sx \&Ao
 block.  Does not have any tail arguments.  block.  Does not have any tail arguments.
 .  
 .Ss \&Ad  .Ss \&Ad
 Address construct: usually in the context of an computational address in  Address construct: usually in the context of an computational address in
 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.
 arguments, although these may not be specified along with a parameter:  This macro may alternatively accepts the following 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 before each author listing.  Renders a line break before each author listing.
Line 983  The opposite of
Line 922  The opposite of
 .Pp  .Pp
 In the AUTHORS section, the default is not to split the first author  In the AUTHORS section, the default is not to split the first author
 listing, but all subsequent author listings, whether or not they're  listing, but all subsequent author listings, whether or not they're
 interspersed by other macros or text, are split.  Thus, specifying  interspersed by other macros or text, are split.
   Thus, specifying
 .Fl split  .Fl split
 will cause the first listing also to be split.  If not in the AUTHORS  will cause the first listing also to be split.
 section, the default is not to split.  If not in the AUTHORS 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 1004  are re-set when entering the AUTHORS section, so if on
Line 941  are re-set when entering the AUTHORS section, so if on
 .Sx \&An Fl nosplit  .Sx \&An Fl nosplit
 in the general document body, it must be re-specified in the AUTHORS  in the general document body, it must be re-specified in the AUTHORS
 section.  section.
 .  
 .Ss \&Ao  .Ss \&Ao
 Begins a block enclosed by angled brackets.  Does not have any head  Begins a block enclosed by angled brackets.
 arguments.  Does not have any head 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 .
 .  
 .Ss \&Ap  .Ss \&Ap
 Inserts an apostrophe without any surrounding white-space.  This is  Inserts an apostrophe without any surrounding white-space.
 generally used as a grammatic device when referring to the verb form of  This is generally used as a grammatic device when referring to the verb
 a function:  form of a function:
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Fn execve Ap d  \&.Fn execve Ap d
 .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 1045  statements, which should use
Line 975  statements, which should use
 .Pp  .Pp
 See also  See also
 .Sx \&Ao .  .Sx \&Ao .
 .  
 .Ss \&Ar  .Ss \&Ar
 Command arguments.  If an argument is not provided, the string  Command arguments.
   If an argument is not provided, the string
 .Dq file ...  .Dq file ...
 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:
 .Bl -tag -width 12n -offset indent  .Bl -tag -width 12n -offset indent
 .It Cm v[1-7] | 32v  .It Cm v[1-7] | 32v
 A version of  A version of
Line 1072  A system version of
Line 1000  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 1086  See also
Line 1012  See also
 .Sx \&Ox ,  .Sx \&Ox ,
 and  and
 .Sx \&Ux .  .Sx \&Ux .
 .  
 .Ss \&Bc  .Ss \&Bc
 Closes a  Closes a
 .Sx \&Bo  .Sx \&Bo
 block.  Does not have any tail arguments.  block.  Does not have any tail arguments.
 .  
 .Ss \&Bd  .Ss \&Bd
 Begins a display block.  A display is collection of macros or text which  Begins a display block.
 may be collectively offset or justified in a manner different from that  A display is collection of macros or text which may be collectively
 of the enclosing context.  By default, the block is preceded by a  offset or justified in a manner different from that
 vertical space.  of the enclosing context.
   By default, the block is preceded by a vertical space.
 .Pp  .Pp
 Each display is associated with a type, which must be one of the  Each display is associated with a type, which must be one of the
 following arguments:  following arguments:
Line 1114  Alias for
Line 1039  Alias for
 Centre-justify each line.  Centre-justify each line.
 .El  .El
 .Pp  .Pp
 The type must be provided first.  Secondary arguments are as follows:  The type must be provided first.
   Secondary arguments are as follows:
 .Bl -tag -width 12n -offset indent  .Bl -tag -width 12n -offset indent
 .It Fl offset Ar width  .It Fl offset Ar width
 Offset by the value of  Offset by the value of
Line 1135  which justifies to the right margin; and
Line 1061  which justifies to the right margin; and
 .Ar center ,  .Ar center ,
 which aligns around an imagined centre axis.  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.
 imaginary macro  The most popular is the imaginary macro
 .Ar \&Ds ,  .Ar \&Ds ,
 which resolves to  which resolves to
 .Ar 6n .  .Ar 6n .
Line 1170  See also
Line 1096  See also
 .Sx \&D1  .Sx \&D1
 and  and
 .Sx \&Dl .  .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  Begins a list composed of one or more list entries.
 .\" specified by the  A list is associated with a type, which is a required argument.
 .\" .Sx \&It  Other arguments are
 .\" macro, which consists of a head and optional body.  By default, a list  .Fl width ,
 .\" is preceded by a blank line.  A list must specify one of the following  defined per-type as accepting a literal or
 .\" list types:  .Sx Scaling Widths
 .\" .Bl -tag -width 12n  value;
 .\" .It Fl bullet  .Fl offset ,
 .\" A list offset by a bullet.  The head of list entries must be empty.  also accepting a literal or
 .\" List entry bodies are justified after the bullet.  .Sx Scaling Widths
 .\" .It Fl column  value setting the list's global offset; and
 .\" A columnated list.  The number of columns is specified as arguments to  .Fl compact ,
 .\" the  suppressing the default vertical space printed before each list entry.
 .\" .Sx \&Bl  A list entry is specified by the
 .\" macro (the deprecated form of following the invocation of  .Sx \&It
 .\" .Fl column  macro, which consists of a head and optional body (depending on the list
 .\" is also accepted).  Arguments dictate the width of columns specified in  type).
 .\" list entries.  List entry bodies must be left empty.  Columns specified  A list must specify one of the following list types:
 .\" in the list entry head are justified to their position in the sequence  .Bl -tag -width 12n -offset indent
 .\" of columns.  .It Fl bullet
 .\" .It Fl dash  A list offset by a bullet.
 .\" A list offset by a dash (hyphen).  The head of list entries must be  The head of list entries must be empty.
 .\" empty.  List entry bodies are justified past the dash.  List entry bodies are positioned after the bullet.
 .\" .It Fl diag  The
 .\" Like  .Fl width
 .\" .Fl inset  argument varies the width of list bodies' left-margins.
 .\" lists, but with additional formatting to the head.  .It Fl column
 .\" .It Fl enum  A columnated list.
 .\" A list offset by a number indicating list entry position.  The head of  The
 .\" list entries must be empty.  List entry bodies are justified past the  .Fl width
 .\" enumeration.  argument has no effect.
 .\" .It Fl hang  The number of columns is specified as parameters to the
 .\" Like  .Sx \&Bl
 .\" .Fl tag ,  macro.
 .\" but instead of list bodies justifying to the head on the first line,  These dictate the width of columns either as
 .\" they trail the head text.  .Sx Scaling Widths
 .\" .It Fl hyphen  or literal text.
 .\" Synonym for  If the initial macro of a
 .\" .Fl dash .  .Fl column
 .\" .It Fl inset  list is not an
 .\" Like  .Sx \&It ,
 .\" .Fl tag ,  an
 .\" but list entry bodies aren't justified.  .Sx \&It
 .\" .It Fl item  context spanning each line is implied until an
 .\" An un-justified list.  This produces blocks of text.  .Sx \&It
 .\" .It Fl ohang  line macro is encountered, at which point list bodies are interpreted as
 .\" List bodies are placed on the line following the head.  described in the
 .\" .It Fl tag  .Sx \&It
 .\" A list offset by list entry heads.  List entry bodies are justified  documentation.
 .\" after the head.  .It Fl dash
 .\" .El  A list offset by a dash (hyphen).
 .\" .Pp  The head of list entries must be empty.
 .\" More...  List entry bodies are positioned past the dash.
 .\" .  The
   .Fl width
   argument varies the width of list bodies' left-margins.
   .It Fl diag
   Like
   .Fl inset ,
   but with additional formatting to the head.
   The
   .Fl width
   argument varies the width of list bodies' left-margins.
   .It Fl enum
   An enumerated list offset by the enumeration from 1.
   The head of list entries must be empty.
   List entry bodies are positioned after the enumeration.
   The
   .Fl width
   argument varies the width of list bodies' left-margins.
   .It Fl hang
   Like
   .Fl tag ,
   but instead of list bodies positioned after the head, they trail the
   head text.
   The
   .Fl width
   argument varies the width of list bodies' left-margins.
   .It Fl hyphen
   Synonym for
   .Fl dash .
   .It Fl inset
   List bodies follow the list head.
   The
   .Fl width
   argument is ignored.
   .It Fl item
   This produces blocks of text.
   The head of list entries must be empty.
   The
   .Fl width
   argument is ignored.
   .It Fl ohang
   List bodies are positioned on the line following the head.
   The
   .Fl width
   argument is ignored.
   .It Fl tag
   A list offset by list entry heads.  List entry bodies are positioned
   after the head as specified by the
   .Fl width
   argument.
   .El
   .Pp
   See also
   .Sx \&It .
 .Ss \&Bo  .Ss \&Bo
 Begins a block enclosed by square brackets.  Does not have any head  Begins a block enclosed by square brackets.
 arguments.  Does not have any head arguments.
 .Pp  .Pp
 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 1259  and
Line 1233  and
 .Pp  .Pp
 See also  See also
 .Sx \&Bo .  .Sx \&Bo .
 .  
 .Ss \&Brc  .Ss \&Brc
 Closes a  Closes a
 .Sx \&Bro  .Sx \&Bro
 block.  Does not have any tail arguments.  block.  Does not have any tail arguments.
 .  
 .Ss \&Bro  .Ss \&Bro
 Begins a block enclosed by curly braces.  Does not have any head  Begins a block enclosed by curly braces.
 arguments.  Does not have any head arguments.
 .Pp  .Pp
 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
 .Sx \&Brq .  .Sx \&Brq .
 .  
 .Ss \&Brq  .Ss \&Brq
 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 .
 .  
 .Ss \&Bsx  .Ss \&Bsx
 Format the BSD/OS version provided as an argument, or a default value if  Format the BSD/OS version provided as an argument, or a default value if
 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 1308  See also
Line 1274  See also
 .Sx \&Ox ,  .Sx \&Ox ,
 and  and
 .Sx \&Ux .  .Sx \&Ux .
 .  
 .Ss \&Bt  .Ss \&Bt
 Prints  Prints
 .Dq is currently in beta test.  .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 ,
Line 1332  See also
Line 1294  See also
 .Sx \&Ox ,  .Sx \&Ox ,
 and  and
 .Sx \&Ux .  .Sx \&Ux .
 .  
 .Ss \&Cd  .Ss \&Cd
 Configuration declaration (suggested for use only in section four  Configuration declaration.
 manuals).  This denotes strings accepted by  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
 white-space and align consecutive  white-space and align consecutive
 .Sx \&Cd  .Sx \&Cd
 declarations.  This practise is discouraged.  declarations.
 .  This practise is discouraged.
 .Ss \&Cm  .Ss \&Cm
 Command modifiers.  Useful when specifying configuration options or  Command modifiers.
 keys.  Useful when specifying configuration options or 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 .
 .  
 .Ss \&D1  .Ss \&D1
 One-line indented display.  This is formatted by the default rules and  One-line indented display.
 is useful for simple indented statements.  It is followed by a newline.  This is formatted by the default rules and 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
 and  and
 .Sx \&Dl .  .Sx \&Dl .
 .  
 .Ss \&Db  .Ss \&Db
 .Ss \&Dc  .Ss \&Dc
 Closes a  Closes a
 .Sx \&Do  .Sx \&Do
 block.  Does not have any tail arguments.  block.  Does not have any tail arguments.
 .  
 .Ss \&Dd  .Ss \&Dd
 Document date.  This is the mandatory first macro of any  Document date.
   This is the mandatory first macro of any
 .Nm  .Nm
 manual.  Its calling syntax is as follows:  manual.
   Its calling syntax is as follows:
 .Pp  .Pp
 .D1 \. Ns Sx \&Dd Cm date  .D1 \. Ns Sx \&Dd Cm date
 .Pp  .Pp
Line 1400  or instead a valid canonical date as specified by
Line 1356  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
 and  and
 .Sx \&Os .  .Sx \&Os .
 .  
 .Ss \&Dl  .Ss \&Dl
 One-line intended display.  This is formatted as literal text and is  One-line intended display.
 useful for commands and invocations.  It is followed by a newline.  This is formatted as literal text and is 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
 and  and
 .Sx \&D1 .  .Sx \&D1 .
 .  
 .Ss \&Do  .Ss \&Do
 Begins a block enclosed by double quotes.  Does not have any head  Begins a block enclosed by double quotes.  Does not have any head
 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
 .Pp  .Pp
 See also  See also
 .Sx \&Do .  .Sx \&Do .
 .  
 .Ss \&Dt  .Ss \&Dt
 Document title.  This is the mandatory second macro of any  Document title.
   This is the mandatory second macro of any
 .Nm  .Nm
 file.  Its calling syntax is as follows:  file.
   Its calling syntax is as follows:
 .Pp  .Pp
 .D1 \. Ns Sx \&Dt Cm title section Op Cm volume | arch  .D1 \. Ns Sx \&Dt Op Cm title Op Cm section Op Cm volume | arch
 .Pp  .Pp
 Its arguments are as follows:  Its arguments are as follows:
 .Bl -tag -width Ds -offset Ds  .Bl -tag -width Ds -offset Ds
 .It Cm title  .It Cm title
 The document's title (name).  This should be capitalised and is  The document's title (name), defaulting to
 required.  .Qq UNKNOWN
   if unspecified.
   It should be capitalised.
 .It Cm section  .It Cm section
 The manual section.  This may be one of  The manual section.
   This may be one of
 .Ar 1  .Ar 1
 .Pq utilities ,  .Pq utilities ,
 .Ar 2  .Ar 2
Line 1496  The manual section.  This may be one of
Line 1449  The manual section.  This may be one of
 or  or
 .Ar paper  .Ar paper
 .Pq paper .  .Pq paper .
 It is also required and should correspond to the manual's filename  It should correspond to the manual's filename suffix and defaults to
 suffix.  .Qq 1
   if unspecified.
 .It Cm volume  .It Cm volume
 This overrides the volume inferred from  This overrides the volume inferred from
 .Ar section .  .Ar section .
Line 1528  or
Line 1482  or
 .Ar CON  .Ar CON
 .Pq contributed manuals .  .Pq contributed manuals .
 .It Cm arch  .It Cm arch
 This specifies a specific relevant architecture.  If  This specifies a specific relevant architecture.
   If
 .Cm volume  .Cm volume
 is not provided, it may be used in its place, else it may be used  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  subsequent that.
   It, too, is optional.
   It must be one of
 .Ar alpha ,  .Ar alpha ,
 .Ar amd64 ,  .Ar amd64 ,
 .Ar amiga ,  .Ar amiga ,
Line 1544  subsequent that.  It, too, is optional.  It must be on
Line 1501  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 1562  or
Line 1520  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  
 \&.Dt FOO 9 KM i386  
 .Ed  
 .Pp  .Pp
 See also  See also
 .Sx \&Dd  .Sx \&Dd
 and  and
 .Sx \&Os .  .Sx \&Os .
 .  
 .Ss \&Dv  .Ss \&Dv
 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 .
 .  
 .Ss \&Dx  .Ss \&Dx
 Format the DragonFly BSD version provided as an argument, or a default  Format the DragonFly BSD version provided as an argument, or a default
 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 1605  See also
Line 1554  See also
 .Sx \&Ox ,  .Sx \&Ox ,
 and  and
 .Sx \&Ux .  .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  Denotes text that should be emphasised.
 presentation term and should not be used for stylistically decorating  Note that this is a presentation term and should not be used for
 technical terms.  stylistically decorating 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 .
 .  
 .Ss \&Es  .Ss \&Es
 .  
 .Ss \&Ev  .Ss \&Ev
 Environmental variables such as those specified in  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.
 first the  This macro must have first the
 .Fl std  .Fl std
 argument specified, then an optional  argument specified, then an optional
 .Ar utility .  .Ar utility .
Line 1663  is provided.
Line 1601  is provided.
 .Ss \&Fc  .Ss \&Fc
 .Ss \&Fd  .Ss \&Fd
 .Ss \&Fl  .Ss \&Fl
 Command-line flag.  Used when listing arguments to command-line  Command-line flag.
 utilities.  Prints a fixed-width hyphen  Used when listing arguments to command-line utilities.
   Prints a fixed-width hyphen
 .Sq \-  .Sq \-
 before each delimited argument.  If no arguments are provided, a hyphen  directly followed by each argument.
 is still printed.  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  .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 .
 .  
 .Ss \&Fn  .Ss \&Fn
 .Ss \&Fo  .Ss \&Fo
 .Ss \&Fr  .Ss \&Fr
Line 1688  Format the FreeBSD version provided as an argument, or
Line 1627  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 1702  See also
Line 1639  See also
 .Sx \&Ox ,  .Sx \&Ox ,
 and  and
 .Sx \&Ux .  .Sx \&Ux .
 .  
 .Ss \&Hf  .Ss \&Hf
 .Ss \&Ic  .Ss \&Ic
 .Ss \&In  .Ss \&In
 .Ss \&It  .Ss \&It
   A list item.  The syntax of this macro depends on the list type.
   .Pp
   Lists
   of type
   .Fl hang ,
   .Fl ohang ,
   .Fl inset ,
   and
   .Fl diag
   have the following calling syntax:
   .Pp
   .D1 \. Ns Sx \&It Cm args
   .Pp
   Lists of type
   .Fl bullet ,
   .Fl dash ,
   .Fl enum ,
   .Fl hyphen
   and
   .Fl item
   have the following calling syntax:
   .Pp
   .D1 \. Ns Sx \&It
   .Pp
   with subsequent lines interpreted within the scope of the
   .Sx \&It
   until either a closing
   .Sx \&El
   or another
   .Sx \&It .
   .Pp
   The
   .Fl tag
   list has syntax
   .Pp
   .D1 \. Ns Sx \&It Op Cm args
   .Pp
   with subsequent lines interpreted as with
   .Fl bullet
   and family.
   The line arguments correspond to the list's left-hand side; body
   arguments correspond to the list's contents.
   .Pp
   The
   .Fl column
   list is the most complicated.
   Its syntax is
   .Pp
   .D1 \. Ns Sx \&It Op Cm args
   .Pp
   where
   .Cm args
   are phrases, a mix of macros and text corresponding to a line column,
   delimited by tabs or the special
   .Sq \&Ta
   pseudo-macro.
   Lines subsequent the
   .Sx \&It
   are interpreted within the scope of the last phrase.
   Calling the pseudo-macro
   .Sq \&Ta
   will open a new phrase scope (this must occur on a macro line to be
   interpreted as a macro).  Note that the tab phrase delimiter may only be
   used within the
   .Sx \&It
   line itself.
   Subsequent this, only the
   .Sq \&Ta
   pseudo-macro may be used to delimit phrases.
   Furthermore, note that quoted sections propogate over tab-delimited
   phrases on an
   .Sx \&It ,
   for example,
   .Pp
   .D1 .It \(dqcol1 ; <TAB> col2 ;\(dq ;
   .Pp
   will preserve the semicolon whitespace except for the last.
   .Pp
   See also
   .Sx \&Bl .
 .Ss \&Lb  .Ss \&Lb
   Specify a library.
   The calling syntax is as follows:
   .Pp
   .D1 \. Ns Sx \&Lb Cm library
   .Pp
   The
   .Cm library
   parameter may be a system library, such as
   .Cm libz
   or
   .Cm libpam ,
   in which case a small library description is printed next to the linker
   invocation; or a custom library, in which case the library name is
   printed in quotes.
   This is most commonly used in the
   .Em SYNOPSIS
   section as described in
   .Sx MANUAL STRUCTURE .
   .Pp
   Examples:
   .D1 \&.Lb libz
   .D1 \&.Lb mdoc
 .Ss \&Li  .Ss \&Li
 .Ss \&Lk  .Ss \&Lk
 Format a hyperlink.  The calling syntax is as follows:  Format a hyperlink.
   The calling syntax is as follows:
 .Pp  .Pp
 .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 .
 .  
 .Ss \&Lp  .Ss \&Lp
 .Ss \&Ms  .Ss \&Ms
 .Ss \&Mt  .Ss \&Mt
Line 1735  Format the NetBSD version provided as an argument, or 
Line 1771  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 1749  See also
Line 1783  See also
 .Sx \&Ox ,  .Sx \&Ox ,
 and  and
 .Sx \&Ux .  .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  Document operating system version.
   This is the mandatory third macro of
 any  any
 .Nm  .Nm
 file.  Its calling syntax is as follows:  file.  Its calling syntax is as follows:
Line 1763  file.  Its calling syntax is as follows:
Line 1797  file.  Its calling syntax is as follows:
 .Pp  .Pp
 The optional  The optional
 .Cm system  .Cm system
 parameter specifies the relevant operating system or environment.  Left  parameter specifies the relevant operating system or environment.
 unspecified, it defaults to the local operating system version.  This is  Left unspecified, it defaults to the local operating system version.
 the suggested form.  This is 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
 and  and
 .Sx \&Dt .  .Sx \&Dt .
 .  
 .Ss \&Ot  .Ss \&Ot
 Unknown usage.  Unknown usage.
 .Pp  .Pp
 .Em Remarks :  .Em Remarks :
 this macro has been deprecated.  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 ,
Line 1804  See also
Line 1832  See also
 .Sx \&Nx ,  .Sx \&Nx ,
 and  and
 .Sx \&Ux .  .Sx \&Ux .
 .  
 .Ss \&Pa  .Ss \&Pa
 .Ss \&Pc  .Ss \&Pc
 .Ss \&Pf  .Ss \&Pf
Line 1815  and
Line 1842  and
 .Ss \&Ql  .Ss \&Ql
 .Ss \&Qo  .Ss \&Qo
 .Ss \&Qq  .Ss \&Qq
 .  
 .Ss \&Re  .Ss \&Re
 Closes a  Closes a
 .Sx \&Rs  .Sx \&Rs
 block.  Does not have any tail arguments.  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 may only  block.
 contain  Does not have any head arguments.
   The block macro may only contain
 .Sx \&%A ,  .Sx \&%A ,
 .Sx \&%B ,  .Sx \&%B ,
 .Sx \&%C ,  .Sx \&%C ,
Line 1843  and
Line 1870  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 1859  If an
Line 1886  If an
 block is used within a SEE ALSO section, a vertical space is asserted  block is used within a SEE ALSO section, a vertical space is asserted
 before the rendered output, else the block continues on the current  before the rendered output, else the block continues on the current
 line.  line.
 .  
 .Ss \&Rv  .Ss \&Rv
 .Ss \&Sc  .Ss \&Sc
 .Ss \&Sh  .Ss \&Sh
Line 1872  line.
Line 1898  line.
 .Ss \&Sy  .Ss \&Sy
 .Ss \&Tn  .Ss \&Tn
 .Ss \&Ud  .Ss \&Ud
   Prints out
   .Dq currently under development.
 .Ss \&Ux  .Ss \&Ux
 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 1889  See also
Line 1916  See also
 .Sx \&Nx ,  .Sx \&Nx ,
 and  and
 .Sx \&Ox .  .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:
   .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
 The comment syntax  The comment syntax
 .Sq \e."  .Sq \e."
 is no longer accepted.  is no longer accepted.
 .It  .It
 In  In groff, the
 .Xr groff 1 ,  
 the  
 .Sx \&Pa  .Sx \&Pa
 macro does not format its arguments when used in the FILES section under  macro does not format its arguments when used in the FILES section under
 certain list types.  This irregular behaviour has been discontinued.  certain list types.
   mandoc does.
 .It  .It
 Historic  Historic groff does not print a dash for empty
 .Xr groff 1  
 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.
 .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.
 .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.
 behaviour is no longer applicable.  This idiosyncratic behaviour is not applicable in mandoc.
 .It  .It
 Display types  Display types
 .Sx \&Bd  .Sx \&Bd
Line 1954  Display types
Line 2026  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 1966  are aliases, as are
Line 2039  are aliases, as are
 and  and
 .Fl unfilled .  .Fl unfilled .
 .It  .It
 Blocks of whitespace are stripped from both macro and free-form text  Historic groff has many un-callable macros.
 lines (except when in literal mode), while groff would retain whitespace  Most of these (excluding some block-level macros) are now callable.
 in free-form text lines.  
 .It  .It
 Historic groff has many un-callable macros.  Most of these (excluding  
 some block-level macros) are now callable, conforming to the  
 non-historic groff version.  
 .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
Line 1990  lists will restart the sequence only for the sub-list.
Line 2057  lists will restart the sequence only for the sub-list.
 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 ,
   .Sx \&Ex ,
   and
   .Sx \&Rv
   macros were stipulated only to occur in certain manual sections.
   mandoc does not have these restrictions.
   .It
   Newer groff and mandoc print
   .Qq AT&T UNIX
   prior to unknown arguments of
   .Sx \&At ;
   older groff did nothing.
 .El  .El
 .  
 .  
 .Sh SEE ALSO  .Sh SEE ALSO
 .Xr mandoc 1 ,  .Xr mandoc 1 ,
 .Xr mandoc_char 7  .Xr mandoc_char 7
 .  
 .  
 .Sh AUTHORS  .Sh AUTHORS
 The  The
 .Nm  .Nm
 reference was written by  reference was written by
 .An Kristaps Dzonsons Aq kristaps@kth.se .  .An Kristaps Dzonsons Aq kristaps@bsd.lv .
 .\"  .\"
 .\" XXX: this really isn't the place for these caveats.  .\" XXX: this really isn't the place for these caveats.
 .\" .  .\" .

Legend:
Removed from v.1.82  
changed lines
  Added in v.1.114

CVSweb