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

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

version 1.64, 2009/10/19 10:18:05 version 1.98, 2010/05/08 22:26:39
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 126  for a complete list.  Examples include
Line 109  for a complete list.  Examples include
 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
 escape followed by an indicator: B (bold), I, (italic), or P and R  escape followed by an indicator: B (bold), I, (italic), R (Roman), or P
 (Roman, or reset).  This form is not recommended for  (revert to previous mode):
   .Pp
   .D1 \efBbold\efR \efIitalic\efP
   .Pp
   A numerical representation 3, 2, or 1 (bold, italic, and Roman,
   respectively) may be used instead.  A text decoration is valid within
   the current font scope only:  if a macro opens a font scope alongside
   its own scope, such as
   .Sx \&Bf
   .Cm \&Sy ,
   in-scope invocations of
   .Sq \ef
   are only valid within the font scope of the macro.  If
   .Sq \ef
   is specified outside of any font scope, such as in unenclosed, free-form
   text, it will affect the remainder of the document.
   .Pp
   Text may also be sized with the
   .Sq \es
   escape, whose syntax is one of
   .Sq \es+-n
   for one-digit numerals;
   .Sq \es(+-nn
   or
   .Sq \es+-(nn
   for two-digit numerals; and
   .Sq \es[+-N] ,
   .Sq \es+-[N] ,
   .Sq \es'+-N' ,
   or
   .Sq \es+-'N'
   for arbitrary-digit numerals:
   .Pp
   .D1 \es+1bigger\es-1
   .D1 \es[+10]much bigger\es[-10]
   .D1 \es+(10much bigger\es-(10
   .D1 \es+'100'much much bigger\es-'100'
   .Pp
   Note these forms are
   .Em not
   recommended for
 .Nm ,  .Nm ,
 which encourages semantic, not presentation, annotation.  which encourages semantic annotation.
 .  
 .  
 .Ss Predefined Strings  .Ss Predefined Strings
 Historically,  Historically,
 .Xr groff 1  .Xr groff 1
 also defined a set of package-specific  also defined a set of package-specific
 .Dq predefined strings ,  .Dq predefined strings ,
 which, like  which, like
 .Sx Special Characters ,  .Sx Special Characters ,
 demark special output characters and strings by way of input codes.  demark special output characters and strings by way of input codes.
 Predefined strings are escaped with the slash-asterisk,  Predefined strings are escaped with the slash-asterisk,
Line 161  for a complete list.  Examples include
Line 180  for a complete list.  Examples include
 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.  If
 arguments are quoted, whitespace within the quotes is retained.  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.  A quoted
 argument begins with a double-quote preceded by whitespace.  The next  argument begins with a double-quote preceded by whitespace.  The next
 double-quote not pair-wise adjacent to another double-quote terminates  double-quote not pair-wise adjacent to another double-quote terminates
 the literal, regardless of surrounding whitespace.  the literal, regardless of surrounding whitespace.
 .  
 .Pp  .Pp
 This produces tokens  This produces tokens
 .Sq a" ,  .Sq a" ,
Line 205  considered literal text.  Thus, the following produces
Line 208  considered literal text.  Thus, the following produces
 .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
 TODO.  There are several macros in
 .  .Nm
   that require a date argument.  The canonical form for dates is the
   American format:
   .Pp
   .D1 Cm Month Day , Year
   .Pp
   The
   .Cm Day
   value is an optionally zero-padded numeral.  The
   .Cm Month
   value is the full month name.  The
   .Cm Year
   value is the full four-digit year.
   .Pp
   Reduced form dates are broken-down canonical form dates:
   .Pp
   .D1 Cm Month , Year
   .D1 Cm Year
   .Pp
   Some examples of valid dates follow:
   .Pp
   .D1 "May, 2009" Pq reduced form
   .D1 "2009" Pq reduced form
   .D1 "May 20, 2009" Pq canonical form
 .Ss Scaling Widths  .Ss Scaling Widths
 Many macros support scaled widths for their arguments, such as  Many macros support scaled widths for their arguments, such as
 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:] ,
Line 264  or
Line 287  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 .
 .  
 .  
 .Sh MANUAL STRUCTURE  .Sh MANUAL STRUCTURE
 Each  A well-formed
 .Nm  .Nm
 document must begin with a document prologue, containing, in order,  document consists of a document prologue followed by one or more
   sections.
   .Pp
   The prologue, which consists of (in order) the
 .Sx \&Dd ,  .Sx \&Dd ,
 .Sx \&Dt ,  .Sx \&Dt ,
 and  and
 .Sx \&Os ,  .Sx \&Os
 then the NAME section containing at least one  macros, is required for every document.
   .Pp
   The first section (sections are denoted by
   .Sx \&Sh )
   must be the NAME section, consisting of at least one
 .Sx \&Nm  .Sx \&Nm
 followed by  followed by
 .Sx \&Nd :  .Sx \&Nd .
   .Pp
   Following that, convention dictates specifying at least the SYNOPSIS and
   DESCRIPTION sections, although this varies between manual sections.
   .Pp
   The following is a well-formed skeleton
   .Nm
   file:
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Dd $\&Mdocdate$  \&.Dd $\&Mdocdate$
 \&.Dt mdoc 7  \&.Dt mdoc 7
Line 320  utility processes files ...
Line 355  utility processes files ...
 \&.\e\*q .Sh BUGS  \&.\e\*q .Sh BUGS
 \&.\e\*q .Sh SECURITY CONSIDERATIONS  \&.\e\*q .Sh SECURITY CONSIDERATIONS
 .Ed  .Ed
 .  
 .Pp  .Pp
 Subsequent SYNOPSIS and DESCRIPTION sections are strongly encouraged,  The sections in a
 but non-compulsory.  .Nm
 .  document are conventionally ordered as they appear above.  Sections
 .  should be composed as follows:
   .Bl -ohang -offset Ds
   .It Em NAME
   The name(s) and a short description of the documented material.  The
   syntax for this as follows:
   .Bd -literal -offset indent
   \&.Nm name0
   \&.Nm name1
   \&.Nm name2
   \&.Nd a short description
   .Ed
   .Pp
   The
   .Sx \&Nm
   macro(s) must precede the
   .Sx \&Nd
   macro.
   .Pp
   See
   .Sx \&Nm
   and
   .Sx \&Nd .
   .It Em LIBRARY
   The name of the library containing the documented material, which is
   assumed to be a function in a section 2 or 3 manual.  The syntax for
   this is as follows:
   .Bd -literal -offset indent
   \&.Lb libarm
   .Ed
   .Pp
   See
   .Sx \&Lb .
   .It Em SYNOPSIS
   Documents the utility invocation syntax, function call syntax, or device
   configuration.
   .Pp
   For the first, utilities (sections 1, 6, and 8), this is
   generally structured as follows:
   .Bd -literal -offset indent
   \&.Nm foo
   \&.Op Fl v
   \&.Op Fl o Ar file
   \&.Op Ar
   \&.Nm bar
   \&.Op Fl v
   \&.Op Fl o Ar file
   \&.Op Ar
   .Ed
   .Pp
   For the second, function calls (sections 2, 3, 9):
   .Bd -literal -offset indent
   \&.Vt extern const char *global;
   \&.In header.h
   \&.Ft "char *"
   \&.Fn foo "const char *src"
   \&.Ft "char *"
   \&.Fn bar "const char *src"
   .Ed
   .Pp
   And for the third, configurations (section 4):
   .Bd -literal -offset indent
   \&.Cd \*qit* at isa? port 0x2e\*q
   \&.Cd \*qit* at isa? port 0x4e\*q
   .Ed
   .Pp
   Manuals not in these sections generally don't need a
   .Em SYNOPSIS .
   .Pp
   See
   .Sx \&Op ,
   .Sx \&Cd ,
   .Sx \&Fn ,
   .Sx \&Ft ,
   and
   .Sx \&Vt .
   .It Em DESCRIPTION
   This expands upon the brief, one-line description in
   .Em NAME .
   It usually contains a break-down of the options (if documenting a
   command), such as:
   .Bd -literal -offset indent
   The arguments are as follows:
   \&.Bl \-tag \-width Ds
   \&.It Fl v
   Print verbose information.
   \&.El
   .Ed
   .Pp
   Manuals not documenting a command won't include the above fragment.
   .It Em IMPLEMENTATION NOTES
   Implementation-specific notes should be kept here.  This is useful when
   implementing standard functions that may have side effects or notable
   algorithmic implications.
   .It Em EXIT STATUS
   Command exit status for section 1, 6, and 8 manuals.  This section is
   the dual of
   .Em RETURN VALUES ,
   which is used for functions.  Historically, this information was
   described in
   .Em DIAGNOSTICS ,
   a practise that is now discouraged.
   .Pp
   See
   .Sx \&Ex .
   .It Em RETURN VALUES
   This section is the dual of
   .Em EXIT STATUS ,
   which is used for commands.  It documents the return values of functions
   in sections 2, 3, and 9.
   .Pp
   See
   .Sx \&Rv .
   .It Em ENVIRONMENT
   Documents any usages of environment variables, e.g.,
   .Xr environ 7 .
   .Pp
   See
   .Sx \&Ev .
   .It Em FILES
   Documents files used.  It's helpful to document both the file and a
   short description of how the file is used (created, modified, etc.).
   .Pp
   See
   .Sx \&Pa .
   .It Em EXAMPLES
   Example usages.  This often contains snippets of well-formed,
   well-tested invocations.  Make doubly sure that your examples work
   properly!
   .It Em DIAGNOSTICS
   Documents error conditions.  This is most useful in section 4 manuals.
   Historically, this section was used in place of
   .Em EXIT STATUS
   for manuals in sections 1, 6, and 8; however, this practise is
   discouraged.
   .Pp
   See
   .Sx \&Bl
   .Fl diag .
   .It Em ERRORS
   Documents error handling in sections 2, 3, and 9.
   .Pp
   See
   .Sx \&Er .
   .It Em SEE ALSO
   References other manuals with related topics.  This section should exist
   for most manuals.  Cross-references should conventionally be ordered
   first by section, then alphabetically.
   .Pp
   See
   .Sx \&Xr .
   .It Em STANDARDS
   References any standards implemented or used.  If not adhering to any
   standards, the
   .Em HISTORY
   section should be used instead.
   .Pp
   See
   .Sx \&St .
   .It Em HISTORY
   The history of any manual without a
   .Em STANDARDS
   section should be described in this section.
   .It Em AUTHORS
   Credits to authors, if applicable, should appear in this section.
   Authors should generally be noted by both name and an e-mail address.
   .Pp
   See
   .Sx \&An .
   .It Em CAVEATS
   Explanations of common misuses and misunderstandings should be explained
   in this section.
   .It Em BUGS
   Extant bugs should be described in this section.
   .It Em SECURITY CONSIDERATIONS
   Documents any security precautions that operators should consider.
   .El
 .Sh MACRO SYNTAX  .Sh MACRO SYNTAX
 Macros are one to three three characters in length and begin with a  Macros are one to three three characters in length and begin with a
 control character ,  control character ,
Line 337  following are equivalent:
Line 546  following are equivalent:
 \&.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
Line 348  parameters;
Line 556  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
Line 358  initial line macro is interpreted as opaque text, such
Line 565  initial line macro is interpreted as opaque text, such
 .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.  If a macro is not parsable, subsequent
 macro invocations on the line will be interpreted as opaque text.  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.  All macros
 contains bodies; only  contains bodies; only
Line 382  contains a head.
Line 585  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 395  contains a head.
Line 597  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 410  All macros have bodies; some
Line 610  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
 \(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 425  has multiple heads.
Line 624  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.  Each
 has at least a body and, in limited circumstances, a head  has at least a body and, in limited circumstances, a head
Line 444  and/or tail
Line 641  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 473  and/or tail
Line 669  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 482  or end of line.
Line 676  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 497  or end of line.
Line 690  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
 Closed by  Closed by
 .Sx Reserved Characters ,  .Sx Reserved Characters ,
Line 515  then the macro accepts an arbitrary number of argument
Line 715  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 528  then the macro accepts an arbitrary number of argument
Line 727  then the macro accepts an arbitrary number of argument
 .It Sx \&%N  Ta    \&No     Ta    \&No     Ta    >0  .It Sx \&%N  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&%O  Ta    \&No     Ta    \&No     Ta    >0  .It Sx \&%O  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&%P  Ta    \&No     Ta    \&No     Ta    >0  .It Sx \&%P  Ta    \&No     Ta    \&No     Ta    >0
   .It Sx \&%Q  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&%R  Ta    \&No     Ta    \&No     Ta    >0  .It Sx \&%R  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&%T  Ta    \&No     Ta    \&No     Ta    >0  .It Sx \&%T  Ta    \&No     Ta    \&No     Ta    >0
   .It Sx \&%U  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&%V  Ta    \&No     Ta    \&No     Ta    >0  .It Sx \&%V  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&Ad  Ta    Yes      Ta    Yes      Ta    n  .It Sx \&Ad  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&An  Ta    Yes      Ta    Yes      Ta    n  .It Sx \&An  Ta    Yes      Ta    Yes      Ta    n
Line 576  then the macro accepts an arbitrary number of argument
Line 777  then the macro accepts an arbitrary number of argument
 .It Sx \&Ot  Ta    \&No     Ta    \&No     Ta    n  .It Sx \&Ot  Ta    \&No     Ta    \&No     Ta    n
 .It Sx \&Ox  Ta    Yes      Ta    Yes      Ta    n  .It Sx \&Ox  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Pa  Ta    Yes      Ta    Yes      Ta    n  .It Sx \&Pa  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Pf  Ta    \&No     Ta    Yes      Ta    1  .It Sx \&Pf  Ta    Yes      Ta    Yes      Ta    1
 .It Sx \&Pp  Ta    \&No     Ta    \&No     Ta    0  .It Sx \&Pp  Ta    \&No     Ta    \&No     Ta    0
 .It Sx \&Rv  Ta    \&No     Ta    \&No     Ta    n  .It Sx \&Rv  Ta    \&No     Ta    \&No     Ta    n
 .It Sx \&Sm  Ta    \&No     Ta    \&No     Ta    1  .It Sx \&Sm  Ta    \&No     Ta    \&No     Ta    1
Line 588  then the macro accepts an arbitrary number of argument
Line 789  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
 block.  Multiple authors should each be accorded their own  block.  Multiple authors should each be accorded their own
 .Sx \%%A  .Sx \%%A
 line.  line.  Author names should be ordered with full or abbreviated
 .Pp  forename(s) first, then full surname.
 Author names should be ordered with full or abbreviated forename(s)  
 first, then full surname.  
 .  
 .Ss \&%B  .Ss \&%B
 Book title of an  Book title of an
 .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
 block.  block.
 .Pp  .Pp
 .Em Compatibility remark :  .Em Remarks :
 this macro is not implemented in  this macro is not implemented in
 .Xr groff 1 .  .Xr groff 1 .
 .  
 .Ss \&%D  .Ss \&%D
 Publication date of an  Publication date of an
 .Sx \&Rs  .Sx \&Rs
 block.  This should follow the canonical syntax for  block.  This should follow the reduced or canonical form syntax
   described in
 .Sx Dates .  .Sx Dates .
 .  
 .Ss \&%I  .Ss \&%I
 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
   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.  This macro may alternatively accepts the following
 arguments, although these may not be specified along with a parameter:  arguments, although these may not be specified along with a parameter:
 .Bl -tag -width 12n -offset indent  .Bl -tag -width 12n -offset indent
 .It Fl split  .It Fl split
 Renders a line break is rendered before each author listing.  Renders a line break before each author listing.
 .It Fl nosplit  .It Fl nosplit
 The opposite of  The opposite of
 .Fl split .  .Fl split .
Line 712  will cause the first listing also to be split.  If not
Line 894  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 727  are re-set when entering the AUTHORS section, so if on
Line 906  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.  Does not have any head
 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 .
 .  
 .Ss \&Ap  .Ss \&Ap
 Inserts an apostrophe without any surrounding white-space.  This is  Inserts an apostrophe without any surrounding white-space.  This is
 generally used as a grammatic device when referring to the verb form of  generally used as a grammatic device when referring to the verb form of
Line 747  a function:
Line 922  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 768  statements, which should use
Line 940  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 strings  Command arguments.  If an argument is not provided, the string
 .Dq file ...  .Dq file ...
 are used as a default.  is used as a default.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .D1 \&.Fl o \&Ns \&Ar file1
 \&.Fl o Ns Ar file1  .D1 \&.Ar
 \&.Ar  .D1 \&.Ar arg1 , arg2 .
 \&.Ar arg1 , arg2 .  
 .Ed  
 .  
 .Ss \&At  .Ss \&At
 Formats an AT&T version.  Accepts at most one parameter:  Formats an AT&T version.  Accepts at most one parameter:
 .Bl -tag -width 12n -offset indent  .Bl -tag -width 12n -offset indent
Line 795  A system version of
Line 963  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  .Pp
 .Ed  See also
 .  .Sx \&Bsx ,
   .Sx \&Bx ,
   .Sx \&Dx ,
   .Sx \&Fx ,
   .Sx \&Nx ,
   .Sx \&Ox ,
   and
   .Sx \&Ux .
 .Ss \&Bc  .Ss \&Bc
 Closes a  Closes a
 .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.  A display is collection of macros or text which
 may be collectively offset or justified in a manner different from that  may be collectively offset or justified in a manner different from that
Line 850  which aligns around an imagined centre axis.
Line 1024  which aligns around an imagined centre axis.
 .It  .It
 As a precalculated width for a named macro.  The most popular is the  As a precalculated width for a named macro.  The most popular is the
 imaginary macro  imaginary macro
 .Ar Ds ,  .Ar \&Ds ,
 which resolves to  which resolves to
 .Ar 6n .  .Ar 6n .
 .It  .It
Line 874  before any text or macros within the block.
Line 1048  before any text or macros within the block.
 .Pp  .Pp
 Examples:  Examples:
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Bd \-literal \-offset indent  
 int  
 main(void)  
 {  
         printf("Hello, world!\en");  
 }  
 \&.Ed  
   
 \&.Bd \-unfilled \-offset two-indent \-compact  \&.Bd \-unfilled \-offset two-indent \-compact
 Hello     Hello       world.
       world.  
 \&.Ed  \&.Ed
 .Ed  .Ed
 .  .Pp
   See also
   .Sx \&D1
   and
   .Sx \&Dl .
 .Ss \&Bf  .Ss \&Bf
 .Ss \&Bk  .Ss \&Bk
 .Ss \&Bl  .Ss \&Bl
   .\" Begins a list composed of one or more list entries.  A list entry is
   .\" specified by the
   .\" .Sx \&It
   .\" macro, which consists of a head and optional body.  By default, a list
   .\" is preceded by a blank line.  A list must specify one of the following
   .\" list types:
   .\" .Bl -tag -width 12n
   .\" .It Fl bullet
   .\" A list offset by a bullet.  The head of list entries must be empty.
   .\" List entry bodies are justified after the bullet.
   .\" .It Fl column
   .\" A columnated list.  The number of columns is specified as arguments to
   .\" the
   .\" .Sx \&Bl
   .\" macro (the deprecated form of following the invocation of
   .\" .Fl column
   .\" is also accepted).  Arguments dictate the width of columns specified in
   .\" list entries.  List entry bodies must be left empty.  Columns specified
   .\" in the list entry head are justified to their position in the sequence
   .\" of columns.
   .\" .It Fl dash
   .\" A list offset by a dash (hyphen).  The head of list entries must be
   .\" empty.  List entry bodies are justified past the dash.
   .\" .It Fl diag
   .\" Like
   .\" .Fl inset
   .\" lists, but with additional formatting to the head.
   .\" .It Fl enum
   .\" A list offset by a number indicating list entry position.  The head of
   .\" list entries must be empty.  List entry bodies are justified past the
   .\" enumeration.
   .\" .It Fl hang
   .\" Like
   .\" .Fl tag ,
   .\" but instead of list bodies justifying to the head on the first line,
   .\" they trail the head text.
   .\" .It Fl hyphen
   .\" Synonym for
   .\" .Fl dash .
   .\" .It Fl inset
   .\" Like
   .\" .Fl tag ,
   .\" but list entry bodies aren't justified.
   .\" .It Fl item
   .\" An un-justified list.  This produces blocks of text.
   .\" .It Fl ohang
   .\" List bodies are placed on the line following the head.
   .\" .It Fl tag
   .\" A list offset by list entry heads.  List entry bodies are justified
   .\" after the head.
   .\" .El
   .\" .Pp
   .\" More...
   .\" .
 .Ss \&Bo  .Ss \&Bo
   Begins a block enclosed by square brackets.  Does not have any head
   arguments.
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.Bo 1 ,
   \&.Dv BUFSIZ \&Bc
   .Ed
   .Pp
   See also
   .Sx \&Bq .
 .Ss \&Bq  .Ss \&Bq
   Encloses its arguments in square brackets.
   .Pp
   Examples:
   .D1 \&.Bq 1 , \&Dv BUFSIZ
   .Pp
   .Em Remarks :
   this macro is sometimes abused to emulate optional arguments for
   commands; the correct macros to use for this purpose are
   .Sx \&Op ,
   .Sx \&Oo ,
   and
   .Sx \&Oc .
   .Pp
   See also
   .Sx \&Bo .
 .Ss \&Brc  .Ss \&Brc
   Closes a
   .Sx \&Bro
   block.  Does not have any tail arguments.
 .Ss \&Bro  .Ss \&Bro
   Begins a block enclosed by curly braces.  Does not have any head
   arguments.
   .Pp
   Examples:
   .Bd -literal -offset indent
   \&.Bro 1 , ... ,
   \&.Va n \&Brc
   .Ed
   .Pp
   See also
   .Sx \&Brq .
 .Ss \&Brq  .Ss \&Brq
   Encloses its arguments in curly braces.
   .Pp
   Examples:
   .D1 \&.Brq 1 , ... , \&Va n
   .Pp
   See also
   .Sx \&Bro .
 .Ss \&Bsx  .Ss \&Bsx
   Format the BSD/OS version provided as an argument, or a default value if
   no argument is provided.
   .Pp
   Examples:
   .D1 \&.Bsx 1.0
   .D1 \&.Bsx
   .Pp
   See also
   .Sx \&At ,
   .Sx \&Bx ,
   .Sx \&Dx ,
   .Sx \&Fx ,
   .Sx \&Nx ,
   .Sx \&Ox ,
   and
   .Sx \&Ux .
 .Ss \&Bt  .Ss \&Bt
   Prints
   .Dq is currently in beta test.
 .Ss \&Bx  .Ss \&Bx
   Format the BSD version provided as an argument, or a default value if no
   argument is provided.
   .Pp
   Examples:
   .D1 \&.Bx 4.4
   .D1 \&.Bx
   .Pp
   See also
   .Sx \&At ,
   .Sx \&Bsx ,
   .Sx \&Dx ,
   .Sx \&Fx ,
   .Sx \&Nx ,
   .Sx \&Ox ,
   and
   .Sx \&Ux .
 .Ss \&Cd  .Ss \&Cd
   Configuration declaration.  This denotes strings accepted by
   .Xr config 8 .
   .Pp
   Examples:
   .D1 \&.Cd device le0 at scode?
   .Pp
   .Em Remarks :
   this macro is commonly abused by using quoted literals to retain
   white-space and align consecutive
   .Sx \&Cd
   declarations.  This practise is discouraged.
 .Ss \&Cm  .Ss \&Cm
   Command modifiers.  Useful when specifying configuration options or
   keys.
   .Pp
   Examples:
   .D1 \&.Cm ControlPath
   .D1 \&.Cm ControlMaster
   .Pp
   See also
   .Sx \&Fl .
 .Ss \&D1  .Ss \&D1
   One-line indented display.  This is formatted by the default rules and
   is useful for simple indented statements.  It is followed by a newline.
   .Pp
   Examples:
   .D1 \&.D1 \&Fl abcdefgh
   .Pp
   See also
   .Sx \&Bd
   and
   .Sx \&Dl .
 .Ss \&Db  .Ss \&Db
 .Ss \&Dc  .Ss \&Dc
   Closes a
   .Sx \&Do
   block.  Does not have any tail arguments.
 .Ss \&Dd  .Ss \&Dd
   Document date.  This is the mandatory first macro of any
   .Nm
   manual.  Its calling syntax is as follows:
   .Pp
   .D1 \. Ns Sx \&Dd Cm date
   .Pp
   The
   .Cm date
   field may be either
   .Ar $\&Mdocdate$ ,
   which signifies the current manual revision date dictated by
   .Xr cvs 1 ,
   or instead a valid canonical date as specified by
   .Sx Dates .
   If a date does not conform, the current date is used instead.
   .Pp
   Examples:
   .D1 \&.Dd $\&Mdocdate$
   .D1 \&.Dd $\&Mdocdate: July 21 2007$
   .D1 \&.Dd July 21, 2007
   .Pp
   See also
   .Sx \&Dt
   and
   .Sx \&Os .
 .Ss \&Dl  .Ss \&Dl
   One-line intended display.  This is formatted as literal text and is
   useful for commands and invocations.  It is followed by a newline.
   .Pp
   Examples:
   .D1 \&.Dl % mandoc mdoc.7 | less
   .Pp
   See also
   .Sx \&Bd
   and
   .Sx \&D1 .
 .Ss \&Do  .Ss \&Do
   Begins a block enclosed by double quotes.  Does not have any head
   arguments.
   .Pp
   Examples:
   .D1 \&.D1 \&Do April is the cruellest month \&Dc \e(em T.S. Eliot
   .Pp
   See also
   .Sx \&Dq .
 .Ss \&Dq  .Ss \&Dq
   Encloses its arguments in double quotes.
   .Pp
   Examples:
   .Bd -literal -offset indent -compact
   \&.Dq April is the cruellest month
   \e(em T.S. Eliot
   .Ed
   .Pp
   See also
   .Sx \&Do .
 .Ss \&Dt  .Ss \&Dt
   Document title.  This is the mandatory second macro of any
   .Nm
   file.  Its calling syntax is as follows:
   .Pp
   .D1 \. Ns Sx \&Dt Cm title section Op Cm volume | arch
   .Pp
   Its arguments are as follows:
   .Bl -tag -width Ds -offset Ds
   .It Cm title
   The document's title (name).  This should be capitalised and is
   required.
   .It Cm section
   The manual section.  This may be one of
   .Ar 1
   .Pq utilities ,
   .Ar 2
   .Pq system calls ,
   .Ar 3
   .Pq libraries ,
   .Ar 3p
   .Pq Perl libraries ,
   .Ar 4
   .Pq devices ,
   .Ar 5
   .Pq file formats ,
   .Ar 6
   .Pq games ,
   .Ar 7
   .Pq miscellaneous ,
   .Ar 8
   .Pq system utilities ,
   .Ar 9
   .Pq kernel functions ,
   .Ar X11
   .Pq X Window System ,
   .Ar X11R6
   .Pq X Window System ,
   .Ar unass
   .Pq unassociated ,
   .Ar local
   .Pq local system ,
   .Ar draft
   .Pq draft manual ,
   or
   .Ar paper
   .Pq paper .
   It is also required and should correspond to the manual's filename
   suffix.
   .It Cm volume
   This overrides the volume inferred from
   .Ar section .
   This field is optional, and if specified, must be one of
   .Ar USD
   .Pq users' supplementary documents ,
   .Ar PS1
   .Pq programmers' supplementary documents ,
   .Ar AMD
   .Pq administrators' supplementary documents ,
   .Ar SMM
   .Pq system managers' manuals ,
   .Ar URM
   .Pq users' reference manuals ,
   .Ar PRM
   .Pq programmers' reference manuals ,
   .Ar KM
   .Pq kernel manuals ,
   .Ar IND
   .Pq master index ,
   .Ar MMI
   .Pq master index ,
   .Ar LOCAL
   .Pq local manuals ,
   .Ar LOC
   .Pq local manuals ,
   or
   .Ar CON
   .Pq contributed manuals .
   .It Cm arch
   This specifies a specific relevant architecture.  If
   .Cm volume
   is not provided, it may be used in its place, else it may be used
   subsequent that.  It, too, is optional.  It must be one of
   .Ar alpha ,
   .Ar amd64 ,
   .Ar amiga ,
   .Ar arc ,
   .Ar arm ,
   .Ar armish ,
   .Ar aviion ,
   .Ar hp300 ,
   .Ar hppa ,
   .Ar hppa64 ,
   .Ar i386 ,
   .Ar landisk ,
   .Ar loongson ,
   .Ar luna88k ,
   .Ar mac68k ,
   .Ar macppc ,
   .Ar mvme68k ,
   .Ar mvme88k ,
   .Ar mvmeppc ,
   .Ar pmax ,
   .Ar sgi ,
   .Ar socppc ,
   .Ar sparc ,
   .Ar sparc64 ,
   .Ar sun3 ,
   .Ar vax ,
   or
   .Ar zaurus .
   .El
   .Pp
   Examples:
   .D1 \&.Dt FOO 1
   .D1 \&.Dt FOO 4 KM
   .D1 \&.Dt FOO 9 i386
   .D1 \&.Dt FOO 9 KM i386
   .Pp
   See also
   .Sx \&Dd
   and
   .Sx \&Os .
 .Ss \&Dv  .Ss \&Dv
   Defined variables such as preprocessor constants.
   .Pp
   Examples:
   .D1 \&.Dv BUFSIZ
   .D1 \&.Dv STDOUT_FILENO
   .Pp
   See also
   .Sx \&Er .
 .Ss \&Dx  .Ss \&Dx
   Format the DragonFly BSD version provided as an argument, or a default
   value if no argument is provided.
   .Pp
   Examples:
   .D1 \&.Dx 2.4.1
   .D1 \&.Dx
   .Pp
   See also
   .Sx \&At ,
   .Sx \&Bsx ,
   .Sx \&Bx ,
   .Sx \&Fx ,
   .Sx \&Nx ,
   .Sx \&Ox ,
   and
   .Sx \&Ux .
 .Ss \&Ec  .Ss \&Ec
 .Ss \&Ed  .Ss \&Ed
 .Ss \&Ef  .Ss \&Ef
 .Ss \&Ek  .Ss \&Ek
 .Ss \&El  .Ss \&El
 .Ss \&Em  .Ss \&Em
   Denotes text that should be emphasised.  Note that this is a
   presentation term and should not be used for stylistically decorating
   technical terms.
   .Pp
   Examples:
   .D1 \&.Em Warnings!
   .D1 \&.Em Remarks :
 .Ss \&En  .Ss \&En
 .Ss \&Eo  .Ss \&Eo
 .Ss \&Er  .Ss \&Er
   Display error constants.
   .Pp
   Examples:
   .D1 \&.Er EPERM
   .D1 \&.Er ENOENT
   .Pp
   See also
   .Sx \&Dv .
 .Ss \&Es  .Ss \&Es
 .Ss \&Ev  .Ss \&Ev
   Environmental variables such as those specified in
   .Xr environ 7 .
   .Pp
   Examples:
   .D1 \&.Ev DISPLAY
   .D1 \&.Ev PATH
 .Ss \&Ex  .Ss \&Ex
   Inserts text regarding a utility's exit values.  This macro must have
   first the
   .Fl std
   argument specified, then an optional
   .Ar utility .
   If
   .Ar utility
   is not provided, the document's name as stipulated in
   .Sx \&Nm
   is provided.
 .Ss \&Fa  .Ss \&Fa
 .Ss \&Fc  .Ss \&Fc
 .Ss \&Fd  .Ss \&Fd
 .Ss \&Fl  .Ss \&Fl
   Command-line flag.  Used when listing arguments to command-line
   utilities.  Prints a fixed-width hyphen
   .Sq \-
   directly followed by each argument.  If no arguments are provided, a hyphen is
   printed followed by a space.  If the argument is a macro, a hyphen is
   prefixed to the subsequent macro output.
   .Pp
   Examples:
   .D1 \&.Fl a b c
   .D1 \&.Fl \&Pf a b
   .D1 \&.Fl
   .D1 \&.Op \&Fl o \&Ns \&Ar file
   .Pp
   See also
   .Sx \&Cm .
 .Ss \&Fn  .Ss \&Fn
 .Ss \&Fo  .Ss \&Fo
 .Ss \&Fr  .Ss \&Fr
 .Ss \&Ft  .Ss \&Ft
 .Ss \&Fx  .Ss \&Fx
   Format the FreeBSD version provided as an argument, or a default value
   if no argument is provided.
   .Pp
   Examples:
   .D1 \&.Fx 7.1
   .D1 \&.Fx
   .Pp
   See also
   .Sx \&At ,
   .Sx \&Bsx ,
   .Sx \&Bx ,
   .Sx \&Dx ,
   .Sx \&Nx ,
   .Sx \&Ox ,
   and
   .Sx \&Ux .
 .Ss \&Hf  .Ss \&Hf
 .Ss \&Ic  .Ss \&Ic
 .Ss \&In  .Ss \&In
Line 939  Hello
Line 1537  Hello
 .Ss \&Lb  .Ss \&Lb
 .Ss \&Li  .Ss \&Li
 .Ss \&Lk  .Ss \&Lk
   Format a hyperlink.  The calling syntax is as follows:
   .Pp
   .D1 \. Ns Sx \&Lk Cm uri Op Cm name
   .Pp
   Examples:
   .D1 \&.Lk http://bsd.lv "The BSD.lv Project"
   .D1 \&.Lk http://bsd.lv
   .Pp
   See also
   .Sx \&Mt .
 .Ss \&Lp  .Ss \&Lp
 .Ss \&Ms  .Ss \&Ms
 .Ss \&Mt  .Ss \&Mt
Line 947  Hello
Line 1555  Hello
 .Ss \&No  .Ss \&No
 .Ss \&Ns  .Ss \&Ns
 .Ss \&Nx  .Ss \&Nx
   Format the NetBSD version provided as an argument, or a default value if
   no argument is provided.
   .Pp
   Examples:
   .D1 \&.Nx 5.01
   .D1 \&.Nx
   .Pp
   See also
   .Sx \&At ,
   .Sx \&Bsx ,
   .Sx \&Bx ,
   .Sx \&Dx ,
   .Sx \&Fx ,
   .Sx \&Ox ,
   and
   .Sx \&Ux .
 .Ss \&Oc  .Ss \&Oc
 .Ss \&Oo  .Ss \&Oo
 .Ss \&Op  .Ss \&Op
 .Ss \&Os  .Ss \&Os
   Document operating system version.  This is the mandatory third macro of
   any
   .Nm
   file.  Its calling syntax is as follows:
   .Pp
   .D1 \. Ns Sx \&Os Op Cm system
   .Pp
   The optional
   .Cm system
   parameter specifies the relevant operating system or environment.  Left
   unspecified, it defaults to the local operating system version.  This is
   the suggested form.
   .Pp
   Examples:
   .D1 \&.Os
   .D1 \&.Os KTH/CSC/TCS
   .D1 \&.Os BSD 4.3
   .Pp
   See also
   .Sx \&Dd
   and
   .Sx \&Dt .
 .Ss \&Ot  .Ss \&Ot
   Unknown usage.
   .Pp
   .Em Remarks :
   this macro has been deprecated.
 .Ss \&Ox  .Ss \&Ox
   Format the OpenBSD version provided as an argument, or a default value
   if no argument is provided.
   .Pp
   Examples:
   .D1 \&.Ox 4.5
   .D1 \&.Ox
   .Pp
   See also
   .Sx \&At ,
   .Sx \&Bsx ,
   .Sx \&Bx ,
   .Sx \&Dx ,
   .Sx \&Fx ,
   .Sx \&Nx ,
   and
   .Sx \&Ux .
 .Ss \&Pa  .Ss \&Pa
 .Ss \&Pc  .Ss \&Pc
 .Ss \&Pf  .Ss \&Pf
Line 963  Hello
Line 1629  Hello
 .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 and may only  block.  Does not have any head arguments.  The block macro may only
 contain  contain
 .Sx \&%A ,  .Sx \&%A ,
 .Sx \&%B ,  .Sx \&%B ,
Line 991  and
Line 1655  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 1007  If an
Line 1671  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 1021  line.
Line 1684  line.
 .Ss \&Tn  .Ss \&Tn
 .Ss \&Ud  .Ss \&Ud
 .Ss \&Ux  .Ss \&Ux
   Format the UNIX name.  Accepts no argument.
   .Pp
   Examples:
   .D1 \&.Ux
   .Pp
   See also
   .Sx \&At ,
   .Sx \&Bsx ,
   .Sx \&Bx ,
   .Sx \&Dx ,
   .Sx \&Fx ,
   .Sx \&Nx ,
   and
   .Sx \&Ox .
 .Ss \&Va  .Ss \&Va
 .Ss \&Vt  .Ss \&Vt
   A variable type.  This is also used for indicating global variables in the
   SYNOPSIS section, in which case a variable name is also specified.  Note that
   it accepts
   .Sx Block partial-implicit
   syntax when invoked as the first macro in the SYNOPSIS section, else it
   accepts ordinary
   .Sx In-line
   syntax.
   .Pp
   Note that this should not be confused with
   .Sx \&Ft ,
   which is used for function return types.
   .Pp
   Examples:
   .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
 Negative scaling units are now truncated to zero instead of creating  The comment syntax
 interesting conditions, such as with  .Sq \e."
 .Sq \&sp -1i .  is no longer accepted.
 Furthermore, the  .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
   arguments.  mandoc and newer groff implementations do.
   .It
   groff behaves irregularly when specifying
   .Sq \ef
   .Sx Text Decoration
   within line-macro scopes.  mandoc follows a consistent system.
   .It
   In mandoc, negative scaling units are truncated to zero; groff would
   move to prior lines.  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 Fl center  .Sx \&Bd
   .Fl center
 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 1072  are aliases, as are
Line 1815  are aliases, as are
 and  and
 .Fl unfilled .  .Fl unfilled .
 .It  .It
 Blocks of whitespace are stripped from both macro and free-form text  
 lines (except when in literal mode), while groff would retain whitespace  
 in free-form text lines.  
 .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 Fl nested  .Sx \&It Fl nested
 is assumed for all lists (it wasn't in historic groff): any list may be  is assumed for all lists (it wasn't in historic groff): any list may be
Line 1095  lists will restart the sequence only for the sub-list.
Line 1833  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 ,
   and
   .Sx \&Ex
   macros were stipulated only to occur in certain manual sections.  mandoc
   does not have these restrictions.
 .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.64  
changed lines
  Added in v.1.98
CVSweb