[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 05/08: doc/groff.texi: Expand on 'ie', 'el', 'while'.
From: |
G. Branden Robinson |
Subject: |
[groff] 05/08: doc/groff.texi: Expand on 'ie', 'el', 'while'. |
Date: |
Thu, 27 Jan 2022 11:05:44 -0500 (EST) |
gbranden pushed a commit to branch master
in repository groff.
commit 956ffa75433167154e1225576c27435c25d6198a
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Jan 26 19:00:16 2022 +1100
doc/groff.texi: Expand on 'ie', 'el', 'while'.
* (if-else): Illustrate behavior of nested `ie`/`el` usage without
conditional blocks (brace escapes), which surprises some people.
* (while): Recast. Clarify. Improve organization. ("Some remarks."
followed by a bulleted list is pretty lazy exposition.) Define the
term "body" in context of a `while` request. Update likening to macro
definition to point out a difference: a `while` body is not read in
copy mode. Fix misleading statement suggesting that the limit to
macro recursion is fixed.
Also:
* Add concept index entries for the distinction between characters and
glyphs.
* man/groff_diff.7.man (New requests) <break, continue, while>:
Synchronize with the above.
---
doc/groff.texi | 72 ++++++++++++++++++++++++------------
man/groff_diff.7.man | 102 ++++++++++++++++++++++++++++++---------------------
2 files changed, 109 insertions(+), 65 deletions(-)
diff --git a/doc/groff.texi b/doc/groff.texi
index 7baf13dd..cf2b34a9 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -9895,6 +9895,8 @@ this is font 1 again
@cindex glyph
@cindex character
+@cindex glyph, distinguished from character
+@cindex character, distinguished from glyph
@cindex ligature
A @dfn{glyph} is a graphical representation of a @dfn{character}. While
a character is an abstract entity containing semantic information, a
@@ -12002,6 +12004,26 @@ requests may be interposed between the @code{ie}
branch and the
.el a was not positive but is now \na.
@result{} a was not positive but is now 1.
@endExample
+
+Another way in which @code{el} is an ordinary request is that it does
+not lexically ``bind'' more tightly to its @code{ie} counterpart than it
+does to any other request. This fact can surprise C programmers.
+
+@Example
+.nr a 1
+.nr z 0
+.ie \nz \
+. ie \na a is true
+. el a is false
+.el z is false
+ @error{} warning: unbalanced 'el' request
+ @result{} a is false
+@endExample
+
+@c Turn the following into a proper @{x,}ref if the conditional blocks
+@c node is relocated elsewhere--but consider if it is wise to do so.
+To conveniently nest conditionals, keep reading.
+
@endDefreq
@c ---------------------------------------------------------------------
@@ -12103,12 +12125,15 @@ condition was false) the remainder of the input line
is interpreted
@subsection while
@cindex while
-@code{groff} provides a looping construct using the @code{while}
-request, which is used much like the @code{if} request.
+@code{groff} 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}
Evaluate the conditional expression @var{cond-expr}, and repeatedly
execute @var{anything} unless and until @var{cond-expr} evaluates false.
+@var{anything}, which is often a conditional block, is referred to as
+the @code{while} request's @dfn{body}.
@Example
.nr a 0 1
@@ -12119,17 +12144,14 @@ execute @var{anything} unless and until
@var{cond-expr} evaluates false.
@result{} 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
@endExample
-Some remarks.
-
@cindex @code{de} request, and @code{while}
-@itemize @bullet
-@item
-The body of a @code{while} request is treated like the body of a
-@code{de} request:@: GNU @code{troff} temporarily stores it in a macro
-that is deleted after the loop exits. It can considerably slow down a
-macro if the body of the @code{while} request (within the macro) is
+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 it exits. 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 as a temporary macro.
+and stored again.
@Example
.de xxx
@@ -12144,9 +12166,10 @@ and stored again as a temporary macro.
@cindex recursive macros
@cindex macros, recursive
@noindent
-The traditional and often better solution (@acronym{AT&T} @code{troff}
-lacked the @code{while} request) is to use a recursive macro instead
-that is parsed only once during its definition.
+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 only be parsed
+once.@footnote{unless you redefine it}
@Example
.de yyy
@@ -12164,12 +12187,14 @@ that is parsed only once during its definition.
@endExample
@noindent
-The number of available recursion levels is set to@tie{}1000
-(this is a compile-time constant value of GNU @code{troff}).
+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 raise the limit, by setting the
+@code{slimit} register. @xref{Debugging}.
-@item
-As noted above, the closing brace of a @code{while} body must end an
-input line.
+As noted above, if a @code{while} body begins with a conditional block,
+its closing brace must end an input line.
@Example
.if 1 \@{\
@@ -12179,20 +12204,19 @@ input line.
.\@}\@}
@error{} unbalanced brace escape sequences
@endExample
-@end itemize
@endDefreq
@Defreq {break, }
@cindex @code{while} request, confusing with @code{br}
@cindex @code{break} request, in a @code{while} loop
@cindex @code{continue} request, in a @code{while} loop
-Break out of a @code{while} loop. Be sure not to confuse this with the
-@code{br} request (causing a line break).
+Exit a @code{while} loop. Do not confuse this request with a
+typographical break or the @code{br} request.
@endDefreq
@Defreq {continue, }
-Finish the current iteration of a @code{while} loop, immediately
-restarting the next iteration.
+Skip the remainder of a @code{while} loop's body, immediately starting
+the next iteration.
@endDefreq
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index f41cc57f..c404e5b3 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -1217,18 +1217,17 @@ discarding any partially collected line in the
diversion.
.
.TP
.B .break
-Break out of a while loop.
-.
-See also the
+Exit a
.B while
-and
-.B continue
-requests.
-.
-Be sure not to confuse this with the
+loop.
+Do not confuse this request with a typographical break or the
.B br
request.
.
+See
+.BR .continue .
+.
+.
.TP
.B .brp
This is the same as
@@ -1705,15 +1704,17 @@ if it is used in
.BR \[rs][ .\|.\|.\& ]
with more than one component.
.
+.
.TP
.B .continue
-Finish the current iteration of a while loop.
-.
-See also the
+Skip the remainder of a
.B while
-and
-.B break
-requests.
+loop's body,
+immediately starting the next iteration.
+.
+See
+.BR .break .
+.
.
.TP
.BI .color\~ n
@@ -3426,53 +3427,72 @@ unless and until
.I cond-expr
evaluates false.
.
-See also the
-.B break
-and
-.B continue
-requests.
+.I anything,
+which is often a conditional block,
+is referred to as the
+.B while
+request's
+.I body.
.
.
.IP
-The body of a
+.I \%@g@troff
+treats the body of a
.B while
-request is treated like the body of a
+request similarly to that of a
.B de
-request:
-.I \%@g@troff
-temporarily stores it in a macro that is deleted after the loop exits.
+request
+(albeit one not read in copy mode),
+but stores it under an internal name and deletes it when it exits.
.
-It can considerably slow down a macro if the body of the
+The operation of a macro containing a
.B while
-request
-(within the macro)
-is large.
+request can slow significantly if the
+.B while
+body is large.
.
Each time the macro is executed,
the
.B while
-body is parsed and stored again as a temporary macro.
-.
+body is parsed and stored again.
.
-.IP
-The traditional and often better solution
-(AT&T
+An often better solution\[em]and one that is more portable,
+since AT&T
.I troff \" AT&T
lacked the
.B while
-request)
-is to use a recursive macro instead that is parsed only once during its
-definition.
+request\[em]is to instead write a recursive macro.
+.
+It will only be parsed once (unless you redefine it).
.
-The number of available recursion levels is set to\~1000
-(this is a compile-time constant value of
-.IR \%@g@troff ).
+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).
+.
+You can disable this protective measure,
+or raise the limit,
+by setting the
+.B slimit
+register.
+.
+See section \[lq]Debugging\[rq] below.
.
.
.IP
-The closing brace of a
+If a
+.B while
+body begins with a conditional block,
+its closing brace must end an input line.
+.
+.
+.IP
+The
+.B break
+and
+.B continue
+requests alter a
.B while
-body must end a line.
+loop's flow of control.
.
.
.TP
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 05/08: doc/groff.texi: Expand on 'ie', 'el', 'while'.,
G. Branden Robinson <=