sync to bsd.lv: enable .Bl documentation

1 files changed, 109 insertions, 56 deletions

diff --git a/usr.bin/mandoc/mdoc.7 b/usr.bin/mandoc/mdoc.7
index 9f7ceb93e85..9e4c5fc5ee6 100644
--- a/usr.bin/mandoc/mdoc.7
+++ b/usr.bin/mandoc/mdoc.7
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.31 2010/05/15 18:25:50 schwarze Exp $
+.\"	$Id: mdoc.7,v 1.32 2010/05/16 02:06:50 schwarze Exp $
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
@@ -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: May 15 2010 $
+.Dd $Mdocdate: May 16 2010 $
 .Dt MDOC 7
 .Os
 .Sh NAME
@@ -1100,60 +1100,113 @@ 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 is associated with a type, which is a required argument.
+Other arguments are
+.Fl width ,
+defined per-type as accepting a literal or
+.Sx Scaling Widths
+value;
+.Fl offset ,
+also accepting a literal or
+.Sx Scaling Widths
+value setting the list's global offset; and
+.Fl compact ,
+suppressing the default vertical space printed before each list entry.
+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.
+The
+.Fl width
+argument varies the width of list bodies' left-margins.
+.It Fl column
+A columnated list.
+The
+.Fl width
+argument has no effect.
+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.
+The
+.Fl width
+argument varies the width of list bodies' left-margins.
+.It Fl diag
+Like
+.Fl inset ,
+but with additional formatting to the head.
+The
+.Fl width
+argument varies the width of list bodies' left-margins.
+.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.
+The
+.Fl width
+argument varies the width of list bodies' left-margins.
+.It Fl hang
+Like
+.Fl tag ,
+but instead of list bodies positioned after the head, they trail the
+head text.
+The
+.Fl width
+argument varies the width of list bodies' left-margins.
+.It Fl hyphen
+Synonym for
+.Fl dash .
+.It Fl inset
+List bodies follow the list head.
+The
+.Fl width
+argument is ignored.
+.It Fl item
+This produces blocks of text.
+The head of list entries must be empty.
+The
+.Fl width
+argument is ignored.
+.It Fl ohang
+List bodies are positioned on the line following the head.
+The
+.Fl width
+argument is ignored.
+.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.