gbranden pushed a commit to branch master in repository groff. commit 05b804f05583e8675e9c5df812c3ca0f89721cb7 Author: G. Branden Robinson <g.branden.robin...@gmail.com> AuthorDate: Mon Apr 24 07:50:18 2023 -0500
[docs]: Tweak escape/control character discussion. * Introduce term "ordinary character", an input character that is not invalid (cf. "special character"). * Recast discussion of control, no-break control, and escape control characters in terms of ordinary characters, ruling out the surmise that a special character can serve as any of these. * Parallelize wording of these. * Tighten and align wording with this terminology. --- doc/groff.texi | 68 ++++++++++++++++++++++++++++----------------------------- man/groff.7.man | 63 +++++++++++++++++++++++++++------------------------- 2 files changed, 67 insertions(+), 64 deletions(-) diff --git a/doc/groff.texi b/doc/groff.texi index b0ef7a91e..abedde37f 100644 --- a/doc/groff.texi +++ b/doc/groff.texi @@ -6360,12 +6360,14 @@ not qualify, so our first attempt got a warning. @section Identifiers @cindex identifiers -GNU @code{troff} has rules for properly formed -@dfn{identifiers}---labels for objects with syntactical importance, like -registers, names (macros, strings, or diversions), typefaces, glyphs, -colors, character classes, environments, and streams. An identifier -consists of one or more characters excepting spaces, tabs, newlines, and -invalid input characters. +An @dfn{identifier} is a label for an object of syntactical +importance:@: a register, name (macro, string, or diversion), typeface, +color, special character, character class, environment, or stream. +Valid identifiers consist of one or more ordinary characters. +@cindex ordinary character +@cindex character, ordinary +An @slanted{ordinary character} is an input character that is not a +leader, tab, newline, or invalid as GNU @code{troff} input. @c XXX: We might move this discussion earlier since it is applicable to @c troff input in general, and include a reference to the `trin` @@ -6403,11 +6405,10 @@ these ranges.@footnote{Consider what happens when a C1 control @code{0x80}--@code{0x9F} is necessary as a continuation byte in a UTF-8 sequence.} -The identifiers @samp{br}, @samp{PP}, @samp{end-list}, +Thus, the identifiers @samp{br}, @samp{PP}, @samp{end-list}, @samp{ref*normal-print}, @samp{|}, @samp{@@_}, and @samp{!"#$%'()*+,-./} are all valid. Discretion should be exercised to prevent confusion. -Some care is required with identifiers starting with @samp{(} or -@samp{[}. +Identifiers starting with @samp{(} or @samp{[} require care. @Example .nr x 9 @@ -6585,24 +6586,25 @@ invoke requests that don't cause breaks is harmless but poor style. @cindex no-break control character, changing (@code{c2}) @cindex character, no-break control, changing (@code{c2}) @cindex control character, no-break, changing (@code{c2}) -The control character @samp{.} and the no-break control character -@samp{'} can be changed with the @code{cc} and @code{c2} requests, -respectively. +The control @samp{.} and no-break control @samp{'} characters can each +be changed to any ordinary character@footnote{Recall @ref{Identifiers}.} +with the @code{cc} and @code{c2} requests, respectively. + +@Defreq {cc, [@Var{o}]} +Recognize the ordinary character@tie{}@var{o} as the control character. +If@tie{}@var{o} is absent or invalid, the default control character +@samp{.} is selected. The identity of the control character is +associated with the environment (@pxref{Environments}). +@endDefreq -@Defreq {cc, [@Var{c}]} -Set the control character to@tie{}@var{c}. With no argument, the -default control character @samp{.} is restored. The identity of the +@Defreq {c2, [@Var{o}]} +Recognize the ordinary character@tie{}@var{o} as the no-break control +character. If@tie{}@var{o} is absent or invalid, the default no-break +control character @samp{'} is selected. The identity of the no-break control character is associated with the environment (@pxref{Environments}). @endDefreq -@Defreq {c2, [@Var{c}]} -Set the no-break control character to@tie{}@var{c}. With no argument, -the default no-break control character @samp{'} is restored. The -identity of the no-break control character is associated with the -environment (@pxref{Environments}). -@endDefreq - When writing a macro, you might wish to know which control character was used to call it. @@ -6949,11 +6951,12 @@ invoked, no input character is recognized as starting an escape sequence in interpretation mode. @endDefreq -@Defreq {ec, [@Var{c}]} +@Defreq {ec, [@Var{o}]} @cindex escape character, changing (@code{ec}) @cindex character, escape, changing (@code{ec}) -Recognize@tie{}@var{c} as the escape character. If@tie{}@var{c} is -absent or invalid, the default escape character @samp{\} is selected. +Recognize the ordinary character@tie{}@var{o} as the escape character. +If@tie{}@var{o} is absent or invalid, the default escape character +@samp{\} is selected. Changing the escape character globally likely breaks macro packages, since GNU @code{troff} has no mechanism to ``intern'' macros, that is, @@ -10742,8 +10745,8 @@ are translated on input to the special character escape sequences @code{\[aa]}, @code{\[-]}, @code{\[ul]}, and @code{\[ga]}, respectively. A special character name of length one is not the same thing as an -ordinary input character: that is, the character @code{a} is not the -same as @code{\[a]}. +ordinary character: that is, the character @code{a} is not the same as +@code{\[a]}. If @var{name} is undefined, a warning in category @samp{char} is produced and the escape is ignored. @xref{Warnings}, for information @@ -12533,13 +12536,10 @@ termed @dfn{conditional expressions}. @table @code @item c @var{glyph} -True if @var{glyph} is available, where @var{glyph} is -@c TODO: "an ordinary character", after we update the section "Fonts and -@c Symbols" to better parallelize it with groff_char(7). -a Unicode basic Latin character, a GNU @code{troff} special character -@samp{\(@var{xx}} or @samp{\[@var{xxx}]}, @samp{\N'@var{xxx}'}, or has -been defined by any of the @code{char}, @code{fchar}, @code{fschar}, or -@code{schar} requests. +True if @var{glyph} is available, where @var{glyph} is an ordinary +character, a special character @samp{\(@var{xx}} or @samp{\[@var{xxx}]}, +@samp{\N'@var{xxx}'}, or has been defined by any of the @code{char}, +@code{fchar}, @code{fschar}, or @code{schar} requests. @item d @var{name} True if a string, macro, diversion, or request called @var{name} exists. diff --git a/man/groff.7.man b/man/groff.7.man index 8c50052bc..07944567d 100644 --- a/man/groff.7.man +++ b/man/groff.7.man @@ -1254,28 +1254,29 @@ containing them is surrounded by parentheses. .\" ==================================================================== . .\" BEGIN Keep (roughly) parallel with groff.texi node "Identifiers". -GNU +An identifier is a label for an object of syntactical importance: +a register, +name +(macro, +string, +or diversion), +typeface, +color, +special character, +character class, +environment, +or stream. +. +Valid identifiers consist of one or more ordinary characters. +. +An +.I ordinary character +is an input character that is not a leader, +tab, +newline, +or invalid as GNU .I troff \" GNU -has rules for properly formed -.IR identifiers \[em]labels -for objects with syntactical importance, -like registers, -names -(macros, -strings, -or diversions), -typefaces, -glyphs, -colors, -character classes, -environments, -and streams. -. -An identifier consists of one or more characters excepting -spaces, -tabs, -newlines, -and invalid input characters. +input. . . .\" XXX: We might move this discussion earlier since it is applicable to @@ -2577,9 +2578,10 @@ Reset no-break control character to .dquoted_char \[aq] . . .TPx -.REQ .c2 "c" -Set no-break control character to -.IR c . +.REQ .c2 "o" +Recognize ordinary character +.I o +as the no-break control character. . .TPx .REQ .cc @@ -2587,9 +2589,10 @@ Reset control character to .squoted_char . . . .TPx -.REQ .cc "c" -Set control character to -.IR c . +.REQ .cc "o" +Recognize ordinary character +.I o +as the control character. . .TPx .REQ .ce @@ -2951,9 +2954,9 @@ as the escape character. . . .TPx -.REQ .ec "c" -Recognize -.I c +.REQ .ec "o" +Recognize ordinary character +.I o as the escape character. . . _______________________________________________ Groff-commit mailing list Groff-commit@gnu.org https://lists.gnu.org/mailman/listinfo/groff-commit