[groff] 02/02: Rework .cflags and .class documentation.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 4bf4c3421de3f4ece5ce1e3ef998cef92e33ea4a
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Jun 11 20:37:21 2020 +1000

    Rework .cflags and .class documentation.
    
    * doc/groff.texi (Using Symbols, Character Classes):
      + Make the lead sentence of the request definition a summary of what
        the request does instead of building up to it with conceptual
        background.
      + Avoid use of the term "symbols" to refer to characters and special
        characters.  I'm wary of the term "symbol" being overloaded.
      + Say "GNU troff" instead of "gtroff".
      + Tighten wording in places, and use more idiomatic English.
      (Using Symbols):
      + Bracket .cflags and .class request definitions in @codequotebacktick
        @codequoteundirected so examples render correctly.
      + Make the lead sentence of the request definition a summary of what
        the request does instead of building up to it with conceptual
        background.
      + Avoid use of the term "symbols" to refer to characters and special
        characters.  I'm wary of the term "symbol" being overloaded.
      + Avoid use of the term "input level" (cf. output level) because the
        concept is not the input level discussed in "Gtroff Internals".
      + Clarify parametric description of a glyph.  The existing wording
        sounded like a definition of a three-dimensional object in common
        parlance (height, width, depth).
      + Note that the cflags value is non-negative and that some
        combinations are meaningless; provide an example.
      + Use imperative mood in descriptions of character flag values.
      + Move lists of characters initially bearing the various flags to the
        ends of the paragraphs describing them.
      + Explain "overlapping" flags more clearly.
      + Use groff character escape style in .cflags examples ('\[en]', not
        '\(en').
      + Interrupt table to note flag values that were developed for East
        Asial language support.
      (Character Classes):
      + Introduce independent example of a simple character class
        ("[quotes]") to develop the topic more gently.  Move existing
        example into later one which depends on it.
    
    * man/groff_diff.7.man:
      + (Escape sequences/'\)'): Use leading dot in reference to .cflags
        request.
      + (New requests/{.cflags,.class}): Paralellize descriptions with
        Texinfo manual.
    
    * man/groff.7.man (Request short reference):
      + Parallelize one-sentence descriptions of .cflags and .class with
        groff_diff(7).
---
 doc/groff.texi       | 191 +++++++++++++++-------------
 man/groff.7.man      |  19 ++-
 man/groff_diff.7.man | 347 ++++++++++++++++++++++++++++++++++++++++++---------
 3 files changed, 403 insertions(+), 154 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 29b435a..bc8e3fd 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -9214,46 +9214,53 @@ This is the same as @code{\[-]}, the minus sign in the 
current font.
 This is the same as @code{\[ul]}, the underline character.
 @endDefesc
 
+@codequotebacktick on
+@codequoteundirected on
 @Defreq {cflags, n c1 c2 @dots{}}
 @cindex glyph properties (@code{cflags})
 @cindex character properties (@code{cflags})
 @cindex properties of glyphs (@code{cflags})
 @cindex properties of characters (@code{cflags})
-Input characters and symbols have certain properties associated with
-it.@footnote{Note that the output glyphs themselves don't have such
-properties.  For @code{gtroff}, a glyph is a numbered box with a given
-width, depth, and height, nothing else.  All manipulations with the
-@code{cflags} request work on the input level.}  These properties can be
-modified with the @code{cflags} request.  The first argument is the sum
-of the desired flags and the remaining arguments are the characters or
-symbols to have those properties.  It is possible to omit the spaces
-between the characters or symbols.  Instead of single characters or
-symbols you can also use character classes (see @ref{Character Classes}
-for more details).
+Assign properties encoded by the number @var{n} to characters @var{c1},
+@var{c2}, and so on.
+
+Input characters, including special characters introduced by an escape,
+have certain properties associated with them.@footnote{Note that output
+glyphs don't have such properties.  For GNU @code{troff}, a glyph is a
+numbered box with a given height above and depth below the baseline, and
+a width---nothing more.}  These properties can be modified with this
+request.  The first argument is the sum of the desired flags and the
+remaining arguments are the characters to be assigned those properties.
+Spaces between the @var{cn} arguments are optional.  Any argument
+@var{cn} can be a character class defined with the @code{class} request
+rather than an individual character.  @xref{Character Classes}.
+
+The non-negative integer @var{n} is the sum of any of the following.
+Some combinations are nonsensical, such as @samp{33} (1 + 32).
 
 @table @code
 @item 1
 @cindex end-of-sentence characters
 @cindex characters, end-of-sentence
