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

Diff for /mandoc/man.7 between version 1.67 and 1.68

version 1.67, 2010/05/12 08:41:17 version 1.68, 2010/05/12 16:52:33
Line 25  The
Line 25  The
 .Nm man  .Nm man
 language was historically used to format  language was historically used to format
 .Ux  .Ux
 manuals.  This reference document describes its syntax, structure, and  manuals.
 usage.  This reference document describes its syntax, structure, and usage.
 .Pp  .Pp
 .Bf -emphasis  .Bf -emphasis
 Do not use  Do not use
Line 42  An
Line 42  An
 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.  Other lines are interpreted within the scope of  are parsed for macros.
   Other lines are interpreted within the scope of
 prior macros:  prior macros:
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.SH Macro lines change control state.  \&.SH Macro lines change control state.
Line 51  Other lines are interpreted within the current state.
Line 52  Other lines are interpreted within the current state.
 .Sh INPUT ENCODING  .Sh INPUT ENCODING
 .Nm  .Nm
 documents may contain only graphable 7-bit ASCII characters, the  documents may contain only graphable 7-bit ASCII characters, the
 space character, and the tabs character.  All manuals must have  space character, and the tabs character.
   All manuals must have
 .Ux  .Ux
 line termination.  line termination.
 .Pp  .Pp
Line 61  vertical space.
Line 63  vertical space.
 Text following a  Text following a
 .Sq \e\*" ,  .Sq \e\*" ,
 whether in a macro or free-form text line, is ignored to the end of  whether in a macro or free-form text line, is ignored to the end of
 line.  A macro line with only a control character and comment escape,  line.
   A macro line with only a control character and comment escape,
 .Sq \&.\e" ,  .Sq \&.\e" ,
 is also ignored.  Macro lines with only a control character and  is also ignored.
 optionally whitespace are stripped from input.  Macro lines with only a control character and optionally whitespace are
   stripped from input.
 .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 75  for two-character sequences; an open-bracket
