Revisions to mm list behavior

[G. Branden Robinson]

Hi folks,

The London/Reiser Unix/32V paper[1] got me taking a much closer look at
the behavior of the memorandum macro package, both in its DWB 3.3 and
groff implementations.

I found myself strongly dissatisfied with list handling.

Let me show you what I mean.  I've attached a document that uses every
predefined DWB list type (AL, BL, DL, ML, RL, VL).

(ML is a little idiosyncratic so it appears in two instances: one with
the default text indentation, and one configured to align with the
paragraph indentation.)

$ DWBHOME=. ./bin/nroff -mm ./lists.mm | col -b | cat -s

                                  - 1 -

       This is an mm document.  Sed ut perspiciatis, unde omnis xxx
       iste natus error sit voluptatem accusantium doloremque.

            This is an indented paragraph.

         1.  a1 a2 a3 a4 a5 a6 a7 a8 a9 a10 a11 a12 a13 a14 a15 a16
             a17 a18 a19 a20 a21 a22 a23 a24 a25 a26 a27 a28 a29
             a30

          o b1 b2 b3 b4 b5 b6 b7 b8 b9 b10 b11 b12 b13 b14 b15 b16
            b17 b18 b19 b20 b21 b22 b23 b24 b25 b26 b27 b28 b29 b30

          - c1 c2 c3 c4 c5 c6 c7 c8 c9 c10 c11 c12 c13 c14 c15 c16
            c17 c18 c19 c20 c21 c22 c23 c24 c25 c26 c27 c28 c29 c30

       ! d1 d2 d3 d4 d5 d6 d7 d8 d9 d10 d11 d12 d13 d14 d15 d16 d17
        d18 d19 d20 d21 d22 d23 d24 d25 d26 d27 d28 d29 d30

          @ e1 e2 e3 e4 e5 e6 e7 e8 e9 e10 e11 e12 e13 e14 e15 e16
            e17 e18 e19 e20 e21 e22 e23 e24 e25 e26 e27 e28 e29 e30

        [1]  f1 f2 f3 f4 f5 f6 f7 f8 f9 f10 f11 f12 f13 f14 f15 f16
             f17 f18 f19 f20 f21 f22 f23 f24 f25 f26 f27 f28 f29
             f30

       tag  g1 g2 g3 g4 g5 g6 g7 g8 g9 g10 g11 g12 g13 g14 g15 g16
            g17 g18 g19 g20 g21 g22 g23 g24 g25 g26 g27 g28 g29 g30

            This is another indented paragraph.  Now we will see
       how these lists handle item prefixes (inapplicable to ML and
       VL).

       * 1.  h1 h2 h3 h4 h5 h6 h7 h8 h9 h10 h11 h12 h13 h14 h15 h16
             h17 h18 h19 h20 h21 h22 h23 h24 h25 h26 h27 h28 h29
             h30

        * o i1 i2 i3 i4 i5 i6 i7 i8 i9 i10 i11 i12 i13 i14 i15 i16
            i17 i18 i19 i20 i21 i22 i23 i24 i25 i26 i27 i28 i29 i30

        * - j1 j2 j3 j4 j5 j6 j7 j8 j9 j10 j11 j12 j13 j14 j15 j16
            j17 j18 j19 j20 j21 j22 j23 j24 j25 j26 j27 j28 j29 j30

       * [1] k1 k2 k3 k4 k5 k6 k7 k8 k9 k10 k11 k12 k13 k14 k15 k16
             k17 k18 k19 k20 k21 k22 k23 k24 k25 k26 k27 k28 k29
             k30

If you look at the London/Reiser paper, you will observe that the
indentation of the text (as opposed to the mark) of the numbered lists
aligns nicely with the paragraph indentation.

This property apparently got lost in later versions of DWB.[2]  And this
isn't just a matter of getting sloppy with nroff output; the same
problems afflict typesetter output.  (See attachment.)

I thought that was a regrettable loss, so I changed it.  But I also made
other changes to make groff mm output _more_ like DWB mm's.

