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

Diff for /mandoc/mdoc.7 between version 1.142 and 1.191

version 1.142, 2010/07/26 13:45:49 version 1.191, 2011/07/18 10:23:02
Line 1 
Line 1 
 .\"     $Id$  .\"     $Id$
 .\"  .\"
 .\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>  .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>  .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
 .\"  .\"
 .\" Permission to use, copy, modify, and distribute this software for any  .\" Permission to use, copy, modify, and distribute this software for any
Line 28  language is used to format
Line 28  language is used to format
 .Bx  .Bx
 .Ux  .Ux
 manuals.  manuals.
 In this reference document, we describe its syntax, structure, and  This reference document describes its syntax, structure, and
 usage.  usage.
 Our reference implementation is mandoc; the  The reference implementation is
   .Xr mandoc 1 ;
   the
 .Sx COMPATIBILITY  .Sx COMPATIBILITY
 section describes compatibility with other troff \-mdoc implementations.  section describes compatibility with other troff \-mdoc implementations.
 .Pp  .Pp
Line 38  An
Line 40  An
 .Nm  .Nm
 document follows simple rules: lines beginning with the control  document follows simple rules: lines beginning with the control
 character  character
 .Sq \.  .Sq \&.
 are parsed for macros.  are parsed for macros.
 Other lines are interpreted within the scope of  Text lines, those not beginning with the control character, are
 prior macros:  interpreted within the scope of prior macros:
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Sh Macro lines change control state.  \&.Sh Macro lines change control state.
 Other lines are interpreted within the current state.  Text 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
 character, and, in certain circumstances, the tab character.  character, and, in certain circumstances, the tab character.
 All manuals must have  .Pp
 .Ux  If the first character of a text line is a space, that line is printed
 line terminators.  with a leading newline.
 .Ss Comments  .Ss Comments
 Text following a  Text following a
 .Sq \e\*q ,  .Sq \e\*q ,
 whether in a macro or free-form text line, is ignored to the end of  whether in a macro or text line, is ignored to the end of
 line.  line.
 A macro line with only a control character and comment escape,  A macro line with only a control character and comment escape,
 .Sq \&.\e\*q ,  .Sq \&.\e\*q ,
 is also ignored.  is also ignored.
 Macro lines with only a control character and optionally whitespace are  Macro lines with only a control character and optional whitespace are
 stripped from input.  stripped from input.
 .Ss Reserved Characters  .Ss Reserved Terms
 Within a macro line, the following characters are reserved:  Within a macro line, the following terms are reserved:
 .Pp  .Pp
 .Bl -tag -width Ds -offset indent -compact  .Bl -tag -width Ds -offset indent -compact
 .It \&.  .It \&.
 .Pq period  .Pq period
   .It \e.
   .Pq escaped period
 .It \&,  .It \&,
 .Pq comma  .Pq comma
 .It \&:  .It \&:
Line 89  Within a macro line, the following characters are rese
Line 93  Within a macro line, the following characters are rese
 .Pq exclamation  .Pq exclamation
 .It \&|  .It \&|
 .Pq vertical bar  .Pq vertical bar
   .It \e*(Ba
   .Pq reserved-word vertical bar
 .El  .El
 .Pp  .Pp
 Use of reserved characters is described in  For general use in macro lines, these can be escaped with a non-breaking
 .Sx MACRO SYNTAX .  space
 For general use in macro lines, these characters can either be escaped  .Pq Sq \e& .
 with a non-breaking space  In text lines, these may be used as normal punctuation.
 .Pq Sq \e&  
 or, if applicable, an appropriate escape sequence can be 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 text lines.
 Sequences begin with the escape character  Sequences begin with the escape character
 .Sq \e  .Sq \e
 followed by either an open-parenthesis  followed by either an open-parenthesis
Line 107  for two-character sequences; an open-bracket
Line 111  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.  or a single one character sequence.
 See  See
 .Xr mandoc_char 7  .Xr mandoc_char 7
 for a complete list.  for a complete list.
Line 120  and
Line 124  and
 .Ss Text Decoration  .Ss Text Decoration
 Terms may be text-decorated using the  Terms may be text-decorated using the
 .Sq \ef  .Sq \ef
 escape followed by an indicator: B (bold), I, (italic), R (Roman), or P  escape followed by an indicator: B (bold), I (italic), R (Roman), or P
 (revert to previous mode):  (revert to previous mode):
 .Pp  .Pp
 .D1 \efBbold\efR \efIitalic\efP  .Dl \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.  respectively) may be used instead.
 A text decoration is valid within  If a macro opens a font scope after calling
 the current font scope only: if a macro opens a font scope alongside  .Sq \ef ,
 its own scope, such as  such as with
 .Sx \&Bf  .Sx \&Bf ,
 .Cm \&Sy ,  the
 in-scope invocations of  
 .Sq \ef  .Sq \ef
 are only valid within the font scope of the macro.  mode will be restored upon exiting the
 If  .Sx \&Bf
 .Sq \ef  scope.
 is specified outside of any font scope, such as in unenclosed, free-form  
 text, it will affect the remainder of the document.  
 .Pp  .Pp
 Note this form is  Note this form is
 .Em not  .Em not
Line 147  recommended for
Line 148  recommended for
 which encourages semantic annotation.  which encourages semantic annotation.
 .Ss Predefined Strings  .Ss Predefined Strings
 Historically,  Historically,
 .Xr groff 1  troff
 also defined a set of package-specific  also defined a set of package-specific
 .Dq predefined strings ,  .Dq predefined strings ,
 which, like  which, like
Line 172  and
Line 173  and
 .Pq vertical bar .  .Pq vertical bar .
 .Ss Whitespace  .Ss Whitespace
 Whitespace consists of the space character.  Whitespace consists of the space character.
 In free-form lines, whitespace is preserved within a line; un-escaped  In text lines, whitespace is preserved within a line; unescaped
 trailing spaces are stripped from input (unless in a literal context).  trailing spaces are stripped from input (unless in a literal context).
 Blank free-form lines, which may include whitespace, are only permitted  Blank text lines, which may include whitespace, are only permitted
 within literal contexts.  within literal contexts.
 .Pp  .Pp
 In macro lines, whitespace delimits arguments and is discarded.  In macro lines, whitespace delimits arguments and is discarded.
Line 183  If arguments are quoted, whitespace within the quotes 
Line 184  If arguments are quoted, whitespace within the quotes 
 Macro arguments may be quoted with double-quotes to group  Macro arguments may be quoted with double-quotes to group
 space-delimited terms or to retain blocks of whitespace.  space-delimited terms or to retain blocks of whitespace.
 A quoted argument begins with a double-quote preceded by whitespace.  A quoted argument begins with a double-quote preceded by whitespace.
 The next double-quote not pair-wise adjacent to another double-quote  The next double-quote not pairwise adjacent to another double-quote
 terminates the literal, regardless of surrounding whitespace.  terminates the literal, regardless of surrounding whitespace.
 .Pp  .Pp
 Note that any quoted text, even if it would cause a macro invocation  Note that any quoted text, even if it would cause a macro invocation
Line 194  Thus, the following produces
Line 195  Thus, the following produces
 \&.Op "Fl a"  \&.Op "Fl a"
 .Ed  .Ed
 .Pp  .Pp
 In free-form mode, quotes are regarded as opaque text.  In text lines, quotes are regarded as opaque text.
 .Ss Dates  
 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:
Line 276  is necessarily non-portable across output media.
Line 249  is necessarily non-portable across output media.
 See  See
 .Sx COMPATIBILITY .  .Sx COMPATIBILITY .
 .Ss Sentence Spacing  .Ss Sentence Spacing
 When composing a manual, make sure that your sentences end at the end of  When composing a manual, make sure that sentences end at the end of
 a line.  a line.
 By doing so, front-ends will be able to apply the proper amount of  By doing so, front-ends will be able to apply the proper amount of
 spacing after the end of sentence (unescaped) period, exclamation mark,  spacing after the end of sentence (unescaped) period, exclamation mark,
 or question mark followed by zero or more non-sentence closing  or question mark followed by zero or more non-sentence closing
 delimiters (  delimiters
 .Ns Sq \&) ,  .Po
   .Sq \&) ,
 .Sq \&] ,  .Sq \&] ,
 .Sq \&' ,  .Sq \&' ,
 .Sq \&" ) .  .Sq \&"
   .Pc .
 .Pp  .Pp
 The proper spacing is also intelligently preserved if a sentence ends at  The proper spacing is also intelligently preserved if a sentence ends at
 the boundary of a macro line, e.g.,  the boundary of a macro line.
   For example:
 .Pp  .Pp
 .D1 \&Xr mandoc 1 \.  .Dl \&.Xr mandoc 1 \&.
 .D1 \&Fl T \&Ns \&Cm ascii \.  .Dl \&.Fl T \&Ns \&Cm ascii \&.
 .Sh MANUAL STRUCTURE  .Sh MANUAL STRUCTURE
 A well-formed  A well-formed
 .Nm  .Nm