-The character ends sentences (initially characters @samp{.?!} have this
-property).
+Recognize the character as ending a sentence if followed by a newline
+or two spaces.  Initially, characters @samp{.?!} have this property.
 
 @item 2
 @cindex hyphenating characters
 @cindex characters, hyphenation
-Lines can be broken before the character (initially no characters have
-this property).  This only works if both the characters before and after
-have non-zero hyphenation codes (as set with the @code{hcode} request).
-Use value@tie{}64 to override this behaviour.
+Enable breaks before the character.  A line is not broken at a character
+with this property unless the characters on each side both have non-zero
+hyphenation codes.  This exception can be overridden by adding 64.
+Initially, no characters have this property.
 
 @item 4
+@cindex @code{\-} glyph, and @code{cflags}
 @cindex @code{hy} glyph, and @code{cflags}
 @cindex @code{em} glyph, and @code{cflags}
-Lines can be broken after the character (initially the character
-@samp{-} and the symbols @samp{\[hy]} and @samp{\[em]} have this
-property).  This only works if both the characters before and after have
-non-zero hyphenation codes (as set with the @code{hcode} request).  Use
-value@tie{}64 to override this behaviour.
+Enable breaks after the character.  A line is not broken at a character
+with this property unless the characters on each side both have non-zero
+hyphenation codes.  This exception can be overridden by adding 64.
+Initially, characters @samp{\-\[hy]\[em]} have this property.
 
 @item 8
 @cindex overlapping characters
@@ -9263,15 +9270,15 @@ value@tie{}64 to override this behaviour.
 @cindex @code{ru} glyph, and @code{cflags}
 @cindex @code{radicalex} glyph, and @code{cflags}
 @cindex @code{sqrtex} glyph, and @code{cflags}
-The character overlaps horizontally if used as a horizontal line
-building element.  Initially the symbols @samp{\[ul]}, @samp{\[rn]},
-@samp{\[ru]}, @samp{\[radicalex]}, and @samp{\[sqrtex]} have this
-property.
+Mark the glyph associated with this character as overlapping other
+instances of itself horizontally.  Initially, characters
+@samp{\[ul]\[rn]\[ru]\[radicalex]\[sqrtex]} have this property.
 
 @item 16
 @cindex @code{br} glyph, and @code{cflags}
-The character overlaps vertically if used as vertical line building
-element.  Initially symbol @samp{\[br]} has this property.
+Mark the glyph associated with this character as overlapping other
+instances of itself vertically.  Initially, the character @samp{\[br]}
+has this property.
 
 @item 32
 @cindex transparent characters
@@ -9285,22 +9292,23 @@ element.  Initially symbol @samp{\[br]} has this 
property.
 @cindex @code{dd} glyph, at end of sentence
 @cindex @code{rq} glyph, at end of sentence
 @cindex @code{cq} glyph, at end of sentence
