===================================================================
RCS file: /cvsrepo/anoncvs/cvs/src/usr.bin/mandoc/Attic/man.7,v
retrieving revision 1.8
retrieving revision 1.9
diff -c -r1.8 -r1.9
*** src/usr.bin/mandoc/Attic/man.7	2009/08/22 16:41:45	1.8
--- src/usr.bin/mandoc/Attic/man.7	2009/08/22 20:14:37	1.9
***************
*** 1,4 ****
! .\"	$Id: man.7,v 1.8 2009/08/22 16:41:45 schwarze Exp $
  .\"
  .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
  .\"
--- 1,4 ----
! .\"	$Id: man.7,v 1.9 2009/08/22 20:14:37 schwarze Exp $
  .\"
  .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
  .\"
***************
*** 17,244 ****
  .Dd $Mdocdate: August 22 2009 $
  .Dt MAN 7
  .Os
! .\" SECTION
  .Sh NAME
! .Nm man
! .Nd man language reference
! .\" SECTION
  .Sh DESCRIPTION
  The
! .Nm man
  language was historically used to format
! .Ux
  manuals.  This reference document describes its syntax, structure, and
  usage.
! .Pp
! .Bf -emphasis
  Do not use
! .Nm
  to write your manuals.
! .Ef
  Use the
! .Xr mdoc 7
  language, instead.
! .\" PARAGRAPH
! .Pp
  An
! .Nm
  document follows simple rules:  lines beginning with the control
  character
! .Sq \&.
  are parsed for macros.  Other lines are interpreted within the scope of
  prior macros:
! .Bd -literal -offset indent
  \&.SH Macro lines change control state.
  Other lines are interpreted within the current state.
! .Ed
! .\" SECTION
  .Sh INPUT ENCODING
! .Nm
  documents may contain only graphable 7-bit ASCII characters, the
  space character, and the tabs character.  All manuals must have
! .Ux
  line termination.
! .Pp
  Blank lines are acceptable; where found, the output will assert a
  vertical space.
! .Pp
  The
! .Sq \ec
  escape is common in historical
! .Nm
  documents; if encountered at the end of a word, it ensures that the
  subsequent word isn't off-set by whitespace.
! .\" SUB-SECTION
! .Ss Comments
  Text following a
! .Sq \e" ,
  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,
! .Sq \&.\e" ,
! is also ignored.
! .\" SUB-SECTION
! .Ss Special Characters
  Special characters may occur in both macro and free-form lines.
  Sequences begin with the escape character
! .Sq \e
  followed by either an open-parenthesis
! .Sq \&(
  for two-character sequences; an open-bracket
! .Sq \&[
  for n-character sequences (terminated at a close-bracket
! .Sq \&] ) ;
  or a single one-character sequence.  See
! .Xr mandoc_char 7
  for a complete list.  Examples include
! .Sq \e(em
! .Pq em-dash
  and
! .Sq \ee
! .Pq back-slash .
! .\" SUB-SECTION----------------------
! .Ss Text Decoration
  Terms may be text-decorated using the
! .Sq \ef
  escape followed by an indicator: B (bold), I, (italic), or P and R
  (Roman, or reset).
! .\" SUB-SECTION----------------------
! .Ss Whitespace
  Unless specifically escaped, consecutive blocks of whitespace are pruned
  from input.  These are later re-added, if applicable, by a front-end
  utility such as
! .Xr mandoc 1 .
! .\" SECTION
! .Sh STRUCTURE
  Each
! .Nm
  document must contain contains at least the
! .Sq \&.TH
  macro describing the document's section and title.  It may occur
  anywhere in the document, although conventionally, it appears as the
  first macro.
! .Pp
! Beyond the
! .Sq \&.TH ,
! at least one macro or text node must appear in the document.
! .\" SECTION
! .Sh SYNTAX
  Macros are one to three three characters in length and begin with a
  control character ,
! .Sq \&. ,
  at the beginning of the line.  An arbitrary amount of whitespace may
  sit between the control character and the macro name.  Thus,
! .Sq \&.PP
  and
! .Sq \&.\ \ \ \&PP
  are equivalent.
! .Pp
! All
! .Nm
! macros follow the same structural rules:
! .Bd -literal -offset indent
! \&.YO \(lBbody...\(rB
! .Ed
! .Pp
  The
! .Dq body
! consists of zero or more arguments to the macro.
! .Pp
! .Nm
! has a primitive notion of multi-line scope for the following macros:
! .Sq \&.TM ,
! .Sq \&.SM ,
! .Sq \&.SB ,
! .Sq \&.BI ,
! .Sq \&.IB ,
! .Sq \&.BR ,
! .Sq \&.RB ,
! .Sq \&.R ,
! .Sq \&.B ,
! .Sq \&.I ,
! .Sq \&.IR
! and
! .Sq \&.RI .
! When these macros are invoked without arguments, the subsequent line is
! considered a continuation of the macro.  Thus:
! .Bd -literal -offset indent
  \&.RI
  foo
! .Ed
! .Pp
  is equivalent to
! .Sq \&.RI foo .
! If two consecutive lines exhibit the latter behaviour,
! an error is raised.  Thus, the following is not acceptable:
! .Bd -literal -offset indent
! \&.RI
! \&.I
! Hello, world.
! .Ed
! .Pp
  The
! .Sq \&.TP
! macro is similar, but does not need an empty argument line to trigger
! the behaviour.
! .\" SECTION
! .Sh MACROS
! This section contains a complete list of all
! .Nm
! macros and corresponding number of arguments.
! .Pp
! .Bl -column "MacroX" "Arguments" -compact -offset indent
! .It Em Macro Ta Em Arguments
! .It \&.TH    Ta    >1, <6
! .It \&.SH    Ta    >0
! .It \&.SS    Ta    >0
! .It \&.TP    Ta    n
! .It \&.LP    Ta    0
! .It \&.PP    Ta    0
! .It \&.P     Ta    0
! .It \&.IP    Ta    <3
! .It \&.HP    Ta    <2
! .It \&.SM    Ta    n
! .It \&.SB    Ta    n
! .It \&.BI    Ta    n
! .It \&.IB    Ta    n
! .It \&.BR    Ta    n
! .It \&.RB    Ta    n
! .It \&.R     Ta    n
! .It \&.B     Ta    n
! .It \&.I     Ta    n
! .It \&.IR    Ta    n
! .It \&.RI    Ta    n
! .El
! .Pp
! Although not historically part of the
! .Nm
! system, the following macros are also supported:
! .Pp
! .Bl -column "MacroX" "Arguments" -compact -offset indent
! .It Em Macro Ta Em Arguments
! .It \&.br    Ta    0
! .It \&.i     Ta    n
! .El
! .Pp
! These follow the same calling conventions as the above
! .Nm
! macros.
! .\" SECTION
  .Sh COMPATIBILITY
! See
! .Xr mdoc 7
! for groff compatibility notes.
! .\" SECTION
  .Sh SEE ALSO
! .Xr mandoc 1 ,
! .Xr mandoc_char 7
! .\" SECTION
  .Sh AUTHORS
  The
! .Nm
! utility was written by
! .An Kristaps Dzonsons Aq kristaps@kth.se .
! .\" SECTION
  .Sh CAVEATS
  Do not use this language.  Use
! .Xr mdoc 7 ,
  instead.
--- 17,467 ----
  .Dd $Mdocdate: August 22 2009 $
  .Dt MAN 7
  .Os
! .
! .
  .Sh NAME
! . Nm man
! . Nd man language reference
! .
! .
  .Sh DESCRIPTION
  The
! . Nm man
  language was historically used to format
! . Ux
  manuals.  This reference document describes its syntax, structure, and
  usage.
! . Pp
! . Bf -emphasis
  Do not use
! .  Nm
  to write your manuals.
! . Ef
  Use the
! . Xr mdoc 7
  language, instead.
! . Pp
  An
! . Nm
  document follows simple rules:  lines beginning with the control
  character
! . Sq \&.
  are parsed for macros.  Other lines are interpreted within the scope of
  prior macros:
! . Bd -literal -offset indent
  \&.SH Macro lines change control state.
  Other lines are interpreted within the current state.
! . Ed
! .
! .
  .Sh INPUT ENCODING
! . Nm
  documents may contain only graphable 7-bit ASCII characters, the
  space character, and the tabs character.  All manuals must have
! . Ux
  line termination.
! . Pp
  Blank lines are acceptable; where found, the output will assert a
  vertical space.
! . Pp
  The
! . Sq \ec
  escape is common in historical
! . Nm
  documents; if encountered at the end of a word, it ensures that the
  subsequent word isn't off-set by whitespace.
! .
! .
! . Ss Comments
  Text following a
! .  Sq \e\*" ,
  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,
! .  Sq \&.\e" ,
! is also ignored.  Macro lines with only a control charater and
! optionally whitespace are stripped from input.
! .
! .
! . Ss Special Characters
  Special characters may occur in both macro and free-form lines.
  Sequences begin with the escape character
! .  Sq \e
  followed by either an open-parenthesis
! .  Sq \&(
  for two-character sequences; an open-bracket
! .  Sq \&[
  for n-character sequences (terminated at a close-bracket
! .  Sq \&] ) ;
  or a single one-character sequence.  See
! .  Xr mandoc_char 7
  for a complete list.  Examples include
! .  Sq \e(em
! .  Pq em-dash
  and
! .  Sq \ee
! .  Pq back-slash .
! .
! .
! . Ss Text Decoration
  Terms may be text-decorated using the
! .  Sq \ef
  escape followed by an indicator: B (bold), I, (italic), or P and R
  (Roman, or reset).
! .
! .
! . Ss Whitespace
  Unless specifically escaped, consecutive blocks of whitespace are pruned
  from input.  These are later re-added, if applicable, by a front-end
  utility such as
! .  Xr mandoc 1 .
! .
! .
! .Sh MANUAL STRUCTURE
  Each
! . Nm
  document must contain contains at least the
! . Sq \&TH
  macro describing the document's section and title.  It may occur
  anywhere in the document, although conventionally, it appears as the
  first macro.
! . Pp
! Beyond
! . Sq \&TH ,
! at least one macro or text node must appear in the document.  Documents
! are generally structured as follows:
! . Bd -literal -offset indent
! \&.TH FOO 1 "13 Aug 2009"
! \&.
! \&.SH NAME
! foo \e- a description goes here
! \&.
! \&.SH SYNOPSIS
! \efBfoo\efR [\efB\e-options\efR] arguments...
! \&.
! \&.SH DESCRIPTION
! The \efBfoo\efR utility does...
! \&.
! \&.\e\*q .SH RETURN VALUES
! \&.\e\*q .SH ENVIRONMENT
! \&.\e\*q .SH FILES
! \&.\e\*q .SH EXAMPLES
! \&.\e\*q .SH DIAGNOSTICS
! \&.\e\*q .SH ERRORS
! \&.\e\*q .SH SEE ALSO
! \&.\e\*q \efBbar\efR(1)
! \&.\e\*q .SH STANDARDS
! \&.\e\*q .SH HISTORY
! \&.\e\*q .SH AUTHORS
! \&.\e\*q .SH CAVEATS
! \&.\e\*q .SH BUGS
! . Ed
! .
! .
! .Sh MACRO SYNTAX
  Macros are one to three three characters in length and begin with a
  control character ,
! . Sq \&. ,
  at the beginning of the line.  An arbitrary amount of whitespace may
  sit between the control character and the macro name.  Thus,
! . Sq \&.PP
  and
! . Sq \&.\ \ \ \&PP
  are equivalent.
! . Pp
  The
! . Nm
! macros are classified by scope: line scope or block scope.  Line-scoped
! macros are only scoped to the current line (and, in some situations,
! the subsequent line).  Block macros are scoped to the current line and
! subsequent lines until closed by another block macro.
! .
! .
! . Ss Line Macros
! Line-macros are scoped to the current line, with the body consisting of
! zero or more arguments.  If a macro is next-line scoped and the line
! arguments are empty, the next line is used instead.  Thus:
! .  Bd -literal -offset indent
  \&.RI
  foo
! .  Ed
! .  Pp
  is equivalent to
! .  Sq \&.RI foo .
! .\" PARAGRAPH
! Consecutive next-line invocations are disallowed.
! .  Bd -literal -offset indent
! \&.YO \(lBbody...\(rB
! \(lBbody...\(rB
! .  Ed
! .  Pp
! .  Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX"
! .   It Em Macro Ta Em Arguments Ta Em Scope
! .   It  \&B     Ta    n         Ta    next-line
! .   It  \&BI    Ta    n         Ta    current
! .   It  \&BR    Ta    n         Ta    current
! .   It  \&I     Ta    n         Ta    next-line
! .   It  \&IB    Ta    n         Ta    current
! .   It  \&IR    Ta    n         Ta    current
! .   It  \&R     Ta    n         Ta    next-line
! .   It  \&RB    Ta    n         Ta    current
! .   It  \&RI    Ta    n         Ta    current
! .   It  \&SB    Ta    n         Ta    next-line
! .   It  \&SM    Ta    n         Ta    next-line
! .   It  \&TH    Ta    >1, <6    Ta    current
! .   It  \&br    Ta    0         Ta    current
! .   It  \&fi    Ta    0         Ta    current
! .   It  \&i     Ta    n         Ta    current
! .   It  \&na    Ta    0         Ta    current
! .   It  \&nf    Ta    0         Ta    current
! .   It  \&r     Ta    0         Ta    current
! .   It  \&sp    Ta    1         Ta    current
! .  El
! .  Pp
! The lower-case 
! .  Sq \&br ,
! .  Sq \&fi ,
! .  Sq \&i ,
! .  Sq \&na ,
! .  Sq \&nf ,
! .  Sq \&r ,
! and
! .  Sq \&sp
! macros aren't historically part of
! .  Nm
! and should not be used.  They're included for compatibility.
! .
! .
! . Ss Block Macros
! Block macros are comprised of a head and body.  The head is scoped to
! the current line and, in one circumstance, the next line; the body is
! scoped to subsequent lines and is closed out by a subsequent block macro
! invocation.
! .  Bd -literal -offset indent
! \&.YO \(lBhead...\(rB
! \(lBhead...\(rB
! \(lBbody...\(rB
! .  Ed
! .  Pp
! If a block macro is next-line scoped, it may only be followed by in-line
! macros (excluding
! .  Sq br ,
! .  Sq na ,
! .  Sq sp ,
! .  Sq nf ,
! .  Sq fi ,
! and
! .  Sq TH ) .
! .  Pp
! .  Bl -column "MacroX" "Arguments" "ScopeXXXX" -compact -offset indent
! .   It Em Macro Ta Em Arguments Ta Em Scope
! .   It \&HP     Ta    <2        Ta    current
! .   It \&IP     Ta    <3        Ta    current
! .   It \&LP     Ta    0         Ta    current
! .   It \&P      Ta    0         Ta    current
! .   It \&PP     Ta    0         Ta    current
! .   It \&SH     Ta    >0        Ta    current
! .   It \&SS     Ta    >0        Ta    current
! .   It \&TP     Ta    n         Ta    next-line
! .  El
! .
! .
! .Sh REFERENCE
! This section is a canonical reference to all macros, arranged
! alphabetically.  For the scoping of individual macros, see
! . Sx MACRO SYNTAX .
! .
! .
! . Ss Terms
! In this reference, a numerical width may be either a standalone natural
! number (such as 3, 4, 10, etc.) or a natural number followed by a width
! multiplier 
! .  Qq n ,
! corresponding to the width of the formatted letter n, or
! .  Qq m ,
! corresponding to the width of the formatted letter m.  The latter is the
! default, if unspecified.  Thus,
! .  Bd -literal -offset indent
! \&.HP 12n
! .  Ed
! .  Pp
! indicates an offset of 12 
! .  Qq n
! .  Ns -sized
! letters.
! .
! .
! . Ss Macro Reference
! .  Bl -tag -width Ds
! .   It \&B
! Text is rendered in bold face.
! .   It \&BI
! Text is rendered alternately in bold face and italic.  Thus, 
! .    Sq \&.BI this word and that
! causes
! .    Sq this
! and
! .    Sq and
! to render in bold face, while 
! .    Sq word
! and
! .    Sq that
! render in italics.  Whitespace between arguments is omitted in output.
! .   It \&BR
! Text is rendered alternately in bold face and roman (the default font).
! Whitespace between arguments is omitted in output.
! .   It \&HP
! Begin a paragraph whose initial output line is left-justified, but
! subsequent output lines are indented, with the following syntax:
! .    Bd -literal -offset indent
! \&.HP [width]
! .    Ed
! .    Pp
! If 
! .    Va width
! is specified, it's saved for later paragraph left-margins; if
! unspecified, the saved or default width is used.
! .   It \&I
! Text is rendered in italics.
! .   It \&IB
! Text is rendered alternately in italics and bold face.  Whitespace
! between arguments is omitted in output.
! .   It \&IP
! Begin a paragraph with the following syntax:
! .    Bd -literal -offset indent
! \&.IP [head [width]]
! .    Ed
! .    Pp
! This follows the behaviour of the
! .    Sq \&TP
! except for the macro syntax (all arguments on the line, instead of
! having next-line scope).  If
! .    Va width
! is specified, it's saved for later paragraph left-margins; if
! unspecified, the saved or default width is used.
! .   It \&IR
! Text is rendered alternately in italics and roman (the default font).
! Whitespace between arguments is omitted in output.
! .   It \&LP, \&P, \&PP
! Begin an undecorated paragraph.  The scope of a paragraph is closed by a
! subsequent paragraph, sub-section, section, or end of file.  The saved
! paragraph left-margin width is re-set to the default.
! .   It \&R
! Text is rendered in roman (the default font).
! .   It \&RB
! Text is rendered alternately in roman (the default font) and bold face.
! Whitespace between arguments is omitted in output.
! .   It \&RI
! Text is rendered alternately in roman (the default font) and italics.
! Whitespace between arguments is omitted in output.
! .   It \&SB
! Text is rendered in small size (one point smaller than the default font)
! bold face.
! .   It \&SH
! Begin a section.  The scope of a section is only closed by another
! section or the end of file.  The paragraph left-margin width is re-set
! to the default.
! .   It \&SM
! Text is rendered in small size (one point smaller than the default
! font).
! .   It \&SS
! Begin a sub-section.  The scope of a sub-section is closed by a
! subsequent sub-section, section, or end of file.  The paragraph
! left-margin width is re-set to the default.
! .   It \&TH
! Sets the title of the manual page with the following syntax:
! .    Bd -literal -offset indent
! \&.TH title section date source volume
! .    Ed
! .    Pp
! At least the 
! .    Va title
! and
! .    Va section
! arguments must be provided.  The
! .    Va date
! argument should be formatted as
! .    Qq %b [%d] %Y
! format, described in
! .    Xr strptime 3 .
  The
! .    Va source
! string specifies the organisation providing the utility.  The
! .    Va volume
! replaces the default rendered volume as dictated by the manual section.
! .   It \&TP
! 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
! buffer to the indentation width.  Subsequent output lines are indented.
! .    Pp
! The indentation width may be set as follows:
! .    Bd -literal -offset indent
! \&.TP [width]
! .    Ed
! .    Pp
! Where
! .    Va width
! must be a properly-formed numeric width.  If
! .    Va width
! is specified, it's saved for later paragraph left-margins; if
! unspecified, the saved or default width is used.
! .   It \&br
! Breaks the current line.  Consecutive invocations have no further effect.
! .   It \&fi
! End literal mode begun by
! .    Sq \&nf .
! .   It \&i
! Italicise arguments.  If no arguments are specified, all subsequent text
! is italicised.
! .   It \&na
! No alignment to the right margin.
! .   It \&nf
! Begin literal mode: all subsequent free-form lines have their end of
! line boundaries preserved.  May be ended by
! .    Sq \&fi .
! .   It \&r
! Fonts and styles (bold face, italics) reset to roman (default font).
! .   It \&sp
! Insert n spaces, where n is the macro's positive numeric argument.  If
! 0, this is equivalent to the
! .    Sq br
! macro.
! .  El
! .
! .
  .Sh COMPATIBILITY
! This section documents compatibility with other roff implementations, at
! this time limited to
! . Xr groff 1 .
! . Bl -hyphen
! .  It
! In quoted literals, groff allowed pair-wise double-quotes to produce a
! standalone double-quote in formatted output.  This idiosyncratic
! behaviour is no longer applicable.
! .  It
! The
! .   Sq \&sp
! macro does not accept negative numbers.
! .  It
! Blocks of whitespace are stripped from both macro and free-form text
! lines (except when in literal mode), while groff would retain whitespace
! in free-form text lines.
! . El
! .
! .
  .Sh SEE ALSO
! . Xr mandoc 1 ,
! . Xr mandoc_char 7
! .
! .
  .Sh AUTHORS
  The
! . Nm
! reference was written by
! . An Kristaps Dzonsons Aq kristaps@kth.se .
! .
! .
  .Sh CAVEATS
  Do not use this language.  Use
! . Xr mdoc 7 ,
  instead.
+ .