[groff] 25/30: groff_tmac(5): Revise.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 92f7e6f58456df11c1c5dbdfcc958da9ec262a43
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Apr 4 08:04:15 2024 -0500

    groff_tmac(5): Revise.
    
    Content:
    * Drop recommendations about macro inclusion best practice; this needs
      more thought.  See
      <https://lists.gnu.org/archive/html/groff/2024-02/msg00087.html> and
      follow-ups.
    * Clarify dimensioning convention of paper format.
    * Clarify "draft mode" suggested procedure.
    * Drop "Diversions" subsection.  I find the analogy to C structure
      pointers to be less than illuminating.  I think the discussion in our
      Texinfo manual and in groff(7) is better.  Also, diversions aren't
      stored in macro files, the topic of this page.
    
    Style:
    * Fix grammar nits (which/that; comma usage)
    * Tighten wording.
    * Use shorter inline metasyntactic variable names.
---
 man/groff_tmac.5.man | 93 +++++++++-------------------------------------------
 1 file changed, 15 insertions(+), 78 deletions(-)

diff --git a/man/groff_tmac.5.man b/man/groff_tmac.5.man
index 57b12a837..d5de5fba0 100644
--- a/man/groff_tmac.5.man
+++ b/man/groff_tmac.5.man
@@ -142,7 +142,7 @@ and the encodings used by documents employing a macro file 
can vary.
 .\" ====================================================================
 .
 Macro packages come in two varieties;
-those which assume responsibility for page layout and other critical
+those that assume responsibility for page layout and other critical
 functions
 (\[lq]major\[rq] or \[lq]full-service\[rq])
 and those that do not
@@ -177,17 +177,6 @@ collisions,
 apart from attempts at compatibility with the demands of historical
 documents.
 .
-As a rule,
-direct the formatter to load full-service macro packages using the
-.B \-m
-option of
-.MR @g@troff 1
-(or a wrapper).
-.
-A document should load auxiliary macro files with the
-.B mso
-request.
-.
 .
 .\" ====================================================================
 .SS "Man pages"
@@ -574,15 +563,15 @@ See
 .
 .TP
 .I papersize
-enables the paper format to be set on the command line by giving a
+enables the paper format to be set on the command line with the
 .RB \[lq] \-d
-.BI \%paper= format\c
+.BI \%paper= fmt\c
 \[rq]
 option to
 .IR @g@troff .
 .
-Possible values for
-.I format
+Valid
+.IR fmt s
 are the ISO and DIN formats
 .RB \[lq] A0 \[en] A6 \[rq],
 .RB \[lq] B0 \[en] B6 \[rq],
@@ -607,7 +596,7 @@ and
 All formats,
 even those for envelopes,
 are in portrait orientation:
-the length measurement is vertical.
+the longer measurement is vertical.
 .
 Appending \[lq]l\[rq] (ell) to any of these denotes landscape
 orientation instead.
@@ -630,7 +619,8 @@ or
 .B ll
 and/or
 .B po
-requests to adjust them.
+requests,
+to adjust them.
 .
 An output device typically requires command-line options
 .B \-p
@@ -846,7 +836,7 @@ to format permuted index entries as produced by the GNU
 program.
 .
 If your formatting needs differ,
-copy the macro into your document and adapt it to your needs.
+copy the macro into your document and adapt it.
 .
 .
 .TP
@@ -1306,12 +1296,15 @@ See section \[lq]Copy mode\[rq] of
 .MR groff @MAN7EXT@ .
 .
 In such cases,
-you might define and test the macro with the escape mechanism doubled,
-then double the backslashes and remove the
+you might define and test the macro with the escape character doubled
+before escape sequences that are interpreted even in copy mode,
+then bracket it with
 .B eo
 and
 .B ec
-requests as a final step.
+requests,
+un-double the escape characters,
+then test again.
 .
 .
 .\" ====================================================================
@@ -1372,62 +1365,6 @@ to clarify a macro's structure.
 .
 .
 .\" ====================================================================
-.SS Diversions
-.\" ====================================================================
-.
-Diversions can be used to implement quite advanced programming
-constructs.
-.
-They are comparable to pointers to large data structures in the
-C\~programming language, but their usage is quite different.
-.
-.
-.P
-In their simplest form, diversions are multi-line strings, but
-diversions get their power when used dynamically within macros.
-.
-The (formatted) information stored in a diversion can be retrieved by
-calling the diversion just like a macro.
-.
-.
-.P
-Most of the problems arising with diversions can be avoided if you
-remember that diversions always store complete lines.
-.
-Using diversions when the line buffer has not been flushed produces
-strange results; not knowing this, many people get desperate about
-diversions.
-.
-To ensure that a diversion works, add line breaks at the right
-places.
-.
-To be safe, enclose everything that has to do with diversions within
-a pair of line breaks; for example, by explicitly using
-.B .br
-requests.
-.
-This rule should be applied to diversion definition, both inside and
-outside, and to all calls of diversions.
-.
-This is a bit of overkill, but it works nicely.
-.
-.
-.P
-(If you really need diversions which should ignore the current partial
-line, use environments to save the current partial line and/\:or use the
-.B .box
-request.)
-.
-.
-.P
-The most powerful feature using diversions is to start a diversion
-within a macro definition and end it within another macro.
-.
-Then everything between each call of this macro pair is stored within
-the diversion and can be manipulated from within the macros.
-.
-.
-.\" ====================================================================
 .SH Authors
 .\" ====================================================================
 .