[groff] 30/51: [mdoc]: Align trap mgmt more closely with man(7).

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 50a2d4165f7b82cb78d7ee96484f776c11a47def
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Sep 7 20:00:31 2022 -0500

    [mdoc]: Align trap mgmt more closely with man(7).
    
    * tmac/mdoc/doc-common: Call new macro (see below)
      `doc-set-up-continuous-rendering` when initializing, if that is mode
      is configured.
    
      (doc-ne): New macro replaces `ne` request in continuous rendering
      mode.  It extends the page length by the amount in the argument or by
      1v if none given.
    
      (doc-bp): New macro replaces `bp` request in continuous rendering
      mode, setting the page length to the vertical drawing position.
    
      (doc-set-up-continuous-rendering): New macro renames requests to
      emplace the foregoing.
    
      (Dd): Interpret this macro call strictly as starting a new mdoc(7)
      document.  (andoc.tmac already makes this assumption, and has for over
      20 years.  groff_mdoc(7) and mandoc_mdoc(7) also prescribe the
      sequence `Dd`, `Dt`, `Os`.)  We require this invariant even more
      rigidly now because it's the only way we can be sure that we can
      process multiple documents while rendering headers and footers with
      information corresponding to the appropriate document.  (man(7)'s `TH`
      has an advantage here in that calling it is "atomic": from its
      arguments alone you can obtain everything you need to know to format
      the header and footer.  In mdoc(7), permuting the initialization macro
      order reliably produces chaos.)  Break the page (if necessary)
      _before_ processing any arguments (instead of after), to flush the
      previous page's footer.  Stop calling `doc-set-up-titles` here; we
      don't have enough information to do that yet.  Also stop writing the
      PDF bookmark here, because `doc-document-title` and `doc-section` will
      not reflect the new page content yet.
    
      (Os): Once the `doc-operating-system` string content has been
      determined, call `doc-set-up-titles`, write the PDF bookmark for the
      page, and call `doc-header`, causing the page header to be formatted.
      These changes further imply a stronger requirement on initialization
      macro ordering being canonical.
    
    Fixes <https://savannah.gnu.org/bugs/?62774> (7/7).
---
 ChangeLog            | 40 ++++++++++++++++++++++++++++
 tmac/andoc.tmac      |  1 +
 tmac/mdoc/doc-common | 73 +++++++++++++++++++++++++++++++++++++++++++---------
 3 files changed, 102 insertions(+), 12 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index f69208a13..acf659cdb 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,43 @@
+2022-09-07  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [mdoc]: Align trap management more closely with man(7).
+
+       * tmac/mdoc/doc-common: Call new macro (see below)
+       `doc-set-up-continuous-rendering` when initializing, if that is
+       mode is configured.
+       (doc-ne): New macro replaces `ne` request
+       in continuous rendering mode.  It extends the page length by the
+       amount in the argument or by 1v if none given.
+       (doc-bp): New macro replaces `bp` request in continuous
+       rendering mode, setting the page length to the vertical drawing
+       position.
+       (doc-set-up-continuous-rendering): New macro renames requests to
+       emplace the foregoing.
+       (Dd): Interpret this macro call strictly as starting a new
+       mdoc(7) document.  (andoc.tmac already makes this assumption,
+       and has for over 20 years.  groff_mdoc(7) and mandoc_mdoc(7)
+       also prescribe the sequence `Dd`, `Dt`, `Os`.)  We require this
+       invariant even more rigidly now because it's the only way we can
+       be sure that we can process multiple documents while rendering
+       headers and footers with information corresponding to the
+       appropriate document.  (man(7)'s `TH` has an advantage here in
+       that calling it is "atomic": from its arguments alone you can
+       obtain everything you need to know to format the header and
+       footer.  In mdoc(7), permuting the initialization macro order
+       reliably produces chaos.)  Break the page (if necessary)
+       _before_ processing any arguments (instead of after), to flush
+       the previous page's footer.  Stop calling `doc-set-up-titles`
+       here; we don't have enough information to do that yet.  Also
+       stop writing the PDF bookmark here, because `doc-document-title`
+       and `doc-section` will not reflect the new page content yet.
+       (Os): Once the `doc-operating-system` string content has been
+       determined, call `doc-set-up-titles`, write the PDF bookmark for
+       the page, and call `doc-header`, causing the page header to be
+       formatted.  These changes further imply a stronger requirement
+       on initialization macro ordering being canonical.
+
+       Fixes <https://savannah.gnu.org/bugs/?62774> (7/7).
+
 2022-09-07  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        [mdoc]: Trivially refactor.  Relocate string and macro
