[groff] 18/18: [me]: Revise `n1` and `n2` interface and behavior.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit d47ea06e3643f47b94a90555204887d5c8f0ef82
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Jan 2 21:03:39 2022 +1100

    [me]: Revise `n1` and `n2` interface and behavior.
    
    There were several bugs in the previous implementation.
    
    * tmac/e.tmac (po): Issue diagnostic if an attempt is made to set the
      page offset to a negative value.
    
      (n1): Accept new optional "C" argument to behave more (but not
      exactly) like roff(1), as the formerly-recognized "c" argument to `n2`
      did.  If present, the line length is reduced by the same amount (in
      new interface register `no`) as the line number field to preserve the
      overall line length.  Save the previous line length in the register in
      `_l` and set a flag, stored in `?N`, indicating this reduction.
      Otherwise, the macro expects to be able to reduce the page offset to
      accommodate the line number.  If it cannot (for example, with the zero
      page offset default used by nroff output devices), see above re: the
      `po` macro.
    
      (n2): Cache the last line number that may have been output, instead of
      the current one, so that we can operate it on it consistently with
      user expectations.  Do this earlier, and rename this macro-local
      variable from `_ln` to `_n` so that we don't need groff's `do` request
      to operate on it.  Drop recognition of "c" as an optional second
      argument.  If turning off line numbering: if the line length was
      shortened (`?N`) restore the saved value and delete `_l` register;
      otherwise, reverse the change to the page offset.  Delete `_n`
      register.
    
      (initialization): Assign `\w'0000'u` to `no` register; this was
      previously hard-coded in `n1` and `n2`.  Initialize `?N` with 0.
    
    * doc/meref.me.in (roff Support): Update to reflect interface changes
      and describe behavior more accurately.
    
    * doc/meref.me.in (Summary):
    * tmac/groff_me.7.in (Registers): Document new `no` register and mark it
      as a groff extension.
    
    * NEWS: Add item documenting interface changes.
    
    Fixes <https://savannah.gnu.org/bugs/?61646>.  See the comments in the
    report for a lengthy enumeration of rendering problems exhibited by the
    previous implementation.
---
 ChangeLog           | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 NEWS                |  9 +++++++++
 doc/meref.me.in     | 35 ++++++++++++++++++-----------------
 tmac/e.tmac         | 48 ++++++++++++++++++++++++++++++++++++++----------
 tmac/groff_me.7.man |  1 +
 5 files changed, 112 insertions(+), 27 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 02b00ef7..165a2a6b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,49 @@
+2022-01-02  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [me]: Revise `n1` and `n2` interface and behavior.
+
+       There were several bugs in the previous implementation.
+
+       * tmac/e.tmac (po): Issue diagnostic if an attempt is made to
+       set the page offset to a negative value.
+
+       (n1): Accept new optional "C" argument to behave more (but not
+       exactly) like roff(1), as the formerly-recognized "c" argument
+       to `n2` did.  If present, the line length is reduced by the same
+       amount (in new interface register `no`) as the line number field
+       to preserve the overall line length.  Save the previous line
+       length in the register in `_l` and set a flag, stored in `?N`,
+       indicating this reduction.  Otherwise, the macro expects to be
+       able to reduce the page offset to accommodate the line number.
+       If it cannot (for example, with the zero page offset default
+       used by nroff output devices), see above re: the `po` macro.
+
+       (n2): Cache the last line number that may have been output,
+       instead of the current one, so that we can operate it on it
+       consistently with user expectations.  Do this earlier, and
+       rename this macro-local variable from `_ln` to `_n` so that we
+       don't need groff's `do` request to operate on it.  Drop
+       recognition of "c" as an optional second argument.  If turning
+       off line numbering: if the line length was shortened (`?N`)
+       restore the saved value and delete `_l` register; otherwise,
+       reverse the change to the page offset.  Delete `_n` register.
+
+       (initialization): Assign `\w'0000'u` to `no` register; this was
+       previously hard-coded in `n1` and `n2`.  Initialize `?N` with 0.
+
+       * doc/meref.me.in (roff Support): Update to reflect interface
+       changes and describe behavior more accurately.
+
+       * doc/meref.me.in (Summary):
+       * tmac/groff_me.7.in (Registers): Document new `no` register and
+       mark it as a groff extension.
+
+       * NEWS: Add item documenting interface changes.
+
+       Fixes <https://savannah.gnu.org/bugs/?61646>.  See the comments
+       in the report for a lengthy enumeration of rendering problems
+       exhibited by the previous implementation.
+
 2022-01-02  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        [me]: Add unit test for line numbering feature.
