[groff] 16/16: [doc]: Support `X` register.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 88e89ebe9ce3931b49fb3cbd7fa20eacb03bf69f
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Dec 14 19:28:07 2022 -0600

    [doc]: Support `X` register.
    
    * tmac/doc.tmac (initialization): Add logic supporting `X` register just
      as our man(7) implementation does.
    
    * tmac/groff_mdoc.7.man (Options): Document it.
    
    * NEWS: Update item.
    
    Fixes part of <https://savannah.gnu.org/bugs/?63046>.
---
 ChangeLog             | 11 +++++++++++
 NEWS                  |  4 ++--
 tmac/doc.tmac         | 18 +++++++++++++++++-
 tmac/groff_mdoc.7.man | 23 ++++++++++++++++++++---
 tmac/mdoc/doc-common  | 15 +++++++++++----
 5 files changed, 61 insertions(+), 10 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 1435bc46a..7e7c70e5d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2022-12-11  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [doc]: Support `X` register.
+
+       * tmac/doc.tmac (initialization): Add logic supporting `X`
+       register just as our man(7) implementation does.
+       * tmac/groff_mdoc.7.man (Options): Document it.
+       * NEWS: Update item.
+
+       Fixes part of <https://savannah.gnu.org/bugs/?63046>.
+
 2022-12-15  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        [doc]: Add unit test for `X` register.
diff --git a/NEWS b/NEWS
index fddc024bc..8fdd2d958 100644
--- a/NEWS
+++ b/NEWS
@@ -320,8 +320,8 @@ o The groff_man(7) man page documenting the groff 
implementation of the
   material supplemented with explanations, examples, and advice for the
   reader who is not an expert in *roff systems or in writing man pages.
 
-o The doc (mdoc) macro package now honors the `C`, `HY`, `IN`, `P`, and
-  `SN` registers as the an (man) package does.
+o The doc (mdoc) macro package now honors the `C`, `HY`, `IN`, `P`,
+  `SN`, and `X` registers as the an (man) package does.
 
 o The doc (mdoc) macro package now renders man page (sub)section cross
   references cited with the `Sx` macro by quoting them instead of
diff --git a/tmac/doc.tmac b/tmac/doc.tmac
index 8fd662c07..bab3df174 100644
--- a/tmac/doc.tmac
+++ b/tmac/doc.tmac
@@ -179,7 +179,23 @@
 .
 .\" TODO: Implement U register.
 .
-.\" TODO: Implement X register.
+.\" page number after which to apply letter suffixes
+.\"
+.\" Unlike most of these parameters, we do not set a default for X; only
+.\" the macro an-footer uses it.  Page numbers are not rendered at all
+.\" in continuous rendering mode.
+.if r X \{\
+.  af doc-page-letter a
+.  if \n[doc-is-output-html] \
+.    ds doc-msg in HTML output\"
+.  if \n[cR] \
+.    ds doc-msg when continuously rendering
+.\}
+.if d doc-msg \{\
+.  tm mdoc: ignoring page number suffix \*[doc-msg]
+.  rr X
+.  rm doc-msg
+.\}
 .
 .
 .\" Load startup files.
diff --git a/tmac/groff_mdoc.7.man b/tmac/groff_mdoc.7.man
index 4266d3485..a0b738a1c 100644
--- a/tmac/groff_mdoc.7.man
+++ b/tmac/groff_mdoc.7.man
@@ -5027,14 +5027,31 @@ is ignored when formatting for terminal devices.
 .
 .
 .Pp
+Setting the
+.Ql X
+register to a page number
+.Ar p
+causes subsequent pages to be numbered as
+.Ar p Ns Li a ,
+.Ar p Ns Li b ,
+.Ar p Ns Li c ,
+and so forth.
+.
+The register tracking the suffixed page letter uses format
+.Ql a
+(see the
+.Ql af
+request in
+.Xr groff @MAN7EXT@ ) .
+.
+.
+.Pp
 The
 .Ql HF
 string
 and
 .Ql FT
-and
-.Ql X
-registers
+register
 are reserved for potential future compatibility with
 .Xr groff_man @MAN7EXT@
 page rendering options.
diff --git a/tmac/mdoc/doc-common b/tmac/mdoc/doc-common
index e00017a3e..ea30365e2 100644
--- a/tmac/mdoc/doc-common
+++ b/tmac/mdoc/doc-common
@@ -1052,29 +1052,36 @@
 .\"
 .\" NS local variables:
 .\" NS   doc-xref
-.\"
-.\" TODO: Support man(7)'s `X` register.
+.\" NS   doc-page-id
 .
 .eo
 .de doc-footer
 .  ds doc-xref \*[doc-page-topic-font]\*[doc-page-topic]\f[]\"
 .  as doc-xref \*[doc-page-section-font](\*[doc-section])\f[]\"
+.  ds doc-page-id \n[%]
+.  if r X \{\
+.    if (\n[%] > \n[X]) \{\
+.      nr doc-page-letter (\n[%] - \n[X])
+.      ds doc-page-id \n[X]\n[doc-page-letter]\"
+.    \}
+.  \}
 .  ev doc-caption-enviroment
 .  doc-setup-page-layout
 .  ie \n[D] \{\
 .    ie e \
 .      tl '%'\*[doc-date-string]'\*[doc-operating-system]'
 .    el \
-.      tl '\*[doc-operating-system]'\*[doc-date-string]'%'
+.      tl '\*[doc-operating-system]'\*[doc-date-string]'\*[doc-page-id]'
 .  \}
 .  el \{\
 .    ie \n[cR] \
 .      tl '\*[doc-operating-system]'\*[doc-date-string]'\*[doc-xref]'
 .    el \
-.      tl '\*[doc-operating-system]'\*[doc-date-string]'%'
+.      tl '\*[doc-operating-system]'\*[doc-date-string]'\*[doc-page-id]'
 .  \}
 .  if !\n[cR] .bp
 .  ev
+.  rm doc-page-id
 .  rm doc-xref
 ..
 .ec