[groff] 02/04: [andoc,man,mdoc]: Fix Savannah #61266.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit a1e6c19176d38823d8dc6c9a619a493ca90bdca4
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Oct 3 23:15:12 2021 +1100

    [andoc,man,mdoc]: Fix Savannah #61266.
    
    Resolve problems in batch rendering of man pages to PDF arising from
    entanglement of end-of-input traps, page location traps, continuous
    rendering mode, and andoc's reloading of the (m)an and (m)doc packages.
    
    * tmac/andoc.tmac (reload-doc, reload-man): Remove end-of-input traps
      alongside others.
    
    * tmac/an.tmac (an-end): Only perform flush and "manual" page footer
      placement if in continuous rendering mode, since this macro is not
      only called by a trap placed only in continuous rendering mode, but
      also by andoc when changing macro packages.  Unconditionally remove
      the `an-header` trap since the next document might be using a
      different macro package.
    
    * tmac/mdoc/doc-common: In initialization, set flag indicating that
      manual header placement will be required.
    
      (Dt): Call `doc-setup-header` (which sets up several types of trap)
      unconditionally, and break the page if the vertical drawing position
      is anywhere but at the top.
    
      (Os): If the package has just been initialized, call `doc-header` to
      force the page header to be written.  (doc-end-macro): Remove
      `doc-header` trap since the next document might be using a different
      macro package.  Break the page.  Set flag indicating that manual
      header placement will be required for the next document.
    
    * tmac/mdoc/doc-ditroff (doc-setup-header): Only set page location traps
      for the header and footer if not continuously rendering.
    
    * tmac/mdoc/doc-nroff (doc-setup-header): Stop calling `doc-header` here
      if continuously rendering.  Emit an unconditional break.  Except for
      the location of the footer trap, the `doc-setup-header`
      implementations are now identical.
    
    Refactoring is needed: some macros and registers have misleading names,
    there is some code duplication in mdoc, and some of the trap management
    problems are solved in slightly different ways in man(7) and mdoc(7),
    perhaps unnecessarily.  We also need some test scripts to protect us
    from regressions.  But this fixes the rendering problems.
    
    Fixes <https://savannah.gnu.org/bugs/?61266>.
---
 ChangeLog             | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 tmac/an.tmac          | 10 +++++++---
 tmac/andoc.tmac       |  2 ++
 tmac/mdoc/doc-common  | 29 ++++++++++++++++++++++++-----
 tmac/mdoc/doc-ditroff |  8 +++++---
 tmac/mdoc/doc-nroff   |  6 +++---
 6 files changed, 87 insertions(+), 14 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 7f1173f..5e9c930 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,49 @@
+2021-10-03  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [andoc,man,mdoc]: Fix Savannah #61266.  Resolve problems in
+       batch rendering of man pages to PDF arising from entanglement
+       of end-of-input traps, page location traps, continuous rendering
+       mode, and andoc's reloading of the (m)an and (m)doc packages.
+
+       * tmac/andoc.tmac (reload-doc, reload-man): Remove end-of-input
+       traps alongside others.
+
+       * tmac/an.tmac (an-end): Only perform flush and "manual" page
+       footer placement if in continuous rendering mode, since this
+       macro is not only called by a trap placed only in continuous
+       rendering mode, but also by andoc when changing macro packages.
+       Unconditionally remove the `an-header` trap since the next
+       document might be using a different macro package.
+
+       * tmac/mdoc/doc-common: In initialization, set flag indicating
+       that manual header placement will be required.
+       (Dt): Call `doc-setup-header` (which sets up several types of
+       trap) unconditionally, and break the page if the vertical
+       drawing position is anywhere but at the top.
+       (Os): If the package has just been initialized, call
+       `doc-header` to force the page header to be written.
+       (doc-end-macro): Remove `doc-header` trap since the next
+       document might be using a different macro package.  Break the
+       page.  Set flag indicating that manual header placement will be
+       required for the next document.
+
+       * tmac/mdoc/doc-ditroff (doc-setup-header): Only set page
+       location traps for the header and footer if not continuously
+       rendering.
+       * tmac/mdoc/doc-nroff (doc-setup-header): Stop calling
+       `doc-header` here if continuously rendering.  Emit an
+       unconditional break.  Except for the location of the footer
+       trap, the `doc-setup-header` implementations are now identical.
+
+       Refactoring is needed: some macros and registers have misleading
+       names, there is some code duplication in mdoc, and some of the
+       trap management problems are solved in slightly different ways
+       in man(7) and mdoc(7), perhaps unnecessarily.  We also need some
+       test scripts to protect us from regressions.  But this fixes the
+       rendering problems.
+
+       Fixes <https://savannah.gnu.org/bugs/?61266>.
+
 2021-10-02  Keith Marshall  <keith.d.marshall@ntlworld.com>
 
        Correct manpage typo/inconsistency.
