[groff] 15/35: groff_diff(7): Correct and clarify items.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit e4b808b0400b3f78b1e7083d3a5842a09535ef72
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Dec 7 12:29:14 2024 -0600

    groff_diff(7): Correct and clarify items.
    
    * Note availability of AT&T compatibility mode very early.
    * Fix error in `char` description: one can define ordinary characters
      too.
    * Improve terminological discipline: favor "interpolation" over
      "expansion".
    * Quote names of requests that overload English words (like "so").
    * Remove extraneous brackets from `output` synopsis: its argument is
      mandatory.
    * Fix misleading verb tense in `pstream` request description.  It
      reports only currently open streams, not any stream that has ever been
      opened.
    * Generalize application of `return`.
    * Explain `rj` more thoroughly.
    * Tighten wording, unstranding lines, single words, and partial words.
    * Clarify annotations to maintainers.
---
 man/groff_diff.7.man | 99 +++++++++++++++++++++++++++-------------------------
 1 file changed, 51 insertions(+), 48 deletions(-)

diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index e75dc0a2c..a7f8c6aa9 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -90,6 +90,13 @@ See
 .MR roff @MAN7EXT@
 for background.
 .
+GNU
+.I troff \" GNU
+can operate in a mode that increases support for documents written for
+AT&T
+.IR troff ; \" AT&T
+see section \[lq]Compatibility mode\[rq] below.
+.
 .
 .\" ====================================================================
 .SH Language
@@ -593,10 +600,8 @@ True if a character
 .I chr
 is available;
 .I chr
-is an ordinary character
-(Unicode basic Latin excluding control characters and the space),
-a special character
-(whether built-in or user-defined),
+is an ordinary or special character
+(whether built-in or user-defined)
 or
 .BI \[rs]N\[aq] index\c
 .BR \[aq] .
@@ -787,11 +792,10 @@ with its leftmost point at the drawing position.
 .
 .TP
 .BI \[rs]D\[aq]E\~ "h v" \[aq]
-Draw filled ellipse with
-.I h
-and
-.I v
-as the axis lengths and its leftmost point at the drawing position.
+Draw filled ellipse with axis lengths
+.IR h ,
+.IR v ,
+and its leftmost point at the drawing position.
 .
 .
 .TP
@@ -844,8 +848,8 @@ selects the minimum supported thickness.
 .
 A negative
 .I n
-selects a thickness proportional to the type size;
-this is the default.
+(the default)
+selects a thickness proportional to the type size.
 .
 .
 .TP
@@ -880,6 +884,8 @@ are synonyms;
 we recommend the former.
 .
 .
+.br
+.ne 4v
 .TP
 .BI \[rs]F f
 .TQ
@@ -1199,8 +1205,9 @@ produce warnings in category
 .BI \[rs]Y[ mac ]
 Interpolate a macro as a device extension command.
 .
-This is similar to
-.BI \[rs]X\[aq]\[rs]*[ mac ]\[aq]\f[R],
+As
+.BI \[rs]X\[aq]\[rs]*[ mac ]\[aq]\c
+,
 except the contents of
 .I mac
 are not interpreted,
@@ -1524,16 +1531,13 @@ requests work like AT&T
 and
 .B ds
 requests,
-accepting an optional leading neutral double-quote
-.B \[dq]
-in an argument that extends to the end of the input line,
+accepting an optional leading neutral double-quote,
+notated
+.RB \[lq][ \[dq] ]\[rq],
+in an argument that the formatter reads
+in copy mode to the end of the input line,
 permitting inclusion of leading spaces.
 .
-Such arguments are labeled
-.I contents,
-are read in copy mode,
-and consume the rest of the input line.
-.
 .
 .TP 8n \" ".break" + 2n
 .BI .aln\~ "new old"
@@ -1611,9 +1615,7 @@ or diversion is aliased,
 redefinitions and appendments \[lq]write through\[rq] alias names.
 .
 To replace an alias with a separately defined object,
-you must use the
-.B rm
-request on its name first.
+remove its name first.
 .
 .
 .TP
@@ -1755,6 +1757,8 @@ If no argument is supplied,
 the default blank line behavior is (re-)established.
 .
 .
+.br
+.ne 4v
 .TP
 .BR .box\~ [\c
 .IR name ]
@@ -2399,9 +2403,7 @@ with compatibility mode disabled.
 .
 Compatibility mode is restored
 (only if it was active)
-when the
-.I expansion
-of
+when the interpolation of
 .I name
 is interpreted;
 that is,
@@ -2412,7 +2414,7 @@ or diversion
 as well as data read from files or pipes if
 .I name
 is any of the
-.BR so ,
+.RB \[lq] so \[rq],
 .BR soquiet ,
 .BR mso ,
 .BR msoquiet ,
@@ -2450,6 +2452,8 @@ if none has been saved.
 Save the current escape character.
 .
 .
+.br
+.ne 5v
 .TP
 .BI .evc\~ env
 Copy the properties of environment
@@ -3253,8 +3257,8 @@ append to it instead of truncating it.
 .
 .
 .TP
-.BR .output \~[[ \[dq] ]\c
-.IR contents ]
+.BR .output \~[ \[dq] ]\c
+.I contents
 Emit
 .I contents
 \[lq]transparently\[rq]
@@ -3400,7 +3404,7 @@ which is passed to
 .B .pstream
 Report,
 to the standard error stream,
-the name of each opened stream,
+the name of each open stream,
 the name of the file backing it,
 and its mode
 (writing or appending).
@@ -3469,9 +3473,10 @@ arguments.
 .TP
 .BR .return\~ [\c
 .IR anything ]
-.\" XXX: useless request warning?
-Stop interpreting a macro,
-skipping to the end of its definition.
+.\" XXX: useless request warning if not interpreting a macro?
+In a macro definition,
+stop interpretation,
+skipping to its end.
 .
 Do not confuse
 .RB \[lq] return \[rq]
@@ -3481,11 +3486,8 @@ with
 If called with an argument
 .I anything,
 the skip is performed twice\[em]once within the macro being interpreted
-and once in an enclosing macro.
-.
-.I trace.tmac
-uses this feature to define a wrapper macro for
-.RB \[lq] return \[rq].
+and once in an enclosing macro,
+permitting a macro to wrap the request.
 .
 .
 .TP
@@ -3507,12 +3509,12 @@ See
 .TP
 .BR .rj\~ [\c
 .IR n ]
-Right-align the
+Break,
+right-align the
 .RI next\~ n
-input lines.
-.
-Without an argument,
-right-align the next input line.
+(default: 1)
+input lines,
+then break again.
 .
 .B rj
 implies
@@ -3522,6 +3524,9 @@ and
 implies
 .RB \[lq] ".rj 0" \[rq].
 .
+If invoked with the no-break control character,
+the first break is suppressed.
+.
 .
 .TP
 .BI .rnn \~r1\~r2
@@ -3583,9 +3588,10 @@ are considered when assigning the soft hyphen character.
 .
 .TP
 .BR .shift\~ [\c
+.\" XXX: useless request warning if not interpreting a macro?
 .IR n ]
 In a macro definition,
-shift the arguments by
+shift arguments by
 .I n
 positions:
 .RI argument\~ i
@@ -3599,9 +3605,6 @@ are no longer available.
 is missing,
 arguments are shifted by\~1.
 .
-No effect otherwise.
-.\" XXX: useless request warning?
-.
 .
 .TP
 .BI .sizes\~ "s1 s2\~"\c