gbranden pushed a commit to branch master
in repository groff.
commit e92379ab7de45d370d95031fcc4db654fda41983
Author: G. Branden Robinson <[email protected]>
AuthorDate: Tue May 26 17:03:52 2026 -0500
[doc,man]: Revise and sync material on strings.
* doc/groff.texi.in: Break input lines in convenient places for roffing
and diffing.
* man/groff.7.man: Delete `string` and `STRING` page-local macro
definitions; they are no longer used.
---
doc/groff.texi.in | 225 +++++++++++++++++++++++++++++++++++++-----------------
man/groff.7.man | 194 ++++++++++++++++++++++++----------------------
2 files changed, 259 insertions(+), 160 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index edabf5c6e..50882a531 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -16074,25 +16074,43 @@ interprets the fill color as a character cell
background color.
@section Strings
@cindex strings
-GNU @code{troff} supports strings primarily for user convenience.
-Conventionally, if one would define a macro only to interpolate a small
-amount of text, without invoking requests or calling any other macros,
-one defines a string instead. Only one string is predefined by the
-language.
+GNU
+@command{troff} @c GNU
+supports strings primarily for user convenience.
+Conventionally,
+if one would define a macro only to interpolate a small amount of text,
+without invoking requests or calling any other macros,
+one defines a string instead.
+The language prefedines only one string.
@Defstr {.T}
@stindex .T
@cindex output device name string (@code{.T})
-Contains the name of the output device (for example, @samp{utf8} or
+Contains the name of the output device
+(for example,
+@samp{utf8}
+or
@samp{pdf}).
@endDefmpstr
-The @code{ds} request creates a string with a specified name and
-contents and the @code{\*} escape sequence dereferences its name,
-interpolating its contents. If the string named by the @code{\*} escape
-sequence does not exist, it is defined as empty, nothing is
-interpolated, and a warning in category @samp{mac} is emitted.
-@xref{Warnings}, regarding the enablement and suppression of warnings.
+The
+@code{ds}
+request creates a string with a specified name and contents,
+@code{as}
+appends to a string,
+and the
+@code{\*}
+escape sequence dereferences a string,
+interpolating its contents.
+If the string named by the
+@code{\*}
+escape sequence does not exist,
+the formatter defines it as empty
+and interpolates nothing.@footnote{GNU
+@command{troff} @c GNU
+emits a warning in category
+@samp{mac}.
+@xref{Warnings}.}
@DefreqList {ds, name [[@code{"}]@Var{contents}]}
@DefreqItemx {ds1, name [[@code{"}]@Var{contents}]}
@@ -16108,25 +16126,55 @@ interpolated, and a warning in category @samp{mac} is
emitted.
@cindex expansion of strings (@code{\*})
@cindex string arguments
@cindex arguments, to strings
-Define a string called @var{name} with contents @var{contents}. If
-@var{name} already exists as an alias, the target of the alias is
-redefined; see @code{als} and @code{rm} below. If @code{ds} is invoked
-with only one argument, @var{name} is defined as an empty string.
-Otherwise, GNU @code{troff} stores @var{contents} in copy
-mode.
+Define a string called
+@var{name}
+with contents
+@var{contents}.
+In
+GNU
+@command{troff}, @c GNU
+if
+@var{name}
+already exists as an alias,
+the request replaces the contents of the alias's target;
+see
+@code{als}
+and
+@code{rm}
+below.
+Omitting
+@var{contents}
+defines
+@var{name}
+as an empty string.
+Otherwise,
+the formatter reads
+@var{contents}
+in copy mode.
@cindex @code{\*}, interpretation in copy mode
-@code{\*} is itself interpreted even in copy mode.@footnote{@xref{Copy
-Mode}.}
+@code{\*}
+is itself interpreted even in copy mode.@footnote{@xref{Copy Mode}.}
-The @code{\*} escape sequence interpolates a previously defined string
-@var{name} (one-character name@tie{}@var{n}, two-character name
-@var{nm}). The bracketed interpolation form accepts arguments that are
-handled as macro arguments are; recall @ref{Calling Macros}. In
-contrast to macro calls, however, if a closing bracket @samp{]} occurs
-in a string argument, that argument must be enclosed in double quotes.
-When defining strings, argument interpolations must be escaped if they
-are to reference parameters from the calling context; see
-@ref{Parameters}.
+The
+@code{\*}
+escape sequence interpolates a previously defined string
+@var{name}
+(one-character name@tie{}@var{n},
+two-character name
+@var{nm}).
+Its bracketed interpolation form accepts arguments
+that are handled as macro arguments are;
+recall @ref{Calling Macros}.
+In contrast to macro calls,
+however,
+if a closing bracket
+@samp{]}
+occurs in a string argument,
+that argument must be enclosed in double quotes.
+When defining strings,
+argument interpolations must be escaped
+if they are to reference parameters
+from the calling context.@footnote{@xref{Parameters}.}
@Example
.ds cite (\\$1, \\$2)
@@ -16166,8 +16214,8 @@ maintenance.
@Example
.ds Si silicon \" use chemical symbol
-We observed a \*[Si]-based life form.
- @result{} We observed a silicon -based life form.
+My tricorder indicates a \*[Si]-based life form.
+ @result{} My tricorder indicates a silicon -based life form.
@endExample
@noindent
@@ -16178,8 +16226,8 @@ to the last character of the string.
@Example
.ds Si silicon\" use chemical symbol
-We observed a \*[Si]-based life form.
- @result{} We observed a silicon-based life form.
+My tricorder indicates a \*[Si]-based life form.
+ @result{} My tricorder indicates a silicon-based life form.
@endExample
Because the first space after the string name separates the arguments,
@@ -16223,10 +16271,14 @@ recall @ref{Calling Macros}.
@cindex newline character, in strings, escaping
@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. When filling is disabled, care
-is required to avoid overrunning the line length when interpolating
-strings.
+@code{\@key{RET}}
+works just as it does elsewhere.
+The resulting string is stored
+@emph{without}
+the newlines.
+When filling is disabled,
+care is required to avoid oversetting the line
+when interpolating strings.
@Example
.ds foo This string contains \
@@ -16234,32 +16286,46 @@ 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
-Names}.
+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
+GNU
+@command{troff}'s @c GNU
+@code{chop}
+request to excise a trailing newline
+as is often done with diversions.@footnote{@xref{Diversions}.}
-Because strings are similar to macros, they too can be defined so as to
-suppress AT&T @code{troff} compatibility mode when used; see
-@ref{Writing Macros} and @ref{Compatibility Mode}. The @code{ds1}
+It is not possible to embed a newline in a string
+that the formatter interprets as such when interpolating it.
+To achieve that effect,
+use
+@code{\*}
+to interpolate a macro instead.@footnote{@xref{Punning Names}.}
+
+@c The next two paragraphs are deliberately swapped in order from
+@c groff(7), because in our Texinfo manual we present synopses to
+@c establish context.
+Because strings are similar to macros,
+they too can be defined so as to suppress AT&T
+@command{troff} @c AT&T
+compatibility mode when used.@footnote{@xref{Writing Macros}.}
+The @code{ds1}
request defines a string such that compatibility mode is off when the
string is later interpolated.
To be more precise,
GNU
@command{troff} @c GNU
inserts a
-a
@dfn{compatibility save}
-token at the beginning of @var{contents},
+token at the beginning of
+@var{contents},
and a
@dfn{compatibility restore}
-token at the end.
+token at the end.@footnote{@xref{Compatibility Mode}.}
@Example
.nr xxx 12345
@@ -16280,11 +16346,25 @@ token at the end.
@DefreqListEndx {as1, name [[@code{"}]@Var{contents}]}
@cindex appending to a string (@code{as})
@cindex string, appending (@code{as})
-The @code{as} request is similar to @code{ds} but appends @var{contents}
-to the string stored as @var{name} instead of redefining it. If
-@var{name} doesn't exist yet, it is created. If @code{as} is invoked
-with only one argument, no operation is performed (beyond dereferencing
-the string).
+The
+@code{as}
+request is similar to
+@code{ds},
+but appends
+@var{contents}
+to the string stored as
+@var{name}
+instead of repopulating it.
+If
+@var{name}
+does not already exist,
+the formatter creates it.
+Omitting
+@var{contents}
+performs no operation,
+beyond dereferencing
+(and thus possibly creating)
+the string.
@Example
.as salutation " with shallots, onions and garlic,\"
@@ -16339,8 +16419,8 @@ removes a leading neutral double quote
from
@var{contents},
permitting initial embedded spaces in it,
-and reads it to the end of the input line in copy mode.
-@xref{Copy Mode}.
+and reads it to the end of the input line
+in copy mode.@footnote{@xref{Copy Mode}.}
@Example
.ds xxx abcd\h'3i'efgh
@@ -16362,8 +16442,7 @@ request above.
@strong{Caution:@:}
If you interpolate a macro or diversion in
-@var{contents}
-(@pxref{Punning Names}),
+@var{contents},@footnote{@xref{Punning Names}.}
the
@code{length}
request counts characters
@@ -16379,17 +16458,23 @@ macro,
or diversion,
use the
@code{pm}
-request.
-@xref{Debugging}.
+request.@footnote{@xref{Debugging}.}
@endDefreq
@Defreq {chop, object}
-Remove the last character from the macro, string, or diversion named
-@var{object}. This is useful for removing the newline from the end of a
-diversion that is to be interpolated as a string. This request can be
-used repeatedly on the same @var{object}; see
-@ref{GNU @command{troff} Internals},
-for details on nodes inserted additionally by GNU @code{troff}.
+Remove the last character from the macro,
+string,
+or diversion named
+@var{object}.
+This is useful for removing the newline from the end of a diversion
+that is to be interpolated as a string.
+You can apply
+@code{chop}
+repeatedly to the same
+@var{object}.@footnote{@xref{GNU @command{troff} Internals},
+for details of nodes inserted automatically by
+GNU
+@command{troff}.} @c GNU
@endDefreq
@Defreq {substring, str start [@Var{end}]}
diff --git a/man/groff.7.man b/man/groff.7.man
index e442edd75..5801386e1 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -214,19 +214,6 @@ language reference
. Text \f[B]\e\\$1\[lB]\f[]\,\f[I]\\$2\/\f[]\f[B]\[rB]\f[]\\$3
..
.
-.\" ========= strings =========
-.
-.\" synopsis for string, with \*[]
-.de STRING
-. Text \[rs]*[\f[B]\\$1\f[]] \\$2
-..
-.\" synopsis for a long string
-.de string
-. if \n[.$]=0 \
-. return
-. Text \f[B]\[rs]*\[lB]\\$1\[rB]\f[]\\$2
-..
-.
.\" ========= registers =========
.
.\" synopsis for registers, with \n[]
@@ -7054,7 +7041,8 @@ this is the default.
.\" ====================================================================
.
.\" BEGIN Keep (roughly) parallel with groff.texi node "Strings".
-.I groff
+GNU
+.I troff \" GNU
supports strings primarily for user convenience.
.
Conventionally,
@@ -7062,84 +7050,98 @@ if one would define a macro only to interpolate a small
amount of text,
without invoking requests or calling any other macros,
one defines a string instead.
.
-Only one string is predefined by the language.
-.
-.
-.TPx
-.STRING .T
-Contains the name of the output device
-(for example,
-.RB \[lq] utf8 \[rq]
-or
-.RB \[lq] pdf \[rq] ).
+The language prefedines only one string,
+.BR .T ,
+which contains the name of the selected output device.
.
.
.P
The
.request ds
-request creates a string with a specified name and contents.
+request creates a string with a specified name and contents,
+.RB \[lq] as \[rq]
+appends to a string,
+and the
+.esc *
+escape sequence dereferences its name,
+interpolating its contents.
+.
+If the string named by the
+.esc *
+escape sequence does not exist,
+the formatter defines it as empty,
+interpolates nothing,
+and emits a warning in category
+.RB \%\[lq] mac \[rq].
+.
+See section \[lq]Warnings\[rq] in
+.MR @g@troff 1 .
.
-If the identifier named by
+.
+.P
+In
+GNU
+.IR troff ,\" GNU
+if the identifier named by
.request ds
already exists as an alias,
-the target of the alias is redefined.
+the request replaces the contents of the alias's target;
+see
+.request als
+and
+.request rm .
.
-If
+Omitting
+arguments after the first to
.request ds
-is invoked with only one argument,
-the named string becomes empty.
+defines
+a string as empty.
.
-The formatter removes a leading neutral double quote from
-.I contents
-to permit the embedding of leading spaces.
+Otherwise,
+the formatter reads
+arguments after the first
+in copy mode.
.
-It interprets any other
-.RB \[oq] \[dq] \[cq] \" single quotes around double quote
-literally,
-but the wise author uses the special character escape sequence
-.B \[rs][dq]
-instead if the string
-might be interpolated as part of a macro argument;
-see section \[lq]Calling macros\[rq] above.
+.esc *
+is itself interpreted even in copy mode.
.
.
.P
-The
.esc *
-escape sequence dereferences a string's name,
-interpolating its contents.
-.
-If the name does not exist,
-the formatter defines it as empty,
-interpolates nothing,
-and emits a warning in category
-.RB \%\[lq] mac \[rq].
+escape sequence interpolates a previously defined string
+(its first or only argument).
.
-See section \[lq]Warnings\[rq] in
-.MR @g@troff 1 .
-.
-The bracketed interpolation form accepts arguments that are handled as
-macro arguments are;
-see section \[lq]Calling macros\[rq] above.
+Its bracketed interpolation form accepts arguments
+that are handled as macro arguments are.
.
In contrast to macro calls,
-an argument containing a closing bracket
+however,
+if a closing bracket
.B ]
-must be enclosed in double quotes.
+occurs in a string argument,
+that argument must be enclosed in double quotes.
.
When defining strings,
-argument interpolations must be escaped if they are to reference
-parameters from the calling context;
-see section \[lq]Parameters\[rq] below.
+argument interpolations must be escaped
+if they are to reference parameters
+from the calling context.
.
-Any non-initial neutral double quote
-.B \[dq]
-is interpreted literally,
-but it is wise to use the special character escape sequence
+.
+.P
+The formatter removes a leading neutral double quote from
+the argument after the first,
+permitting initial embedded spaces in it.
+.
+It interprets any other
+.RB \[oq] \[dq] \[cq] \" single quotes around double quote
+literally,
+but the wise author uses the special character escape sequence
.B \[rs][dq]
-instead if the string might be interpolated as part of a macro argument;
-see section \[lq]Calling macros\[rq] above.
+instead if the string
+might be interpolated as part of a macro argument.
+.
.
+.P
Strings are not limited to a single input line of text.
.BI \[rs] newline
works just as it does elsewhere.
@@ -7149,8 +7151,8 @@ The resulting string is stored
the newlines.
.
When filling is disabled,
-care is required to avoid overrunning the line length when interpolating
-strings.
+care is required to avoid oversetting the line
+when interpolating strings.
.
Conversely,
when filling is enabled,
@@ -7160,13 +7162,16 @@ 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
+GNU
+.IR troff 's\" GNU
.B chop
-request to excise a trailing newline as is often done with diversions.
+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.
+.
+.P
+It is not possible to embed a newline in a string
+that the formatter interprets as such when interpolating it.
.
To achieve that effect,
use
@@ -7175,18 +7180,23 @@ to interpolate a macro instead;
see section \[lq]Punning names\[rq] below.
.
.
+.\" The next two paragraphs are deliberately swapped in order from our
+.\" Texinfo manual, because in the man page we don't present synopses to
+.\" establish context.
.P
The
.RB \[lq] as \[rq]
request is similar to
-.request ds
-but appends to a string instead of redefining it.
+.request ds ,
+but appends to an existing string
+instead of repopulating it.
.
-If
-.RB \[lq] as \[rq]
-is invoked with only one argument,
-no operation is performed
-(beyond dereferencing the string).
+Omitting
+arguments after the first
+performs no operation,
+beyond dereferencing
+(and thus possibly creating)
+the string.
.
.
.P
@@ -7208,10 +7218,15 @@ with compatibility mode suspended when the appended
portion of the
string is later interpolated.
.
.
+.br
+.ne 2v
.P
.I Caution:
-These requests treat the remainder of the input line
-as their second argument,
+The
+.B ds
+and
+.RB \[lq] as \[rq]
+requests treat the remainder of the input line as their second argument,
including any spaces,
up to a newline or comment escape sequence.
.
@@ -7269,21 +7284,20 @@ and aliasing
(\c
.request rn ,
.request rm ,
-.request als).
+.request als ).
.
.
.br
.ne 2v
.P
-Redefinitions and appendments \[lq]write through\[rq] request,
+When a request,
macro,
string,
-and diversion names.
+or diversion is aliased,
+redefinitions and appendments \[lq]write through\[rq] alias names.
.
-To replace an aliased object with a separately defined one,
-you must use the
-.B rm
-request on its name first.
+To replace an alias with a separately defined object,
+remove its name first.
.\" END Keep (roughly) parallel with groff.texi node "Strings".
.
.
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
