gbranden pushed a commit to branch master
in repository groff.
commit c2e27a9af6993a244716abc44d6ddc489c3d2fa4
Author: G. Branden Robinson <[email protected]>
AuthorDate: Tue Apr 21 12:56:53 2026 -0500
[doc,man]: Update and resync brace escape stuff.
Also break Texinfo input lines in a roff-friendly way.
---
doc/groff.texi.in | 75 ++++++++++++++++++++++++++++++++++++++++---------------
man/groff.7.man | 49 ++++++++++++++++++++++++++++--------
2 files changed, 94 insertions(+), 30 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index e1bb2c87d..114e9bb3b 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -16248,10 +16248,21 @@ To conveniently nest conditionals, keep reading.
@cindex blocks, conditional
It is frequently desirable for a control structure to govern more than
-one request, macro call, text line, or combination of the foregoing.
-The opening and closing brace escape sequences @code{\@{} and @code{\@}}
-define such groups. These @dfn{conditional blocks} can furthermore be
-nested.
+one request,
+macro call,
+text line,
+or combination of the foregoing.
+The opening and closing brace escape sequences
+@code{\@{}
+and
+@code{\@}}
+define such groups.
+These
+@dfn{conditional blocks}
+can furthermore be nested.
+
+Brace escape sequences outside of control structures have no meaning and
+produce no output.@c TODO: footnote: style warning
@DefescList {\@\{, , , }
@DefescListEnd {\@\}, , , }
@@ -16267,26 +16278,50 @@ nested.
@cindex escape sequences, brace (@code{\@{}, @code{\@}})
@cindex opening brace escape sequence (@code{\@}})
@cindex closing brace escape sequence (@code{\@})}
-@code{\@{} begins a conditional block; it must appear (after optional
-spaces and tabs) immediately subsequent to the conditional expression of
-an @code{if}, @code{ie}, or @code{while}
-request,@footnote{@xref{while}.} or as the argument to an @code{el}
+@code{\@{}
+begins a conditional block;
+it must appear
+(after optional spaces and tabs)
+immediately subsequent to the conditional expression of an
+@code{if},
+@code{ie},
+or
+@code{while}
+request,@footnote{@xref{while}.}
+or as the argument to an
+@code{el}
request.
-@code{\@}} ends a conditional block and should appear on a line with
-other occurrences of itself as necessary to match @code{\@{} sequences.
-It can be preceded by a control character, spaces, and tabs. Input
-after any quantity of @code{\@}} sequences on the same line is processed
-only if all of the preceding conditions to which they correspond are
-true. Furthermore, a @code{\@}} closing the body of a @code{while}
+@code{\@}}
+ends a conditional block and should appear on an input line
+with other occurrences of itself as necessary to match
+@code{\@{}
+sequences.
+It can be preceded by a control character,
+spaces,
+and tabs.
+Input after any quantity of opening brace escape sequences
+@code{\@}}
+on the same line is processed
+only if all of the preceding conditions to which they correspond
+are true.
+Furthermore,
+a closing brace escape sequence
+@code{\@}}
+closing the body of a
+@code{while}
request must be the last such escape sequence on an input line.
-Brace escape sequences outside of control structures have no meaning and
-produce no output.
-
-@strong{Caution:@:} Input lines using @code{\@{} often end with
-@code{\RET}, especially in macros that consist primarily of control
-lines. Forgetting to use @code{\RET} on an input line after @code{\@{}
+@strong{Caution:@:}
+Input lines using
+@code{\@{}
+often end with
+@code{\RET},
+especially in macros that consist primarily of control lines.
+Forgetting to use
+@code{\RET}
+on an input line after
+@code{\@{}
is a common source of error.
@endDefesc
diff --git a/man/groff.7.man b/man/groff.7.man
index 74c256921..45f1834f9 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2219,21 +2219,34 @@ The opening and closing brace escape sequences
.esc {
and
.esc }
-perform such grouping.
+define such groups.
+.
+These
+.I "conditional blocks"
+can furthermore be nested.
.
Brace escape sequences outside of control structures have no meaning and
-produce no output.
+produce no output.\" TODO: footnote: style warning
.
.
.P
.esc {
-should appear
+begins a conditional block;
+it must appear
(after optional spaces and tabs)
-immediately subsequent to the request's conditional expression.
+immediately subsequent to the conditional expression of an
+.RB \[lq] if \[rq],
+.BR ie ,
+or
+.RB \[lq] while \[rq]
+request,\" @footnote{@xref{while}.}
+or as the argument to an
+.B el
+request.
.
.esc }
-should appear on a line with other occurrences of itself as necessary to
-match
+ends a conditional block and should appear on an input line
+with other occurrences of itself as necessary to match
.esc {
sequences.
.
@@ -2241,19 +2254,35 @@ It can be preceded by a control character,
spaces,
and tabs.
.
-Input after any quantity of
+Input after any quantity of opening brace escape sequences
.esc }
-sequences on the same line is processed only if all the preceding
-conditions to which they correspond are true.
+on the same line is processed
+only if all of the preceding conditions to which they correspond
+are true.
.
Furthermore,
-a
+a closing brace escape sequence
.esc }
closing the body of a
.RB \[lq] while \[rq]
request must be the last such escape sequence on an input line.
.
.
+.P
+.I Caution:
+Input lines using
+.esc {
+often end with
+.escarg \& newline ,
+especially in macros that consist primarily of control lines.
+.
+Forgetting to use
+.escarg \& newline
+on an input line after
+.esc {
+is a common source of error.
+.
+.
.\" ====================================================================
.SS "while loops"
.\" ====================================================================
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
