internal update

3 files changed, 169 insertions, 99 deletions

diff --git a/tmac/doc-common.new b/tmac/doc-common.new
index dd1fd3c2..6813165c 100755
--- a/tmac/doc-common.new
+++ b/tmac/doc-common.new
@@ -929,7 +929,6 @@
 .  \}
 .
 .  tm doc-have-indent == \n[doc-have-indent]
-.  tm doc-have-tag-width == \n[doc-have-tag-width]
 .  tm doc-saved-Pa-font == `\*[doc-saved-Pa-font]'
 .  tm doc-curr-type == \n[doc-curr-type]
 .  tm doc-curr-arg == `\*[doc-curr-arg]'
diff --git a/tmac/groff_mdoc.reference.man b/tmac/groff_mdoc.reference.man
index a6f6b5e4..b020a99c 100755
--- a/tmac/groff_mdoc.reference.man
+++ b/tmac/groff_mdoc.reference.man
@@ -491,8 +491,7 @@ To change this, insert
 .Ql \e&
 before or after the dot:
 .
-.Pp
-.Bd -literal -offset indent -compact
+.Bd -literal -offset indent
 The
 \&.Ql .
 character.
@@ -1486,6 +1485,9 @@ produces:
 The
 .Fl std
 option is valid only for manual page sections\~2 and\~3.
+Currently, this macro does nothing if used without the
+.Fl std
+flag.
 .
 .Ss "Interactive Commands"
 .
@@ -1971,7 +1973,7 @@ The
 font mode must be ended with the
 .Ql .Ef
 macro (the latter doesn't take parameters).
-Font modes may not be nested within other font modes.
+Font modes may be nested within other font modes.
 .Pp
 .Ql .Bf
 has the following syntax:
@@ -2827,7 +2829,7 @@ It has the following syntax:
 .Bl -tag -xwidth ".Li .Bd" -offset indent
 .It Li .Bd Xo
 .Bro \-literal | \-filled | \-unfilled | \-ragged | \-centered Brc
-.Oo \-offset Ao string Ac Oc Oo \-compact Oc Xc
+.Oo \-offset Ao string Ac Oc Oo \-file Ao file name Ac Oc Oo \-compact Oc Xc
 .El
 .Pp
 .
@@ -2849,15 +2851,16 @@ and right side).
 Display block with literal font (usually fixed-width).
 Useful for source code or simple tabbed or spaced text.
 .It Fl file Ao Ar file name Ac
-The file name following the
+The file which name follows the
 .Fl file
-flag is read and displayed.
-Literal mode is asserted and tabs are set at 8\~constant width character
-intervals.
-However, any
+flag is read and displayed before any data enclosed with
+.Ql .Bd
+and
+.Ql .Ed ,
+using the selected display type.
+Any
 .Xr troff/ Ns Nm \-mdoc
 commands in the file will be processed.
-Currently, this feature is not implemented.
 .It Fl offset Ao Ar string Ac
 If
 .Fl offset
@@ -3337,53 +3340,147 @@ was produced by:
 .El
 .Pp
 .
-\#
-\#=====================================================================
-\#
 Other keywords:
 .
