[groff] 12/16: [docs]: Fix Savannah #65118 (`device` behavior).

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit c8935f2361b44414be83a34f5e7e4b2ad57cd8b2
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Jan 8 19:02:34 2024 -0600

    [docs]: Fix Savannah #65118 (`device` behavior).
    
    * doc/groff.texi (Postprocessor Access):
    * man/groff_diff.7.man (New requests): Clarify a point of `device`
      request behavior; a partially collected line in the top-level
      diversion must exist at least once.
    
    Fixes <https://savannah.gnu.org/bugs/?65118>.
---
 ChangeLog            |  9 +++++++++
 doc/groff.texi       |  6 ++++++
 man/groff_diff.7.man | 12 ++++++++++++
 3 files changed, 27 insertions(+)

diff --git a/ChangeLog b/ChangeLog
index 6c0fde1ce..ad0a6b8f6 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2024-01-08  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       * doc/groff.texi (Postprocessor Access):
+       * man/groff_diff.7.man (New requests): Clarify a point of
+       `device` request behavior; a partially collected line in the
+       top-level diversion must exist at least once.
+
+       Fixes <https://savannah.gnu.org/bugs/?65118>.
+
 2024-01-08  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * src/roff/troff/div.cpp (top_level_diversion::output)
diff --git a/doc/groff.texi b/doc/groff.texi
index f479f47c7..b4b7fe6b1 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -16461,6 +16461,12 @@ rendered as glyphs in the output; instead, they remain 
abstract
 characters---in a PDF bookmark or a URL, for example.} The use of any
 other escape sequence in @code{\X} parameters is normally an error.
 
+A device control command issued with the @code{device} request will not
+be reflected in the output unless a partially collected line exists at
+least once in the top-level diversion (recall @ref{Diversions}).  When
+experimenting with such device controls in minimal documents, a
+@code{br} request will ensure this to be the case.
+
 @kindex use_charnames_in_special
 @cindex @file{DESC} file, and @code{use_charnames_in_special} keyword
 @cindex @code{\X}, and special characters
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 15479e74e..1ff305aed 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -2232,6 +2232,18 @@ is stripped to allow the embedding of
 leading spaces.
 .
 .
+.P
+A device control command issued with the
+.B device
+request will not be reflected in the output unless a partially collected
+line exists in the top-level diversion at least once.
+.
+When experimenting with such device controls in minimal documents,
+a
+.B br
+request will ensure this to be the case.
+.
+.
 .TP
 .BI .devicem\~ name
 Write contents of macro or string