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

Diff for /mandoc/mdoc.7 between version 1.153 and 1.182

version 1.153, 2010/08/24 13:07:01 version 1.182, 2011/03/17 14:50:14
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 52  Other lines are interpreted within the current state.
Line 52  Other lines are interpreted within the current state.
 .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 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 ,
Line 65  A macro line with only a control character and comment
Line 65  A macro line with only a control character and comment
 is also ignored.  is also ignored.
 Macro lines with only a control character and optional 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 91  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  Use of reserved terms is described in
 .Sx MACRO SYNTAX .  .Sx MACRO SYNTAX .
 For general use in macro lines, these characters can either be escaped  For general use in macro lines, these can be escaped with a non-breaking
 with a non-breaking space  space
 .Pq Sq \e&  .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 free-form lines.
 Sequences begin with the escape character  Sequences begin with the escape character
Line 125  Terms may be text-decorated using the
Line 128  Terms may be text-decorated using the
 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.
Line 197  Thus, the following produces
Line 200  Thus, the following produces
 .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  
 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 283  a line.
Line 258  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.  the boundary of a macro line.
 For example:  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 331  file:
Line 308  file:
 \&.Sh NAME  \&.Sh NAME
 \&.Nm foo  \&.Nm foo
 \&.Nd a description goes here  \&.Nd a description goes here
 \&.\e\*q The next is for sections 2, 3, & 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 foo
 \&.Op Fl options  \&.Op Fl options
Line 342  The
Line 320  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 362  utility processes files ...
Line 341  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 an  The sections in an
Line 601  closes it out.
Line 581  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 728  and/or tail
Line 709  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 761  section line, else it is
Line 742  section line, else it is
 .Sx In-line .  .Sx In-line .
 .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
Line 791  then the macro accepts an arbitrary number of argument
Line 772  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 800  then the macro accepts an arbitrary number of argument
Line 781  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    n
 .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 880  block.
Line 861  block.
 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 935  Memory address.
Line 918  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 966  for the first author listing and
Line 949  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 983  This is generally used as a grammatical device when re
Line 966  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 1009  If an argument is not provided, the string
Line 992  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 1028  A version of
Line 1011  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 1197  Be careful in using over-long lines within a keep bloc
Line 1180  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 1332  See also
Line 1315  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 1365  See also
Line 1348  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 1374  Format the BSD/OS version provided as an argument, or 
Line 1357  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 1394  Format the BSD version provided as an argument, or a d
Line 1377  Format the BSD version provided as an argument, or a d
 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 1412  This denotes strings accepted by
Line 1395  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 1425  Command modifiers.
Line 1408  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 1437  statements.
Line 1420  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 1463  This is the mandatory first macro of any
Line 1446  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 1491  invocations.
Line 1493  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 1643  It must be one of
Line 1645  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 1658  or
Line 1661  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
Line 1670  and
Line 1673  and
 Defined variables such as preprocessor constants.  Defined variables such as preprocessor constants.
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Dv BUFSIZ  .Dl \&.Dv BUFSIZ
 .D1 \&.Dv STDOUT_FILENO  .Dl \&.Dv STDOUT_FILENO
 .Pp  .Pp
 See also  See also
 .Sx \&Er .  .Sx \&Er .
Line 1680  Format the DragonFly BSD version provided as an argume
Line 1683  Format the DragonFly BSD version provided as an argume
 value if no argument is provided.  value if no argument is provided.
 .Pp  .Pp
 Examples:  Examples:
 .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 1727  Note that this is a presentation term and should not b
Line 1730  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 1753  will emulate
Line 1756  will emulate
 Display error constants.  Display error constants.
 .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 .
Line 1765  Environmental variables such as those specified in
Line 1768  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
 .Ss \&Ex  .Ss \&Ex
 Insert a standard sentence regarding exit values.  Insert a standard sentence regarding exit values.
 Its syntax is as follows:  Its syntax is as follows:
Line 1806  Furthermore, if the following macro is another
Line 1809  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 1836  If the argument is a macro, a hyphen is prefixed to th
Line 1839  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 1858  are delimited by commas.
Line 1861  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 "int funcname" "int arg0" "int arg1"
 .D1 \&.Fn funcname "int arg0"  .Dl \&.Fn funcname "int arg0"
 .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 1908  Its syntax is as follows:
Line 1914  Its syntax is as follows:
 .D1 Pf \. Sx \&Ft Cm functype  .D1 Pf \. Sx \&Ft Cm 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 1926  version provided as an argument, or a default value
Line 1932  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 1947  This is similar to
Line 1953  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 Fl literal  .Sx \&Bd Fl literal
Line 1969  preceded by
Line 1975  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 2049  phrases on an
Line 2055  phrases on an
 .Sx \&It ,  .Sx \&It ,
 for example,  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 2076  section as described in
