gbranden pushed a commit to branch master
in repository groff.
commit 165eca68eec5491cc1fedcb44cd001ce593dcdc9
Author: G. Branden Robinson <[email protected]>
AuthorDate: Thu Apr 4 18:58:43 2024 -0500
[docs]: Make clarifications.
* Expand on consequences of strings not containing newlines.
* Speak of special characters and character classes in the same
"breath", since they're in the same name space.
* Tweak grammar to better reflect the fact that the `el` request, while
it has no predicate component, does possess a branch.
* Clarify use of indentation in *roff source.
* Update synchrony annotation to reflect past node/section renaming.
---
doc/groff.texi.in | 31 ++++++++++++++++++++-----------
man/groff.7.man | 33 +++++++++++++++++++++++----------
2 files changed, 43 insertions(+), 21 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index cc7b0acdc..9b1db89af 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -6544,9 +6544,9 @@ not qualify, so our first attempt got a warning.
@cindex identifiers
An @dfn{identifier} labels a GNU @code{troff} datum such as 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.
+name (macro, string, or diversion), typeface, color, special character
+or 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 the
@@ -6674,7 +6674,7 @@ empty, and interpolates nothing. If the identifier is
interpreted as a
register, GNU @code{troff} emits a warning in category @samp{reg},
initializes it to zero, and interpolates that value. @xref{Warnings},
@ref{Interpolating Registers}, and @ref{Strings}. Attempting to use an
-undefined typeface, special character, color, character class,
+undefined typeface, special character or character class, color,
environment, or stream generally provokes an error diagnostic.
@need 1000
@@ -6763,7 +6763,7 @@ available via both requests and escape sequences.
The mechanism of using @code{roff}'s control characters to invoke
requests and call macros was introduced in @ref{Requests and Macros}.
Control characters are recognized only at the beginning of an input
-line, or at the beginning of the branch of a control structure request;
+line, or at the beginning of a branch of a control structure request;
see @ref{Conditionals and Loops}.
A few requests cause a break implicitly; use the no-break control
@@ -6830,7 +6830,8 @@ sense.
@c ---------------------------------------------------------------------
-@c BEGIN Keep (roughly) parallel with section "Requests" of groff(7).
+@c BEGIN Keep (roughly) parallel with section "Invoking requests" of
+@c groff(7).
@node Invoking Requests, Calling Macros, Control Characters, Formatter
Instructions
@subsection Invoking Requests
@cindex invoking requests
@@ -6875,8 +6876,8 @@ argument. @xref{Strings}.
@cindex package, package, structuring the source of
@cindex indentation, of @code{roff} source code
Spaces and tabs immediately after a control character are ignored.
-Commonly, authors structure the source of documents or macro files with
-them.
+Commonly, authors use them to indent the source of documents or macro
+files.
@Example
.de center
@@ -6920,7 +6921,8 @@ definitions (or any input lines) with blank lines.
@endExample
@xref{Blank Line Traps}.
-@c END Keep (roughly) parallel with section "Requests" of groff(7).
+@c END Keep (roughly) parallel with section "Invoking requests" of
+@c groff(7).
@c ---------------------------------------------------------------------
@@ -12631,8 +12633,9 @@ interpolated as part of a macro argument; see
@ref{Calling Macros}.
@cindex escaping newline characters, in strings
Strings are not limited to a single input line of text.
@code{\@key{RET}} works just as it does elsewhere. The resulting string
-is stored @emph{without} the newlines. Care is therefore required when
-interpolating strings while filling is disabled.
+is stored @emph{without} the newlines. When filling is disabled, care
+is required to avoid overrunning the line length when interpolating
+strings.
@Example
.ds foo This string contains \
@@ -12640,6 +12643,12 @@ text on multiple lines \
of input.
@endExample
+Conversely, when filling is enabled, it is not necessary to append
+@code{\c} to a string interpolation to prevent a break afterward, as
+might be required in a macro argument. Nor does a string require use of
+the GNU @command{troff} @code{chop} request to excise a trailing newline
+as is often done with diversions.
+
It is not possible to embed a newline in a string that will be
interpreted as such when the string is interpolated. To achieve that
effect, use @code{\*} to interpolate a macro instead; see @ref{Punning
diff --git a/man/groff.7.man b/man/groff.7.man
index 3dd44a779..9c28f9ed4 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -1267,8 +1267,7 @@ string,
or diversion),
typeface,
color,
-special character,
-character class,
+special character or character class,
environment,
or stream.
.
@@ -1289,7 +1288,7 @@ input.
.\" troff input in general, and include a reference to the `trin`
.\" request.
.P
-Invalid input characters are subset of control characters
+Invalid input characters are a subset of control characters
(from the sets \[lq]C0 Controls\[rq] and \[lq]C1 Controls\[rq] as
Unicode describes them).
.
@@ -1401,9 +1400,8 @@ and subsection \[lq]Interpolating registers\[rq] and
section
Attempting to use an undefined
typeface,
style,
-special character,
+special character or character class,
color,
-character class,
environment,
or stream generally provokes an error diagnostic.
.
@@ -1430,7 +1428,7 @@ No other object types do.
.\" requests and call macros was introduced in @ref{Requests and Macros}.
Control characters are recognized only at the beginning of an input
line,
-or at the beginning of the branch of a control structure request;
+or at the beginning of a branch of a control structure request;
.\" see @ref{Conditionals and Loops}.
see section \[lq]Control structures\[rq] below.
.
@@ -1539,8 +1537,9 @@ See section \[lq]Strings\[rq] below.
Spaces and tabs immediately after a control character are ignored.
.
Commonly,
-authors structure the source of documents or macro files with them.
-.\" END Keep (roughly) parallel with groff.texi node "Requests".
+authors use them to indent the source of documents or macro files.
+.\" END Keep (roughly) parallel with groff.texi node "Invoking
+.\" Requests".
.
.
.\" ====================================================================
@@ -5859,8 +5858,22 @@ The resulting string is stored
.I without
the newlines.
.
-Care is therefore required when interpolating strings while filling is
-disabled.
+When filling is disabled,
+care is required to avoid overrunning the line length when interpolating
+strings.
+.
+Conversely,
+when filling is enabled,
+it is not necessary to append
+.B \[rs]c
+to a string interpolation to prevent a break afterward,
+as might be required in a macro argument.
+.
+Nor does a string require use of
+the GNU
+.I troff \" GNU
+.B chop
+request to excise a trailing newline as is often done with diversions.
.
It is not possible to embed a newline in a string that will be
interpreted as such when the string is interpolated.
_______________________________________________
Groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