Line 79  for two-character sequences; an open-bracket
 .Sq \&[  .Sq \&[
 for n-character sequences (terminated at a close-bracket  for n-character sequences (terminated at a close-bracket
 .Sq \&] ) ;  .Sq \&] ) ;
 or a single one-character sequence.  See  or a single one-character sequence.
   See
 .Xr mandoc_char 7  .Xr mandoc_char 7
 for a complete list.  Examples include  for a complete list.
   Examples include
 .Sq \e(em  .Sq \e(em
 .Pq em-dash  .Pq em-dash
 and  and
Line 92  escape followed by an indicator: B (bold), I, (italic)
Line 98  escape followed by an indicator: B (bold), I, (italic)
 .D1 \efBbold\efR \efIitalic\efP  .D1 \efBbold\efR \efIitalic\efP
 .Pp  .Pp
 A numerical representation 3, 2, or 1 (bold, italic, and Roman,  A numerical representation 3, 2, or 1 (bold, italic, and Roman,
 respectively) may be used instead.  A text decoration is only valid, if  respectively) may be used instead.
 specified in free-form text, until the next macro invocation; if  A text decoration is only valid, if specified in free-form text, until
 specified within a macro, it's only valid until the macro closes scope.  the next macro invocation; if specified within a macro, it's only valid
   until the macro closes scope.
 Note that macros like  Note that macros like
 .Sx \&BR  .Sx \&BR
 open and close a font scope with each argument.  open and close a font scope with each argument.
Line 132  trailing spaces are stripped from input (unless in a l
Line 139  trailing spaces are stripped from input (unless in a l
 Blank free-form lines, which may include spaces, are permitted and  Blank free-form lines, which may include spaces, are permitted and
 rendered as an empty line.  rendered as an empty line.
 .Pp  .Pp
 In macro lines, whitespace delimits arguments and is discarded.  If  In macro lines, whitespace delimits arguments and is discarded.
 arguments are quoted, whitespace within the quotes is retained.  If arguments are quoted, whitespace within the quotes is retained.
 .Ss Dates  .Ss Dates
 The  The
 .Sx \&TH  .Sx \&TH
 macro is the only  macro is the only
 .Nm  .Nm
 macro that requires a date.  The form for this date is the ISO-8601  macro that requires a date.
   The form for this date is the ISO-8601
 standard  standard
 .Cm YYYY-MM-DD .  .Cm YYYY-MM-DD .
 .Ss Scaling Widths  .Ss Scaling Widths
Line 152  stipulating a two-inch paragraph indentation with the 
Line 160  stipulating a two-inch paragraph indentation with the 
 The syntax for scaled widths is  The syntax for scaled widths is
 .Sq Li [+-]?[0-9]*.[0-9]*[:unit:]? ,  .Sq Li [+-]?[0-9]*.[0-9]*[:unit:]? ,
 where a decimal must be preceded or proceeded by at least one digit.  where a decimal must be preceded or proceeded by at least one digit.
 Negative numbers, while accepted, are truncated to zero.  The following  Negative numbers, while accepted, are truncated to zero.
 scaling units are accepted:  The following scaling units are accepted:
 .Pp  .Pp
 .Bl -tag -width Ds -offset indent -compact  .Bl -tag -width Ds -offset indent -compact
 .It c  .It c
Line 209  Each
Line 217  Each
 .Nm  .Nm
 document must contain contains at least the  document must contain contains at least the
 .Sx \&TH  .Sx \&TH
 macro describing the document's section and title.  It may occur  macro describing the document's section and title.
 anywhere in the document, although conventionally, it appears as the  It may occur anywhere in the document, although conventionally, it
 first macro.  appears as the first macro.
 .Pp  .Pp
 Beyond  Beyond
 .Sx \&TH ,  .Sx \&TH ,
 at least one macro or text node must appear in the document.  Documents  at least one macro or text node must appear in the document.
 are generally structured as follows:  Documents are generally structured as follows:
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.TH FOO 1 2009-10-10  \&.TH FOO 1 2009-10-10
 \&.  \&.
Line 256  The \efBfoo\efR utility processes files...
Line 264  The \efBfoo\efR utility processes files...
 .Pp  .Pp
 The sections in a  The sections in a
 .Nm  .Nm
 document are conventionally ordered as they appear above.  Sections  document are conventionally ordered as they appear above.
 should be composed as follows:  Sections should be composed as follows:
 .Bl -ohang -offset indent  .Bl -ohang -offset indent
 .It Em NAME  .It Em NAME
 The name(s) and a short description of the documented material.  The  The name(s) and a short description of the documented material.
 syntax for this is generally as follows:  The syntax for this is generally as follows:
 .Pp  .Pp
 .D1 \efBname\efR \e(en description  .D1 \efBname\efR \e(en description
 .It Em LIBRARY  .It Em LIBRARY
 The name of the library containing the documented material, which is  The name of the library containing the documented material, which is
 assumed to be a function in a section 2 or 3 manual.  For functions in  assumed to be a function in a section 2 or 3 manual.
 the C library, this may be as follows:  For functions in the C library, this may be as follows:
 .Pp  .Pp
 .D1 Standard C Library (libc, -lc)  .D1 Standard C Library (libc, -lc)
 .It Em SYNOPSIS  .It Em SYNOPSIS
Line 295  This expands upon the brief, one-line description in
Line 303  This expands upon the brief, one-line description in
 It usually contains a break-down of the options (if documenting a  It usually contains a break-down of the options (if documenting a
 command).  command).
 .It Em IMPLEMENTATION NOTES  .It Em IMPLEMENTATION NOTES
 Implementation-specific notes should be kept here.  This is useful when  Implementation-specific notes should be kept here.
 implementing standard functions that may have side effects or notable  This is useful when implementing standard functions that may have side
 algorithmic implications.  effects or notable algorithmic implications.
 .It Em RETURN VALUES  .It Em RETURN VALUES
 This section is the dual of  This section is the dual of
 .Em EXIT STATUS ,  .Em EXIT STATUS ,
 which is used for commands.  It documents the return values of functions  which is used for commands.
 in sections 2, 3, and 9.  It documents the return values of functions in sections 2, 3, and 9.
 .It Em ENVIRONMENT  .It Em ENVIRONMENT
 Documents any usages of environment variables, e.g.,  Documents any usages of environment variables, e.g.,
 .Xr environ 7 .  .Xr environ 7 .
 .It Em FILES  .It Em FILES
 Documents files used.  It's helpful to document both the file and a  Documents files used.
 short description of how the file is used (created, modified, etc.).  It's helpful to document both the file and a short description of how
   the file is used (created, modified, etc.).
 .It Em EXIT STATUS  .It Em EXIT STATUS
 Command exit status for section 1, 6, and 8 manuals.  This section is  Command exit status for section 1, 6, and 8 manuals.
 the dual of  This section is the dual of
 .Em RETURN VALUES ,  .Em RETURN VALUES ,
 which is used for functions.  Historically, this information was  which is used for functions.
 described in  Historically, this information was described in
 .Em DIAGNOSTICS ,  .Em DIAGNOSTICS ,
 a practise that is now discouraged.  a practise that is now discouraged.
 .It Em EXAMPLES  .It Em EXAMPLES
 Example usages.  This often contains snippets of well-formed,  Example usages.
 well-tested invocations.  Make doubly sure that your examples work  This often contains snippets of well-formed,
 properly!  well-tested invocations.
   Make doubly sure that your examples work properly!
 .It Em DIAGNOSTICS  .It Em DIAGNOSTICS
 Documents error conditions.  This is most useful in section 4 manuals.  Documents error conditions.
   This is most useful in section 4 manuals.
 Historically, this section was used in place of  Historically, this section was used in place of
 .Em EXIT STATUS  .Em EXIT STATUS
 for manuals in sections 1, 6, and 8; however, this practise is  for manuals in sections 1, 6, and 8; however, this practise is
Line 330  discouraged.
Line 341  discouraged.
 .It Em ERRORS  .It Em ERRORS
 Documents error handling in sections 2, 3, and 9.  Documents error handling in sections 2, 3, and 9.
 .It Em SEE ALSO  .It Em SEE ALSO
 References other manuals with related topics.  This section should exist  References other manuals with related topics.
 for most manuals.  This section should exist for most manuals.
 .Pp  .Pp
 .D1 \&.BR bar \&( 1 \&),  .D1 \&.BR bar \&( 1 \&),
 .Pp  .Pp
Line 364  Documents any security precautions that operators shou
Line 375  Documents any security precautions that operators shou
 Macros are one to three three characters in length and begin with a  Macros are one to three three characters in length and begin with a
 control character ,  control character ,
 .Sq \&. ,  .Sq \&. ,
 at the beginning of the line.  The  at the beginning of the line.
   The
 .Sq \(aq  .Sq \(aq
 macro control character is also accepted.  An arbitrary amount of  macro control character is also accepted.
 whitespace (spaces or tabs) may sit between the control character and  An arbitrary amount of whitespace (spaces or tabs) may sit between the
 the macro name.  Thus, the following are equivalent:  control character and the macro name.
   Thus, the following are equivalent:
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.PP  \&.PP
 \&.\ \ \ PP  \&.\ \ \ PP
Line 376  the macro name.  Thus, the following are equivalent:
Line 389  the macro name.  Thus, the following are equivalent:
 .Pp  .Pp
 The  The
 .Nm  .Nm
 macros are classified by scope: line scope or block scope.  Line  macros are classified by scope: line scope or block scope.
 macros are only scoped to the current line (and, in some situations,  Line macros are only scoped to the current line (and, in some
 the subsequent line).  Block macros are scoped to the current line and  situations, the subsequent line).
 subsequent lines until closed by another block macro.  Block macros are scoped to the current line and subsequent lines until
   closed by another block macro.
 .Ss Line Macros  .Ss Line Macros
 Line macros are generally scoped to the current line, with the body  Line macros are generally scoped to the current line, with the body
 consisting of zero or more arguments.  If a macro is scoped to the next  consisting of zero or more arguments.
 line and the line arguments are empty, the next line, which must be  If a macro is scoped to the next line and the line arguments are empty,
 text, is used instead.  Thus:  the next line, which must be text, is used instead.
   Thus:
 .Bd -literal -offset indent  .Bd -literal -offset indent
 \&.I  \&.I
 foo  foo
Line 438  The syntax is as follows:
Line 453  The syntax is as follows:
 Macros marked as  Macros marked as
 .Qq compat  .Qq compat
 are included for compatibility with the significant corpus of existing  are included for compatibility with the significant corpus of existing
 manuals that mix dialects of roff.  These macros should not be used for  manuals that mix dialects of roff.
 portable  These macros should not be used for portable
 .Nm  .Nm
 manuals.  manuals.
 .Ss Block Macros  .Ss Block Macros
 Block macros are comprised of a head and body.  Like for in-line macros,  Block macros are comprised of a head and body.
 the head is scoped to the current line and, in one circumstance, the  Like for in-line macros, the head is scoped to the current line and, in
 next line (the next-line stipulations as in  one circumstance, the next line (the next-line stipulations as in
 .Sx Line Macros  .Sx Line Macros
 apply here as well).  apply here as well).
 .Pp  .Pp
Line 500  If a block macro is next-line scoped, it may only be f
Line 515  If a block macro is next-line scoped, it may only be f
 macros for decorating text.  macros for decorating text.
 .Sh REFERENCE  .Sh REFERENCE
 This section is a canonical reference to all macros, arranged  This section is a canonical reference to all macros, arranged
 alphabetically.  For the scoping of individual macros, see  alphabetically.
   For the scoping of individual macros, see
 .Sx MACRO SYNTAX .  .Sx MACRO SYNTAX .
 .Ss \&B  .Ss \&B
 Text is rendered in bold face.  Text is rendered in bold face.
Line 513  See also
Line 529  See also
 and  and
 .Sx \&r .  .Sx \&r .
 .Ss \&BI  .Ss \&BI
 Text is rendered alternately in bold face and italic.  Thus,  Text is rendered alternately in bold face and italic.
   Thus,
 .Sq .BI this word and that  .Sq .BI this word and that
 causes  causes
 .Sq this  .Sq this
Line 523  to render in bold face, while
Line 540  to render in bold face, while
 .Sq word  .Sq word
 and  and
 .Sq that  .Sq that
 render in italics.  Whitespace between arguments is omitted in output.  render in italics.
   Whitespace between arguments is omitted in output.
 .Pp  .Pp
 Examples:  Examples:
 .Pp  .Pp
Line 558  See also
Line 576  See also
 and  and
 .Sx \&IR .  .Sx \&IR .
 .Ss \&DT  .Ss \&DT
 Has no effect.  Included for compatibility.  Has no effect.
   Included for compatibility.
 .Ss \&HP  .Ss \&HP
 Begin a paragraph whose initial output line is left-justified, but  Begin a paragraph whose initial output line is left-justified, but
 subsequent output lines are indented, with the following syntax:  subsequent output lines are indented, with the following syntax:
Line 622  default width is used.
Line 641  default width is used.
 .Pp  .Pp
 The  The
 .Cm head  .Cm head
 argument is used as a leading term, flushed to the left margin.  This is  argument is used as a leading term, flushed to the left margin.
 useful for bulleted paragraphs and so on.  This is useful for bulleted paragraphs and so on.
 .Pp  .Pp
 See also  See also
 .Sx \&HP ,  .Sx \&HP ,
Line 648  See also
Line 667  See also
 and  and
 .Sx \&RI .  .Sx \&RI .
 .Ss \&LP  .Ss \&LP
 Begin an undecorated paragraph.  The scope of a paragraph is closed by a  Begin an undecorated paragraph.
 subsequent paragraph, sub-section, section, or end of file.  The saved  The scope of a paragraph is closed by a subsequent paragraph,
 paragraph left-margin width is re-set to the default.  sub-section, section, or end of file.
   The saved paragraph left-margin width is re-set to the default.
 .Pp  .Pp
 See also  See also
 .Sx \&HP ,  .Sx \&HP ,
Line 725  See also
Line 745  See also
 and  and
 .Sx \&IR .  .Sx \&IR .
 .Ss \&RS  .Ss \&RS
 Begin a part setting the left margin.  The left margin controls the  Begin a part setting the left margin.
 offset, following an initial indentation, to un-indented text such as  The left margin controls the offset, following an initial indentation,
 that of  to un-indented text such as that of
 .Sx \&PP .  .Sx \&PP .
 This has the following syntax:  This has the following syntax:
 .Bd -filled -offset indent  .Bd -filled -offset indent
Line 744  If not specified, the saved or default width is used.
Line 764  If not specified, the saved or default width is used.
 Text is rendered in small size (one point smaller than the default font)  Text is rendered in small size (one point smaller than the default font)
 bold face.  bold face.
 .Ss \&SH  .Ss \&SH
 Begin a section.  The scope of a section is only closed by another  Begin a section.
 section or the end of file.  The paragraph left-margin width is re-set  The scope of a section is only closed by another section or the end of
 to the default.  file.
   The paragraph left-margin width is re-set to the default.
 .Ss \&SM  .Ss \&SM
 Text is rendered in small size (one point smaller than the default  Text is rendered in small size (one point smaller than the default
 font).  font).
 .Ss \&SS  .Ss \&SS
 Begin a sub-section.  The scope of a sub-section is closed by a  Begin a sub-section.
 subsequent sub-section, section, or end of file.  The paragraph  The scope of a sub-section is closed by a subsequent sub-section,
 left-margin width is re-set to the default.  section, or end of file.
   The paragraph left-margin width is re-set to the default.
 .Ss \&TH  .Ss \&TH
 Sets the title of the manual page with the following syntax:  Sets the title of the manual page with the following syntax:
 .Bd -filled -offset indent  .Bd -filled -offset indent
Line 766  At least the upper-case document title
Line 788  At least the upper-case document title
 .Cm title  .Cm title
 and numeric manual section  and numeric manual section
 .Cm section  .Cm section
 arguments must be provided.  The  arguments must be provided.
   The
 .Cm date  .Cm date
 argument should be formatted as described in  argument should be formatted as described in
 .Sx Dates :  .Sx Dates :
 if it does not conform, the current date is used instead.  The  if it does not conform, the current date is used instead.
   The
 .Cm source  .Cm source
 string specifies the organisation providing the utility.  The  string specifies the organisation providing the utility.
   The
 .Cm volume  .Cm volume
 string replaces the default rendered volume, which is dictated by the  string replaces the default rendered volume, which is dictated by the
 manual section.  manual section.
Line 783  Examples:
Line 808  Examples:
 .Ss \&TP  .Ss \&TP
 Begin a paragraph where the head, if exceeding the indentation width, is  Begin a paragraph where the head, if exceeding the indentation width, is
 followed by a newline; if not, the body follows on the same line after a  followed by a newline; if not, the body follows on the same line after a
 buffer to the indentation width.  Subsequent output lines are indented.  buffer to the indentation width.
   Subsequent output lines are indented.
 The syntax is as follows:  The syntax is as follows:
 .Bd -filled -offset indent  .Bd -filled -offset indent
 .Pf \. Sx \&TP  .Pf \. Sx \&TP
Line 813  and
Line 839  and
 .\" .Ss \&UC  .\" .Ss \&UC
 .\" Has no effect.  Included for compatibility.  .\" Has no effect.  Included for compatibility.
 .Ss \&br  .Ss \&br
 Breaks the current line.  Consecutive invocations have no further effect.  Breaks the current line.
   Consecutive invocations have no further effect.
 .Pp  .Pp
 See also  See also
 .Sx \&sp .  .Sx \&sp .
Line 821  See also
Line 848  See also
 End literal mode begun by  End literal mode begun by
 .Sx \&nf .  .Sx \&nf .
 .Ss \&i  .Ss \&i
 Italicise arguments.  Synonym for  Italicise arguments.
   Synonym for
 .Sx \&I .  .Sx \&I .
 .Pp  .Pp
 See also  See also
Line 835  and
Line 863  and
 Don't align to the right margin.  Don't align to the right margin.
 .Ss \&nf  .Ss \&nf
 Begin literal mode: all subsequent free-form lines have their end of  Begin literal mode: all subsequent free-form lines have their end of
 line boundaries preserved.  May be ended by  line boundaries preserved.
   May be ended by
 .Sx \&fi .  .Sx \&fi .
 .Ss \&r  .Ss \&r
 Fonts and styles (bold face, italics) reset to roman (default font).  Fonts and styles (bold face, italics) reset to roman (default font).
Line 860  spaces, which must conform to
Line 889  spaces, which must conform to
 .Sx Scaling Widths .  .Sx Scaling Widths .
 If 0, this is equivalent to the  If 0, this is equivalent to the
 .Sx \&br  .Sx \&br
 macro.  Defaults to 1, if unspecified.  macro.
   Defaults to 1, if unspecified.
 .Pp  .Pp
 See also  See also
 .Sx \&br .  .Sx \&br .
Line 888  language.
Line 918  language.
 .Bl -dash -compact  .Bl -dash -compact
 .It  .It
 In quoted literals, GNU troff allowed pair-wise double-quotes to produce  In quoted literals, GNU troff allowed pair-wise double-quotes to produce
 a standalone double-quote in formatted output.  It is not known whether  a standalone double-quote in formatted output.
 this behaviour is exhibited by other formatters.  It is not known whether this behaviour is exhibited by other formatters.
 .It  .It
 The  The
 .Sx \&sp  .Sx \&sp
 macro does not accept negative values in mandoc.  In GNU troff, this  macro does not accept negative values in mandoc.
 would result in strange behaviour.  In GNU troff, this would result in strange behaviour.
 .It  .It
 The  The
 .Sq \(aq  .Sq \(aq
Line 912  The
Line 942  The
 reference was written by  reference was written by
 .An Kristaps Dzonsons Aq kristaps@bsd.lv .  .An Kristaps Dzonsons Aq kristaps@bsd.lv .
 .Sh CAVEATS  .Sh CAVEATS
 Do not use this language.  Use  Do not use this language.
   Use
 .Xr mdoc 7 ,  .Xr mdoc 7 ,
 instead.  instead.

Legend:
Removed from v.1.67  
changed lines
  Added in v.1.68

CVSweb