gbranden pushed a commit to branch master
in repository groff.
commit e5d50e22777a7a02328425648291906a5e67dbb4
Author: G. Branden Robinson <[email protected]>
AuthorDate: Sat Jan 3 21:01:04 2026 -0600
[doc,man]: Recast `while` request description.
* Favor active voice over passive.
* Favor present tense over future.
* Sync content between Texinfo and man pages, bringing a discussion of
the `while` request's unique characteristics into groff(7).
* Break input lines consistently in Texinfo and man pages.
---
doc/groff.texi.in | 71 ++++++++++++++++++++++++++++++++++++++--------------
man/groff.7.man | 50 ++++++++++++++++++++++++++++++++++++
man/groff_diff.7.man | 26 +++++++++++--------
3 files changed, 118 insertions(+), 29 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 12d0d249c..45bf894fc 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -15306,8 +15306,15 @@ package. Indentation is used to clarify the logic.
@subsection while
@cindex @code{while} request
-@code{groff} provides a looping construct:@: the @code{while} request.
-Its syntax matches the @code{if} request.
+GNU
+@command{troff} @c GNU
+provides a looping construct:@:
+the
+@code{while}
+request.
+Its syntax matches the
+@code{if}
+request.
@cindex body, of a while request
@Defreq {while, cond-expr anything}
@@ -15326,13 +15333,26 @@ the @code{while} request's @dfn{body}.
@endExample
@cindex @code{de} request, and @code{while}
-GNU @code{troff} treats the body of a @code{while} request similarly to
-that of a @code{de} request (albeit one not read in copy
-mode@footnote{@xref{Copy Mode}.}), but stores it under an internal name
-and deletes it when the loop finishes. The operation of a macro
-containing a @code{while} request can slow significantly if the
-@code{while} body is large. Each time the macro is executed, the
-@code{while} body is parsed and stored again.
+GNU
+@command{troff} @c GNU
+treats the body of a
+@code{while}
+request similarly to that of a
+@code{de}
+request
+(albeit one not read in copy mode@footnote{@xref{Copy Mode}.}),
+but stores it under an internal name
+and deletes it when the loop finishes.
+The operation of a macro containing a
+@code{while}
+request can slow significantly if its body is large.
+Each time
+GNU
+@command{troff} @c GNU
+interpolates the macro,
+it parses and stores the
+@code{while}
+body again.
@Example
.de xxx
@@ -15347,10 +15367,13 @@ containing a @code{while} request can slow
significantly if the
@cindex recursive macros
@cindex macros, recursive
@noindent
-An often better solution---and one that is more portable, since
-@acronym{AT&T} @code{troff} lacked the @code{while} request---is to
-instead write a recursive macro. It will be parsed only
-once.@footnote{unless you redefine it}
+An often better solution---and one that is more portable,
+since @acronym{AT&T}
+@command{troff} @c AT&T
+lacked the
+@code{while}
+request---is to instead write a recursive macro,
+which is parsed only once.@footnote{unless you redefine it}
@Example
.de yy
@@ -15368,13 +15391,23 @@ once.@footnote{unless you redefine it}
@endExample
@noindent
-To prevent infinite loops, the default number of available recursion
-levels is 1,000 or somewhat less.@footnote{``somewhat less'' because
-things other than macro calls can be on the input stack} You can
-disable this protective measure, or alter the limit, by setting the
-@code{slimit} register. @xref{Debugging}.
+To prevent infinite loops,
+GNU
+@command{troff} @c GNU
+limits the default number of available recursion levels
+to 1,000 or somewhat less.@footnote{``somewhat less'' because
+things other than macro calls can be on the input stack}
+You can disable this protective measure,
+or alter the limit,
+by setting the
+@code{slimit}
+register.
+@xref{Debugging}.
-As noted above, if a @code{while} body begins with a conditional block,
+As noted above,
+if a
+@code{while}
+body begins with a conditional block,
its closing brace must end an input line.
@Example
diff --git a/man/groff.7.man b/man/groff.7.man
index 7958f5208..395f56fc6 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2223,6 +2223,56 @@ closing the body of a
request must be the last such escape sequence on an input line.
.
.
+.P
+GNU
+.I troff \" GNU
+treats the body of a
+.RB \[lq] while \[rq]
+request similarly to that of a
+.B de
+request
+(albeit one not read in copy mode),
+but stores it under an internal name
+and deletes it when the loop finishes.
+.
+The operation of a macro containing a
+.RB \[lq] while \[rq]
+request can slow significantly if its
+body is large.
+.
+Each time
+GNU
+.I troff \" GNU
+interpolates the macro,
+it parses and stores the
+.RB \[lq] while \[rq]
+body again.
+.
+An often better solution\[em]and one that is more portable,
+since AT&T
+.I troff \" AT&T
+lacked the
+.RB \[lq] while \[rq]
+request\[em]is to instead write a recursive macro,
+which is parsed only once
+(unless you redefine it).
+.
+To prevent infinite loops,
+GNU
+.I troff \" GNU
+limits the default number of available recursion levels
+to 1,000 or somewhat less
+(because things other than macro calls can be on the input stack).
+.
+You can disable this protective measure,
+or alter the limit,
+by setting the
+.B slimit
+register.
+.
+See section \[lq]Debugging\[rq] below.
+.
+.
.\" ====================================================================
.SS "Conditional expressions"
.\" ====================================================================
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 11533a796..6b044b344 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -4624,31 +4624,37 @@ request similarly to that of a
.B de
request
(albeit one not read in copy mode),
-but stores it under an internal name and deletes it when the loop
-finishes.
+but stores it under an internal name
+and deletes it when the loop finishes.
.
The operation of a macro containing a
.RB \[lq] while \[rq]
request can slow significantly if its
body is large.
.
-Each time the macro is executed,
-the
+Each time
+GNU
+.I troff \" GNU
+interpolates the macro,
+it parses and stores the
.RB \[lq] while \[rq]
-body is parsed and stored again.
+body again.
.
An often better solution\[em]and one that is more portable,
since AT&T
.I troff \" AT&T
lacked the
.RB \[lq] while \[rq]
-request\[em]is to instead write a recursive macro.
-.
-It will be parsed only once (unless you redefine it).
+request\[em]is to instead write a recursive macro,
+which is parsed only once
+(unless you redefine it).
.
To prevent infinite loops,
-the default number of available recursion levels is 1,000 or somewhat
-less (because things other than macro calls can be on the input stack).
+GNU
+.I troff \" GNU
+limits the default number of available recursion levels
+to 1,000 or somewhat less
+(because things other than macro calls can be on the input stack).
.
You can disable this protective measure,
or alter the limit,
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
