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

Diff for /mandoc/mdoc.7 between version 1.184 and 1.185

version 1.184, 2011/04/01 19:50:49 version 1.185, 2011/04/06 11:39:25
Line 40  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.
 .Pp  .Pp
 If the first character of a line is a space, that line is printed  If the first character of a text line is a space, that line is printed
 with a leading newline.  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 ,
Line 102  Use of reserved terms is described in
Line 102  Use of reserved terms is described in
 For general use in macro lines, these can be escaped with a non-breaking  For general use in macro lines, these can be escaped with a non-breaking
 space  space
 .Pq Sq \e& .  .Pq Sq \e& .
   In text lines, these may be used as normal punctuation.
 .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 132  escape followed by an indicator: B (bold), I (italic),
Line 133  escape followed by an indicator: B (bold), I (italic),
 .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 177  and
Line 175  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; unescaped  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 199  Thus, the following produces
Line 197  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 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 270  The proper spacing is also intelligently preserved if 
Line 268  The proper spacing is also intelligently preserved if 
 the boundary of a macro line.  the boundary of a macro line.
 For example:  For example:
 .Pp  .Pp
 .Dl \&Xr mandoc 1 \.  .Dl \&.Xr mandoc 1 \&.
 .Dl \&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 359  The syntax for this as follows:
Line 357  The syntax for this as follows:
 \&.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 386  configuration.
Line 388  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
 \&.In header.h  \&.In header.h
Line 406  For the second, function calls (sections 2, 3, 9):
Line 410  For the second, function calls (sections 2, 3, 9):
 \&.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 454  or
Line 466  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 breakdown 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 604  column, if applicable, describes closure rules.
Line 622  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 1040  Its syntax is as follows:
Line 1061  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 1157  and
Line 1178  and
 .Ss \&Bk  .Ss \&Bk
 Keep the output generated from each macro input line together  Keep the output generated from each macro input line together
 on one single output line.  on one single output line.
 Line breaks in free-form text lines are unaffected.  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 1851  A function name.
Line 1872  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 1882  This is a multi-line version of
Line 1903  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
Line 1911  and
Line 1932  and
 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:
 .Dl \&.Ft int  .Dl \&.Ft int
Line 1992  and
Line 2013  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 2065  See also
Line 2086  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 2098  and
Line 2119  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:
 .Dl \&.Lk http://bsd.lv \*qThe BSD.lv Project\*q  .Dl \&.Lk http://bsd.lv \*qThe BSD.lv Project\*q
Line 2113  Synonym for
Line 2134  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:
 .Dl \&.Ms sigma  .Dl \&.Ms sigma
Line 2124  Format a
Line 2145  Format a
 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:
 .Dl \&.Mt discuss@manpages.bsd.lv  .Dl \&.Mt discuss@manpages.bsd.lv
Line 2262  any
Line 2283  any
 file.  file.
 Its syntax is as follows:  Its syntax is as follows:
 .Pp  .Pp
 .D1 Pf \. Sx \&Os Op Cm system Op Cm version  .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.
Line 2324  Removes the space
Line 2345  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:
 .Dl \&.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 2452  Its syntax is as follows:
Line 2473  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 2679  Link to another manual
Line 2700  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.
Line 2712  This macro should not be used; it is implemented for c
Line 2733  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,

Legend:
Removed from v.1.184  
changed lines
  Added in v.1.185

CVSweb