Re-addition of cleaned-up list documentation in mdoc.7.

1 files changed, 69 insertions, 55 deletions

diff --git a/mdoc.7 b/mdoc.7
index f588cc12..2795a785 100644
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.102 2010/05/14 14:21:17 kristaps Exp $
+.\"	$Id: mdoc.7,v 1.103 2010/05/14 15:02:03 kristaps Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
@@ -1092,60 +1092,74 @@ and
 .Ss \&Bf
 .Ss \&Bk
 .Ss \&Bl
-.\" Begins a list composed of one or more list entries.  A list entry is
-.\" specified by the
-.\" .Sx \&It
-.\" macro, which consists of a head and optional body.  By default, a list
-.\" is preceded by a blank line.  A list must specify one of the following
-.\" list types:
-.\" .Bl -tag -width 12n
-.\" .It Fl bullet
-.\" A list offset by a bullet.  The head of list entries must be empty.
-.\" List entry bodies are justified after the bullet.
-.\" .It Fl column
-.\" A columnated list.  The number of columns is specified as arguments to
-.\" the
-.\" .Sx \&Bl
-.\" macro (the deprecated form of following the invocation of
-.\" .Fl column
-.\" is also accepted).  Arguments dictate the width of columns specified in
-.\" list entries.  List entry bodies must be left empty.  Columns specified
-.\" in the list entry head are justified to their position in the sequence
-.\" of columns.
-.\" .It Fl dash
-.\" A list offset by a dash (hyphen).  The head of list entries must be
-.\" empty.  List entry bodies are justified past the dash.
-.\" .It Fl diag
-.\" Like
-.\" .Fl inset
-.\" lists, but with additional formatting to the head.
-.\" .It Fl enum
-.\" A list offset by a number indicating list entry position.  The head of
-.\" list entries must be empty.  List entry bodies are justified past the
-.\" enumeration.
-.\" .It Fl hang
-.\" Like
-.\" .Fl tag ,
-.\" but instead of list bodies justifying to the head on the first line,
-.\" they trail the head text.
-.\" .It Fl hyphen
-.\" Synonym for
-.\" .Fl dash .
-.\" .It Fl inset
-.\" Like
-.\" .Fl tag ,
-.\" but list entry bodies aren't justified.
-.\" .It Fl item
-.\" An un-justified list.  This produces blocks of text.
-.\" .It Fl ohang
-.\" List bodies are placed on the line following the head.
-.\" .It Fl tag
-.\" A list offset by list entry heads.  List entry bodies are justified
-.\" after the head.
-.\" .El
-.\" .Pp
-.\" More...
-.\" .
+Begins a list composed of one or more list entries.
+A list entry is specified by the
+.Sx \&It
+macro, which consists of a head and optional body (depending on the list
+type).
+A list must specify one of the following list types:
+.Bl -tag -width 12n -offset indent
+.It Fl bullet
+A list offset by a bullet.
+The head of list entries must be empty.
+List entry bodies are positioned after the bullet.
+.It Fl column
+A columnated list.
+The number of columns is specified as parameters to the
+.Sx \&Bl
+macro.
+These dictate the width of columns either as
+.Sx Scaling Widths
+or literal text.
+List entry bodies must be left empty.
+Column bodies have the following syntax:
+.Pp
+.D1 .It col1 <TAB> ... coln
+.D1 .It col1 Ta ... coln
+.D1 .It col1 <TAB> col2 Ta coln
+.Pp
+where columns may be separated by tabs, the literal string
+.Qq Ta ,
+or a mixture of both.
+These are equivalent except that quoted sections propogate over tabs,
+for example,
+.Pp
+.D1 .It \(dqcol1 ; <TAB> col2 ;\(dq ;
+.Pp
+will preserve the semicolon whitespace except for the last.
+.It Fl dash
+A list offset by a dash (hyphen).
+The head of list entries must be empty.
+List entry bodies are positioned past the dash.
+.It Fl diag
+Like
+.Fl inset ,
+but with additional formatting to the head.
+.It Fl enum
+An enumerated list offset by the enumeration from 1.
+The head of list entries must be empty.
+List entry bodies are positioned after the enumeration.
+.It Fl hang
+Like
+.Fl tag ,
+but instead of list bodies positioned after the head, they trail the
+head text.
+.It Fl hyphen
+Synonym for
+.Fl dash .
+.It Fl inset
+List bodies follow the list head.
+.It Fl item
+This produces blocks of text.
+The head of list entries must be empty.
+.It Fl ohang
+List bodies are positioned on the line following the head.
+.It Fl tag
+A list offset by list entry heads.  List entry bodies are positioned
+after the head as specified by the
+.Fl width
+argument.
+.El
 .Ss \&Bo
 Begins a block enclosed by square brackets.
 Does not have any head arguments.