[groff] 12/32: [troff]: Implement new `.nn` register

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 51f12c7f61bebe78730e561ef4786fdc32b4b687
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Nov 28 00:33:16 2022 -0600

    [troff]: Implement new `.nn` register
    
    ...to report the remaining count of lines to have their numbering
    suppressed.
    
    * src/roff/troff/env.h (class environment): Declare new member function
      `get_no_number_count()`.
    
    * src/roff/troff/env.cpp (get_no_number_count): Define new member
      function, returning value of member variable `no_number_count`.
    
      (init_env_requests): Define new ".nn" register and attach it to
      `get_no_number_count()`.
    
    * doc/groff.texi (Miscellaneous): Document it.  Include example of use
      to determine whether current output line will be numbered.  Also
      clarify meaning of register; `.nn` is not decremented except when
      output line numbering is enabled.
    
    * man/groff.7.man (Read-only registers): Document it.
    
    * src/roff/groff/tests/dot-nn_register_works.sh: Test it.
    * src/roff/groff/groff.am (groff_TESTS): Run test.
    
    * NEWS: Add item.
    
    See <https://lists.gnu.org/archive/html/groff/2022-11/msg00153.html>.
---
 ChangeLog                                     | 27 ++++++++++
 NEWS                                          | 15 +++---
 doc/groff.texi                                | 53 ++++++++++++++++--
 man/groff.7.man                               | 15 +++---
 src/roff/groff/groff.am                       |  1 +
 src/roff/groff/tests/dot-nn_register_works.sh | 77 +++++++++++++++++++++++++++
 src/roff/troff/env.cpp                        |  6 +++
 src/roff/troff/env.h                          |  1 +
 8 files changed, 180 insertions(+), 15 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index badd6d8dd..da18773c7 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,30 @@
+2022-11-28  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [troff]: Implement new `.nn` register to report the remaining
+       count of lines to have their numbering suppressed.
+
+       * src/roff/troff/env.h (class environment): Declare new member
+       function `get_no_number_count()`.
+       * src/roff/troff/env.cpp (get_no_number_count): Define new
+       member function, returning value of member variable
+       `no_number_count`.
+       (init_env_requests): Define new ".nn" register and attach it to
+       `get_no_number_count()`.
+
+       * doc/groff.texi (Miscellaneous): Document it.  Include example
+       of use to determine whether current output line will be
+       numbered.  Also clarify meaning of register; `.nn` is not
+       decremented except when output line numbering is enabled.
+       * man/groff.7.man (Read-only registers): Document it.
+
+       * src/roff/groff/tests/dot-nn_register_works.sh: Test it.
+       * src/roff/groff/groff.am (groff_TESTS): Run test.
+
+       * NEWS: Add item.
+
+       See <https://lists.gnu.org/archive/html/groff/2022-11/\
+       msg00153.html>.
+
 2022-11-27  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * tmac/fallbacks.tmac: Comment out four of the fallback
diff --git a/NEWS b/NEWS
index 356856db3..1a2c75fd6 100644
--- a/NEWS
+++ b/NEWS
@@ -22,12 +22,15 @@ o A new read-only register `.cp` is implemented.  Within a 
`do` request,
   groff_diff(7) or the groff Texinfo manual for rationale, use case, and
   example.
 
-o A new read-only register `.nm` is implemented.  It reports the
-  enablement status of output line numbering (caused by the `nm`
-  request) irrespective of the temporary suspension of numbering with
-  the `nn` request.  This register was introduced because there was no
-  way to introspect its state, tbl(1) needs to be able to do so, and the
-  writable line number register `ln` is not a reliable proxy for it.
+o New read-only registers `.nm` and `.nn` are implemented.  `.nm` is of
+  Boolean sense, reporting the enablement status of output line
+  numbering (caused by the `nm` request) irrespective of the temporary
+  suspension of numbering with the `nn` request.  `.nn` holds the count
+  of numbered output lines still to have that numbering suppressed.
+  These registers were introduced because there was no way for the
+  formatter (and thus a document) to introspect their state, tbl(1)
+  needs to be able to do so, and the writable line number register `ln`
+  is not a reliable proxy for this information.
 
 o Type size escape sequences of the form "\sNN", where NN is in the
   range 10-39, are now recognized only in compatibility mode ("groff
diff --git a/doc/groff.texi b/doc/groff.texi
index 4903ea755..9c119269d 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -15979,11 +15979,58 @@ The result is as follows.
 @endExample
 @endDefreq
 
-@Defreq {nn, [@Var{skip}]}
-Temporarily turn off line numbering.  The argument is the number of
-lines not to be numbered; this defaults to@tie{}1.
+@codequotebacktick on
+@codequoteundirected on
+
+@DefreqList {nn, [@Var{skip}]}
+@DefregListEndx {.nn}
+Suppress numbering of the next @var{skip} output lines that would
+otherwise be numbered.  The default is@tie{}1.  @code{nn} can be invoked
+when line numbering is not active; suppression of numbering will take
+effect for @var{skip} lines once @code{nm} enables it.
+
+The @code{.nn} register stores the count of output lines still to have
+their numbering suppressed.
+
+This count is associated with the environment (@pxref{Environments}).
 @endDefreq
 
+To test whether the current output line will be numbered, you must check
+both the @code{.nm} and @code{.nn} registers.
+
+@Example
+  .de is-numbered
+  .  nop This line
+  .  ie (\\n[.nm] & (1-\\n[.nn])) IS
+  .  el                           ISN'T
+  .  nop numbered.
+  .  br
+  ..
+  Test line numbering.
+  .is-numbered
+  .nm 1
+  .nn 2
+  .is-numbered
+  .is-numbered
+  .is-numbered
+  .nm
+  .is-numbered
+@endExample
+
+@noindent
+The output lines correctly report their numbering status.
+
+@Example
+  Test line numbering.  This line ISN'T numbered.
+  This line ISN'T numbered.
+  This line ISN'T numbered.
+    1 This line IS numbered.
+  This line ISN'T numbered.
+@endExample
+
+@codequotebacktick off
+@codequoteundirected off
+
 @Defreq {mc, glyph [@Var{dist}]}
 @cindex margin glyph (@code{mc})
 @cindex glyph, for margins (@code{mc})
diff --git a/man/groff.7.man b/man/groff.7.man
index 2eb836a5e..544ea2f2e 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -3413,15 +3413,16 @@ In line number mode, set number, multiple, spacing, and 
indentation.
 .
 .TPx
 .REQ .nn
-Do not number next line.
+Suppress numbering of the next line to be numbered with
+.BR nm .
 .
 .TPx
-.REQ .nn "N"
-Do not number next
-.I N
+.REQ .nn n
+Suppress numbering next
+.I n
+.BR nm -numbered
 lines.
 .
-.
 .TPx
 .REQ .nop "anything"
 Interpret
@@ -5420,13 +5421,15 @@ request that caused a trap to be sprung.
 Useful in conjunction with register
 .BR .trunc .
 .
-.
 .TPx
 .REG .nm
 1\~if output line numbering is enabled
 (even if temporarily suppressed),
 0\~otherwise.
 .
+.TPx
+.REG .nn
+The count of output lines remaining to have numbering suppressed.
 .
 .TPx
 .REG .ns
diff --git a/src/roff/groff/groff.am b/src/roff/groff/groff.am
index 874400887..8937d4ced 100644
--- a/src/roff/groff/groff.am
+++ b/src/roff/groff/groff.am
@@ -43,6 +43,7 @@ groff_TESTS = \
   src/roff/groff/tests/do_not_loop_infinitely_when_breaking_cjk.sh \
   src/roff/groff/tests/dot-cp_register_works.sh \
   src/roff/groff/tests/dot-nm_register_works.sh \
+  src/roff/groff/tests/dot-nn_register_works.sh \
   src/roff/groff/tests/evc_produces_no_output_if_invalid.sh \
   src/roff/groff/tests/fp_should_not_traverse_directories.sh \
   src/roff/groff/tests/handle_special_input_code_points.sh \
diff --git a/src/roff/groff/tests/dot-nn_register_works.sh 
b/src/roff/groff/tests/dot-nn_register_works.sh
new file mode 100755
index 000000000..0998cb05a
--- /dev/null
+++ b/src/roff/groff/tests/dot-nn_register_works.sh
@@ -0,0 +1,77 @@
+#!/bin/sh
+#
+# Copyright (C) 2022 Free Software Foundation, Inc.
+#
+# This file is part of groff.
+#
+# groff is free software; you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# groff is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+# for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+
+groff="${abs_top_builddir:-.}/test-groff"
+
+# Unit test .nn register.
+
+fail=
+
+wail () {
+  echo ...FAILED >&2
+  fail=YES
+}
+
+input='.ec @
+.de is-numbered
+.  nop This line
+.  ie (@@n[.nm] & (1-@@n[.nn])) IS
+.  el                           ISN'"'"'T
+.  nop numbered.
+.  br
+..
+Test line numbering.
+.is-numbered
+.nm 1
+.nn 2
+.is-numbered
+.is-numbered
+.is-numbered
+.nm
+.is-numbered
+.pl @n[nl]u'
+
+# Apply line numbers to the output externally for easy grepping.
+output=$(echo "$input" | $groff -Tascii | nl)
+echo "$output"
+
+echo "verifying that line 1 isn't numbered" >&2
+echo "$output" | \
+  grep -Eq "[[:space:]]+1[[:space:]]+Test line numbering\." || wail
+
+echo "verifying that line 2 isn't numbered" >&2
+echo "$output" | \
+  grep -Eq "[[:space:]]+2[[:space:]]+This line ISN'T" || wail
+
+echo "verifying that line 3 isn't numbered" >&2
+echo "$output" | \
+  grep -Eq "[[:space:]]+3[[:space:]]+This line ISN'T" || wail
+
+echo "verifying that line 4 is numbered" >&2
+echo "$output" | \
+  grep -Eq "[[:space:]]+4[[:space:]]+1 +This line IS numbered" || wail
+
+echo "verifying that line 5 isn't numbered" >&2
+echo "$output" | \
+  grep -Eq "[[:space:]]+5[[:space:]]+This line ISN'T" || wail
+
+test -z "$fail"
+
+# vim:set autoindent expandtab shiftwidth=2 tabstop=2 textwidth=72:
diff --git a/src/roff/troff/env.cpp b/src/roff/troff/env.cpp
index 71bb88581..68aafaa0c 100644
--- a/src/roff/troff/env.cpp
+++ b/src/roff/troff/env.cpp
@@ -417,6 +417,11 @@ int environment::get_right_justify_lines()
   return right_justify_lines;
 }
 
+int environment::get_no_number_count()
+{
+  return no_number_count;
+}
+
 void environment::add_italic_correction()
 {
   if (current_tab) {
@@ -3493,6 +3498,7 @@ void init_env_requests()
   init_string_env_reg(".m", get_glyph_color_string);
   init_hunits_env_reg(".n", get_prev_text_length);
   init_int_env_reg(".nm", get_numbering_nodes);
+  init_int_env_reg(".nn", get_no_number_count);
   init_int_env_reg(".ps", get_point_size);
   init_int_env_reg(".psr", get_requested_point_size);
   init_vunits_env_reg(".pvs", get_post_vertical_spacing);
diff --git a/src/roff/troff/env.h b/src/roff/troff/env.h
index c7c6e2039..f6c1d211c 100644
--- a/src/roff/troff/env.h
+++ b/src/roff/troff/env.h
@@ -311,6 +311,7 @@ public:
   hunits get_hyphenation_margin();
   int get_center_lines();
   int get_right_justify_lines();
+  int get_no_number_count();
   int get_prev_line_interrupted() { return prev_line_interrupted; }
   color *get_fill_color();
   color *get_glyph_color();