diff --git a/tmac/an.tmac b/tmac/an.tmac
index e3a406d..0cfa2c7 100644
--- a/tmac/an.tmac
+++ b/tmac/an.tmac
@@ -98,10 +98,12 @@
 .  pl \\n[nl]u
 ..
 .
-.\" We need an end macro for continuous rendering as well, to flush any
-.\" pending output line and write the footer for the final man page
-.\" rendered.
+.\" We need an end macro to flush any pending output line and write the
+.\" footer for the final man page rendered.  We can also be called by
+.\" andoc when switching to an mdoc(7) page, irrespective of continuous
+.\" rendering mode.
 .de1 an-end
+.  if \\n[cR] \{\
 .  fl
 .  pl +1v
 .  sp 1v
@@ -115,6 +117,8 @@
 \D'l \\n[LL]u 0'
 .    fi
 .  \}
+.  \}
+.  ch an-header
 .  bp
 ..
 .
diff --git a/tmac/andoc.tmac b/tmac/andoc.tmac
index 35dfc81..ee4d387 100644
--- a/tmac/andoc.tmac
+++ b/tmac/andoc.tmac
@@ -61,6 +61,7 @@
 .  do als ne andoc-ne
 .  do blm            \" no blank line trap
 .  do lsm            \" no leading space trap
+.  em                \" no end-of-input trap
 .
 .  do rm Dd          \" force reinitialization of doc.tmac
 .  do mso doc.tmac
@@ -83,6 +84,7 @@
 .  do als em andoc-em
 .  do als bp andoc-bp
 .  do blm            \" no blank line trap
+.  em                \" no end-of-input trap
 .
 .  do rm TH          \" force reinitialization of an.tmac
 .  do mso an.tmac
diff --git a/tmac/mdoc/doc-common b/tmac/mdoc/doc-common
index 33c414b..e9aa3d9 100644
--- a/tmac/mdoc/doc-common
+++ b/tmac/mdoc/doc-common
@@ -388,11 +388,10 @@
 .    if "\*[doc-volume]"LOCAL" \
 .      ds doc-volume \$3
 .
-.  if !\n[cR] \
-.    if \n[nl] \{\
-.      doc-setup-header
-.      bp
-.    \}
+.  doc-setup-header
+.
+.  if \n[nl] \
+.    bp
 ..
 .ec
 .
@@ -885,6 +884,11 @@
 .    if !"\$2"" \
 .      as doc-operating-system " \$2
 .  \}\}\}\}\}\}\}\}
+.
+.  if \n[doc-is-first-page-of-document] \{\
+.    doc-header
+.    nr doc-is-first-page-of-document 0
+.  \}
 ..
 .ec
 .
@@ -1016,6 +1020,9 @@
 .
 .\" NS doc-end-macro macro
 .\" NS   finish output
+.\" NS
+.\" NS modifies:
+.\" NS   doc-is-first-page-of-document
 .
 .eo
 .de doc-end-macro
@@ -1046,6 +1053,9 @@
 .    \" suppress empty lines after the footer
 .    pl \n[nl]u
 .  \}
+.  ch doc-header
+.  bp
+.  nr doc-is-first-page-of-document 1
 ..
 .ec
 .
@@ -1149,6 +1159,15 @@
 .nr doc-in-authors-section 0
 .
 .
+.\" NS doc-is-first-page-of-document global register (bool)
+.\" NS   whether the drawing position is at the top of the first page of
+.\" NS   a document
+.\" NS
+.\" NS This is necessarily true when the macro package is loaded.
+.
+.nr doc-is-first-page-of-document 1
+.
+.
 .\" NS doc-first-parameter macro
 .\" NS   return first parameter
 .\" NS
diff --git a/tmac/mdoc/doc-ditroff b/tmac/mdoc/doc-ditroff
index 0964e82..a959aca 100644
--- a/tmac/mdoc/doc-ditroff
+++ b/tmac/mdoc/doc-ditroff
@@ -205,11 +205,13 @@
 .  if !"\*[doc-section]"Null" \
 .    as doc-header-string \|(\*[doc-section])
 .
-.  wh 0 doc-header
-.  wh -1.25i doc-footer
-.
 .  br
 .
+.  if !\n[cR] \{\
+.    wh 0 doc-header
+.    wh -1.25i doc-footer
+.  \}
+.
 .  e@ doc-end-macro
 ..
 .ec
diff --git a/tmac/mdoc/doc-nroff b/tmac/mdoc/doc-nroff
index c0d8962..fb07753 100644
--- a/tmac/mdoc/doc-nroff
+++ b/tmac/mdoc/doc-nroff
@@ -206,9 +206,9 @@
 .  if !"\*[doc-section]"Null" \
 .    as doc-header-string (\*[doc-section])
 .
-.  ie \n[cR] \
-.    doc-header
-.  el \{\
+.  br
+.
+.  if !\n[cR] \{\
 .    wh 0 doc-header
 .    wh -1.167i doc-footer
 .  \}