Line 320  sections, although this varies between manual sections
Line 296  sections, although this varies between manual sections
 .Pp  .Pp
 The following is a well-formed skeleton  The following is a well-formed skeleton
 .Nm  .Nm
 file:  file for a utility
   .Qq progname :
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Dd $\&Mdocdate$  \&.Dd $\&Mdocdate$
 \&.Dt mdoc 7  \&.Dt PROGNAME section
 \&.Os  \&.Os
 \&.Sh NAME  \&.Sh NAME
 \&.Nm foo  \&.Nm progname
 \&.Nd a description goes here  \&.Nd a description goes here
 \&.\e\*q The next is for sections 2, 3, & 9 only.  
 \&.\e\*q .Sh LIBRARY  \&.\e\*q .Sh LIBRARY
   \&.\e\*q For sections 2, 3, & 9 only.
   \&.\e\*q Not used in OpenBSD.
 \&.Sh SYNOPSIS  \&.Sh SYNOPSIS
 \&.Nm foo  \&.Nm progname
 \&.Op Fl options  \&.Op Fl options
 \&.Ar  \&.Ar
 \&.Sh DESCRIPTION  \&.Sh DESCRIPTION
Line 339  The
Line 317  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 2, 3, & 9 only.  \&.\e\*q Not used in OpenBSD.
 \&.\e\*q .Sh RETURN VALUES  \&.\e\*q .Sh RETURN VALUES
 \&.\e\*q The next is for sections 1, 6, 7, & 8 only.  \&.\e\*q For sections 2, 3, & 9 only.
 \&.\e\*q .Sh ENVIRONMENT  \&.\e\*q .Sh ENVIRONMENT
   \&.\e\*q For sections 1, 6, 7, & 8 only.
 \&.\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 EXIT STATUS
   \&.\e\*q For sections 1, 6, & 8 only.
 \&.\e\*q .Sh EXAMPLES  \&.\e\*q .Sh EXAMPLES
 \&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.  
 \&.\e\*q .Sh DIAGNOSTICS  \&.\e\*q .Sh DIAGNOSTICS
 \&.\e\*q The next is for sections 2, 3, & 9 only.  \&.\e\*q For sections 1, 4, 6, 7, & 8 only.
 \&.\e\*q .Sh ERRORS  \&.\e\*q .Sh ERRORS
   \&.\e\*q For sections 2, 3, & 9 only.
 \&.\e\*q .Sh SEE ALSO  \&.\e\*q .Sh SEE ALSO
 \&.\e\*q .Xr foobar 1  \&.\e\*q .Xr foobar 1
 \&.\e\*q .Sh STANDARDS  \&.\e\*q .Sh STANDARDS
Line 359  utility processes files ...
Line 338  utility processes files ...
 \&.\e\*q .Sh CAVEATS  \&.\e\*q .Sh CAVEATS
 \&.\e\*q .Sh BUGS  \&.\e\*q .Sh BUGS
 \&.\e\*q .Sh SECURITY CONSIDERATIONS  \&.\e\*q .Sh SECURITY CONSIDERATIONS
   \&.\e\*q Not used in OpenBSD.
 .Ed  .Ed
 .Pp  .Pp
 The sections in a  The sections in an
 .Nm  .Nm
 document are conventionally ordered as they appear above.  document are conventionally ordered as they appear above.
 Sections 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 one-line description of the documented material.  The name(s) and a one line description of the documented material.
 The 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 ,
 \&.Nm name2  \&.Nm name2
 \&.Nd a one-line description  \&.Nd a one line description
 .Ed  .Ed
 .Pp  .Pp
   Multiple
   .Sq \&Nm
   names should be separated by commas.
   .Pp
 The  The
 .Sx \&Nm  .Sx \&Nm
 macro(s) must precede the  macro(s) must precede the