Here's the output of the same document using groff Git.  The document
adds supplemental material (conditioned on the `.g` register) to
illustrate groff mm extensions.

$ nroff --version | head -n 1
GNU nroff (groff) version 1.23.0.1470-18847
$ nroff -mm ./EXPERIMENTS/lists.mm | cat -s
m.tmac:./EXPERIMENTS/lists.mm:75: warning: LI: overlong mark '*\ [1]'

                                   ‐ 1 ‐

       This is an mm document.  Sed ut perspiciatis, unde omnis xxx
       iste natus error sit voluptatem accusantium doloremque.

            This is an indented paragraph.

         1. a1 a2 a3 a4 a5 a6 a7 a8 a9 a10 a11 a12 a13 a14 a15 a16
            a17 a18 a19 a20 a21 a22 a23 a24 a25 a26 a27 a28 a29 a30

          • b1 b2 b3 b4 b5 b6 b7 b8 b9 b10 b11 b12 b13 b14 b15 b16
            b17 b18 b19 b20 b21 b22 b23 b24 b25 b26 b27 b28 b29 b30

         ‐‐ c1 c2 c3 c4 c5 c6 c7 c8 c9 c10 c11 c12 c13 c14 c15 c16
            c17 c18 c19 c20 c21 c22 c23 c24 c25 c26 c27 c28 c29 c30

       ! d1 d2 d3 d4 d5 d6 d7 d8 d9 d10 d11 d12 d13 d14 d15 d16 d17
         d18 d19 d20 d21 d22 d23 d24 d25 d26 d27 d28 d29 d30

          @ e1 e2 e3 e4 e5 e6 e7 e8 e9 e10 e11 e12 e13 e14 e15 e16
            e17 e18 e19 e20 e21 e22 e23 e24 e25 e26 e27 e28 e29 e30

        [1] f1 f2 f3 f4 f5 f6 f7 f8 f9 f10 f11 f12 f13 f14 f15 f16
            f17 f18 f19 f20 f21 f22 f23 f24 f25 f26 f27 f28 f29 f30

       tag  g1 g2 g3 g4 g5 g6 g7 g8 g9 g10 g11 g12 g13 g14 g15 g16
            g17 g18 g19 g20 g21 g22 g23 g24 g25 g26 g27 g28 g29 g30

            This is another indented paragraph.  Now we will see
       how these lists handle item prefixes (inapplicable to ML and
       VL).  groff mm warns us of an overlong mark in the final
       case, prompting us to consider increasing the value of the
       Li register.

       * 1. h1 h2 h3 h4 h5 h6 h7 h8 h9 h10 h11 h12 h13 h14 h15 h16
            h17 h18 h19 h20 h21 h22 h23 h24 h25 h26 h27 h28 h29 h30

        * • i1 i2 i3 i4 i5 i6 i7 i8 i9 i10 i11 i12 i13 i14 i15 i16
            i17 i18 i19 i20 i21 i22 i23 i24 i25 i26 i27 i28 i29 i30

       * ‐‐ j1 j2 j3 j4 j5 j6 j7 j8 j9 j10 j11 j12 j13 j14 j15 j16
            j17 j18 j19 j20 j21 j22 j23 j24 j25 j26 j27 j28 j29 j30

       * [1] k1 k2 k3 k4 k5 k6 k7 k8 k9 k10 k11 k12 k13 k14 k15 k16
            k17 k18 k19 k20 k21 k22 k23 k24 k25 k26 k27 k28 k29 k30

            In groff mm, we can eliminate the padding between the
       prefix and the mark.  Thus we can make the RL reference list
       mark fit again.

        *1. l1 l2 l3 l4 l5 l6 l7 l8 l9 l10 l11 l12 l13 l14 l15 l16
            l17 l18 l19 l20 l21 l22 l23 l24 l25 l26 l27 l28 l29 l30

         *• m1 m2 m3 m4 m5 m6 m7 m8 m9 m10 m11 m12 m13 m14 m15 m16
            m17 m18 m19 m20 m21 m22 m23 m24 m25 m26 m27 m28 m29 m30

                                   ‐ 2 ‐

        *‐‐ n1 n2 n3 n4 n5 n6 n7 n8 n9 n10 n11 n12 n13 n14 n15 n16
            n17 n18 n19 n20 n21 n22 n23 n24 n25 n26 n27 n28 n29 n30

       *[1] o1 o2 o3 o4 o5 o6 o7 o8 o9 o10 o11 o12 o13 o14 o15 o16
            o17 o18 o19 o20 o21 o22 o23 o24 o25 o26 o27 o28 o29 o30

