[groff] 10/12: [docs]: Revise description of `return` request.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit a9fe0544eb52dba799d1b8dbcdd72eda420793a8
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Nov 10 15:04:07 2023 -0600

    [docs]: Revise description of `return` request.
---
 doc/groff.texi       |  9 +++++----
 man/groff.7.man      |  7 ++++---
 man/groff_diff.7.man | 25 +++++++++++++++++--------
 3 files changed, 26 insertions(+), 15 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 043a82018..f30f1c27f 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -13497,10 +13497,11 @@ description of the @code{als} request}, for pitfalls 
when redefining a
 macro that is aliased.
 
 @Defreq {return, [@Var{anything}]}
-Exit a macro, immediately returning to the caller.  If called with an
-argument @var{anything}, exit twice---the current macro and the macro
-one level higher.  This is used to define a wrapper macro for
-@code{return} in @file{trace.tmac}.
+Stop interpreting a macro, skipping to the end of its definition.  Do
+not confuse @code{return} with @code{rt}.  If called with an argument
+@var{anything}, the skip is performed twice---once within the macro
+being interpreted and once in an enclosing macro.  @file{trace.tmac}
+uses this feature to define a wrapper macro for @code{return}.
 @endDefreq
 
 @menu
diff --git a/man/groff.7.man b/man/groff.7.man
index a6b3dec17..ed4d195be 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -3978,9 +3978,10 @@ skipping the remainder of its definition.
 .
 .TPx
 .REQ .return anything
-Return twice,
-namely from the macro at the current level and from the macro one level
-higher.
+As
+.BR return ,
+but perform the skip twice\[em]once within the macro being interpreted
+and once in an enclosing macro.
 .
 .TPx
 .REQ .rfschar "f c1 c2 \fR\&.\|.\|.\&\fP"
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 556da1b39..b0a82b5c6 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -3147,16 +3147,25 @@ arguments.
 .
 .
 .TP
-.B .return
-Within a macro,
-return immediately.
+.BR .return\~ [
+.IR anything ]
+.\" XXX: useless request warning?
+Stop interpreting a macro,
+skipping to the end of its definition.
 .
-If called with an argument,
-return twice,
-namely from the current macro and from the macro one level higher.
+Do not confuse
+.RB \[lq] return \[rq]
+with
+.BR rt .
 .
-No effect otherwise.
-.\" XXX: useless request warning?
+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].
 .
 .
 .TP