-.Bl -tag -xwidth ".Fl width Ar \&Fl" -offset indent
-.It Fl width Ar "\&Fl"
-sets the width to the default width for a flag.
-All callable
-macros have a default width value.
-The
-.Ql \&.Fl ,
-value is presently
-set to ten constant width characters or about five sixth of
-an inch.
-.It Fl width Ar "24n"
-sets the width to 24 constant width characters or about two
-inches.
-The
-.Ql n
-is absolutely necessary for the scaling to work correctly.
-.It Fl width Ar "ENAMETOOLONG"
-sets width to the constant width length of the
-string given.
-.It Fl width Ar "\\*qint mkfifo\\*q"
-again, the width is set to the constant width of the string
-given.
-.El
-.Pp
-If a width is not specified for the tag list type, the first
-time
-.Ql \&.It
-is invoked, an attempt is made to determine an appropriate
-width.
+.Bl -tag -xwidth ".Fl indent Ao Ar string Ac"
+.It Fl width Ao Ar string Ac
+If
+.Ao string Ac
+is a valid numeric expression
+.Pf ( Em with a scale indicator other than
+.Sq Em u ) ,
+use that value for indentation.
+The most useful scale indicators are
+.Sq m
+and
+.Sq n ,
+specifying the so-called
+.Em \&Em
+and
+.Em "En square" .
+This is approximately the width of the letter
+.Sq m
+resp.\& the letter
+.Sq n
+of the current font (for nroff output, both scale indicators give the same
+values).
+If
+.Ao string Ac
+isn't a numeric expression, it is tested whether it is an
+.Nm \-mdoc
+macro name, and the default offset value associated with this macro is used.
+Finally, if all tests fail,
+the width of
+.Ao string Ac
+(typeset with a fixed-width font) is taken as the offset.
+.Pp
+If a width is not specified for the tag list type, the first time
+.Ql .It
+is invoked, an attempt is made to determine an appropriate width.
 If the first argument to
-.Ql ".It"
-is a callable macro, the default width for that macro will be used
-as if the macro name had been supplied as the width.
-However,
-if another item in the list is given with a different callable
+.Ql .It
+is a callable macro, the default width for that macro will be used as if the
+macro name had been supplied as the width (otherwise, the default width of
+.Ql .No
+is used).
+However, if another item in the list is given with a different callable
 macro name, a new and nested list is assumed.
-This effectively
-means that
+This effectively means that
 .Fl width
-is required for the tag list type.
+or
+.Fl xwidth
+is required for more complicated tag lists.
+.It Fl xwidth Ao Ar string Ac
+Interpret
+.Ao string Ac
+and use the width of the result.
+Almost all lists in this document use this option.
+.Pp
+Example:
+.
+.Bd -literal -offset indent
+\&.Bl -tag -xwidth ".Fl test Ao Ar string Ac"
+\&.It Fl test Ao Ar string Ac
+This is a longer sentence to show how the
+\&.Fl xwidth
+flag works in combination with a tag list.
+\&.El
+.Ed
+.Pp
 .
+gives:
 .
+.Bl -tag -xwidth ".Fl test Ao Ar string Ac"
+.It Fl test Ao Ar string Ac
+This is a longer sentence to show how the
+.Fl xwidth
+flag works in combination with a tag list.
+.El
+.Pp
+.
+Note that the current state of
+.Nm \-mdoc
+is saved before
+.Ao string Ac
+is interpreted; afterwards, all variables are restored again.
+However, boxes (used for enclosures) can't be saved in
+.Tn GNU
+.Xr troff 1 ;
+as a consequence, arguments must always be
+.Em balanced
+to avoid nasty errors.
+For example, don't say
+.Ql ".Ao string"
+but
+.Ql ".Ao string Xc"
+instead if you really need only an opening angle bracket.
+.It Fl offset Ao Ar string Ac
+If
+.Ao string Ac
+is
+.Ql -indent ,
+a default indent value (normally set to\~6n, similar to the value used in
+.Ql .Dl
+or
+.Ql .Bd )
+is used.
+If
+.Ao string Ac
+is a valid numeric expression instead
+.Pf ( Em with a scale indicator other than
+.Sq Em u ) ,
+use that value for indentation.
+The most useful scale indicators are
+.Sq m
+and
+.Sq n ,
+specifying the so-called
+.Em \&Em
+and
+.Em "En square" .
+This is approximately the width of the letter
+.Sq m
+resp.\& the letter
+.Sq n
+of the current font (for nroff output, both scale indicators give the same
+values).
+If
+.Ao string Ac
+isn't a numeric expression, it is tested whether it is an
+.Nm \-mdoc
+macro name, and the default offset value associated with this macro is used.
+Finally, if all tests fail,
+the width of
+.Ao string Ac
+(typeset with a fixed-width font) is taken as the offset.
+.It Fl compact
+Suppress insertion of vertical space before the list and between list items.
+.El
+.
+.
+\#
+\#=====================================================================
+\#
 .Sh "MISCELLANEOUS MACROS"
 .
 .Bl -tag -xwidth ".Li .Bt"