diff --git a/NEWS b/NEWS
index 0deb1577..c71cdd65 100644
--- a/NEWS
+++ b/NEWS
@@ -224,6 +224,15 @@ o The doc (mdoc) macro package now honors the HY register 
as the an
   furthermore recognizes the `AD` string (see above) for compatibility
   with an (man), but at present ignores its value.
 
+o The e (me) macro package has changed its support for output line
+  numbering with the `n1` and `n2` macros to resolve several bugs in the
+  previous implementation.  The `n1` macro now accepts an optional `C`
+  argument to set the line number at the existing page offset instead of
+  reducing the page offset to make the line number appear in the left
+  margin.  A second argument to the `n2` macro is no longer supported.
+  A new register `no` makes configurable the amount of horizontal space
+  to be used for the line number (the default is unchanged).
+
 o The e (me) macro package now uses strings `wa` and `wc` to store the
   terms the package produces in chapter headings created by the `$c`
   macro.  The strings, which default to "Appendix" and "Chapter",
diff --git a/doc/meref.me.in b/doc/meref.me.in
index 0d1901be..5663a5c9 100644
--- a/doc/meref.me.in
+++ b/doc/meref.me.in
@@ -1293,33 +1293,33 @@ Equivalent to \(lq\fB.af % i\fP\(rq.
 Equivalent to \(lq\fB.af % 1\fP\(rq.
 .TL
 .b .n1
+.i C
 .DE
 Number output lines starting from 1.
-The line length is reduced by the width of four numerals
-and indented by the same amount
+If
+.i C
+is
+.b C ,
+the line length is reduced
+and correspondingly indented;
+otherwise,
+the page offset is reduced
 to accommodate the line number.
+The amount in all cases is
+.NR (no
+[\ew\(aq0000\(aqu
+(the width of four numerals
+in the current font)].
 .TL
 .b .n2
 .i \(+-n
-.i C
 .DE
-Stop numbering if
-.i n
-missing;
-resume where stopped if
+Stop numbering output lines if
 .i n
-unsigned,
-or with number modified by
+missing,
+otherwise continue with the number modified by
 \(+-\c
 .i n.
-If
-.i C
-is
-.b c,
-shorten the line length to accommodate numbers,
-as
-.i roff (1)
-did.
 .TL
 .b .sk
 .DE
@@ -2282,6 +2282,7 @@ and a square \(sq marks \*G extensions.
 \&.ne  M\(sc   need vertical space
 \&.nf  M\(sc   disable filling
 \&.nh  M\(sc   disable automatic hyphenation
+\en(no R\(sq   line numbering offset
 \&.np  M       begin numbered paragraph
 \&.nr  M\(sc   set register
 \&.ns  M\(sc   begin no-space mode
diff --git a/tmac/e.tmac b/tmac/e.tmac
index 1fcbd5d0..de49a6e5 100644
--- a/tmac/e.tmac
+++ b/tmac/e.tmac
@@ -32,6 +32,8 @@
 .\"    @(#)e.tmac      8.1 (Berkeley) 06/05/93
 .\"
 .\"    Modified by James Clark for use with groff.
+.\"    Further modifications by Werner Lemberg, George Helffrich, and
+.\"    G. Branden Robinson.
 .\"
 .\"**************************************************************
 .\"*                                                           *
@@ -544,6 +546,8 @@
 .
 .de po                 \" *** page offset
 .@O \\$1
+.if \\n(.o<0 \
+.      do @err page offset is negative (\\n(.ou)
 .nr _o \\n(.o
 ..
 .
@@ -582,8 +586,27 @@
 .if !'\\n(.z'' \!.@s \\$1
 ..
 .
+.\" Even with the following facilities, this package's simulation of
+.\" roff(1) line numbering features does not exhibit complete fidelity
+.\" to that program's Unix V7 behavior.  roff(1) always increased the
+.\" page offset by 5n and set a three-digit line number, leaving _two_
+.\" spaces between the number and the start of unindented text.  This
+.\" package indents by \n(no instead.  Further, roff(1) did _not_ reduce
+.\" the line length to compensate for the increase in page offset.  GBR
+.\" presumes that the document author was expected to use an `ll`
+.\" request to perform that action if desired, but has no corpus of
+.\" idiomatic, line-numbered roff(1) documents to examine.
+.\"
 .de n1                 \" *** line numbering 1
-.ll -\w'0000'u
+.ie \\n(.$ \
+.      if '\\$1'C' \
+\{\
+.              nr ?N 1
+.              nr _l \\n(.l
+.              ll -\\n(nou
+.\}
+.if !\\n(?N \
+.      po -\\n(nou
 .nr ?n 1
 .do nr _#p \\n(.s
 .do nr _#f \\n(.f
@@ -591,12 +614,9 @@
 ..
 .
 .de n2                 \" *** line numbering 2
+.nr _n \\n(ln-1\"      save last line number that may have been output
 .ie \\n(.$ \
 \{\
-.      ie !`\\$2`c` \
-.              po -\w'0000'u
-.      el \
-.              ll -\w'0000'u
 .      do ie \\B`\\$1` \
 \{\
 .              ds |i \\$1
@@ -607,12 +627,12 @@
 .              do length |l \\$1
 .              if \\n(|l>1 .do substring |j 1\"        \" for +N / -N
 .              ie `\\*(|i`+` \
-.                      do nr ln (\\n[_ln])+\\*(|j
+.                      nr ln (\\n(_n)+\\*(|j
 .\" This file's brace style doesn't permit indentation of \{. --GBR
 .              el \
 \{\
 .                      ie `\\*(|i`-` \
-.                              do nr ln (\\n[_ln])-\\*(|j
+.                              nr ln (\\n(_n)-\\*(|j
 .                      el \
 .                              nr ln \\$1      \" unsigned N
 .              \}
@@ -629,12 +649,18 @@
 .el \
 \{\
 .      nm
-.      do nr _ln \\n(ln
-.      po +\w'0000'u
-.      ll \\n($lu
+.      ie \\n(?N \
+\{\
+.              ll \\n(_lu
+.              rr _l
+.              nr ?N 0
+.\}
+.      el \
+.              po +\\n(nou
 .      nr ?n 0
 .      nr ln 0
 .\}
+.rr _n
 ..
 .
 .de pa                 \" *** new page
@@ -2008,6 +2034,7 @@
 .nr ss 12p                     \" section prespacing
 .nr si 0                       \" section indent
 .nr sx 0.2m                    \" super/subscript x-height adjustment
+.nr no \w'0000'u               \" offset for line numbers
 .
 .@R 0x\" set by GNU pic to _disable_ \x in super/scripting
 .
@@ -2091,6 +2118,7 @@
 .@R ?e\"               \" in equation?
 .@R ?H\"               \" suppress headers and footers next page?
 .@R ?I\"               \" has the header trap been sprung?
+.@R ?N\"               \" numbering with shorter line length?
 .@R ?n\"               \" n1 mode?
 .@R ?o\"               \" footnote overflow?
 .@R ?R\"               \" renumbered chapter?
diff --git a/tmac/groff_me.7.man b/tmac/groff_me.7.man
index f25e08b4..ee46462f 100644
--- a/tmac/groff_me.7.man
+++ b/tmac/groff_me.7.man
@@ -398,6 +398,7 @@ fs  footnote prespace
 fu     footnote undent (right indentation)
 hm     header margin
 ii     indented paragraph indentation
+no     line numbering offset\fB*
 pf     paragraph font
 pi     paragraph indentation
 po     page offset