[groff] 29/40: [man, mdoc]: Fix Savannah #63500.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 478494e32112aabaa04f8314b5305c7bf6ea1689
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Dec 12 10:31:19 2022 -0600

    [man, mdoc]: Fix Savannah #63500.
    
    Support use of `P` (initial page number) register when batch rendering,
    regardless of switching macro packages between man(7) and mdoc(7) or
    setting of `C` (continuous numbering) register.  (`P` without `C` means
    "start numbering each rendered document at \n[P]".)
    
    * tmac/an.tmac (an-end): Call `an*break-page-with-new-number` instead of
      invoking `bp`.
    
      (an*break-page-with-new-number): If `P` is set and `C` is not, use
      value of `P` as the next page number.
    
      (TH): If `C` register is set, remove `P` register after ending a
      previous document.
    
      (initialization): If `P` is set, assign the page number using the `pn`
      request if the transition to the first formatted page has not yet
      occurred; otherwise update page number register `%` directly.  Also
      ignore it with diagnostic if `ps4html` register (for grohtml's
      internal use) is set.   Add explanatory comment.
    
    * tmac/mdoc/doc-common (Dd): If `C` register is set, remove `P` register
      after ending a previous document.
    
      (doc-end-macro): Call `doc-break-page-with-new-number` instead of
      invoking `bp`.
    
      (doc-break-page-with-new-number): If `P` is set and `C` is not, use
      value of `P` as the next page number.
    
    * tmac/doc.tmac (initialization): If `P` is set, assign the page number
      using the `pn` request if the transition to the first formatted page
      has not yet occurred; otherwise update page number register `%`
      directly.  Also ignore it with diagnostic if `ps4html` register (for
      grohtml's internal use) is set.  Add explanatory comment.
    
    Fixes <https://savannah.gnu.org/bugs/?63500>.
---
 ChangeLog            | 35 +++++++++++++++++++++++++++++++++++
 tmac/an.tmac         | 39 ++++++++++++++++++++++++++++++++++-----
 tmac/doc.tmac        | 27 ++++++++++++++++++++++++---
 tmac/mdoc/doc-common | 13 +++++++++++--
 4 files changed, 104 insertions(+), 10 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 11ff26ef9..422b81a52 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,38 @@
+2022-12-12  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [man, mdoc]: Fix Savannah #63500.  Support use of `P` (initial
+       page number) register when batch rendering, regardless of
+       switching macro packages between man(7) and mdoc(7) or setting
+       of `C` (continuous numbering) register.  (`P` without `C` means
+       "start numbering each rendered document at \n[P]".)
+
+       * tmac/an.tmac (an-end): Call `an*break-page-with-new-number`
+       instead of invoking `bp`.
+       (an*break-page-with-new-number): If `P` is set and `C` is not,
+       use value of `P` as the next page number.
+       (TH): If `C` register is set, remove `P` register after ending a
+       previous document.
+       (initialization): If `P` is set, assign the page number using
+       the `pn` request if the transition to the first formatted page
+       has not yet occurred; otherwise update page number register `%`
+       directly.  Also ignore it with diagnostic if `ps4html` register
+       {for grohtml's internal use} is set.  Add explanatory comment.
+
+       * tmac/mdoc/doc-common (Dd): If `C` register is set, remove `P`
+       register after ending a previous document.
+       (doc-end-macro): Call `doc-break-page-with-new-number` instead
+       of invoking `bp`.
+       (doc-break-page-with-new-number): If `P` is set and `C` is not,
+       use value of `P` as the next page number.
+       * tmac/doc.tmac (initialization): If `P` is set, assign the page
+       number using the `pn` request if the transition to the first
+       formatted page has not yet occurred; otherwise update page
+       number register `%` directly.  Also ignore it with diagnostic if
+       `ps4html` register (for grohtml's internal use) is set.  Add
+       explanatory comment.
+
+       Fixes <https://savannah.gnu.org/bugs/?63500>.
+
 2022-12-11  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        [doc]: Support `P` register.
diff --git a/tmac/an.tmac b/tmac/an.tmac
index 76eaaed67..1ebe5bee4 100644
--- a/tmac/an.tmac
+++ b/tmac/an.tmac
@@ -134,7 +134,7 @@
 .  \}
 .  rr an-TH-was-called
 .  ch an-header
-.  bp
+.  an*break-page-with-new-number
 ..
 .
 .\" Move macros into place for continuous rendering.
@@ -178,9 +178,16 @@
 .
 .\" Break the page and update its number depending on the C (consecutive
 .\" numbering) register.
+.\"
+.\" Corner case: if formatting multiple documents and P (starting page
+.\" number) is defined but C is not set, start numbering each document
+.\" at \n[P].  Not strictly necessary if not switching macro packages.
 .de an*break-page-with-new-number
 .  ie \\n[C] .bp (\\n[%] + 1) \" argument NOT redundant before page 1
-.  el        .bp 1
+.  el \{\
+.    ie r P .bp \\n[P]
+.    el     .bp 1
+.  \}
 ..
 .
 .\" Localize manual section titles for English.
@@ -220,6 +227,7 @@
 .    ch an-header
 .    an*break-page-with-new-number
 .  \}
