gbranden pushed a commit to branch master
in repository groff.
commit b912c1d3a9038077ee6ca5b23b5e1b3f3ab9578a
Author: G. Branden Robinson <[email protected]>
AuthorDate: Sun Jun 22 23:45:36 2025 -0500
doc/*,man/*: Parallelize `char` material.
Favor active voice over passive.
Document that indexed characters (`\N'100'`) can be user-defined as
well.
Recast material pertaining to recursively defined characters,
anticipating weisenheimery.
Also align input line breaks between Texinfo and man(7) documents.
---
doc/groff.texi.in | 51 +++++++++++++++++++++++++++++++++++-----------
man/groff_diff.7.man | 57 ++++++++++++++++++++++++++++++----------------------
2 files changed, 72 insertions(+), 36 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index e70b69055..8b5d16bee 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -11818,15 +11818,36 @@ permitting initial embedded spaces in it,
and reads it to the end of the input line in copy mode.
@xref{Copy Mode}.
-Defining (or redefining) a character @var{c} creates a formatter object
-that is recognized like any other ordinary or special character on
-input, and produces @var{contents} on output. Every time @var{c} is to
-be output, @var{contents} is processed in a temporary environment and
-the result encapsulated in a node.@footnote{@xref{Gtroff Internals}.}
-Compatibility mode is disabled and the escape character set to @code{\}
-while @var{contents} is interpreted. Any emboldening, constant spacing,
-or track kerning is applied to this object rather than to individual
-glyphs in @var{contents}.
+Defining
+(or redefining)
+a
+character@tie{}@var{c}
+creates a formatter object
+that is recognized like any other ordinary,
+special,
+or indexed character on input,
+and produces
+@var{contents}
+on output.
+When
+formatting
+@var{c},
+GNU
+@command{troff} @c GNU
+processes
+@var{contents}
+in a temporary environment and enscapsulates the result
+in a node;@footnote{@xref{Gtroff Internals}.}
+disabling compatibility mode
+and setting the escape character
+to@tie{}@code{\}
+while interpreting
+@var{contents}.
+Any emboldening,
+constant spacing,
+or track kerning applies to this object
+rather than to individual glyphs resulting from the formatting of
+@var{contents}.
@c TODO: Document Peter Schaffter's diversion-as-character trick.
@c https://lists.gnu.org/archive/html/groff/2024-12/msg00085.html
@@ -11862,9 +11883,15 @@ a user-defined character
does not participate at its boundaries
in kerning adjustments or italic corrections.
-There is a special anti-recursion feature: use of the object within its
-own definition is handled like a normal character (not
-defined with @code{char}).
+The formatter prevents infinite recursion
+by treating an occurrence
+of a character in its own definition
+as if were undefined;
+when interpolating such a character,
+GNU
+@command{troff} @c GNU
+emits a warning in category @samp{char}.@footnote{Mutually recursive
+character definitions are handled similarly.}
The @code{tr} and @code{trin} requests take precedence if @code{char}
accesses the same symbol.
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 27e081d38..a5b260d58 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -2143,36 +2143,39 @@ Defining
(or redefining)
a
.RI character\~ c
-creates a formatter object that is recognized like any other
-ordinary or special character on input,
+creates a formatter object
+that is recognized like any other ordinary,
+special,
+or indexed character on input,
and produces
.I contents
on output.
.
-Every time
-.I c
-is to be output,
+When
+formatting
+.IR c ,
+GNU
+.I troff \" GNU
+processes
.I contents
-is processed in a temporary environment and the result encapsulated in a
-node.
-.
-(See section \[lq]Gtroff Internals\[rq] in
+in a temporary environment and encapsulates the result
+in a node
+(see section \[lq]Gtroff Internals\[rq] in
.IR "Groff: The GNU Implementation of troff" ,
the
.I groff
-Texinfo manual.)
-.
-Compatibility mode is disabled and the escape character set
+Texinfo manual);
+disabling compatibility mode
+and setting the escape character to
.RB to\~ \[rs]
-while
-.I contents
-is processed.
+while interpreting
+.I contents.
.
Any emboldening,
constant spacing,
-or track kerning is applied to this object as a whole,
-not to each character in
-.IR contents .
+or track kerning applies to this object
+rather than to individual glyphs resulting from the formatting of
+.I contents.
.
.
.IP
@@ -2211,13 +2214,19 @@ in kerning adjustments or italic corrections.
.
.
.IP
-To prevent infinite recursion,
-occurrences of
-.I c
-within its own definition are treated normally
-(as if it were not being defined with
-.BR char ).
+The formatter prevents infinite recursion
+by treating an occurrence
+of a character in its own definition
+as if were undefined;
+when interpolating such a character,
+GNU
+.I troff \" GNU
+emits a warning in category
+.RB \[lq] char \[rq].
+(Mutually recursive character definitions are handled similarly.)
.
+.
+.IP
The
.B tr
and
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
