gbranden pushed a commit to branch master
in repository groff.
commit 1a50fb97a607bcaebbd91643b29efe424ed36289
Author: G. Branden Robinson <[email protected]>
AuthorDate: Thu Jun 11 14:44:49 2026 -0500
doc/groff.texi.in: Revise special character stuff.
* Distinguish Plan 9 troff behavior from others.
* Clarify.
* Drop misleading statement.
* Favor footnotes over inlining for forward references.
* Favor @command over @code Texinfo command for referring to "troff" to
discuss the formatter's language or behavior.
* Use Texinfo `@:` command after colons, producing more *roff-like
spacing. A colon doesn't end a sentence (despite what some page page
authors think), so we want to prevent TeX from supplementing it with
inter-sentence space. (Yes, TeX does that too--a fact unnoticed by
partisans who proclaim its superiority to *roff on this very point.)
* Break input lines in convenient places for roffing and diffing.
---
doc/groff.texi.in | 104 +++++++++++++++++++++++++++++++++++-------------------
1 file changed, 68 insertions(+), 36 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 73925a38f..cc77d5842 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -13866,20 +13866,31 @@ capital letter ``A'' with a ``hook accent'' (ogonek).
There is no special syntax for one-character names---the analogous form
@samp{\@var{n}}
would collide with other escape sequences.
-A few escape sequences that are not
-special characters also produce glyphs;
-these exist for syntactical or historical reasons.
-A special character name of length one is not the same thing as an
-ordinary character: that is, the character @code{a} is not the same as
+A special character name of length one
+is not the same thing as an ordinary character:@:
+that is,
+the character
+@code{a}
+is not the same as
@code{\[a]}.
+If
+@var{name}
+is undefined,
+the formatter ignores the escape sequence.@footnote{GNU
+@command{troff} @c GNU
+emits a warning in category @samp{char}.
+Plan@tie{}9
+@command{troff}, @c Plan 9
+uniquely,
+formats
+@var{name}
+as text.}
-If @var{name} is undefined, a warning in category @samp{char} is
-produced and the escape is ignored. @xref{Warnings}, for information
-about the enablement and suppression of warnings.
-
-GNU @code{troff} resolves @code{\[@r{@dots{}}]} with more than a single
-component as follows:
+GNU
+@command{troff} resolves
+@code{\[@r{@dots{}}]}
+with multiple components (arguments) as follows.
@itemize @bullet
@item
@@ -13938,8 +13949,6 @@ but
has some advantages:@:
it is compatible with @acronym{AT&T} device-independent
@command{troff}
-(and therefore available in compatibility
-mode@footnote{@xref{Compatibility Mode}.})
and can interpolate special characters with
@samp{]}
in their names.
@@ -14011,12 +14020,20 @@ request.
@cindex unnamed glyphs
@cindex glyphs, unnamed
The code of each glyph is given in the fourth column in the font
-description file after the @code{charset} command. It is possible to
-include unnamed glyphs in the font description file by using a name of
-@samp{---}; the @code{\N} escape sequence is the only way to use these.
+description file after the
+@code{charset}
+command.
+It is possible to include unnamed glyphs in the font description file
+by using a name of
+@samp{---};
+the
+@code{\N}
+escape sequence is the only way to use these.
@endDefesc
-A few escape sequences are also special characters.
+@need 500
+A few escape sequences abbreviate special character escape sequences;
+these exist for syntactical or historical reasons.
@Defesc {\@code{'}, , , }
An escaped neutral apostrophe is a synonym for @code{\[aa]} (acute
@@ -14072,8 +14089,12 @@ such as
@item 1
@cindex end-of-sentence characters
@cindex characters, end-of-sentence
-Recognize the character as ending a sentence if followed by a newline
-or two spaces. 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
@@ -14081,7 +14102,8 @@ or two spaces. Initially, characters @samp{.?!} have
this property.
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.
+Initially,
+no characters have this property.
@item 4
@cindex @code{\-} glyph, and @code{cflags}
@@ -14090,7 +14112,10 @@ Initially, no characters have this property.
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.
+Initially,
+characters
+@samp{\-\[hy]\[em]}
+have this property.
@item 8
@cindex overlapping characters
@@ -14100,14 +14125,20 @@ Initially, characters @samp{\-\[hy]\[em]} have this
property.
@cindex @code{ru} glyph, and @code{cflags}
@cindex @code{radicalex} glyph, and @code{cflags}
@cindex @code{sqrtex} glyph, and @code{cflags}
-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.
+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}
-Mark the glyph associated with this character as overlapping other
-instances of itself vertically. Initially, the character @samp{\[br]}
+Mark the glyph associated with this character
+as overlapping other instances of itself vertically.
+Initially,
+the character
+@samp{\[br]}
has this property.
@item 32
@@ -14122,8 +14153,8 @@ 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
-Mark the character as transparent for the purpose of end-of-sentence
-recognition.
+Mark the character
+as transparent for the purpose of end-of-sentence recognition.
In other words,
GNU
@command{troff} @c GNU
@@ -14132,15 +14163,16 @@ followed by any number of characters with this
property
as the end of a sentence if followed by a newline
or two spaces.@footnote{This is the same as
having a zero space factor in @TeX{}.}
-At startup,
+Initially,
characters
@samp{"')]*\[dg]\[dd]\[rq]\[cq]}
have this property.
@item 64
-Ignore hyphenation codes of the surrounding characters. Use this in
-combination with values 2 and@tie{}4 (initially, no characters have this
-property).
+Ignore hyphenation codes of the surrounding characters.
+Use this value in combination with 2 and@tie{}4.
+Initially,
+no characters have this property.
For example, if you need an automatic break point after the en-dash in
numeric ranges like ``3000--5000'', insert
@@ -14542,15 +14574,15 @@ 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
+ignores the range expression and any remaining arguments.
+@c
@c Further, classes can be nested.
-@c
+@c
@c @Example
@c .class [prepunct] , : ; > @}
@c .class [prepunctx] \C'[prepunct]' \[u2013]-\[u2016]
@c @endExample
-@c
+@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
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