@@ -3682,15 +3779,6 @@ Occasionally it
 separates the last parenthesis, and sometimes
 looks ridiculous if a line is in fill mode.
 .Pp
-If the outer-most list definition doesn't have a
-.Fl width
-argument, the
-.Ql ".It"
-elements of inner lists may not work (producing a list where
-each successive element
-.Sq walks
-to the right).
-.Pp
 The list and display macros to not do any keeps
 and certainly should be able to.
 .\" Note what happens if the parameter list overlaps a newline
diff --git a/tmac/tmac.doc.new b/tmac/tmac.doc.new
index 2f40e012..c171f8d7 100755
--- a/tmac/tmac.doc.new
+++ b/tmac/tmac.doc.new
@@ -702,22 +702,24 @@
 .  if \n[doc-arg-limit] \{\
 .    nr doc-arg-ptr +1
 .    ie (\n[doc-arg-limit] >= \n[doc-arg-ptr]) \{\
-.      ie (\n[doc-type\n[doc-arg-ptr]] == 1) \{\
+.      if (\n[doc-type\n[doc-arg-ptr]] == 1) \{\
 .        tm Usage: .\$0 \*[doc-\$0-usage] ... (#\n[.c])
 .
-.        \" the right action here would be to reset the argument counters --
-.        \" unfortunately, a small number of manual pages (less than 2%
-.        \" for FreeBSD which has been used for testing) relies on the old
-.        \" behaviour, so it is commented out
+.        \" the right action here would be to reset the argument counters
+.        \" and bail out -- unfortunately, a small number of manual pages
+.        \" (less than 2% for FreeBSD which has been used for testing)
+.        \" relied on the old behaviour (silently ignore this error),
+.        \" so it is commented out
 .
-.        \" .doc-reset-args
+.\"      doc-reset-args
 .      \}
-.      el \{\
+.\"    el \{\
 .        nr doc-curr-font \n[.f]
 .        nr doc-curr-size \n[.ps]
 .        nop \*[doc-\$0-font]\c
 .        doc-print-recursive
-.    \}\}
+.\"    \}
+.    \}
 .    el \{\
 .      tm Usage: .\$0 \*[doc-\$0-usage] ... (#\n[.c])
 .      doc-reset-args
@@ -3137,12 +3139,6 @@
 ..
 .
 .
-.\" NS doc-have-tag-width global register (bool)
-.\" NS   set if a tag width has been explicitly given
-.
-.nr doc-have-tag-width 0
-.
-.
 .\" NS doc-do-Bl-args macro
 .\" NS   resolve remaining .Bl arguments
 .\" NS
@@ -3150,7 +3146,6 @@
 .\" NS   doc-arg-ptr
 .\" NS   doc-argXXX
 .\" NS   doc-compact-list-stackXXX
-.\" NS   doc-have-tag-width
 .\" NS   doc-list-indent-stackXXX
 .\" NS   doc-list-offset-stackXXX
 .\" NS   doc-num-columns
@@ -3190,9 +3185,6 @@
 .
 .    el \{ .ie "\*[doc-arg\n[doc-arg-ptr]]"-width" \{\
 .      nr doc-arg-ptr +1
-.      \" XXX: this code should be modified to handle nested lists
-.      \"      of any type
-.      nr doc-have-tag-width 1
 .      ds doc-tag-width-stack\n[doc-list-depth] TagwidtH
 .      ds doc-str-dBla "\*[doc-arg\n[doc-arg-ptr]]
 .
@@ -3239,9 +3231,6 @@
 .
 .    el \{ .ie "\*[doc-arg\n[doc-arg-ptr]]"-xwidth" \{\
 .      nr doc-arg-ptr +1
-.      \" XXX: this code should be modified to handle nested lists
-.      \"      of any type
-.      nr doc-have-tag-width 1
 .      ds doc-tag-width-stack\n[doc-list-depth] TagwidtH
 .
 .      ds doc-str-dBla \*[doc-arg\n[doc-arg-ptr]]
@@ -3278,7 +3267,9 @@
 .          nr doc-list-offset-stack\n[doc-list-depth] \*[doc-str-dBla]
 .        el \{\
 .          doc-get-arg-width \n[doc-arg-ptr]
-.          ie (\n[doc-width] == 2) \{\
+.          ie (\n[doc-width] <= 3) \{\
+.            \" if the offset parameter is a macro, use the macro's
+.            \" width as specified in doc-common
 .            doc-get-arg-type \*[doc-str-dBla]
 .            ie (\n[doc-arg-type] == 1) \
 .              nr doc-list-offset-stack\n[doc-list-depth] \n[\*[doc-str-dBla]]
@@ -3384,7 +3375,6 @@
 .  \}
 .
 .  nr doc-have-indent-saved \n[doc-have-indent]
-.  nr doc-have-tag-width-saved \n[doc-have-tag-width]
 .  ds doc-saved-Pa-font-saved "\*[doc-saved-Pa-font]
 .  nr doc-curr-type-saved \n[doc-curr-type]
 .  ds doc-curr-arg-saved "\*[doc-curr-arg]
@@ -3524,7 +3514,6 @@
 .  \}
 .
 .  nr doc-have-indent \n[doc-have-indent-saved]
-.  nr doc-have-tag-width \n[doc-have-tag-width-saved]
 .  ds doc-saved-Pa-font "\*[doc-saved-Pa-font-saved]
 .  nr doc-curr-type \n[doc-curr-type-saved]
 .  ds doc-curr-arg "\*[doc-curr-arg-saved]
@@ -4007,7 +3996,7 @@
 .  ev
 .  box
 .
-.  if !\n[doc-have-tag-width] \
+.  if !"TagwidtH"\*[doc-tag-width-stack\n[doc-list-depth]]" \
 .    doc-get-tag-width
 .  doc-set-vertical-and-indent 1
 .  nr doc-reg-dtl (\n[doc-list-indent-stack\n[doc-list-depth]]u + \n[doc-digit-width]u)
@@ -4036,7 +4025,7 @@
 .
 .
 .\" NS doc-get-tag-width macro
-.\" NS   resolve unknown tag width (.Bl [inset | tag] only)
+.\" NS   resolve unknown tag width (`tag' list-type only)
 .\" NS
 .\" NS modifies:
 .\" NS   doc-have-indent
@@ -4048,16 +4037,13 @@
 .\" NS   doc-curr-type
 .
 .de doc-get-tag-width
-.  if !"TagwidtH"\*[doc-tag-width-stack\n[doc-list-depth]]" \{\
-.    ie (\n[doc-curr-type] == 1) \{\
-.      ds doc-tag-width-stack\n[doc-list-depth] \*[doc-curr-arg]
-.      nr doc-list-indent-stack\n[doc-list-depth] \n[\*[doc-curr-arg]]
-.    \}
-.    el \{\
-.      ds doc-tag-width-stack\n[doc-list-depth] No
-.      nr doc-list-indent-stack\n[doc-list-depth] \n[No]
-.    \}
-.    nr doc-have-tag-width 1
+.  ie (\n[doc-curr-type] == 1) \{\
+.    ds doc-tag-width-stack\n[doc-list-depth] \*[doc-curr-arg]
+.    nr doc-list-indent-stack\n[doc-list-depth] \n[\*[doc-curr-arg]]
+.  \}
+.  el \{\
+.    ds doc-tag-width-stack\n[doc-list-depth] No
+.    nr doc-list-indent-stack\n[doc-list-depth] \n[No]
 .  \}
 ..
 .
@@ -4068,7 +4054,6 @@
 .\" NS
 .\" NS modifies:
 .\" NS   doc-have-indent
-.\" NS   doc-have-tag-width
 .
 .de doc-set-vertical-and-indent
 .  ie \n[doc-have-indent] \{\
@@ -4162,8 +4147,6 @@
 .  doc-decrement-list-stack
 .  nr doc-list-depth -1
 .  doc-increment-list-stack
-.
-.  nr doc-have-tag-width 0
 ..
 .
 .