+.  if \\n[C] .rr P
 .
 .  nr an-TH-was-called 1 \" an-end can make certain assumptions.
 .
@@ -1419,9 +1427,30 @@ contains unsupported escape sequence
 .  rm an-msg
 .\}
 .
-.if !r ps4html \
-.  if r P \
-.    pn 0\n[P]
+.\" Setting the page number turns out to be tricky when batch rendering
+.\" and switching macro packages.  We must use different techniques
+.\" depending on whether the transition to the first output page has
+.\" happened yet.  If it has not, `nl` will be `-1` and we use `pn`.  If
+.\" it has, we set `%`.  Technically this is fragile since in theory a
+.\" page could assign a negative value to `nl`.  We might then be
+.\" justified in saying they've broken the macro package and they get to
+.\" keep both pieces.  But if not, consider using a nonce register,
+.\" initially set but then permanently cleared adjacent to this logic,
+.\" and whose state is shared with mdoc (and andoc.tmac, if necessary).
+.\"
+.\" Also, we can't use the `P` register with grohtml at all.
+.ie r ps4html \{\
+.  if r P \{\
+.     tm \*[an]: ignoring starting page number in HTML output
+.     rr P
+.  \}
+.\}
+.el \{\
+.  if r P \{\
+.    ie (\n[nl] = -1) .pn 0\n[P]
+.    el               .nr % 0\n[P]
+.  \}
+.\}
 .
 .\" type size
 .if !r S \{\
diff --git a/tmac/doc.tmac b/tmac/doc.tmac
index 4da964da1..4d72d6509 100644
--- a/tmac/doc.tmac
+++ b/tmac/doc.tmac
@@ -149,9 +149,30 @@
 .  rm doc-msg
 .\}
 .
-.if !r ps4html \
-.  if r P \
-.    pn 0\n[P]
+.\" Setting the page number turns out to be tricky when batch rendering
+.\" and switching macro packages.  We must use different techniques
+.\" depending on whether the transition to the first output page has
+.\" happened yet.  If it has not, `nl` will be `-1` and we use `pn`.  If
+.\" it has, we set `%`.  Technically this is fragile since in theory a
+.\" page could assign a negative value to `nl`.  We might then be
+.\" justified in saying they've broken the macro package and they get to
+.\" keep both pieces.  But if not, consider using a nonce register,
+.\" initially set but then permanently cleared adjacent to this logic,
+.\" and whose state is shared with man (and andoc.tmac, if necessary).
+.\"
+.\" Also, we can't use the `P` register with grohtml at all.
+.ie r ps4html \{\
+.  if r P \{\
+.     tm mdoc: ignoring starting page number in HTML output
+.     rr P
+.  \}
+.\}
+.el \{\
+.  if r P \{\
+.    ie (\n[nl] = -1) .pn 0\n[P]
+.    el               .nr % 0\n[P]
+.  \}
+.\}
 .
 .\" Use -rSN=<xxx> to set the subsection heading indentation amount.
 .if !r SN .nr SN 3n
diff --git a/tmac/mdoc/doc-common b/tmac/mdoc/doc-common
index 9890eab75..e00017a3e 100644
--- a/tmac/mdoc/doc-common
+++ b/tmac/mdoc/doc-common
@@ -300,6 +300,7 @@
 .    ch doc-header
 .    doc-break-page-with-new-number
 .  \}
+.  if \n[C] .rr P
 .
 .  if !\n[.$] \
 .    tm mdoc warning: .Dd directive expects an argument (#\n[.c])
@@ -1135,7 +1136,7 @@
 .    pl \n[nl]u
 .  \}
 .  ch doc-header
-.  bp
+.  doc-break-page-with-new-number
 .
 .  \" Reset strings to reduce info leaks from one man page to the next.
 .  ds doc-date-string UNDATED\"
@@ -1151,11 +1152,19 @@
 .\" NS doc-break-page-with-new-number macro
 .\" NS   Break the page and update its number depending on the C
 .\" NS   (consecutive numbering) register.
+.\" NS
+.\" NS  Corner case: if formatting multiple documents and P (starting
+.\" NS  page number) is defined but C is not set, start numbering each
+.\" NS  document at \n[P].  Not strictly necessary if not switching
+.\" NS  macro packages.
 .
 .eo
 .de doc-break-page-with-new-number
 .  ie \n[C] .bp (\n[%] + 1) \" argument NOT redundant before page 1
-.  el       .bp 1
+.  el \{\
+.    ie r P .bp \n[P]
+.    el     .bp 1
+.  \}
 ..
 .ec
 .