diff --git a/tmac/andoc.tmac b/tmac/andoc.tmac
index 4e3f0dd35..8a3d61dc5 100644
--- a/tmac/andoc.tmac
+++ b/tmac/andoc.tmac
@@ -83,6 +83,7 @@
 .
 .  do als em andoc-em
 .  do als bp andoc-bp
+.  do als ne andoc-ne
 .  do blm            \" no blank line trap
 .  em                \" no end-of-input trap
 .
diff --git a/tmac/mdoc/doc-common b/tmac/mdoc/doc-common
index 98e21fb5e..2f60d26e8 100644
--- a/tmac/mdoc/doc-common
+++ b/tmac/mdoc/doc-common
@@ -192,6 +192,45 @@
 .nr doc-punct! 3
 .
 .
+.\" Define alternate requests to handle continuous rendering.
+.\"
+.\" This .ne replacement avoids page breaks; instead, the page length is
+.\" increased to the necessary amount (this is needed for tables).
+.
+.eo
+.de doc-ne
+.  ie \n[.$] .nr doc-amount (v;\$*)
+.  el        .nr doc-amount 1v
+.  if (\n[doc-amount] >= \n[.t]) \
+.    pl +(\n[doc-amount]u - \n[.t]u + 1v)
+.  rr doc-amount
+..
+.ec
+.
+.\" This .bp replacement for continuous rendering mode adjusts the page
+.\" length to the current position so that no empty lines are inserted.
+.
+.eo
+.de doc-bp
+.  pl \n[nl]u
+..
+.ec
+.
+.
+.\" NS doc-set-up-continuous-rendering
+.\"   Move macros into place for continuous rendering.  An end-of-input
+.\"   macro is set up by doc-set-up-titles.
+.de doc-set-up-continuous-rendering
+.  rn ne doc-real-ne
+.  rn bp doc-real-bp
+.  rn doc-ne ne
+.  rn doc-bp bp
+..
+.
+.if \n[cR] \
+.  doc-set-up-continuous-rendering
+.
+.
 .\" header assembly macros
 .
 .\" NS doc-document-title global string
@@ -265,6 +304,21 @@
 .
 .eo
 .de Dd
+.  \" If batch processing (rendering multiple) man page documents, we
+.  \" must handle the end of a previous document.
+.  \"
+.  \" If also continuously rendering, cause a page transition to a new
+.  \" mdoc(7) document.  Clear the page header trap first so it is not
+.  \" sprung with stale information.
+.  if !\n[doc-is-first-page-of-document] \{\
+.    ie \n[cR] .doc-end-macro
+.    el \{\
+.      ch doc-header
+.      bp 1
+.    \}
+.    nr doc-is-first-page-of-document 1
+.  \}
+.
 .  if !\n[.$] \
 .    tm mdoc warning: .Dd directive expects an argument (#\n[.c])
 .  if \n[.$] \{\
@@ -446,14 +500,6 @@
 .  if !"\$3"" \
 .    if "\*[doc-volume]"LOCAL" \
 .      ds doc-volume \$3
-.
-.  doc-set-up-titles
-.
-.  if \n[nl] \
-.    bp
-.
-.  if '\*[.T]'pdf' \
-.    pdfbookmark 1 "\*[doc-document-title](\*[doc-section])"
 ..
 .ec
 .
@@ -944,10 +990,13 @@
 .      as doc-operating-system " \$2
 .  \}\}\}\}\}\}\}\}
 .
-.  if \n[doc-is-first-page-of-document] \{\
-.    doc-header
-.    nr doc-is-first-page-of-document 0
-.  \}
+.  doc-set-up-titles
+.
+.  if '\*[.T]'pdf' \
+.    pdfbookmark 1 "\*[doc-document-title](\*[doc-section])"
+.
+.  doc-header
+.  nr doc-is-first-page-of-document 0
 ..
 .ec
 .