Line 2082  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 2095  Its syntax is as follows:
Line 2101  Its syntax is as follows:
 .D1 Pf \. Sx \&Lk Cm uri Op Cm name  .D1 Pf \. Sx \&Lk Cm uri Op Cm name
 .Pp  .Pp
 Examples:  Examples:
 .D1 \&.Lk http://bsd.lv \*qThe BSD.lv Project\*q  .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 2110  Its syntax is as follows:
Line 2116  Its syntax is as follows:
 .D1 Pf \. Sx \&Ms Cm symbol  .D1 Pf \. Sx \&Ms Cm 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:
Line 2121  Its syntax is as follows:
Line 2127  Its syntax is as follows:
 .D1 Pf \. Sx \&Mt Cm address  .D1 Pf \. Sx \&Mt Cm 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
Line 2131  section subsequent the
Line 2137  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 2189  A
Line 2195  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
Line 2209  version provided as an argument, or a default value if
Line 2217  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 2241  Used when listing options to command-line utilities.
Line 2249  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 2263  Left unspecified, it defaults to the local operating s
Line 2271  Left unspecified, it defaults to the local operating s
 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 2283  version provided as an argument, or a default value
Line 2291  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 2297  and
Line 2305  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 2320  The
Line 2331  The
 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 \&Cm prefix suffix
 .Ss \&Po  .Ss \&Po
 Multi-line version of  Multi-line version of
 .Sx \&Pq .  .Sx \&Pq .
Line 2580  The referenced section or sub-section name must be ide
Line 2591  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 2596  and
Line 2612  and
 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 .
Line 2605  Format the UNIX name.
Line 2621  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 2620  and
Line 2636  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 2640  Note that this should not be confused with
Line 2656  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 2651  and
Line 2667  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 .
Line 2675  This behaviour is for compatibility with
Line 2695  This behaviour is for compatibility with
 GNU troff.  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 2707  troff implementations, at this time limited to GNU tro
Line 2727  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.
Line 2720  The following problematic behaviour is found in groff:
Line 2740  The following problematic behaviour is found in groff:
 .Pp  .Pp
 .Bl -dash -compact  .Bl -dash -compact
 .It  .It
   Display macros
   .Po
   .Sx \&Bd ,
   .Sx \&Dl ,
   and
   .Sx \&D1
   .Pc
   may not be nested.
   \*[hist]
   .It
 .Sx \&At  .Sx \&At
 with unknown arguments produces no output at all.  with unknown arguments produces no output at all.
 \*[hist]  \*[hist]
Line 2737  does not start a new line.
Line 2767  does not start a new line.
 \*[hist]  \*[hist]
 .It  .It
 .Sx \&Dd  .Sx \&Dd
 without an argument prints  with non-standard arguments behaves very strangely.
 .Dq Epoch .  When there are three arguments, they are printed verbatim.
 In mandoc, it resolves to the current date.  Any other number of arguments is replaced by the current date,
   but without any arguments the string
   .Dq Epoch
   is printed.
 .It  .It
 .Sx \&Fl  .Sx \&Fl
 does not print a dash for an empty argument.  does not print a dash for an empty argument.
Line 2801  can only be called by other macros, but not at the beg
Line 2834  can only be called by other macros, but not at the beg
 .Sx \&%C  .Sx \&%C
 is not implemented.  is not implemented.
 .It  .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.  Historic groff has many un-callable macros.
 Most of these (excluding some block-level macros) are callable  Most of these (excluding some block-level macros) are callable
 in new groff and mandoc.  in new groff and mandoc.
Line 2848  The
Line 2886  The
 .Pq zero-length character ,  .Pq zero-length character ,
 .Sq \ew  .Sq \ew
 .Pq string length ,  .Pq string length ,
   .Sq \ek
   .Pq horizontal position marker ,
   .Sq \eo
   .Pq text overstrike ,
 and  and
 .Sq \es  .Sq \es
 .Pq text size  .Pq text size
Line 2862  standalone double-quote in formatted output.
Line 2904  standalone double-quote in formatted output.
 This is not supported by mandoc.  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  .Sh HISTORY
 The  The
 .Nm  .Nm
 language first appeared as a troff macro package in  language first appeared as a troff macro package in
 .Bx 4.4 .  .Bx 4.4 .
 It was later significantly updated by Werner Lemberg and Ruslan Ermilov  It was later significantly updated by Werner Lemberg and Ruslan Ermilov
 in groff-1.20.1.  in groff-1.17.
 The standalone implementation that is part of the  The standalone implementation that is part of the
 .Xr mandoc 1  .Xr mandoc 1
 utility written by Kristaps Dzonsons appeared in  utility written by Kristaps Dzonsons appeared in
Legend:
Removed from v.1.153  
changed lines
  Added in v.1.182
CVSweb