gbranden pushed a commit to branch master
in repository groff.
commit fed12ee7f720ea32c466bf3ad57af1a4b49157b7
Author: G. Branden Robinson <[email protected]>
AuthorDate: Fri Dec 5 07:31:43 2025 -0600
[doc,man]: Revise `class` request description.
* De-document class nesting. It doesn't work. See Savannah #67770.
* Recast.
* Sync discussions and input line breaks between our Texinfo manual and
man pages.
---
doc/groff.texi.in | 157 +++++++++++++++++++++++++++++++--------------------
man/groff.7.man | 21 +++++--
man/groff_diff.7.man | 80 +++++++++++---------------
3 files changed, 147 insertions(+), 111 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 631305bd9..140b94019 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -12636,80 +12636,117 @@ can operate on character classes.
@c including interpolation,
@c is an error.
-@Defreq {class, name c1 c2 @dots{}}
+@Defreq {class, ident c @dots{}}
@cindex character class (@code{class})
@cindex defining character class (@code{class})
@cindex class of characters (@code{class})
-Define a character class (or simply ``class'') @var{name} comprising
-the characters @var{c1}, @var{c2}, and so on.
-
-A class thus defined can then be referred to in lieu of listing all the
-characters within it. Currently, only the @code{cflags} request can
-handle references to character classes.
-
-In the request's simplest form, each @var{cn} is a character (or special
-character).
+Define a character class
+(or simply ``class'')
+@var{ident}
+comprising the members
+@var{c}
+@dots{},
+where each
+@var{c}
+is an
+ordinary,
+special,
+or
+indexed
+character;
+or a
+@slanted{range expression}.
+A class thus defined can then be referred to
+in a
+@code{cflags}
+request in lieu of listing all the characters within it.
@Example
.class [quotes] ' \[aq] \[dq] \[oq] \[cq] \[lq] \[rq]
@endExample
-Since class and glyph names share the same name space, it is recommended
-to start and end the class name with @code{[} and @code{]},
-respectively, to avoid collisions with existing character names defined
-by GNU @code{troff} or the user (with @code{char} and related requests).
-This practice applies the presence of @code{]} in the class name to
+Since class and special character names share the same name space,
+we recommend starting and ending the class name with
+@samp{[}
+and
+@samp{]},
+respectively,
+to avoid collisions with existing special character names defined by
+GNU
+@command{troff} @c GNU
+or the user
+(with
+@code{char}
+and related requests).
+This practice applies the presence of
+@samp{]}
+in the class name to
prevent the use of the special character escape form
-@code{\[@r{@dots{}}]}, thus you must use the @code{\C} escape to access
-a class with such a name.
+@samp{\[@r{@dots{}}]},
+you must therefore access a class thus named via the
+@code{\C}
+escape sequence.
@cindex GGL (@code{groff} glyph list)
@cindex @code{groff} glyph list (GGL)
-You can also use a character range notation consisting of a
-start character followed by @samp{-} and then an end character.
-Internally, GNU @code{troff} converts these two symbol names to
-Unicode code points (according to the @code{groff} glyph list [GGL]),
-which then give the start and end value of the range. If that fails,
-the class definition is skipped.
-
-Furthermore, classes can be nested.
-
-@Example
-.class [prepunct] , : ; > @}
-.class [prepunctx] \C'[prepunct]' \[u2013]-\[u2016]
-@endExample
-
-@noindent
-The class @samp{[prepunctx]} thus contains the contents of the class
-@code{[prepunct]} as defined above (the set @samp{, : ; > @}}), and
-characters in the range between @code{U+2013} and @code{U+2016}.
-
-If you want to include @samp{-} in a class, it must be the first
-character value in the argument list, otherwise it gets misinterpreted
-as part of the range syntax.
-
-It is not possible to use class names as end points of range
-definitions.
-
-Typically,
-one sets up a character class
-to then apply breaking and hyphenation properties
-to it with the
-@code{cflags}
-request.
-For example,
-to inhibit line breaks before the characters belonging
-to the
-@samp{prepunctx}
-class defined in the previous example,
-you can write the following.
+An argument
+@var{c}
+can alternatively be a
+@dfn{range expression}
+consisting of a start character followed by
+@samp{-}
+and then an end character.
+Internally,
+GNU
+@command{troff} @c GNU
+converts these two symbol names to Unicode code points
+(according to the
+@code{groff}
+glyph list [GGL]),
+which determine the start and end values of the range.
+If that conversion fails,
+GNU
+@command{troff} @c GNU
+skips the range expression and any remaining arguments.
+@c
+@c Furthermore, classes can be nested.
+@c
+@c @Example
+@c .class [prepunct] , : ; > @}
+@c .class [prepunctx] \C'[prepunct]' \[u2013]-\[u2016]
+@c @endExample
+@c
+@c @noindent
+@c The class @samp{[prepunctx]} thus contains the contents of the class
+@c @code{[prepunct]} as defined above (the set @samp{, : ; > @}}), and
+@c characters in the range between @code{U+2013} and @code{U+2016}.
-@Example
-.cflags 2 \C'[prepunctx]'
-@endExample
+If you want to include
+@samp{-}
+in a class,
+it must be the first character in a
+@var{c}
+argument;
+otherwise
+GNU
+@command{troff} @c GNU
+interprets the argument
+as a range expression.
-@noindent
-See the @code{cflags} request in @ref{Using Symbols}, for more details.
+@c
+@c For example,
+@c to inhibit line breaks before the characters belonging
+@c to the
+@c @samp{prepunctx}
+@c class defined in the previous example,
+@c you can write the following.
+@c
+@c @Example
+@c .cflags 2 \C'[prepunctx]'
+@c @endExample
+@c
+@c @noindent
+@c See the @code{cflags} request in @ref{Using Symbols}, for more details.
@endDefreq
@c ---------------------------------------------------------------------
diff --git a/man/groff.7.man b/man/groff.7.man
index 08b12b861..909c48c6f 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -3120,13 +3120,26 @@ or diversion
.I name.
.
.TPx
-.REQ .class "ident c1 c2 \fR\&.\|.\|.\&\fP"
+.REQ .class "ident c \fR\&.\|.\|.\&\fP"
Define a (character) class
.I ident
comprising the characters or range expressions
-.IR c1 ,
-.IR c2 ,
-and so on.
+.IR c ,
+where each
+.I c
+is an
+ordinary,
+special,
+or
+indexed
+character;
+or a
+.I "range expression."
+.
+A class thus defined can then be referred to
+in a
+.B \%cflags
+request in lieu of listing all the characters within it.
.
.TPx
.REQ .close stream
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 703432cd5..9c6bd788b 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -2553,21 +2553,23 @@ for discussion of nodes inserted by
Define a character class
(or simply \[lq]class\[rq])
.I ident
-comprising the characters or range expressions
-.I c.
-.
-A class thus defined can then be referred to in lieu of listing all the
-characters within it.
-.
-Currently,
-only the
-.B cflags
-request can handle references to character classes.
-.
-In the request's simplest form,
-each
+comprising the members
+.IR c \&.\|.\|.,
+where each
.I c
-is an ordinary or special character.
+is an
+ordinary,
+special,
+or
+indexed
+character;
+or a
+.I "range expression."
+.
+A class thus defined can then be referred to
+in a
+.B \%cflags
+request in lieu of listing all the characters within it.
.
.
.IP
@@ -2577,8 +2579,9 @@ we recommend starting and ending the class name with
and
.RB \[lq] ] \[rq],
respectively,
-to avoid collisions with existing character names defined by
-.I groff
+to avoid collisions with existing special character names defined by
+GNU
+.I troff \" GNU
or the user
(with
.B char
@@ -2589,14 +2592,17 @@ This practice applies the presence of
in the class name to prevent the usage of the special character escape
form
.RB \[lq] \[rs][ .\|.\|. ] \[rq],
-thus you must use the
+you must therefore access a class thus named via the
.B \[rs]C
-escape sequence to access a class with such a name.
+escape sequence.
.
.
.IP
-You can also use a character range expression consisting of a start
-character followed by
+An argument
+.I c
+can alternatively be a
+.I "range expression"
+consisting of a start character followed by
.RB \[lq] \- \[rq]
and then an end character.
.
@@ -2609,33 +2615,13 @@ converts these two character names to Unicode code
points
glyph list [GGL]),
which determine the start and end values of the range.
.
-If that fails,
-the class definition is skipped.
-.
-Furthermore,
-classes can be nested.
-.
-.
-.IP
-If you want to include
-.RB \[lq] \- \[rq]
-in a class,
-it must be the first character value in the argument list,
-otherwise it gets misinterpreted as part of the range syntax.
-.
-.
-.IP
-It is not possible to use class names as end points of range
-definitions.
-.
-.
-.IP
-Typically,
-one sets up a character class
-to then apply breaking and hyphenation properties
-to it with the
-.B \%cflags
-request.
+If that conversion fails,
+GNU
+.I troff \" GNU
+skips the range expression and any remaining arguments.
+.\" .
+.\" Furthermore,
+.\" classes can be nested.
.
.
.TP
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