You see that we get a warning when the mark is too wide for the text
indentation.  This new diagnostic, in my opinion, mitigates the change
to the default `AL` and `RL` text indentation amounts.  A document
author can tune the indentation of lists (and paragraphs) and not have
to rely on eyeballs to detect misalignment; the package does that job.

Here are the relevant NEWS items.

o The m (mm) macro package's `Li` register now defaults to 5 ens (not 6)
  to align with the `Pi` register default.

o The m (mm) macro package's `Li` register now configures the text
  indentation of items in `RL` lists (as it long has for `AL` lists)
  instead of hard-coding a value of 6 ens as DWB 3.3 mm does.

o The m (mm) macro package's `BVL` and `VL` macros' first arguments are
  now optional.  If omitted, the paragraph indentation amount (register
  `Pi`) is used for list items' text indentations.

o The m (mm) macro package's `DL` macro now uses the `EM` string as the
  mark instead of an em dash special character literal.  (The latter
  remains the default definition of the `EM` string.)

o The m (mm) macro package's `LI` macro now interprets its second
  argument as a Boolean indicating whether a space should separate the
  list item mark from its prefix (the first argument).  Thus, where you
  formerly specified "2" to indicate no such separation, you would now
  use "0", matching the semantics of the `Limsp` register (which
  configures a default prefix/mark separation policy).  "2" continues to
  be recognized and handled as before, but prompts a warning; migrate
  your documents.

Naturally, I have constructed a unit test exercising the above behaviors
which should help us avoid unintended regressions or behavioral changes.

Finally, the groff mm extension register `Limsp` seems useless and I
plan to get rid of it, as noted in a recent commit message.

    I contemplate removing the `Limsp` register; even under old `LI`
    semantics you had to always type some kind of second argument to get
    this macro's first argument treated as a prefix.  (This aspect is a
    DWB 3.3 mm feature.  Idiomatically, one would just put "1" here as
    with numerous other mm macros, but the package would not
    consistently test for that exact value; any old non-empty string
    would do.)  Having a default prefix padding selector seems
    pointless; it saves no typing.

Any thoughts from mm users?

Regards,
Branden

[1] https://www.bell-labs.com/usr/dmr/www/otherports/32vscan.pdf

[2] My guess is that early versions of mm didn't support "mark
    prefixing",[3] and that a compromise was made here to keep the
    default text indentation the same (a) whether not a (fairly short)
    prefix was applied and (b) even if the list had more than 9 items.

[3] groff_mm(7) describes mark prefixing as follows.

     LI [mark [pad‐prefix]]
             Begin a list item.  mm collects input into a list item
             until the current list terminates or LI is called again.
             By default, the item’s text is preceded by any mark
             configured by the current list.  If only mark is specified,
             it replaces the configured mark.  If the width of the mark
             plus any padding (specified in the list’s LB call) exceeds
             the text indentation, groff mm warns and uses one en of
             padding.  A second argument prefixes mark to the configured
             mark and conditionally puts an unbreakable space between
             the prefix and mark per the argument’s Boolean value. ...

lists.mm
Description: Text Data

lists.mm.dwb.ps
Description: PostScript document

lists.mm.dwb.txt
Description: Text document

lists.mm.groff.ps
Description: PostScript document

lists.mm.groff.txt
Description: Text document

signature.asc
Description: PGP signature