===================================================================
RCS file: /cvs/mandoc/man.7,v
retrieving revision 1.23
retrieving revision 1.27
diff -u -p -r1.23 -r1.27
--- mandoc/man.7	2009/08/13 12:15:58	1.23
+++ mandoc/man.7	2009/08/18 08:48:30	1.27
@@ -1,4 +1,4 @@
-.\"	$Id: man.7,v 1.23 2009/08/13 12:15:58 kristaps Exp $
+.\"	$Id: man.7,v 1.27 2009/08/18 08:48:30 kristaps Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: August 13 2009 $
+.Dd $Mdocdate: August 18 2009 $
 .Dt MAN 7
 .Os
 .\" SECTION
@@ -238,6 +238,7 @@ invocation.
 .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 ,
@@ -262,6 +263,26 @@ and
 This section is a canonical reference to all macros, arranged
 alphabetically.  For the scoping of individual macros, see
 .Sx MACRO SYNTAX .
+.\" SUBSECTION
+.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.
+.\" SUBSECTION
+.Ss Macro Reference
 .Bl -tag -width Ds
 .It \&B
 Text is rendered in bold face.
@@ -282,21 +303,40 @@ Text is rendered alternately in bold face and roman (t
 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.
-.\" TODO.
+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
-.\" TODO.
+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.
+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
@@ -310,13 +350,15 @@ Text is rendered in small size (one point smaller than
 bold face.
 .It \&SH
 Begin a section.  The scope of a section is only closed by another
-section or the end of file.
+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.
+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
@@ -339,10 +381,23 @@ string specifies the organisation providing the utilit
 .Va volume
 replaces the default rendered volume as dictated by the manual section.
 .It \&TP
-.\" TODO.
+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.
-.\" TODO.
 .It \&fi
 End literal mode begun by
 .Sq \&nf .