[groff] 02/03: Rewrite documentation of .do request.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 58fefeb90b8a6b8e92cecf021ed3b73b1e203c83
Author: G. Branden Robinson <address@hidden>
AuthorDate: Wed Apr 15 17:51:10 2020 +1000

    Rewrite documentation of .do request.
    
    * doc/groff.texi:
    * man/groff_diff.7.man: Rewrite description of .do request, and
      replace example with a more illustrative one.
    
    * man/groff.7.man: Rewrite description of .do request briefly.
    
    Also I'd like to again register a complaint about the page-private
    macros in groff(7).  Their days are numbered...
---
 ChangeLog            |  8 ++++++
 doc/groff.texi       | 44 +++++++++++++++++++++--------
 man/groff.7.man      | 20 ++++++++++---
 man/groff_diff.7.man | 79 +++++++++++++++++++++++++++++++++++++---------------
 4 files changed, 112 insertions(+), 39 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index db10236..63e3d0f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2020-04-15  G. Branden Robinson <address@hidden>
+
+       * doc/groff.texi:
+       * man/groff_diff.7.man: Rewrite description of .do request, and
+       replace example with a more illustrative one.
+
+       * man/groff.7.man: Rewrite description of .do request briefly.
+
 2020-04-14  G. Branden Robinson <address@hidden>
 
        * src/roff/groff/tests/smoke-test_html_device.sh: Simplify
diff --git a/doc/groff.texi b/doc/groff.texi
index bca067d..b00889f 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -26,7 +26,7 @@
 @copying
 This manual documents GNU @code{troff} version 1.22.4.
 
-Copyright @copyright{} 1994--2018 Free Software Foundation, Inc.
+Copyright @copyright{} 1994--2018, 2020 Free Software Foundation, Inc.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -14351,7 +14351,7 @@ compatibility mode GNU @code{troff} interprets long 
names in the
 traditional way (which means that they are not recognized as names).
 
 @DefreqList {cp, [@Var{n}]}
-@DefreqItemx {do, cmd}
+@DefreqItemx {do, name}
 @DefregListEndx {.C}
 If @var{n} is missing or non-zero, turn on compatibility mode;
 otherwise, turn it off.
@@ -14362,20 +14362,40 @@ is on, 0@tie{}otherwise.
 Compatibility mode can be also turned on with the @option{-C}
 command-line option.
 
-The @code{do} request turns off compatibility mode while executing its
-arguments as a @code{gtroff} command.  However, it does not turn off
-compatibility mode while processing the macro itself.  To do that, use
-the @code{de1} request.  @xref{Writing Macros}.
+The @code{do} request interprets the string, request, diversion, or
+macro @var{name} (along with any further arguments) with compatibility
+mode disabled.  Note that compatibility mode is restored (if and only if
+it was active) when the @emph{expansion} of @var{name} is interpreted;
+that is, the restored compatibility state applies to the contents of the
+macro (string, @dots{}) @var{name} as well as file or pipe data read if
+@var{name} is the @code{.so}, @code{.mso}, or @code{.pso} request.
+
+For example,
 
 @Example
-.do fam T
+.de mac1
+FOO
+..
+.de1 mac2
+groff
+.mac1
+..
+.de mac3
+compatibility
+.mac1
+..
+.de ma
+\\$1
+..
+.cp 1
+.do mac1
+.do mac2 \" mac2, defined with .de1, calls "mac1"
+.do mac3 \" mac3 calls "ma" with argument "c1"
+.do mac3 \[ti] \" groff syntax accepted in .do arguments
+    @result{} FOO groff FOO compatibility c1 ~
 @endExample
 
-@noindent
-executes the @code{fam} request when compatibility mode is enabled.
-
-@code{gtroff} restores the previous compatibility setting before
-interpreting any files sourced by the @var{cmd}.
+illustrates several aspects of @code{do} behavior.
 @endDefreq
 
 @cindex input level in delimited arguments
diff --git a/man/groff.7.man b/man/groff.7.man
index fc1c958..33eff7b 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -10,7 +10,7 @@ groff \- a short reference for the GNU roff language
 .\" Legal Terms
 .\" ====================================================================
 .\"
-.\" Copyright (C) 2000-2018 Free Software Foundation, Inc.
+.\" Copyright (C) 2000-2018, 2020 Free Software Foundation, Inc.
 .\"
 .\" This file is part of groff, the GNU roff type-setting system.
 .\"
@@ -1571,11 +1571,23 @@ See
 for more details.
 .
 .TPx
-.REQ .do "name"
-Interpret
-.BI . name
+.REQ .do "name \fR\&.\|.\|.\&\fP"
+Interpret the string,
+request,
+diversion,
+or macro
+.I name
+(along with any arguments)
 with compatibility mode disabled.
 .
+Note that compatibility mode is restored
+(if and only if it was active)
+when the
+.I expansion
+of
+.I name
+is interpreted.
+.
 .TPx
 .REQ .ds "stringvar anything"
 Set
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 3565830..0b5ee12 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -17,7 +17,7 @@ groff_diff \- differences between GNU troff and classical 
troff
 .\" Legal Terms
 .\" ====================================================================
 .\"
-.\" Copyright (C) 1989-2018 Free Software Foundation, Inc.
+.\" Copyright (C) 1989-2018, 2020 Free Software Foundation, Inc.
 .\"
 .\" This file is part of groff, the GNU roff type-setting system.
 .\"
@@ -1314,37 +1314,70 @@ escape (to embed the contents of a macro into the 
intermediate
 output preceded with \[oq]x\~X\[cq]).
 .
 .TP
-.BI .do\  xxx
-Interpret
-.I .xxx
+.BI .do\~ name\~\c
+\&...
+Interpret the string,
+request,
+diversion,
+or macro
+.I name
+(along with any arguments)
 with compatibility mode disabled.
 .
-For example,
-.
-.RS
+Note that compatibility mode is restored
+(if and only if it was active)
+when the
+.I expansion
+of
+.I name
+is interpreted;
+that is,
+the restored compatibility state applies to the contents of the macro
+(string, \&...\&)
+.I name
+as well as file or pipe data read if
+.I name
+is the
+.BR .so ,
+.BR .mso ,
+or
+.B .pso
+request.
 .
 .IP
+For example,
+.RS
+.RS \" one "extra" RS to get us inboard of this indented paragraph
 .EX
-\&.do fam T
+\&.de mac1
+FOO
+\&..
+\&.de1 mac2
+groff
+\&.mac1
+\&..
+\&.de mac3
+compatibility
+\&.mac1
+\&..
+\&.de ma
+\[rs]\[rs]$1
+\&..
+\&.cp 1
+\&.do mac1
+\&.do mac2 \[rs]" mac2, defined with .de1, calls "mac1"
+\&.do mac3 \[rs]" mac3 calls "ma" with argument "c1"
+\&.do mac3 \[rs][ti] \[rs]" groff syntax accepted in .do arguments
 .EE
-.
-.P
-would have the same effect as
-.
-.IP
+.RE
+results in
+.RS
 .EX
-\&.fam T
+FOO groff FOO compatibility c1 \[ti]
 .EE
-.
-.P
-except that it would work even if compatibility mode had been enabled.
-.
-Note that the previous compatibility mode is restored before any files
-sourced by
-.I xxx
-are interpreted.
-.
 .RE
+as output.
+.RE \" this "extra" RE avoids indentation of the remaining paragraphs
 .
 .TP
 .BI .ds1\  xx\ yy