Complete, rigorous documentation of the `Bl' and `It' macros, including

the peculiarities with `It'-less `Bl -column' invocations, column
phrases, per-type syntax of `It', etc.

diff --git a/mdoc.7 b/mdoc.7
index 184ccf737fcdbabe32a091c02ff00f026923c6e6..a74704f6d8d2ded9cf03ef09ee741da614ea2998 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"    $Id: mdoc.7,v 1.113 2010/06/02 12:01:00 kristaps Exp $
+.\"    $Id: mdoc.7,v 1.114 2010/06/03 14:29:52 kristaps Exp $

 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
 .\"
 .\" 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.
 .\"
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"

-.Dd $Mdocdate: June 2 2010 $
+.Dd $Mdocdate: June 3 2010 $

 .Dt MDOC 7
 .Os
 .Sh NAME
 .Dt MDOC 7
 .Os
 .Sh NAME


@@ -1136,22 +1136,18 @@ macro.
 These dictate the width of columns either as
 .Sx Scaling Widths
 or literal text.
 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.
+If the initial macro of a
+.Fl column
+list is not an
+.Sx \&It ,
+an
+.Sx \&It
+context spanning each line is implied until an
+.Sx \&It
+line macro is encountered, at which point list bodies are interpreted as
+described in the
+.Sx \&It
+documentation.

 .It Fl dash
 A list offset by a dash (hyphen).
 The head of list entries must be empty.
 .It Fl dash
 A list offset by a dash (hyphen).
 The head of list entries must be empty.


@@ -1206,6 +1202,9 @@ after the head as specified by the
 .Fl width
 argument.
 .El
 .Fl width
 argument.
 .El

+.Pp
+See also
+.Sx \&It .

 .Ss \&Bo
 Begins a block enclosed by square brackets.
 Does not have any head arguments.
 .Ss \&Bo
 Begins a block enclosed by square brackets.
 Does not have any head arguments.


@@ -1644,6 +1643,86 @@ and
 .Ss \&Ic
 .Ss \&In
 .Ss \&It
 .Ss \&Ic
 .Ss \&In
 .Ss \&It

+A list item.  The syntax of this macro depends on the list type.
+.Pp
+Lists
+of type
+.Fl hang ,
+.Fl ohang ,
+.Fl inset ,
+and
+.Fl diag
+have the following calling syntax:
+.Pp
+.D1 \. Ns Sx \&It Cm args
+.Pp
+Lists of type
+.Fl bullet ,
+.Fl dash ,
+.Fl enum ,
+.Fl hyphen
+and
+.Fl item
+have the following calling syntax:
+.Pp
+.D1 \. Ns Sx \&It
+.Pp
+with subsequent lines interpreted within the scope of the
+.Sx \&It
+until either a closing
+.Sx \&El
+or another
+.Sx \&It .
+.Pp
+The
+.Fl tag
+list has syntax
+.Pp
+.D1 \. Ns Sx \&It Op Cm args
+.Pp
+with subsequent lines interpreted as with
+.Fl bullet
+and family.
+The line arguments correspond to the list's left-hand side; body
+arguments correspond to the list's contents.
+.Pp
+The
+.Fl column
+list is the most complicated.
+Its syntax is
+.Pp
+.D1 \. Ns Sx \&It Op Cm args
+.Pp
+where
+.Cm args
+are phrases, a mix of macros and text corresponding to a line column,
+delimited by tabs or the special
+.Sq \&Ta
+pseudo-macro.
+Lines subsequent the
+.Sx \&It
+are interpreted within the scope of the last phrase.
+Calling the pseudo-macro
+.Sq \&Ta
+will open a new phrase scope (this must occur on a macro line to be
+interpreted as a macro).  Note that the tab phrase delimiter may only be
+used within the
+.Sx \&It
+line itself.
+Subsequent this, only the
+.Sq \&Ta
+pseudo-macro may be used to delimit phrases.
+Furthermore, note that quoted sections propogate over tab-delimited
+phrases on an
+.Sx \&It ,
+for example,
+.Pp
+.D1 .It \(dqcol1 ; <TAB> col2 ;\(dq ;
+.Pp
+will preserve the semicolon whitespace except for the last.
+.Pp
+See also
+.Sx \&Bl .

 .Ss \&Lb
 Specify a library.
 The calling syntax is as follows:
 .Ss \&Lb
 Specify a library.
 The calling syntax is as follows: