[groff] 17/32: groff_diff(7): Revise section "Extended requests".

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit c380673af83ecf5faa5abda3ad04c271565eb684
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Jun 17 01:36:34 2023 -0500

    groff_diff(7): Revise section "Extended requests".
    
    Content:
    * Use more meaningful metasyntactic variable names.
    * Mark end macro names as optional arguments to macro definition and
      appendment requests.
    * Mark contents as optional arguments to string definition and
      appendment requests.
    
    Style:
    * Stop setting request names with a leading dot in running text.
    * Tighten wording.
    
    Markup:
    * Apply poor man's keep to control dead-tree pagination.
    * Annotate that `cf`'s interface hasn't changed, and it might be better
      described in section "Implementation differences".
---
 man/groff_diff.7.man | 50 +++++++++++++++++++++++++++++---------------------
 1 file changed, 29 insertions(+), 21 deletions(-)

diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 23ae6cdf5..c5a7b9719 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -4011,41 +4011,50 @@ request.
 is read in copy mode.
 .
 .
+.br
+.ne 6v
 .\" ====================================================================
 .SS "Extended requests"
 .\" ====================================================================
 .
+.\" XXX: .cf might better belong in "Implementation differences".
 .TP
-.BI .cf\~ filename
-When used in a diversion, this embeds in the diversion an object
-which, when reread, will cause the contents of
-.I filename
-to be transparently copied through to the output.
+.BI .cf\~ file
+In a diversion,
+embed an object which,
+when reread,
+will cause the contents of
+.I file
+to be copied verbatim to the output.
 .
 In AT&T
 .IR troff ,
 the contents of
-.I filename
-are immediately copied through to the output regardless of whether there
-is a current diversion;
+.I file
+are immediately copied to the output regardless of whether a diversion
+is being written to;
 this behavior is so anomalous that it must be considered a bug.
 .
 .
 .TP
-.BI .de\~ "xx yy"
+.BI .de\~ name\~\c
+.RI [ end-name ]
 .TQ
-.BI .am\~ "xx yy"
+.BI .am\~ name\~\c
+.RI [ end-name ]
 .TQ
-.BI .ds\~ "xx yy"
+.BI .ds\~ name\~\c
+.RI [ contents ]
 .TQ
-.BI .as\~ "xx yy"
+.BI .as\~ name\~\c
+.RI [ contents ]
 In compatibility mode,
 these requests behave similarly to
-.BR .de1 ,
-.BR .am1 ,
-.BR .ds1 ,
+.BR de1 ,
+.BR am1 ,
+.BR ds1 ,
 and
-.BR .as1 ,
+.BR as1 ,
 respectively:
 a \[lq]compatibility save\[rq] token is inserted at the beginning,
 and a \[lq]compatibility restore\[rq] token at the end,
@@ -4060,11 +4069,10 @@ and the latter enables hyphenation after the first 
character in a word.
 .
 .
 .TP
-.BI .ss\~ "word-space-size additional-sentence-space-size"
-A second argument to the
-.B .ss
-request sets the amount of additional space separating sentences on the
-same output line.
+.BI .ss\~ word-space-size\~\c
+.RI [ additional-sentence-space-size ]
+A second argument sets the amount of additional space separating
+sentences on the same output line.
 .
 If omitted,
 this amount is set to