-An end-of-sentence character followed by any number of characters with
-this property is treated as the end of a sentence if followed by a
-newline or two spaces; in other words the character is @dfn{transparent}
-for the purposes of end-of-sentence recognition---this is the same as
-having a zero space factor in @TeX{} (initially characters @samp{"')]*}
-and the symbols @samp{\[dg]}, @samp{\[dd]}, @samp{\[rq]}, and
-@samp{\[cq]} have this property).
+Mark the character as transparent for the purpose of end-of-sentence
+recognition.  In other words, an end-of-sentence character followed by
+any number of characters with this property is treated as the end of a
+sentence if followed by a newline or two spaces.  This is the same as
+having a zero space factor in @TeX{}.  Initially, characters
+@samp{"')]*\[dg]\[dd]\[rq]\[cq]} have this property.
 
 @item 64
 Ignore hyphenation code values of the surrounding characters.  Use this
-in combination with values 2 and@tie{}4 (initially no characters have
-this property).  For example, if you need an automatic break point after
-the en-dash in number ranges like `3000--5000', insert
+in combination with values 2 and@tie{}4 (initially, no characters have
+this property).
+
+For example, if you need an automatic break point after the en-dash in
+numerical ranges like ``3000--5000'', insert
 
 @Example
-.cflags 68 \(en
+.cflags 68 \[en]
 @endExample
 
 @noindent
@@ -9308,32 +9316,39 @@ into your document.  Note, however, that this can lead 
to bad layout if
 done without thinking; in most situations, a better solution instead of
 changing the @code{cflags} value is to insert @code{\:} right after the
 hyphen at the places that really need a break point.
+@end table
+
+The remaining values were implemented for East Asian language support;
+those who use alphabetic scripts exclusively can disregard them.
 
+@table @code
 @item 128
 Prohibit a line break before the character, but allow a line break after
 the character.  This works only in combination with flags 256 and 512
-(see below) and has no effect otherwise.  Initially no characters have
-this property.
+and has no effect otherwise.  Initially, no characters have this
+property.
 
 @item 256
 Prohibit a line break after the character, but allow a line break before
 the character.  This works only in combination with flags 128 and 512
-(see below) and has no effect otherwise.  Initially no characters have
-this property.
+and has no effect otherwise.  Initially, no characters have this
+property.
 
 @item 512
 Allow line break before or after the character.  This works only in
 combination with flags 128 and 256 and has no effect otherwise.
-Initially no characters have this property.
+Initially, no characters have this property.
+@end table
 
-Contrary to flag values 2 and@tie{}4, the flags 128, 256, and 512 work
+In contrast to values 2 and@tie{}4, the values 128, 256, and 512 work
 pairwise.  If, for example, the left character has value 512, and the
-right character 128, no line break gets inserted.  If we use
-value@tie{}6 instead for the left character, a line break after the
-character can't be suppressed since the right neighbour character
-doesn't get examined.
-@end table
+right character 128, no break will be automatically inserted between
+them.  If we use value@tie{}6 instead for the left character, a break
+after the character can't be suppressed since the neighboring character
+on the right doesn't get examined.
 @endDefreq
+@codequotebacktick off
+@codequoteundirected off
 
 @DefreqList {char, g [@Var{string}]}
 @DefreqItemx {fchar, g [@Var{string}]}
@@ -9414,8 +9429,7 @@ Finally, the @code{schar} request defines a global 
fallback glyph:
 of fonts declared as global special fonts with the @code{special}
 request, but before the already mounted special fonts.
 
-@xref{Using Symbols}, for a detailed description of the glyph searching
-mechanism in @code{gtroff}.
+@xref{Character Classes}.
 @endDefreq
 
 @DefreqList {rchar, c1 c2 @dots{}}
@@ -9442,74 +9456,83 @@ The request @code{rfschar} removes glyph definitions 
defined with
 @cindex character classes
 @cindex classes, character
 
+@codequotebacktick on
+@codequoteundirected on
 Classes are particularly useful for East Asian languages such as
 Chinese, Japanese, and Korean, where the number of needed characters is
 much larger than in European languages, and where large sets of
 characters share the same properties.
 
-@Defreq {class, n c1 c2 @dots{}}
+@Defreq {class, name c1 c2 @dots{}}
 @cindex character class (@code{class})
 @cindex defining character class (@code{class})
 @cindex class of characters (@code{class})
-In @code{groff}, a @dfn{character class} (or simply ``class'') is a set
-of characters, grouped by some user aspect.  The @code{class} request
-defines such classes so that other requests can refer to all characters
-belonging to this set with a single class name.  Currently, only the
-@code{cflags} request can handle character classes.
+Define a character class (or simply ``class'') @var{name} comprising
+the characters @var{c1}, @var{c2}, and so on.
 
-A @code{class} request takes a class name followed by a list of
-entities.  In its simplest form, the entities are characters or symbols:
+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).
 
 @Example
-.class [prepunct] , : ; > @}
+.class [quotes] ' \[rs] \[dq] \[oq] \[cq] \[lq] \[rq]
 @endExample
 
 Since class and glyph names share the same namespace, it is recommended
 to start and end the class name with @code{[} and @code{]},
-respectively, to avoid collisions with normal @code{groff} symbols (and
-symbols defined by the user).  In particular, the presence of @code{]}
-in the symbol name intentionally prevents the usage of @code{\[...]},
-thus you must use the @code{\C} escape to access a class with such a
-name.
+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
+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.
 
 @cindex GGL (groff glyph list)
 @cindex groff glyph list (GGL)
-You can also use a special character range notation, consisting of a
-start character or symbol, followed by @samp{-}, and an end character or
-symbol.  Internally, @code{gtroff} converts these two symbol names to
-Unicode values (according to the groff glyph gist), which then give the
-start and end value of the range.  If that fails, the class definition
-is skipped.
+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 groff glyph list [GGL]), which
+then give the start and end value of the range.  If that fails, the
+class definition is skipped.
 
-Finally, classes can be nested, too.
-
-Here is a more complex example:
+Furthermore, classes can be nested.
 
 @Example
+.class [prepunct] , : ; > @}
 .class [prepunctx] \C'[prepunct]' \[u2013]-\[u2016]
 @endExample
 
-The class @samp{prepunctx} now contains the contents of the class
-@code{prepunct} as defined above (the set @samp{, : ; > @}}), and
+@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 add @samp{-} to a class, it must be the first character
-value in the argument list, otherwise it gets misinterpreted as a range.
+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.
 
-Note that it is not possible to use class names within range
+Note that it is not possible to use class names as end points of range
 definitions.
 
-Typical use of the @code{class} request is to control line-breaking and
-hyphenation rules as defined by the @code{cflags} request.  For example,
-to inhibit line breaks before the characters belonging to the
-@code{prepunctx} class, you can write:
+A typical use of the @code{class} request is to control line-breaking
+and hyphenation rules as defined by the @code{cflags} request.  For
+example, to inhibit line breaks before the characters belonging to the
+@code{prepunctx} class defined in the previous example, you can write
+the following.
 
 @Example
 .cflags 2 \C'[prepunctx]'
 @endExample
 
+@noindent
 See the @code{cflags} request in @ref{Using Symbols}, for more details.
 @endDefreq
+@codequoteundirected off
+@codequotebacktick off
 
 @c ---------------------------------------------------------------------
 
diff --git a/man/groff.7.man b/man/groff.7.man
index e548d73..2a54682 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -1391,14 +1391,13 @@ Copy contents of file
 unprocessed to stdout or to the diversion.
 .
 .TPx
-.REQ .cflags "mode c1 c2 \fR\&.\|.\|.\&\fP"
-Treat characters
+.REQ .cflags "n c1 c2 \fR\&.\|.\|.\&\fP"
+Assign properties encoded by the number
+.I n
+to characters
 .IR c1 ,
 .IR c2 ,
-\&.\|.\|.\&
-according to
-.I mode
-number.
+and so on.
 .
 .TPx
 .REQ .ch "trap N"
@@ -1422,12 +1421,12 @@ Chop the last character off macro, string, or diversion
 .
 .TPx
 .REQ .class "name c1 c2 \fR\&.\|.\|.\&\fP"
-Assign a set of characters, character ranges, or classes
+Define a (character) class
+.I name
+comprising the characters or range expressions
 .IR c1 ,
 .IR c2 ,
-\&.\|.\|.\&
-to
-.IR name .
+and so on.
 .
 .TPx
 .REQ .close "stream"
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index fd0fd51..cec431d 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -752,7 +752,7 @@ request.
 Like
 .B \[rs]&
 except that it behaves like a character declared with the
-.B cflags
+.B .cflags
 request to be transparent for the purposes of end-of-sentence
 recognition.
 .
@@ -1124,90 +1124,202 @@ This is the same as
 .BR \[rs]p .
 .
 .TP
-.BI .cflags\~ "n c1 c2 \*[ellipsis]"
-Characters
+.BI .cflags\~ "n c1 c2"\c
+\~\*[ellipsis]
+Assign properties encoded by the number
+.I n
+to characters
 .IR c1 ,
 .IR c2 ,
-.IR \*[ellipsis] ,
-have properties determined by
-.IR n ,
-which is ORed from the following:
+and so on.
+.
+.IP
+Input characters,
+including special characters introduced by an escape,
+have certain properties associated with them.
+.
+(Note that output glyphs don't have such properties.
+.
+In
+.IR groff ,
+a glyph is a numbered box with a given height above and depth below the 
baseline, and
+a width\[em]nothing more.)
+.
+These properties can be modified with this request.
+.
+The first argument is the sum of the desired flags and the remaining
+arguments are the characters to be assigned those properties.
+.
+Spaces between the
+.I cn
+arguments are optional.
+.
+Any argument
+.I cn
+can be a character class defined with the
+.B .class
+request rather than an individual character.
+.
+.IP
+The non-negative integer
+.I n
+is the sum of any of the following.
+.
+Some combinations are nonsensical,
+such as
+.RB \[lq] 33 \[rq]
+(1 + 32).
 .
 .RS
 .IP 1
-The character ends sentences (initially characters
-.B .?!\&
-have this property).
+Recognize the character as ending a sentence if followed by a newline
+or two spaces.
+.
+Initially,
+characters
+.RB \[lq] .?! \[rq]
+have this property.
 .
 .IP 2
-Lines can be broken before the character (initially no characters have
-this property); a line is not broken at a character with this property
-unless the characters on each side both have non-zero hyphenation
-codes.
-This can be overridden with value 64.
+Enable breaks before the character.
+.
+A line is not broken at a character with this property unless the
+characters on each side both have non-zero hyphenation codes.
+.
+This exception can be overridden by adding 64.
+.
+Initially,
+no characters have this property.
 .
 .IP 4
-Lines can be broken after the character (initially characters
-.B \-\[rs][hy]\[rs][em]
-have this property); a line is not broken at a character with this
-property unless the characters on each side both have non-zero
-hyphenation codes.
-This can be overridden with value 64.
+Enable breaks after the character.
+.
+A line is not broken at a character with this property unless the
+characters on each side both have non-zero hyphenation codes.
+.
+This exception can be overridden by adding 64.
+.
+Initially,
+characters
+.RB \[lq] \-\[rs][hy]\[rs][em] \[rq]
+have this property.
 .
 .IP 8
-The glyph associated with this character overlaps horizontally
-(initially characters
-.B \[rs][ul]\[rs][rn]\[rs][ru]\[rs][radicalex]\[rs][sqrtex]
-have this property).
+Mark the glyph associated with this character as overlapping other
+instances of itself horizontally.
+.
+Initially,
+characters
+.RB \[lq] \[rs][ul]\[rs][rn]\[rs][ru]\[rs][radicalex]\[rs][sqrtex] \[rq]
+have this property.
 .
 .IP 16
-The glyph associated with this character overlaps vertically
-(initially glyph
-.B \[rs][br]
-has this property).
+Mark the glyph associated with this character as overlapping other
+instances of itself vertically.
+.
+Initially,
+the character
+.RB \[lq] \[rs][br] \[rq]
+has this property.
 .
 .IP 32
-An end-of-sentence character followed by any number of characters with
+Mark the character as transparent for the purpose of end-of-sentence
+recognition.
+.
+In other words,
+an end-of-sentence character followed by any number of characters with
 this property is treated as the end of a sentence if followed by a
-newline or two spaces; in other words the character is transparent for
-the purposes of end-of-sentence recognition; this is the same as having
-a zero space factor in \*[tx] (initially characters
-.B \[dq]')]*\[rs][dg]\[rs][dd]\[rs][rq]\[rs][cq]
-have this property).
+newline or two spaces.
+.
+This is the same as having a zero space factor in \*[tx].
+.
+Initially,
+characters
+.\" The following is ordered with the apostrophe and (single) closing
+.\" quote on the ends so they are more easily visually distinguished
+.\" from the double quotation marks in roman.
+.RB \[lq] '")]*\[rs][dg]\[rs][dd]\[rs][rq]\[rs][cq] \[rq]
+have this property.
 .
 .IP 64
 Ignore hyphenation code values of the surrounding characters.
-Use this in combination with values 2 and\~4 (initially no characters
-have this property).
+.
+Use this value in combination with values 2 and\~4.
+.
+Initially, no characters have this property.
+.
+.IP
+For example,
+if you need an automatic break point after
+the en-dash in numerical ranges like \[lq]3000\[en]5000\[rq],
+insert
+.RS
+.RS
+.EX
+\&.cflags 68 \[rs][en]
+.EE
+.RE
+into your document.
+.
+Note,
+however,
+that this can lead to bad layout if done without thinking;
+in most situations,
+a better solution than
+changing the
+.B .cflags
+value is inserting
+.RB \[lq]\[rs]:\[rq]
+right after the hyphen at the places that really need a break point.
+.RE
+.
+.PP
+The remaining values were implemented for East Asian language support;
+those who use alphabetic scripts exclusively can disregard them.
 .
 .IP 128
-Prohibit a line break before the character, but allow a line break after
-the character.
-This works only in combination with flags 256 and 512 and has no effect
+Prohibit a break before the character,
+but allow a break after the character.
+.
+This works only in combination with values 256 and 512 and has no effect
 otherwise.
 .
+Initially, no characters have this property.
+.
 .IP 256
-Prohibit a line break after the character, but allow a line break before
-the character.
-This works only in combination with flags 128 and 512 and has no effect
+Prohibit a break after the character,
+but allow a break before the character.
+.
+This works only in combination with values 128 and 512 and has no effect
 otherwise.
 .
+Initially, no characters have this property.
+.
 .IP 512
-Allow line break before or after the character.
-This works only in combination with flags 128 and 256 and has no effect
+Allow a break before or after the character.
+.
+This works only in combination with values 128 and 256 and has no effect
 otherwise.
+.
+Initially, no characters have this property.
 .RE
 .
 .IP
-Contrary to flag values 2 and\~4, the flags 128, 256, and 512 work
+In contrast to values 2 and\~4,
+the values 128,
+256,
+and 512 work
 pairwise.
 .
-If, for example, the left character has value 512, and the right
-character 128, no line break gets inserted.
+If,
+for example,
+the left character has value 512,
+and the right character 128,
+no break will be automatically inserted between them.
 .
-If we use value\~6 instead for the left character, a line break after
-the character can't be suppressed since the right neighbour character
-doesn't get examined.
+If we use value\~6 instead for the left character,
+a break after the character can't be suppressed since the neighboring
+character on the right doesn't get examined.
 .
 .TP
 .BI .char\~ c\~string
@@ -1278,22 +1390,137 @@ Chop the last element off macro, string, or diversion
 This is useful for removing the newline from the end of diversions
 that are to be interpolated as strings.
 .
+.
 .TP
-.BI .class\~ "name c1 c2 \*[ellipsis]"
-Assign
+.BI .class\~ "name c1 c2"\c
+\~\*[ellipsis]
+Define a character class
+(or simply \[lq]class\[rq])
 .I name
-to a set of characters
+comprising the characters or range expressions
 .IR c1 ,
 .IR c2 ,
-.IR \*[ellipsis] ,
-so that they can be referred to from other requests easily (currently
+and so on.
+.
+.IP
+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.
+.
+.IP
+In the request's simplest form,
+each
+.I cn
+is a character
+(or special character).
+.
+.RS
+.RS
+.EX
+\&.class [quotes] ' \[rs][aq] \[rs][dq] \[rs][oq] \[rs][cq] \[rs][lq] \
+\[rs][rq]
+.EE
+.RE
+.RE
+.
+.IP
+Since class and glyph names share the same namespace,
+it is recommended to start and end the class name with
+.RB \[lq] [ \[rq]
+and
+.RB \[lq] ] \[rq],
+respectively,
+to avoid collisions with existing character names defined by
+.I groff
+or the user
+(with
+.B .char
+and related requests).
+.
+This practice applies the presence of
+.RB \[lq] ] \[rq]
+in the class name to prevent the usage of the special character escape
+form
+.RB \[lq] \[rs][ .\|.\|. ] \[rq],
+thus you must use the
+.B \[rs]C
+escape to access a class with such a name.
+.
+.
+.IP
+You can also use a character range expression consisting of a start
+character followed by
+.RB \[lq] \- \[rq]
+and then an end character.
+.
+Internally,
+.I groff
+converts these two character names to Unicode code points
+(according to the
+.I groff
+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.
+.
+.RS
+.RS
+.EX
+\&.class [prepunct] , : ; > }
+\&.class [prepunctx] \[rs]C'[prepunct]' \[rs][u2013]-\[rs][u2016]
+.EE
+.RE
+The class
+.RB \[lq] [prepunctx] \[rq]
+thus contains the contents of the class
+.RB \[lq] [prepunct] \[rq]
+and characters in the range U+2013\[en]U+2016.
+.RE
+.
+.
+.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
+Note that it is not possible to use class names as end points of range
+definitions.
+.
+.
+.IP
+A typical use of the
+.B .class
+request is to control line-breaking and hyphenation rules as defined by
+the
 .B .cflags
-only).
+request.
+.
+For example,
+to inhibit line breaks before the characters belonging to the
+.RB \[lq] [prepunctx] \[rq]
+class defined in the previous example,
+you can write the following.
 .
-Character ranges (indicated by an intermediate \[oq]\-\[cq]) and
-nested classes are possible also.
+.RS
+.RS
+.EX
+\&.cflags 2 \[rs]C'[prepunctx]'
+.EE
+.RE
+.RE
 .
-This is useful to assign properties to a large set of characters.
 .
 .TP
 .BI .close\~ stream