Description of Bl ... -width

["Anthony J. Bentley" <anthony@cathet.us>]

Hi,

I've spent a long time blindly typing ".Bl -tag -width Ds" without
understanding what it meant. In the back of my mind I just assumed Ds
triggered an indent of two characters, never noticing that the indent
in the result is obviously not two characters.

This is what mdoc(7) says about the -width argument to Bl:

     The -width and -offset arguments accept scaling widths as
     described in roff(7) or use the length of the given string.

In reality:

        /*
         * Calculate the real width of a list from the -width string,
         * which may contain a macro (with a known default width), a
         * literal string, or a scaling width.
         *
         * If the value to -width is a macro, then we re-write it to be
         * the macro's width as set in share/tmac/mdoc/doc-common.
         */

The macro part is documented in mdoc(7), but only under Bd's -offset:

           -offset width  Indent the display by the width, which may be one of
                          the following:
                          ...
                          A macro invocation, which selects a predefined width
                          associated with that macro.  The most popular is the
                          imaginary macro Ds, which resolves to 6n.
                          ...

It looks like Bl's -offset matches the manual and doesn't support
determining macro widths. So that leaves just Bl's -width that is
documented wrong. Here is an attempt to fix it--does this make sense?
But I'm not sure the paragraph flows very well now.

Index: mdoc.7
===================================================================
RCS file: /cvs/src/share/man/man7/mdoc.7,v
retrieving revision 1.120
diff -u -p -u -p -r1.120 mdoc.7
--- mdoc.7	12 Oct 2014 02:59:04 -0000	1.120
+++ mdoc.7	29 Oct 2014 03:27:35 -0000
@@ -940,6 +940,14 @@ and
 arguments accept scaling widths as described in
 .Xr roff 7
 or use the length of the given string.
+In addition, the argument to
+.Fl width
+may be a macro invocation, in which case a predefined width associated with
+that macro is chosen.
+The most popular is the imaginary macro
+.Ar \&Ds ,
+which resolves to the scaling width
+.Sy 6n .
 The
 .Fl offset
 is a global indentation for the whole list, affecting both item heads

--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv