[groff] 15/16: doc/ms.ms: Stick traffic cone in pothole.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 58af00e5c2a679b9afa9a185bb71fa0bd077a2f6
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Sep 4 10:30:36 2023 -0500

    doc/ms.ms: Stick traffic cone in pothole.
    
    [ms]: Doug McIlroy pointed out a hazard of the Berkeley DD display
    distance feature when footnotes end with displays; offer advice.
    
    * doc/ms.ms: Document caveat with display usage in footnotes.
    * doc/groff.texi (ms keeps and displays): Sync.
    
    Fixes <https://savannah.gnu.org/bugs/?64531>.
---
 ChangeLog      | 10 ++++++++++
 doc/groff.texi | 19 +++++++++++++++++++
 doc/ms.ms      | 24 ++++++++++++++++++++++++
 3 files changed, 53 insertions(+)

diff --git a/ChangeLog b/ChangeLog
index 357a48f7a..649f83551 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2023-09-04  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [ms]: Doug McIlroy pointed out a hazard of the Berkeley DD
+       display distance feature when footnotes end with displays; offer
+       advice.
+
+       * doc/ms.ms: Document caveat with display usage in footnotes.
+
+       Fixes <https://savannah.gnu.org/bugs/?64531>.
+
 2023-09-03  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * tmac/doc.tmac (doc-str-Ar-default, Ar): Stop setting ellipsis
diff --git a/doc/groff.texi b/doc/groff.texi
index 50b8f8a79..e535daeee 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -4007,6 +4007,25 @@ arguments, to @samp{.DS I} without an indentation 
argument, and to
 indented equations set with @samp{.EQ}.  Changes to either register take
 effect at the next display boundary.
 
+The display distance applies even in footnotes (discussed below), which
+may cause a footnote to ``emptily'' spill to the next page.  Consider
+the following tactic to compensate.
+
+@c Wrap example at 58 columns.
+@CartoucheExample
+.FS
+Recall the ideal gas law.
+.nr DD-saved \n[DD] \" stash display distance
+@c We have to drag the comment below inboard for Texinfo.
+.nr DD 0       \" eliminate automatic space around display
+.sp \n[DD-saved]u   \" manually put space before it
+.EQ
+P V = n R T
+.EN
+.FE
+.nr DD \n[DD-saved] \" restore previous setting
+@endCartoucheExample
+
 @c ---------------------------------------------------------------------
 
 @node ms Insertions, ms Footnotes, ms keeps and displays, ms Body Text
diff --git a/doc/ms.ms b/doc/ms.ms
index 6eb757d49..936d0d514 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -2448,6 +2448,30 @@ and to equations set with
 Changes to either register take effect at the next display boundary.
 .
 .
+.PP
+The display distance applies even in footnotes
+(discussed below),
+which may cause a footnote to \[lq]emptily\[rq] spill to the next page.
+.
+Consider the following tactic to compensate.
+.
+.
+.TS
+box center;
+lf(CR).
+\&.FS
+Recall the ideal gas law.
+\&.nr DD-saved \[rs]n[DD] \[rs]" stash display distance
+\&.nr DD 0            \[rs]" eliminate automatic space around display
+\&.sp \[rs]n[DD-saved]u   \[rs]" manually put space before it
+\&.EQ
+P V = n R T
+\&.EN
+\&.FE
+\&.nr DD \[rs]n[DD-saved] \[rs]" restore previous setting
+.TE
+.
+.
 .KS
 .NH 2
 Tables, figures, equations, and references