Line 403  configuration.
Line 387  configuration.
 For the first, utilities (sections 1, 6, and 8), this is  For the first, utilities (sections 1, 6, and 8), this is
 generally structured as follows:  generally structured as follows:
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Nm foo  \&.Nm bar
 \&.Op Fl v  \&.Op Fl v
 \&.Op Fl o Ar file  \&.Op Fl o Ar file
 \&.Op Ar  \&.Op Ar
 \&.Nm bar  \&.Nm foo
 \&.Op Fl v  \&.Op Fl v
 \&.Op Fl o Ar file  \&.Op Fl o Ar file
 \&.Op Ar  \&.Op Ar
 .Ed  .Ed
 .Pp  .Pp
   Commands should be ordered alphabetically.
   .Pp
 For the second, function calls (sections 2, 3, 9):  For the second, function calls (sections 2, 3, 9):
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Vt extern const char *global;  
 \&.In header.h  \&.In header.h
   \&.Vt extern const char *global;
 \&.Ft "char *"  \&.Ft "char *"
 \&.Fn foo "const char *src"  \&.Fn foo "const char *src"
 \&.Ft "char *"  \&.Ft "char *"
 \&.Fn bar "const char *src"  \&.Fn bar "const char *src"
 .Ed  .Ed
 .Pp  .Pp
   Ordering of
   .Sx \&In ,
   .Sx \&Vt ,
   .Sx \&Fn ,
   and
   .Sx \&Fo
   macros should follow C header-file conventions.
   .Pp
 And for the third, configurations (section 4):  And for the third, configurations (section 4):
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Cd \*qit* at isa? port 0x2e\*q  \&.Cd \*qit* at isa? port 0x2e\*q
Line 445  section, particularly
Line 439  section, particularly
 and  and
 .Sx \&Ft .  .Sx \&Ft .
 All of these macros are output on their own line.  All of these macros are output on their own line.
 If two such dissimilar macros are pair-wise invoked (except for  If two such dissimilar macros are pairwise invoked (except for
 .Sx \&Ft  .Sx \&Ft
 before  before
 .Sx \&Fo  .Sx \&Fo
Line 471  or
Line 465  or
 .Sx \&Ss  .Sx \&Ss
 macro or the end of an enclosing block, whichever comes first.  macro or the end of an enclosing block, whichever comes first.
 .It Em DESCRIPTION  .It Em DESCRIPTION
 This expands upon the brief, one-line description in  This begins with an expansion of the brief, one line description in
 .Em NAME .  .Em NAME :
 It usually contains a break-down of the options (if documenting a  .Bd -literal -offset indent
   The
   \&.Nm
   utility does this, that, and the other.
   .Ed
   .Pp
   It usually follows with a breakdown of the options (if documenting a
 command), such as:  command), such as:
 .Bd -literal -offset indent  .Bd -literal -offset indent
 The arguments are as follows:  The arguments are as follows:
Line 489  Implementation-specific notes should be kept here.
Line 489  Implementation-specific notes should be kept here.
 This is useful when implementing standard functions that may have side  This is useful when implementing standard functions that may have side
 effects or notable algorithmic implications.  effects or notable algorithmic implications.
 .It Em RETURN VALUES  .It Em RETURN VALUES
 This section is the dual of  This section documents the
 .Em EXIT STATUS ,  return values of functions in sections 2, 3, and 9.
 which is used for commands.  
 It documents the return values of functions in sections 2, 3, and 9.  
 .Pp  .Pp
 See  See
 .Sx \&Rv .  .Sx \&Rv .
Line 513  the file is used (created, modified, etc.).
Line 511  the file is used (created, modified, etc.).
 See  See
 .Sx \&Pa .  .Sx \&Pa .
 .It Em EXIT STATUS  .It Em EXIT STATUS
 Command exit status for section 1, 6, and 8 manuals.  This section documents the
 This section is the dual of  command exit status for section 1, 6, and 8 utilities.
 .Em RETURN VALUES ,  
 which is used for functions.  
 Historically, this information was described in  Historically, this information was described in
 .Em DIAGNOSTICS ,  .Em DIAGNOSTICS ,
 a practise that is now discouraged.  a practise that is now discouraged.
Line 526  See
Line 522  See
 .It Em EXAMPLES  .It Em EXAMPLES
 Example usages.  Example usages.
 This often contains snippets of well-formed, well-tested invocations.  This often contains snippets of well-formed, well-tested invocations.
 Make doubly sure that your examples work properly!  Make sure that examples work properly!
 .It Em DIAGNOSTICS  .It Em DIAGNOSTICS
 Documents error conditions.  Documents error conditions.
 This is most useful in section 4 manuals.  This is most useful in section 4 manuals.
Line 560  section should be used instead.
Line 556  section should be used instead.
 See  See
 .Sx \&St .  .Sx \&St .
 .It Em HISTORY  .It Em HISTORY
 The history of any manual without a  A brief history of the subject, including where support first appeared.
 .Em STANDARDS  
 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 the person or persons who wrote the code and/or documentation.
 Authors should generally be noted by both name and email address.  Authors should generally be noted by both name and email address.
 .Pp  .Pp
 See  See
Line 573  See
Line 567  See
 Common misuses and misunderstandings should be explained  Common misuses and misunderstandings should be explained
 in this section.  in this section.
 .It Em BUGS  .It Em BUGS
 Known bugs, limitations and work-arounds should be described  Known bugs, limitations, and work-arounds should be described
 in this section.  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.
Line 604  closes it out.
Line 598  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 also be called by passing its name
 line-macro.  as an argument to another macro.
 If a macro is not callable, then its invocation after the initial line  If a macro is not callable but its name appears as an argument
 macro is interpreted as opaque text, such that  to another macro, it is interpreted as opaque text.
   For example,
 .Sq \&.Fl \&Sh  .Sq \&.Fl \&Sh
 produces  produces
 .Sq Fl \&Sh .  .Sq Fl \&Sh .
 .Pp  .Pp
 The  The
 .Em Parsed  .Em Parsed
 column indicates whether the macro may be followed by further  column indicates whether the macro may call other macros by receiving
 (ostensibly callable) macros.  their names as arguments.
 If a macro is not parsed, subsequent macro invocations on the line  If a macro is not parsed but the name of another macro appears
 will be interpreted as opaque text.  as an argument, it is interpreted as opaque text.
 .Pp  .Pp
 The  The
 .Em Scope  .Em Scope
Line 626  column, if applicable, describes closure rules.
Line 621  column, if applicable, describes closure rules.
 Multi-line scope closed by an explicit closing macro.  Multi-line scope closed by an explicit closing macro.
 All macros contains bodies; only  All macros contains bodies; only
 .Sx \&Bf  .Sx \&Bf
 contains a head.  and
   .Pq optionally
   .Sx \&Bl
   contain a head.
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB  \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
 \(lBbody...\(rB  \(lBbody...\(rB
Line 731  and/or tail
Line 729  and/or tail
 .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 Terms
 or end of line.  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
Line 762  in a
Line 760  in a
 .Em SYNOPSIS  .Em SYNOPSIS
 section line, else it is  section line, else it is
 .Sx In-line .  .Sx In-line .
   .Ss Special block macro
   The
   .Sx \&Ta
   macro can only be used below
   .Sx \&It
   in
   .Sx \&Bl Fl column
   lists.
   It delimits blocks representing table cells;
   these blocks have bodies, but no heads.
   .Pp
   .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -compact -offset indent
   .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
   .It Sx \&Ta  Ta    Yes      Ta    Yes    Ta closed by Sx \&Ta , Sx \&It
   .El
 .Ss In-line  .Ss In-line
 Closed by  Closed by
 .Sx Reserved Characters ,  .Sx Reserved Terms ,
 end of line, fixed argument lengths, and/or subsequent macros.  end of line, fixed argument lengths, and/or subsequent macros.
 In-line macros have only text children.  In-line macros have only text children.
 If a number (or inequality) of 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
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb  \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB
   
 \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...  \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
   
Line 794  then the macro accepts an arbitrary number of argument
Line 807  then the macro accepts an arbitrary number of argument
 .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 \&%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    >0
 .It Sx \&An  Ta    Yes      Ta    Yes      Ta    n  .It Sx \&An  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Ap  Ta    Yes      Ta    Yes      Ta    0  .It Sx \&Ap  Ta    Yes      Ta    Yes      Ta    0
 .It Sx \&Ar  Ta    Yes      Ta    Yes      Ta    n  .It Sx \&Ar  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&At  Ta    Yes      Ta    Yes      Ta    1  .It Sx \&At  Ta    Yes      Ta    Yes      Ta    1
Line 803  then the macro accepts an arbitrary number of argument
Line 816  then the macro accepts an arbitrary number of argument
 .It Sx \&Bt  Ta    \&No     Ta    \&No     Ta    0  .It Sx \&Bt  Ta    \&No     Ta    \&No     Ta    0
 .It Sx \&Bx  Ta    Yes      Ta    Yes      Ta    n  .It Sx \&Bx  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Cd  Ta    Yes      Ta    Yes      Ta    >0  .It Sx \&Cd  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Cm  Ta    Yes      Ta    Yes      Ta    n  .It Sx \&Cm  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Db  Ta    \&No     Ta    \&No     Ta    1  .It Sx \&Db  Ta    \&No     Ta    \&No     Ta    1
 .It Sx \&Dd  Ta    \&No     Ta    \&No     Ta    n  .It Sx \&Dd  Ta    \&No     Ta    \&No     Ta    n
 .It Sx \&Dt  Ta    \&No     Ta    \&No     Ta    n  .It Sx \&Dt  Ta    \&No     Ta    \&No     Ta    n
 .It Sx \&Dv  Ta    Yes      Ta    Yes      Ta    n  .It Sx \&Dv  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Dx  Ta    Yes      Ta    Yes      Ta    n  .It Sx \&Dx  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Em  Ta    Yes      Ta    Yes      Ta    >0  .It Sx \&Em  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&En  Ta    \&No     Ta    \&No     Ta    0  .It Sx \&En  Ta    \&No     Ta    \&No     Ta    0
 .It Sx \&Er  Ta    Yes      Ta    Yes      Ta    >0  .It Sx \&Er  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Es  Ta    \&No     Ta    \&No     Ta    0  .It Sx \&Es  Ta    \&No     Ta    \&No     Ta    0
 .It Sx \&Ev  Ta    Yes      Ta    Yes      Ta    n  .It Sx \&Ev  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Ex  Ta    \&No     Ta    \&No     Ta    n  .It Sx \&Ex  Ta    \&No     Ta    \&No     Ta    n
 .It Sx \&Fa  Ta    Yes      Ta    Yes      Ta    n  .It Sx \&Fa  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Fd  Ta    \&No     Ta    \&No     Ta    >0  .It Sx \&Fd  Ta    \&No     Ta    \&No     Ta    >0
 .It Sx \&Fl  Ta    Yes      Ta    Yes      Ta    n  .It Sx \&Fl  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Fn  Ta    Yes      Ta    Yes      Ta    >0  .It Sx \&Fn  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Fr  Ta    \&No     Ta    \&No     Ta    n  .It Sx \&Fr  Ta    \&No     Ta    \&No     Ta    n
 .It Sx \&Ft  Ta    Yes      Ta    Yes      Ta    n  .It Sx \&Ft  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Fx  Ta    Yes      Ta    Yes      Ta    n  .It Sx \&Fx  Ta    Yes      Ta    Yes      Ta    n
 .It Sx \&Hf  Ta    \&No     Ta    \&No     Ta    n  .It Sx \&Hf  Ta    \&No     Ta    \&No     Ta    n
 .It Sx \&Ic  Ta    Yes      Ta    Yes      Ta    >0  .It Sx \&Ic  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&In  Ta    \&No     Ta    \&No     Ta    n  .It Sx \&In  Ta    \&No     Ta    \&No     Ta    1
 .It Sx \&Lb  Ta    \&No     Ta    \&No     Ta    1  .It Sx \&Lb  Ta    \&No     Ta    \&No     Ta    1
 .It Sx \&Li  Ta    Yes      Ta    Yes      Ta    n  .It Sx \&Li  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Lk  Ta    Yes      Ta    Yes      Ta    n  .It Sx \&Lk  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Lp  Ta    \&No     Ta    \&No     Ta    0  .It Sx \&Lp  Ta    \&No     Ta    \&No     Ta    0
 .It Sx \&Ms  Ta    Yes      Ta    Yes      Ta    >0  .It Sx \&Ms  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Mt  Ta    Yes      Ta    Yes      Ta    >0  .It Sx \&Mt  Ta    Yes      Ta    Yes      Ta    >0
Line 879  referring to book titles.
Line 892  referring to book titles.
 Publication city or location of an  Publication city or location of an
 .Sx \&Rs  .Sx \&Rs
 block.  block.
 .Pp  
 .Em Remarks :  
 this macro is not implemented in  
 .Xr groff 1 .  
 .Ss \&%D  .Ss \&%D
 Publication date of an  Publication date of an
 .Sx \&Rs  .Sx \&Rs
 block.  block.
 This should follow the reduced or canonical form syntax described in  Recommended formats of arguments are
 .Sx Dates .  .Ar month day , year
   or just
   .Ar year .
 .Ss \&%I  .Ss \&%I
 Publisher or issuer name of an  Publisher or issuer name of an
 .Sx \&Rs  .Sx \&Rs
Line 942  Memory address.
Line 953  Memory address.
 Do not use this for postal addresses.  Do not use this for postal addresses.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Ad [0,$]  .Dl \&.Ad [0,$]
 .D1 \&.Ad 0x00000000  .Dl \&.Ad 0x00000000
 .Ss \&An  .Ss \&An
 Author name.  Author name.
 Requires either the name of an author or one of the following arguments:  Requires either the name of an author or one of the following arguments:
Line 973  for the first author listing and
Line 984  for the first author listing and
 for all other author listings.  for all other author listings.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.An -nosplit  .Dl \&.An -nosplit
 .D1 \&.An Kristaps Dzonsons \&Aq kristaps@bsd.lv  .Dl \&.An Kristaps Dzonsons \&Aq kristaps@bsd.lv
 .Ss \&Ao  .Ss \&Ao
 Begin a block enclosed by angle brackets.  Begin a block enclosed by angle brackets.
 Does not have any head arguments.  Does not have any head arguments.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac  .Dl \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac
 .Pp  .Pp
 See also  See also
 .Sx \&Aq .  .Sx \&Aq .
Line 990  This is generally used as a grammatical device when re
Line 1001  This is generally used as a grammatical device when re
 form of a function.  form of a function.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Fn execve \&Ap d  .Dl \&.Fn execve \&Ap d
 .Ss \&Aq  .Ss \&Aq
 Encloses its arguments in angle brackets.  Encloses its arguments in angle brackets.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Fl -key= \&Ns \&Aq \&Ar val  .Dl \&.Fl -key= \&Ns \&Aq \&Ar val
 .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 1016  If an argument is not provided, the string
Line 1027  If an argument is not provided, the string
 is used as a default.  is used as a default.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Fl o \&Ns \&Ar file1  .Dl \&.Fl o \&Ns \&Ar file1
 .D1 \&.Ar  .Dl \&.Ar
 .D1 \&.Ar arg1 , arg2 .  .Dl \&.Ar arg1 , arg2 .
 .Ss \&At  .Ss \&At
 Formats an AT&T version.  Formats an AT&T version.
 Accepts one optional argument:  Accepts one optional argument:
Line 1035  A version of
Line 1046  A version of
 Note that these arguments do not begin with a hyphen.  Note that these arguments do not begin with a hyphen.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.At  .Dl \&.At
 .D1 \&.At V.1  .Dl \&.At V.1
 .Pp  .Pp
 See also  See also
 .Sx \&Bsx ,  .Sx \&Bsx ,
Line 1064  Its syntax is as follows:
Line 1075  Its syntax is as follows:
 .Pp  .Pp
 Display blocks are used to select a different indentation and  Display blocks are used to select a different indentation and
 justification than the one used by the surrounding text.  justification than the one used by the surrounding text.
 They may contain both macro lines and free-form text lines.  They may contain both macro lines and text lines.
 By default, a display block is preceded by a vertical space.  By default, a display block is preceded by a vertical space.
 .Pp  .Pp
 The  The
Line 1161  and
Line 1172  and
 argument are equivalent, as are  argument are equivalent, as are
 .Fl symbolic  .Fl symbolic
 and  and
 .Cm \&Sy,  .Cm \&Sy ,
 and  and
 .Fl literal  .Fl literal
 and  and
Line 1179  See also
Line 1190  See also
 and  and
 .Sx \&Sy .  .Sx \&Sy .
 .Ss \&Bk  .Ss \&Bk
 Keep the output generated from each macro input line together  For each macro, keep its output together on the same output line,
 on one single output line.  until the end of the macro or the end of the input line is reached,
 Line breaks in free-form text lines are unaffected.  whichever comes first.
   Line breaks in text lines are unaffected.
 The syntax is as follows:  The syntax is as follows:
 .Pp  .Pp
 .D1 Pf \. Sx \&Bk Fl words  .D1 Pf \. Sx \&Bk Fl words
Line 1204  Be careful in using over-long lines within a keep bloc
Line 1216  Be careful in using over-long lines within a keep bloc
 Doing so will clobber the right margin.  Doing so will clobber the right margin.
 .Ss \&Bl  .Ss \&Bl
 Begin a list.  Begin a list.
 Lists consist of items started by the  Lists consist of items specified using the
 .Sx \&It  .Sx \&It
 macro, containing a head or a body or both.  macro, containing a head or a body or both.
 The list syntax is as follows:  The list syntax is as follows:
Line 1339  See also
Line 1351  See also
 Encloses its arguments in square brackets.  Encloses its arguments in square brackets.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Bq 1 , \&Dv BUFSIZ  .Dl \&.Bq 1 , \&Dv BUFSIZ
 .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 1372  See also
Line 1384  See also
 Encloses its arguments in curly braces.  Encloses its arguments in curly braces.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Brq 1 , ... , \&Va n  .Dl \&.Brq 1 , ... , \&Va n
 .Pp  .Pp
 See also  See also
 .Sx \&Bro .  .Sx \&Bro .
Line 1381  Format the BSD/OS version provided as an argument, or 
Line 1393  Format the BSD/OS version provided as an argument, or 
 no argument is provided.  no argument is provided.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Bsx 1.0  .Dl \&.Bsx 1.0
 .D1 \&.Bsx  .Dl \&.Bsx
 .Pp  .Pp
 See also  See also
 .Sx \&At ,  .Sx \&At ,
Line 1395  and
Line 1407  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:
 .D1 \&.Bx 4.4  .Dl \&.Bx 4.4
 .D1 \&.Bx  .Dl \&.Bx
 .Pp  .Pp
 See also  See also
 .Sx \&At ,  .Sx \&At ,
Line 1419  This denotes strings accepted by
Line 1431  This denotes strings accepted by
 .Xr config 8 .  .Xr config 8 .
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Cd device le0 at scode?  .Dl \&.Cd device le0 at scode?
 .Pp  .Pp
 .Em Remarks :  .Em Remarks :
 this macro is commonly abused by using quoted literals to retain  this macro is commonly abused by using quoted literals to retain
Line 1432  Command modifiers.
Line 1444  Command modifiers.
 Useful when specifying configuration options or keys.  Useful when specifying configuration options or keys.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Cm ControlPath  .Dl \&.Cm ControlPath
 .D1 \&.Cm ControlMaster  .Dl \&.Cm ControlMaster
 .Pp  .Pp
 See also  See also
 .Sx \&Fl .  .Sx \&Fl .
Line 1444  statements.
Line 1456  statements.
 It is followed by a newline.  It is followed by a newline.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.D1 \&Fl abcdefgh  .Dl \&.D1 \&Fl abcdefgh
 .Pp  .Pp
 See also  See also
 .Sx \&Bd  .Sx \&Bd
Line 1470  This is the mandatory first macro of any
Line 1482  This is the mandatory first macro of any
 manual.  manual.
 Its syntax is as follows:  Its syntax is as follows:
 .Pp  .Pp
 .D1 Pf \. Sx \&Dd Op Ar date  .D1 Pf \. Sx \&Dd Ar month day , year
 .Pp  .Pp
 The  The
 .Ar date  .Ar month
 may be either  is the full English month name, the
 .Ar $\&Mdocdate$ ,  .Ar day
 which signifies the current manual revision date dictated by  is an optionally zero-padded numeral, and the
   .Ar year
   is the full four-digit year.
   .Pp
   Other arguments are not portable; the
   .Xr mandoc 1
   utility handles them as follows:
   .Bl -dash -offset 3n -compact
   .It
   To have the date automatically filled in by the
   .Ox
   version of
 .Xr cvs 1 ,  .Xr cvs 1 ,
 or instead a valid canonical date as specified by  the special string
 .Sx Dates .  .Dq $\&Mdocdate$
 If a date does not conform or is empty, the current date is used.  can be given as an argument.
   .It
   A few alternative date formats are accepted as well
   and converted to the standard form.
   .It
   If a date string cannot be parsed, it is used verbatim.
   .It
   If no date string is given, the current date is used.
   .El
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Dd $\&Mdocdate$  .Dl \&.Dd $\&Mdocdate$
 .D1 \&.Dd $\&Mdocdate: July 21 2007$  .Dl \&.Dd $\&Mdocdate: July 21 2007$
 .D1 \&.Dd July 21, 2007  .Dl \&.Dd July 21, 2007
 .Pp  .Pp
 See also  See also
 .Sx \&Dt  .Sx \&Dt
Line 1498  invocations.
Line 1529  invocations.
 It is followed by a newline.  It is followed by a newline.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Dl % mandoc mdoc.7 \e(ba less  .Dl \&.Dl % mandoc mdoc.7 \e(ba less
 .Pp  .Pp
 See also  See also
 .Sx \&Bd  .Sx \&Bd
Line 1650  It must be one of
Line 1681  It must be one of
 .Ar luna88k ,  .Ar luna88k ,
 .Ar mac68k ,  .Ar mac68k ,
 .Ar macppc ,  .Ar macppc ,
   .Ar mips64 ,
 .Ar mvme68k ,  .Ar mvme68k ,
 .Ar mvme88k ,  .Ar mvme88k ,
 .Ar mvmeppc ,  .Ar mvmeppc ,
Line 1665  or
Line 1697  or
 .El  .El
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Dt FOO 1  .Dl \&.Dt FOO 1
 .D1 \&.Dt FOO 4 KM  .Dl \&.Dt FOO 4 KM
 .D1 \&.Dt FOO 9 i386  .Dl \&.Dt FOO 9 i386
 .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, constant symbols,
   enumeration values, and so on.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Dv BUFSIZ  .Dl \&.Dv NULL
 .D1 \&.Dv STDOUT_FILENO  .Dl \&.Dv BUFSIZ
   .Dl \&.Dv STDOUT_FILENO
 .Pp  .Pp
 See also  See also
 .Sx \&Er .  .Sx \&Er
   and
   .Sx \&Ev
   for special-purpose constants and
   .Sx \&Va
   for variable symbols.
 .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:
 .D1 \&.Dx 2.4.1  .Dl \&.Dx 2.4.1
 .D1 \&.Dx  .Dl \&.Dx
 .Pp  .Pp
 See also  See also
 .Sx \&At ,  .Sx \&At ,
Line 1734  Note that this is a presentation term and should not b
Line 1773  Note that this is a presentation term and should not b
 stylistically decorating technical terms.  stylistically decorating technical terms.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Em Warnings!  .Dl \&.Em Warnings!
 .D1 \&.Em Remarks :  .Dl \&.Em Remarks :
 .Pp  .Pp
 See also  See also
 .Sx \&Bf ,  .Sx \&Bf ,
Line 1757  argument is used as the enclosure head, for example, s
Line 1796  argument is used as the enclosure head, for example, s
 will emulate  will emulate
 .Sx \&Do .  .Sx \&Do .
 .Ss \&Er  .Ss \&Er
 Display error constants.  Error constants for definitions of the
   .Va errno
   libc global variable.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Er EPERM  .Dl \&.Er EPERM
 .D1 \&.Er ENOENT  .Dl \&.Er ENOENT
 .Pp  .Pp
 See also  See also
 .Sx \&Dv .  .Sx \&Dv
   for general constants.
 .Ss \&Es  .Ss \&Es
 This macro is obsolete and not implemented.  This macro is obsolete and not implemented.
 .Ss \&Ev  .Ss \&Ev
Line 1772  Environmental variables such as those specified in
Line 1814  Environmental variables such as those specified in
 .Xr environ 7 .  .Xr environ 7 .
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Ev DISPLAY  .Dl \&.Ev DISPLAY
 .D1 \&.Ev PATH  .Dl \&.Ev PATH
   .Pp
   See also
   .Sx \&Dv
   for general constants.
 .Ss \&Ex  .Ss \&Ex
 Insert a standard sentence regarding exit values.  Insert a standard sentence regarding command exit values of 0 on success
   and >0 on failure.
 Its syntax is as follows:  Its syntax is as follows:
 .Pp  .Pp
 .D1 Pf \. Sx \&Ex Fl std Op Ar utility  .D1 Pf \. Sx \&Ex Fl std Op Ar utility...
 .Pp  .Pp
 When  If
 .Ar utility  .Ar utility
 is not specified, the document's name set by  is not specified, the document's name set by
 .Sx \&Nm  .Sx \&Nm
 is used.  is used.
   Multiple
   .Ar utility
   arguments are treated as separate utilities.
 .Pp  .Pp
 See also  See also
 .Sx \&Rv .  .Sx \&Rv .
Line 1813  Furthermore, if the following macro is another
Line 1863  Furthermore, if the following macro is another
 the last argument will also have a trailing comma.  the last argument will also have a trailing comma.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Fa \(dqconst char *p\(dq  .Dl \&.Fa \(dqconst char *p\(dq
 .D1 \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq  .Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq
 .D1 \&.Fa foo  .Dl \&.Fa foo
 .Pp  .Pp
 See also  See also
 .Sx \&Fo .  .Sx \&Fo .
Line 1843  If the argument is a macro, a hyphen is prefixed to th
Line 1893  If the argument is a macro, a hyphen is prefixed to th
 output.  output.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Fl a b c  .Dl \&.Fl a b c
 .D1 \&.Fl \&Pf a b  .Dl \&.Fl \&Pf a b
 .D1 \&.Fl  .Dl \&.Fl
 .D1 \&.Op \&Fl o \&Ns \&Ar file  .Dl \&.Op \&Fl o \&Ns \&Ar file
 .Pp  .Pp
 See also  See also
 .Sx \&Cm .  .Sx \&Cm .
Line 1855  A function name.
Line 1905  A function name.
 Its syntax is as follows:  Its syntax is as follows:
 .Bd -ragged -offset indent  .Bd -ragged -offset indent
 .Pf \. Ns Sx \&Fn  .Pf \. Ns Sx \&Fn
 .Op Cm functype  .Op Ar functype
 .Cm funcname  .Ar funcname
 .Op Oo Cm argtype Oc Cm argname  .Op Oo Ar argtype Oc Ar argname
 .Ed  .Ed
 .Pp  .Pp
 Function arguments are surrounded in parenthesis and  Function arguments are surrounded in parenthesis and
Line 1865  are delimited by commas.
Line 1915  are delimited by commas.
 If no arguments are specified, blank parenthesis are output.  If no arguments are specified, blank parenthesis are output.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Fn "int funcname" "int arg0" "int arg1"  .Dl \&.Fn \*qint funcname\*q \*qint arg0\*q \*qint arg1\*q
 .D1 \&.Fn funcname "int arg0"  .Dl \&.Fn funcname \*qint arg0\*q
 .D1 \&.Fn funcname arg0  .Dl \&.Fn funcname arg0
 .Bd -literal -offset indent -compact  .Bd -literal -offset indent -compact
 \&.Ft functype  \&.Ft functype
 \&.Fn funcname  \&.Fn funcname
 .Ed  .Ed
 .Pp  .Pp
   When referring to a function documented in another manual page, use
   .Sx \&Xr
   instead.
 See also  See also
 .Sx MANUAL STRUCTURE  .Sx MANUAL STRUCTURE
 and  and
Line 1883  This is a multi-line version of
Line 1936  This is a multi-line version of
 .Sx \&Fn .  .Sx \&Fn .
 Its syntax is as follows:  Its syntax is as follows:
 .Pp  .Pp
 .D1 Pf \. Sx \&Fo Cm funcname  .D1 Pf \. Sx \&Fo Ar funcname
 .Pp  .Pp
 Invocations usually occur in the following context:  Invocations usually occur in the following context:
 .Bd -ragged -offset indent  .Bd -ragged -offset indent
 .Pf \. Sx \&Ft Cm functype  .Pf \. Sx \&Ft Ar functype
 .br  .br
 .Pf \. Sx \&Fo Cm funcname  .Pf \. Sx \&Fo Ar funcname
 .br  .br
 .Pf \. Sx \&Fa Oo Cm argtype Oc Cm argname  .Pf \. Sx \&Fa Oo Ar argtype Oc Ar argname
 .br  .br
 \.\.\.  \&.\.\.
 .br  .br
 .Pf \. Sx \&Fc  .Pf \. Sx \&Fc
 .Ed  .Ed
Line 1908  See also
Line 1961  See also
 .Sx \&Fc ,  .Sx \&Fc ,
 and  and
 .Sx \&Ft .  .Sx \&Ft .
   .Ss \&Fr
   This macro is obsolete and not implemented.
 .Ss \&Ft  .Ss \&Ft
 A function type.  A function type.
 Its syntax is as follows:  Its syntax is as follows:
 .Pp  .Pp
 .D1 Pf \. Sx \&Ft Cm functype  .D1 Pf \. Sx \&Ft Ar functype
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Ft int  .Dl \&.Ft int
 .Bd -literal -offset indent -compact  .Bd -literal -offset indent -compact
 \&.Ft functype  \&.Ft functype
 \&.Fn funcname  \&.Fn funcname
Line 1927  See also
Line 1982  See also
 and  and
 .Sx \&Fo .  .Sx \&Fo .
 .Ss \&Fx  .Ss \&Fx
 Format the FreeBSD version provided as an argument, or a default value  Format the
   .Fx
   version provided as an argument, or a default value
 if no argument is provided.  if no argument is provided.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Fx 7.1  .Dl \&.Fx 7.1
 .D1 \&.Fx  .Dl \&.Fx
 .Pp  .Pp
 See also  See also
 .Sx \&At ,  .Sx \&At ,
Line 1952  This is similar to
Line 2009  This is similar to
 but used for instructions rather than values.  but used for instructions rather than values.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Ic hash  .Dl \&.Ic hash
 .D1 \&.Ic alias  .Dl \&.Ic alias
 .Pp  .Pp
 Note that using  Note that using
 .Sx \&Bd No Fl literal  .Sx \&Bd Fl literal
 or  or
 .Sx \&D1  .Sx \&D1
 is preferred for displaying code; the  is preferred for displaying code; the
Line 1974  preceded by
Line 2031  preceded by
 the arguments is enclosed in angle brackets.  the arguments is enclosed in angle brackets.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.In sys/types  .Dl \&.In sys/types
 .Pp  .Pp
 See also  See also
 .Sx MANUAL STRUCTURE .  .Sx MANUAL STRUCTURE .
Line 1991  and
Line 2048  and
 .Fl diag  .Fl diag
 have the following syntax:  have the following syntax:
 .Pp  .Pp
 .D1 Pf \. Sx \&It Cm args  .D1 Pf \. Sx \&It Ar args
 .Pp  .Pp
 Lists of type  Lists of type
 .Fl bullet ,  .Fl bullet ,
Line 2028  The
Line 2085  The
 list is the most complicated.  list is the most complicated.
 Its syntax is as follows:  Its syntax is as follows:
 .Pp  .Pp
 .D1 Pf \. Sx \&It Op Cm args  .D1 Pf \. Sx \&It Ar cell Op <TAB> Ar cell ...
   .D1 Pf \. Sx \&It Ar cell Op Sx \&Ta Ar cell ...
 .Pp  .Pp
 The  The arguments consist of one or more lines of text and macros
 .Cm args  representing a complete table line.
 are phrases, a mix of macros and text corresponding to a line column,  Cells within the line are delimited by tabs or by the special
 delimited by tabs or the special  .Sx \&Ta
 .Sq \&Ta  block macro.
 pseudo-macro.  The tab cell delimiter may only be used within the
 Lines subsequent the  
 .Sx \&It  .Sx \&It
 are interpreted within the scope of the last phrase.  line itself; on following lines, only the
 Calling the pseudo-macro  .Sx \&Ta
 .Sq \&Ta  macro can be used to delimit cells, and
 will open a new phrase scope (this must occur on a macro line to be  .Sx \&Ta
 interpreted as a macro).  is only recognized as a macro when called by other macros,
 Note that the tab phrase delimiter may only be used within the  not as the first macro on a line.
   .Pp
   Note that quoted strings may span tab-delimited cells on an
 .Sx \&It  .Sx \&It
 line itself.  line.
 Subsequent this, only the  For example,
 .Sq \&Ta  
 pseudo-macro may be used to delimit phrases.  
 Furthermore, note that quoted sections propagate over tab-delimited  
 phrases on an  
 .Sx \&It ,  
 for example,  
 .Pp  .Pp
 .D1 .It \(dqcol1 ; <TAB> col2 ;\(dq \&;  .Dl .It \(dqcol1 ; <TAB> col2 ;\(dq \&;
 .Pp  .Pp
 will preserve the semicolon whitespace except for the last.  will preserve the semicolon whitespace except for the last.
 .Pp  .Pp
Line 2064  See also
Line 2117  See also
 Specify a library.  Specify a library.
 The syntax is as follows:  The syntax is as follows:
 .Pp  .Pp
 .D1 Pf \. Sx \&Lb Cm library  .D1 Pf \. Sx \&Lb Ar library
 .Pp  .Pp
 The  The
 .Cm library  .Ar library
 parameter may be a system library, such as  parameter may be a system library, such as
 .Cm libz  .Ar libz
 or  or
 .Cm libpam ,  .Ar libpam ,
 in which case a small library description is printed next to the linker  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  invocation; or a custom library, in which case the library name is
 printed in quotes.  printed in quotes.
Line 2081  section as described in
Line 2134  section as described in
 .Sx MANUAL STRUCTURE .  .Sx MANUAL STRUCTURE .
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Lb libz  .Dl \&.Lb libz
 .D1 \&.Lb mdoc  .Dl \&.Lb mdoc
 .Ss \&Li  .Ss \&Li
 Denotes text that should be in a literal font mode.  Denotes text that should be in a literal font mode.
 Note that this is a presentation term and should not be used for  Note that this is a presentation term and should not be used for
Line 2097  and
Line 2150  and
 Format a hyperlink.  Format a hyperlink.
 Its syntax is as follows:  Its syntax is as follows:
 .Pp  .Pp
 .D1 Pf \. Sx \&Lk Cm uri Op Cm name  .D1 Pf \. Sx \&Lk Ar uri Op Ar name
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Lk http://bsd.lv "The BSD.lv Project"  .Dl \&.Lk http://bsd.lv \*qThe BSD.lv Project\*q
 .D1 \&.Lk http://bsd.lv  .Dl \&.Lk http://bsd.lv
 .Pp  .Pp
 See also  See also
 .Sx \&Mt .  .Sx \&Mt .
Line 2112  Synonym for
Line 2165  Synonym for
 Display a mathematical symbol.  Display a mathematical symbol.
 Its syntax is as follows:  Its syntax is as follows:
 .Pp  .Pp
 .D1 Pf \. Sx \&Ms Cm symbol  .D1 Pf \. Sx \&Ms Ar symbol
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Ms sigma  .Dl \&.Ms sigma
 .D1 \&.Ms aleph  .Dl \&.Ms aleph
 .Ss \&Mt  .Ss \&Mt
 Format a  Format a
 .Dq mailto:  .Dq mailto:
 hyperlink.  hyperlink.
 Its syntax is as follows:  Its syntax is as follows:
 .Pp  .Pp
 .D1 Pf \. Sx \&Mt Cm address  .D1 Pf \. Sx \&Mt Ar address
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Mt discuss@manpages.bsd.lv  .Dl \&.Mt discuss@manpages.bsd.lv
 .Ss \&Nd  .Ss \&Nd
 A one-line description of the manual's content.  A one line description of the manual's content.
 This may only be invoked in the  This may only be invoked in the
 .Em SYNOPSIS  .Em SYNOPSIS
 section subsequent the  section subsequent the
Line 2136  section subsequent the
Line 2189  section subsequent the
 macro.  macro.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Sx \&Nd mdoc language reference  .Dl \&.Sx \&Nd mdoc language reference
 .D1 \&.Sx \&Nd format and display UNIX manuals  .Dl \&.Sx \&Nd format and display UNIX manuals
 .Pp  .Pp
 The  The
 .Sx \&Nd  .Sx \&Nd
Line 2194  A
Line 2247  A
 macro used to terminate prior macro contexts.  macro used to terminate prior macro contexts.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Sx \&Fl ab \&No cd \&Fl ef  .Dl \&.Sx \&Fl ab \&No cd \&Fl ef
 .Ss \&Ns  .Ss \&Ns
 Suppress a space.  Suppress a space.
 Following invocation, text is interpreted as free-form text until a  Following invocation, text is interpreted as free-form text until a
 macro is encountered.  macro is encountered.
 .Pp  .Pp
   This has no effect when invoked at the start of a macro line.
   .Pp
 Examples:  Examples:
 .D1 \&.Fl o \&Ns \&Ar output  .Dl \&.Fl o \&Ns \&Ar output
 .Pp  .Pp
 See also  See also
 .Sx \&No  .Sx \&No
 and  and
 .Sx \&Sm .  .Sx \&Sm .
 .Ss \&Nx  .Ss \&Nx
 Format the NetBSD version provided as an argument, or a default value if  Format the
   .Nx
   version provided as an argument, or a default value if
 no argument is provided.  no argument is provided.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Nx 5.01  .Dl \&.Nx 5.01
 .D1 \&.Nx  .Dl \&.Nx
 .Pp  .Pp
 See also  See also
 .Sx \&At ,  .Sx \&At ,
Line 2244  Used when listing options to command-line utilities.
Line 2301  Used when listing options to command-line utilities.
 Prints the argument(s) in brackets.  Prints the argument(s) in brackets.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Op \&Fl a \&Ar b  .Dl \&.Op \&Fl a \&Ar b
 .D1 \&.Op \&Ar a | b  .Dl \&.Op \&Ar a | b
 .Pp  .Pp
 See also  See also
 .Sx \&Oo .  .Sx \&Oo .
Line 2257  any
Line 2314  any
 file.  file.
 Its syntax is as follows:  Its syntax is as follows:
 .Pp  .Pp
 .D1 Pf \. Sx \&Os Op Cm system  .D1 Pf \. Sx \&Os Op Ar system Op Ar version
 .Pp  .Pp
 The optional  The optional
 .Cm system  .Ar system
 parameter specifies the relevant operating system or environment.  parameter specifies the relevant operating system or environment.
 Left unspecified, it defaults to the local operating system version.  Left unspecified, it defaults to the local operating system version.
 This is the suggested form.  This is the suggested form.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Os  .Dl \&.Os
 .D1 \&.Os KTH/CSC/TCS  .Dl \&.Os KTH/CSC/TCS
 .D1 \&.Os BSD 4.3  .Dl \&.Os BSD 4.3
 .Pp  .Pp
 See also  See also
 .Sx \&Dd  .Sx \&Dd
Line 2280  Unknown usage.
Line 2337  Unknown usage.
 .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
   .Ox
   version provided as an argument, or a default value
 if no argument is provided.  if no argument is provided.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Ox 4.5  .Dl \&.Ox 4.5
 .D1 \&.Ox  .Dl \&.Ox
 .Pp  .Pp
 See also  See also
 .Sx \&At ,  .Sx \&At ,
Line 2298  and
Line 2357  and
 .Sx \&Ux .  .Sx \&Ux .
 .Ss \&Pa  .Ss \&Pa
 A file-system path.  A file-system path.
   If an argument is not provided, the string
   .Dq \(ti
   is used as a default.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Pa /usr/bin/mandoc  .Dl \&.Pa /usr/bin/mandoc
 .D1 \&.Pa /usr/share/man/man7/mdoc.7  .Dl \&.Pa /usr/share/man/man7/mdoc.7
 .Pp  .Pp
 See also  See also
 .Sx \&Lk .  .Sx \&Lk .
Line 2314  Removes the space
Line 2376  Removes the space
 between its arguments.  between its arguments.
 Its syntax is as follows:  Its syntax is as follows:
 .Pp  .Pp
 .D1 Pf \. \&Pf Cm prefix suffix  .D1 Pf \. \&Pf Ar prefix suffix
 .Pp  .Pp
 The  The
 .Cm suffix  .Ar suffix
 argument may be a macro.  argument may be a macro.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Pf \e. \&Sx \&Pf \&Cm prefix suffix  .Dl \&.Pf \e. \&Sx \&Pf \&Ar prefix suffix
 .Ss \&Po  .Ss \&Po
 Multi-line version of  Multi-line version of
 .Sx \&Pq .  .Sx \&Pq .
Line 2404  block is used within a SEE ALSO section, a vertical sp
Line 2466  block is used within a SEE ALSO section, a vertical sp
 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
 Inserts text regarding a function call's return value.  Insert a standard sentence regarding a system call's return value of 0
 This macro must consist of the  on success and \-1 on error, with the
 .Fl std  .Va errno
 argument followed by an optional  libc global variable set on error.
 .Ar function .  Its syntax is as follows:
   .Pp
   .D1 Pf \. Sx \&Rv Fl std Op Ar function...
   .Pp
 If  If
 .Ar function  .Ar function
 is not provided, the document's name as stipulated by the first  is not specified, the document's name set by
 .Sx \&Nm  .Sx \&Nm
 is provided.  is used.
   Multiple
   .Ar function
   arguments are treated as separate functions.
 .Pp  .Pp
 See also  See also
 .Sx \&Ex .  .Sx \&Ex .
Line 2442  Its syntax is as follows:
Line 2510  Its syntax is as follows:
 .D1 Pf \. Sx \&Sm Cm on | off  .D1 Pf \. Sx \&Sm Cm on | off
 .Pp  .Pp
 By default, spacing is  By default, spacing is
 .Cm on .  .Ar on .
 When switched  When switched
 .Cm off ,  .Ar off ,
 no white space is inserted between macro arguments and between the  no white space is inserted between macro arguments and between the
 output generated from adjacent macros, but free-form text lines  output generated from adjacent macros, but text lines
 still get normal spacing between words and sentences.  still get normal spacing between words and sentences.
 .Ss \&So  .Ss \&So
 Multi-line version of  Multi-line version of
Line 2581  The referenced section or sub-section name must be ide
Line 2649  The referenced section or sub-section name must be ide
 enclosed argument, including whitespace.  enclosed argument, including whitespace.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Sx MANUAL STRUCTURE  .Dl \&.Sx MANUAL STRUCTURE
   .Pp
   See also
   .Sx \&Sh
   and
   .Sx \&Ss .
 .Ss \&Sy  .Ss \&Sy
 Format enclosed arguments in symbolic  Format enclosed arguments in symbolic
 .Pq Dq boldface .  .Pq Dq boldface .
Line 2593  See also
Line 2666  See also
 .Sx \&Li ,  .Sx \&Li ,
 and  and
 .Sx \&Em .  .Sx \&Em .
   .Ss \&Ta
   Table cell separator in
   .Sx \&Bl Fl column
   lists; can only be used below
   .Sx \&It .
 .Ss \&Tn  .Ss \&Tn
 Format a tradename.  Format a tradename.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Tn IBM  .Dl \&.Tn IBM
 .Ss \&Ud  .Ss \&Ud
 Prints out  Prints out
 .Dq currently under development.  .Dq currently under development .
 .Ss \&Ux  .Ss \&Ux
 Format the UNIX name.  Format the UNIX name.
 Accepts no argument.  Accepts no argument.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Ux  .Dl \&.Ux
 .Pp  .Pp
 See also  See also
 .Sx \&At ,  .Sx \&At ,
Line 2621  and
Line 2699  and
 A variable name.  A variable name.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Va foo  .Dl \&.Va foo
 .D1 \&.Va const char *bar ;  .Dl \&.Va const char *bar ;
 .Ss \&Vt  .Ss \&Vt
 A variable type.  A variable type.
 This is also used for indicating global variables in the  This is also used for indicating global variables in the
Line 2641  Note that this should not be confused with
Line 2719  Note that this should not be confused with
 which is used for function return types.  which is used for function return types.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Vt unsigned char  .Dl \&.Vt unsigned char
 .D1 \&.Vt extern const char * const sys_signame[] \&;  .Dl \&.Vt extern const char * const sys_signame[] \&;
 .Pp  .Pp
 See also  See also
 .Sx MANUAL STRUCTURE  .Sx MANUAL STRUCTURE
Line 2652  and
Line 2730  and
 Close a scope opened by  Close a scope opened by
 .Sx \&Xo .  .Sx \&Xo .
 .Ss \&Xo  .Ss \&Xo
 Open an extension scope.  Extend the header of an
 This macro originally existed to extend the 9-argument limit of troff;  .Sx \&It
 since this limit has been lifted, the macro has been deprecated.  macro or the body of a partial-implicit block macro
   beyond the end of the input line.
   This macro originally existed to work around the 9-argument limit
   of historic
   .Xr roff 7 .
 .Ss \&Xr  .Ss \&Xr
 Link to another manual  Link to another manual
 .Pq Qq cross-reference .  .Pq Qq cross-reference .
 Its syntax is as follows:  Its syntax is as follows:
 .Pp  .Pp
 .D1 Pf \. Sx \&Xr Cm name section  .D1 Pf \. Sx \&Xr Ar name section
 .Pp  .Pp
 The  The
 .Cm name  .Ar name
 and  and
 .Cm section  .Ar section
 are the name and section of the linked manual.  are the name and section of the linked manual.
 If  If
 .Cm section  .Ar section
 is followed by non-punctuation, an  is followed by non-punctuation, an
 .Sx \&Ns  .Sx \&Ns
 is inserted into the token stream.  is inserted into the token stream.
 This behaviour is for compatibility with  This behaviour is for compatibility with
 .Xr groff 1 .  GNU troff.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Xr mandoc 1  .Dl \&.Xr mandoc 1
 .D1 \&.Xr mandoc 1 \&;  .Dl \&.Xr mandoc 1 \&;
 .D1 \&.Xr mandoc 1 \&Ns s behaviour  .Dl \&.Xr mandoc 1 \&Ns s behaviour
 .Ss \&br  .Ss \&br
 Emits a line-break.  Emits a line-break.
 This macro should not be used; it is implemented for compatibility with  This macro should not be used; it is implemented for compatibility with
Line 2693  This macro should not be used; it is implemented for c
Line 2775  This macro should not be used; it is implemented for c
 historical manuals.  historical manuals.
 Its syntax is as follows:  Its syntax is as follows:
 .Pp  .Pp
 .D1 Pf \. Sx \&sp Op Cm height  .D1 Pf \. Sx \&sp Op Ar height
 .Pp  .Pp
 The  The
 .Cm height  .Ar height
 argument must be formatted as described in  argument must be formatted as described in
 .Sx Scaling Widths .  .Sx Scaling Widths .
 If unspecified,  If unspecified,
Line 2708  troff implementations, at this time limited to GNU tro
Line 2790  troff implementations, at this time limited to GNU tro
 .Pq Qq groff .  .Pq Qq groff .
 The term  The term
 .Qq historic groff  .Qq historic groff
 refers to groff versions before the  refers to groff versions before 1.17,
   which featured a significant update of the
 .Pa doc.tmac  .Pa doc.tmac
 file re-write  file.
 .Pq somewhere between 1.15 and 1.19 .  
 .Pp  .Pp
 Heirloom troff, the other significant troff implementation accepting  Heirloom troff, the other significant troff implementation accepting
 \-mdoc, is similar to historic groff.  \-mdoc, is similar to historic groff.
 .Pp  .Pp
   The following problematic behaviour is found in groff:
   .ds hist (Historic groff only.)
   .Pp
 .Bl -dash -compact  .Bl -dash -compact
 .It  .It
 An empty  Display macros
 .Sq \&Dd  .Po
 macro in groff prints  .Sx \&Bd ,
 .Dq Epoch .  .Sx \&Dl ,
 In mandoc, it resolves to the current date.  and
   .Sx \&D1
   .Pc
   may not be nested.
   \*[hist]
 .It  .It
 The \es (font size), \em (font colour), and \eM (font filling colour)  .Sx \&At
 font decoration escapes are all discarded in mandoc.  with unknown arguments produces no output at all.
   \*[hist]
   Newer groff and mandoc print
   .Qq AT&T UNIX
   and the arguments.
 .It  .It
 Old groff fails to assert a newline before  .Sx \&Bl Fl column
 .Sx \&Bd Fl ragged compact .  does not recognize trailing punctuation characters when they immediately
   precede tabulator characters, but treats them as normal text and
   outputs a space before them.
 .It  .It
 groff behaves inconsistently when encountering  .Sx \&Bd Fl ragged compact
 .Pf non- Sx \&Fa  does not start a new line.
 children of  \*[hist]
   .It
   .Sx \&Dd
   with non-standard arguments behaves very strangely.
   When there are three arguments, they are printed verbatim.
   Any other number of arguments is replaced by the current date,
   but without any arguments the string
   .Dq Epoch
   is printed.
   .It
   .Sx \&Fl
   does not print a dash for an empty argument.
   \*[hist]
   .It
   .Sx \&Fn
   does not start a new line unless invoked as the line macro in the
   .Em SYNOPSIS
   section.
   \*[hist]
   .It
 .Sx \&Fo  .Sx \&Fo
 regarding spacing between arguments.  with
 In mandoc, this is not the case: each argument is consistently followed  .Pf non- Sx \&Fa
 by a single space and the trailing  children causes inconsistent spacing between arguments.
 .Sq \&)  In mandoc, a single space is always inserted between arguments.
 suppresses prior spacing.  
 .It  .It
 groff behaves inconsistently when encountering  
 .Sx \&Ft  .Sx \&Ft
 and  
 .Sx \&Fn  
 in the  in the
 .Em SYNOPSIS :  .Em SYNOPSIS
 at times newline(s) are suppressed depending on whether a prior  causes inconsistent vertical spacing, depending on whether a prior
 .Sx \&Fn  .Sx \&Fn
 has been invoked.  has been invoked.
 In mandoc, this is not the case.  
 See  See
 .Sx \&Ft  .Sx \&Ft
 and  and
 .Sx \&Fn  .Sx \&Fn
 for the normalised behaviour.  for the normalised behaviour in mandoc.
 .It  .It
 Historic groff does not break before an  
 .Sx \&Fn  
 when not invoked as the line macro in the  
 .Em SYNOPSIS  
 section.  
 .It  
 Historic groff formats the  
 .Sx \&In  .Sx \&In
 badly: trailing arguments are trashed and  ignores additional arguments and is not treated specially in the
 .Em SYNOPSIS  .Em SYNOPSIS .
 is not specially treated.  \*[hist]
 .It  .It
 groff does not accept the  .Sx \&It
 .Sq \&Ta  sometimes requires a
 pseudo-macro as a line macro.  .Fl nested
 mandoc does.  flag.
   \*[hist]
   In new groff and mandoc, any list may be nested by default and
   .Fl enum
   lists will restart the sequence only for the sub-list.
 .It  .It
 The comment syntax  .Sx \&Li
 .Sq \e\."  followed by a reserved character is incorrectly used in some manuals
 is no longer accepted.  instead of properly quoting that character, which sometimes works with
   historic groff.
 .It  .It
 In groff, the  .Sx \&Lk
   only accepts a single link-name argument; the remainder is misformatted.
   .It
 .Sx \&Pa  .Sx \&Pa
 macro does not format its arguments when used in the FILES section under  does not format its arguments when used in the FILES section under
 certain list types.  certain list types.
 mandoc does.  
 .It  .It
 Historic groff does not print a dash for empty  .Sx \&Ta
 .Sx \&Fl  can only be called by other macros, but not at the beginning of a line.
 arguments.  
 mandoc and newer groff implementations do.  
 .It  .It
 groff behaves irregularly when specifying  .Sx \&%C
   is not implemented.
   .It
   Historic groff only allows up to eight or nine arguments per macro input
   line, depending on the exact situation.
   Providing more arguments causes garbled output.
   The number of arguments on one input line is not limited with mandoc.
   .It
   Historic groff has many un-callable macros.
   Most of these (excluding some block-level macros) are callable
   in new groff and mandoc.
   .It
   .Sq \(ba
   (vertical bar) is not fully supported as a delimiter.
   \*[hist]
   .It
 .Sq \ef  .Sq \ef
   .Pq font face
   and
   .Sq \ef
   .Pq font family face
 .Sx Text Decoration  .Sx Text Decoration
 within line-macro scopes.  escapes behave irregularly when specified within line-macro scopes.
 mandoc follows a consistent system.  
 .It  .It
 In mandoc, negative scaling units are truncated to zero; groff would  Negative scaling units return to prior lines.
 move to prior lines.  Instead, mandoc truncates them to zero.
 Furthermore, the  .El
 .Sq f  .Pp
 scaling unit, while accepted, is rendered as the default unit.  The following features are unimplemented in mandoc:
   .Pp
   .Bl -dash -compact
 .It  .It
 In quoted literals, groff allowed pair-wise double-quotes to produce a  .Sx \&Bd
 standalone double-quote in formatted output.  .Fl file Ar file .
 This idiosyncratic behaviour is not applicable in mandoc.  
 .It  .It
 Display offsets  
 .Sx \&Bd  .Sx \&Bd
 .Fl offset Ar center  .Fl offset Ar center
 and  and
 .Fl offset Ar right  .Fl offset Ar right .
 are disregarded in mandoc.  Groff does not implement centered and flush-right rendering either,
 Furthermore, troff specifies a  but produces large indentations.
 .Fl file Ar file  
 argument that is not supported in mandoc.  
 Lastly, since text is not right-justified in mandoc (or even groff),  
 .Fl ragged  
 and  
 .Fl filled  
 are aliases, as are  
 .Fl literal  
 and  
 .Fl unfilled .  
 .It  .It
 Historic groff has many un-callable macros.  The
 Most of these (excluding some block-level macros) are now callable.  .Sq \eh
 .It  .Pq horizontal position ,
 The vertical bar  .Sq \ev
 .Sq \(ba  .Pq vertical position ,
 made historic groff  .Sq \em
 .Qq go orbital  .Pq text colour ,
 but has been a proper delimiter since then.  .Sq \eM
 .It  .Pq text filling colour ,
 .Sx \&It Fl nested  .Sq \ez
 is assumed for all lists (it wasn't in historic groff): any list may be  .Pq zero-length character ,
 nested and  .Sq \ew
 .Fl enum  .Pq string length ,
 lists will restart the sequence only for the sub-list.  .Sq \ek
 .It  .Pq horizontal position marker ,
 Some manuals use  .Sq \eo
 .Sx \&Li  .Pq text overstrike ,
 incorrectly by following it with a reserved character and expecting the  
 delimiter to render.  
 This is not supported in mandoc.  
 .It  
 In groff, the  
 .Sx \&Cd ,  
 .Sx \&Er ,  
 .Sx \&Ex ,  
 and  and
 .Sx \&Rv  .Sq \es
 macros were stipulated only to occur in certain manual sections.  .Pq text size
 mandoc does not have these restrictions.  escape sequences are all discarded in mandoc.
 .It  .It
 Newer groff and mandoc print  The
 .Qq AT&T UNIX  .Sq \ef
 prior to unknown arguments of  scaling unit is accepted by mandoc, but rendered as the default unit.
 .Sx \&At ;  .It
 older groff did nothing.  In quoted literals, groff allows pairwise double-quotes to produce a
   standalone double-quote in formatted output.
   This is not supported by mandoc.
 .El  .El
 .Sh SEE ALSO  .Sh SEE ALSO
   .Xr man 1 ,
 .Xr mandoc 1 ,  .Xr mandoc 1 ,
   .Xr eqn 7 ,
   .Xr man 7 ,
 .Xr mandoc_char 7  .Xr mandoc_char 7
   .Xr roff 7 ,
   .Xr tbl 7
   .Sh HISTORY
   The
   .Nm
   language first appeared as a troff macro package in
   .Bx 4.4 .
   It was later significantly updated by Werner Lemberg and Ruslan Ermilov
   in groff-1.17.
   The standalone implementation that is part of the
   .Xr mandoc 1
   utility written by Kristaps Dzonsons appeared in
   .Ox 4.6 .
 .Sh AUTHORS  .Sh AUTHORS
 The  The
 .Nm  .Nm

Legend:
Removed from v.1.142  
changed lines
  Added in v.1.191

CVSweb