[groff] 19/26: [mdoc]: Support `FT` register.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit d0ae281616da88d55134d877fdc3735df5cde8dc
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Dec 18 13:41:44 2022 -0600

    [mdoc]: Support `FT` register.
    
    * tmac/doc.tmac (initialization): Add logic supporting `FT` register
      just as our man(7) implementation does.
    * tmac/mdoc/doc-common (doc-set-up-titles): Plant footer trap in
      validated user-requested location.
    * tmac/groff_mdoc.7.man (Options): Document it.
    * NEWS: Update item.
    
    Fixes part of <https://savannah.gnu.org/bugs/?63046>.
---
 ChangeLog             | 13 +++++++++++++
 NEWS                  |  4 ++--
 tmac/doc.tmac         | 38 ++++++++++++++++++++++++++++++++++++++
 tmac/groff_mdoc.7.man | 19 +++++++++++++++----
 tmac/mdoc/doc-common  | 12 ++++++++----
 5 files changed, 76 insertions(+), 10 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index b60bc4a39..d8ba0ea27 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,16 @@
+2022-12-18  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [mdoc]: Support `FT` register.
+
+       * tmac/doc.tmac (initialization): Add logic supporting `FT`
+       register just as our man(7) implementation does.
+       * tmac/mdoc/doc-common (doc-set-up-titles): Plant footer trap in
+       validated user-requested location.
+       * tmac/groff_mdoc.7.man (Options): Document it.
+       * NEWS: Update item.
+
+       Fixes part of <https://savannah.gnu.org/bugs/?63046>.
+
 2022-12-18  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * tmac/an.tmac: Fix code style nit: use `as` requests to
diff --git a/NEWS b/NEWS
index 1010976be..808223202 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`,
-  `SN`, and `X` registers as the an (man) package does.
+o The doc (mdoc) macro package now honors the `C`, `FT`, `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 4edc408f6..587cef1ee 100644
--- a/tmac/doc.tmac
+++ b/tmac/doc.tmac
@@ -117,6 +117,44 @@
 .       nr D 0
 .    \}
 .
+.\" footer distance
+.\"
+.\" Unlike most of these parameters, we do not set a default for FT; the
+.\" doc-set-up-titles macro places page location traps only if not
+.\" continuously rendering.
+.if r FT \{\
+.  \" Validate it.  Continuous rendering ignores FT.  Measuring a footer
+.  \" distance from the page top isn't done.  A footer distance of over
+.  \" half the page length is unlikely.  A footer distance of less than
+.  \" one line height is too.
+.  ie \n[cR] \
+.    ds doc-msg footer distance when continuously rendering\"
+.  el \{\
+.    nr doc-tmp 1v
+.    ds doc-help " (1v=\n[doc-tmp]u)\"
+.    ie (\n[FT] : (\n[FT] = 0)) \
+.      ds doc-msg non-negative footer distance: \n[FT]u\*[doc-help]\"
+.    el \{\
+.      ie (-(\n[FT]) > (\n[.p] / 2)) \{\
+.        ds doc-msg implausibly large footer distance:\"
+.        as doc-msg " \n[FT]u\*[doc-help]\"
+.      \}
+.      el \
+.        if (-(\n[FT]) < 1v) \{\
+.          ds doc-msg implausibly small footer distance:\"
+.          as doc-msg " \n[FT]u\*[doc-help]\"
+.        \}
+.    rm doc-help
+.    rr doc-tmp
+.    \}
+.  \}
+.  if d doc-msg \{\
+.    tm mdoc: ignoring \*[doc-msg]
+.    rr FT
+.    rm doc-msg
+.  \}
+.\}
+.
 .\" TODO: Implement HF string.
 .
 .\" \n[HY] is recognized for groff_man(7) compatibility, particuarly via
diff --git a/tmac/groff_mdoc.7.man b/tmac/groff_mdoc.7.man
index 3d50e3666..a31bebd45 100644
--- a/tmac/groff_mdoc.7.man
+++ b/tmac/groff_mdoc.7.man
@@ -4965,6 +4965,20 @@ swapping places with the arguments to
 .
 .
 .Pp
+The value of the
+.Ql FT
+register determines the footer's distance from the page bottom;
+this amount is always negative and should specify a scaling unit.
+.
+At one half-inch above this location,
+the page text is broken before writing the footer.
+.
+It is ignored if continuous rendering is enabled.
+.
+The default is \-0.5i.
+.
+.
+.Pp
 Normally,
 automatic hyphenation is enabled using a mode appropriate to the
 .Xr groff
@@ -5052,10 +5066,7 @@ request in
 The
 .Ql HF
 string
-and
-.Ql FT
-register
-are reserved for potential future compatibility with
+is 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 ea30365e2..a00a96943 100644
--- a/tmac/mdoc/doc-common
+++ b/tmac/mdoc/doc-common
@@ -253,8 +253,9 @@
 .
 .\" NS doc-set-up-titles macro
 .\" NS   install and initialize header and footer support
-.\"
-.\" TODO: Support man(7)'s `FT` register.
+.\" NS
+.\" NS local variables:
+.\" NS   doc-footer-location
 .
 .eo
 .de doc-set-up-titles
@@ -262,8 +263,11 @@
 .
 .  if !\n[cR] \{\
 .    wh 0 doc-header
-.    wh -1.0i doc-break-body-text
-.    wh -.5i doc-footer
+.    ie r FT .nr doc-footer-location \n[FT]
+.    el      .nr doc-footer-location (-.5i)
+.    wh \n[doc-footer-location]u doc-footer
+.    wh (\n[doc-footer-location]u - .5i) doc-break-body-text
+.    rr doc-footer-location
 .  \}
 .
 .  e@ doc-end-macro