gbranden pushed a commit to branch master
in repository groff.
commit f0e20e5d38b5a4966201bffcf3f4c62f803e503e
Author: G. Branden Robinson <g.branden.robin...@gmail.com>
AuthorDate: Tue Jul 15 14:55:26 2025 -0500
doc/*,man/*: Clarify and sync.
Also fix typographical nits in groff(7).
---
doc/groff.texi.in | 84 +++++++++++++++++++++++++++++++++++++++++--------------
man/groff.7.man | 37 ++++++++++++------------
2 files changed, 82 insertions(+), 39 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 8791860aa..6e1c64f60 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -8890,12 +8890,18 @@ This is an uninteresting sentence.
@cindex line, productive input
To clearly present the next couple of requests, we must introduce the
concept of ``productive'' input lines. A @dfn{productive input line} is
-one that directly produces formatted output. Text lines produce
-output,@footnote{though not necessarily to the output device; see
-@ref{Diversions}} as do control lines containing requests like @code{tl}
-or escape sequences like @code{\D}. Macro calls are not @emph{directly}
-productive, and thus not counted, but their interpolated contents can
-be. Empty requests, and requests and escape sequences that define
+one that directly produces formatted output.
+Text lines produce output,@footnote{though not necessarily to the output
+device;
+see
+@ref{Diversions}}
+as do control lines containing requests like
+@samp{.tl //Page %//}
+or escape sequences like
+@samp{\l'1i'}.
+Macro calls are not themselves productive,
+but their interpolations can be.
+Empty requests, and requests and escape sequences that define
registers or strings or alter the formatting environment (as with
changes to the size, face, height, slant, or color of the type) are not
productive.@footnote{If you're not sure whether an input line has been
@@ -14036,10 +14042,17 @@ in the branches or bodies of these structures is
unusual.
@cindex @code{while} request, operators to use with
@cindex conditional expressions
@cindex expressions, conditional
-In @code{if}, @code{ie}, and @code{while} requests, in addition to the
-numeric expressions described in @ref{Numeric Expressions}, several
-Boolean operators are available; the members of this expanded class are
-termed @dfn{conditional expressions}.
+The
+@code{if},
+@code{ie},
+and
+@code{while}
+requests test the truth values of numeric expressions.
+They also support several additional Boolean operators;
+the members of this expanded class are termed
+@dfn{conditional expressions};
+.IR "conditional expressions" ;
+their truth values are as shown below.
@table @code
@item c @var{chr}
@@ -14104,9 +14117,17 @@ early-vintage @acronym{AT&T} @code{troff} to a form
suitable for
Versatec and Benson-Varian plotters.}
@end table
-If the first argument to an @code{if}, @code{ie}, or @code{while}
-request begins with a non-alphanumeric character apart from @code{!}
-(see below), it performs an @slanted{output comparison test}.
+If the first argument to an
+@code{if},
+@code{ie},
+or
+@code{while}
+request begins with a non-alphanumeric character apart from
+@code{!}
+(see below)
+and is not a numeric expression,
+it performs an
+@slanted{output comparison test}.
@footnote{Strictly,
letters not otherwise recognized
@emph{are}
@@ -14126,12 +14147,26 @@ may provide additional operators in the future.}
@cindex output comparison operator
@table @code
@item @code{'}@var{xxx}@code{'}@var{yyy}@code{'}
-True if formatting the comparands @var{xxx} and @var{yyy} produces the
-same output commands. The delimiter need not be a neutral apostrophe:
+This
+@dfn{output comparison operator}
+interpolates a true value
+if formatting the comparands
+@var{xxx}
+and
+@var{yyy}
+produces the same output commands.
+The delimiter need not be a neutral apostrophe:
the output comparison operator accepts the same delimiters as most
-escape sequences; see @ref{Delimiters}. This @dfn{output comparison
-operator} formats @var{xxx} and @var{yyy} in separate scratch buffers;
-after the comparison, the resulting data are discarded.
+escape sequences;
+see @ref{Delimiters}.
+@command{troff} @c generic
+formats
+@var{xxx}
+and
+@var{yyy}
+in separate scratch buffers;
+after comparison,
+it discards the resulting data.
@Example
.ie "|"\fR|\fP" true
@@ -14140,9 +14175,16 @@ after the comparison, the resulting data are discarded.
@endExample
@noindent
-The resulting glyph properties, including font family, style, size, and
-slant, must match, but not necessarily the requests and/or escape
-sequences used to obtain them. In the previous example, @samp{|} and
+The resulting glyph properties,
+including font family,
+style,
+size,
+and
+slant,
+must match,
+but not necessarily the requests and/or escape sequences
+used to obtain them.
+In the previous example, @samp{|} and
@samp{\fR|\fP} result in @samp{|} glyphs in the same typefaces at the
same positions, so the comparands are equal. If @samp{.ft@tie{}I} had
been added before the @samp{.ie}, they would differ: the first @samp{|}
diff --git a/man/groff.7.man b/man/groff.7.man
index dadf24fd7..b1a6bc529 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -1095,7 +1095,7 @@ GNU
emits a warning in category
.RB \%\[lq] range \[rq].
See section \[lq]Warnings\[rq] of
-.MR @g@troff 1 ).
+.MR @g@troff 1 .)
.
.
.P
@@ -2098,7 +2098,7 @@ Furthermore,
a
.esc }
closing the body of a
-.request .while
+.RB \[lq] while \[rq]
request must be the last such escape sequence on an input line.
.
.
@@ -2109,10 +2109,10 @@ request must be the last such escape sequence on an
input line.
.\" BEGIN Keep (roughly) parallel with groff.texi node "Operators in
.\" Conditionals".
The
-.request .if ,
-.request .ie ,
+.RB \[lq] if \^\[rq],
+.BR ie ,
and
-.request .while
+.RB \[lq] while \[rq]
requests test the truth values of numeric expressions.
.
They also support several additional Boolean operators;
@@ -2209,13 +2209,14 @@ T}
.ne 2v
.P
If the first argument to an
-.BR .if ,
-.BR .ie ,
+.RB \[lq] if \^\[rq],
+.BR ie ,
or
-.B .while
+.RB \[lq] while \[rq]
request begins with a non-alphanumeric character apart from
-.B !\&
-(see below);
+.RB \[lq] !\& \[rq]
+(see below)
+and is not a numeric expression,
it performs an
.I output comparison test.
.
@@ -2231,14 +2232,14 @@ produces the same output commands.
Other delimiters can be used in place of the neutral apostrophes;
see section \[lq]Delimiters\[rq] above.
.
-.I @g@troff
+.I troff \" generic
formats
.I s1
and
.I s2
in separate scratch buffers;
-after the comparison,
-the resulting data are discarded.
+after comparison,
+it discards the resulting data.
.
The resulting glyph properties,
including font family,
@@ -2247,8 +2248,8 @@ size,
and
slant,
must match,
-but not necessarily the requests and/or escape sequences used to obtain
-them.
+but not necessarily the requests and/or escape sequences
+used to obtain them.
.
Motions must match in orientation and magnitude to within the applicable
horizontal or vertical motion quantum of the device,
@@ -2412,7 +2413,7 @@ in file names supplied as arguments to requests.
.
.TPx
.I font
-is a typeface specified as a font name,
+is a typeface specified as a font identifier,
an abstract style,
or a mounting position.
.
@@ -2469,9 +2470,9 @@ those that directly produce formatted output.
.
Text lines produce output,
as do control lines containing requests like
-.request .tl
+.RB \[lq] ".tl //\^Page %//\^" \[rq]
or escape sequences like
-.esc D .
+.RB \[lq] \[rs]\^l\[aq]1i\[aq] \[rq].
.
Macro calls are not themselves productive,
but their interpolations can be.
_______________________________________________
groff-commit mailing list
groff-commit@gnu.org
https://lists.gnu.org/mailman/listinfo/groff-commit
