[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 04/04: Update string documentation (again).
From: |
G. Branden Robinson |
Subject: |
[groff] 04/04: Update string documentation (again). |
Date: |
Wed, 5 Aug 2020 10:32:55 -0400 (EDT) |
gbranden pushed a commit to branch master
in repository groff.
commit 1d1ee5548410af3a1e3278fa4ee6664f0e60a78d
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Aug 1 17:07:27 2020 +1000
Update string documentation (again).
* doc/groff.texi (Strings):
+ Convert paragraph before .ds/.ds1/\* list to serve more of a
"TL;DR" function, since what follows takes up literally pages of
text in PDF form.
+ Drop mention that "GNU troff" parses the contents of an interpolated
string. What else would do it?
+ Add example of nested string interpolation.
+ Drop phrases "for more details" and "for more information" after
cross-references. Without more, I think constructions like this add
nothing. Why else would you follow a cross-reference?
+ Drop characterization of, e.g., ".ds foo" as "explicitly" defining
an empty string. This is true but tautologous, I think.
+ Clarify that arguments after the first to .ds and friends consume
the _remainder_ of the input line, not the "entire" line.
+ Clarify why inline comments can lead to trailing spaces in string
definitions/appendments. (It's because those blessed few who
comment source at all generally do not do so barbarously by smashing
the comment character into the immediately preceding material.)
+ Clarify that escape sequence semantics are not overridden by string
definition argument handling.
+ Stop describing non-escaped newlines as "real" in favor of a more
explicit explanation.
+ With .ds1 moved in a previous commit, the discussion of string/macro
interpolation mixture now flows much more naturally. Now it almost
reads as if it were planned that way...recast to assist illusion.
+ Add forward cross-reference to Parameters node when discussion
string interpolation of macro definition; \$0 has not been seen
before in the manual.
+ Coalesce adjacent one-sentence paragraphs.
+ Clarify how compatibility save/restore tokens work--they affect the
behavior of a string when it is later interpolated, not at the time
the .ds1 and .as1 macros are used (you already have to be outside of
compatibility mode to use them).
+ Change metasyntactic variable name of .length request from "str" to
"anything". .length can measure things that are not (named)
strings. Mark up that same argument correctly, with @var instead of
@code.
+ Change metasyntactic variable name of .chop request from "xx" to
"object".
+ Change metasyntactic variable names of .rn request from "xx" and
"yy" to "old" and "new".
+ Change metasyntactic variable name of .rm request from "xx" to
"name". Clarify that it is the _name_, not the _object_ to which it
refers, that is subsequently treated as never having been defined.
+ Add "@:" (Texinfo's '\&') after ":" where it is not followed by a
new sentence. In general, a colon does not terminate a sentence.
What madness is this?
+ Recast language for brevity or less awkwardness (in my opinion).
+ Fix typo.
+ Unhyphenate "previously-defined"; per some online style guides, an
adverbial qualifier to a phrasal adjectives cancels the hyphenation
requirement of its portion of an adjectival phrase. Hence
"previously defined string variables" but "putatively long-term
obligations" (not "putatively-long-term", which I would have
recognized as wrong on sight). Thanks to Dave Kemper for correcting
my hypercorrection.
* man/groff.7.man:
+ (.as, .as1, .chop, .ds, ds1, .length, .substring): Sync
metasyntactic variable renames with our Texinfo manual.
+ (.chop, .ds, .length, .substring): Sync request explanations with
our Texinfo manual (keeping them to one or occasionally two
sentences).
+ (Strings): Resync with material from our Texinfo manual, in
abbreviated form.
* man/groff_diff.7.man:
+ (.als): Prefix request names with a leading dot.
+ (.as1, .chop, .ds1, .length, .stringdown, .stringup, .substring):
Sync metasyntactic variable renames with our Texinfo manual. Sync
request explanations with our Texinfo manual.
+ (.stringdown, .stringup): Fix special character escapes in example.
---
doc/groff.texi | 152 ++++++++++++++++++++++++++-------------------------
man/groff.7.man | 141 ++++++++++++++++++++++++++++++++---------------
man/groff_diff.7.man | 116 ++++++++++++++++++++++++++-------------
3 files changed, 254 insertions(+), 155 deletions(-)
diff --git a/doc/groff.texi b/doc/groff.texi
index 0930342..f0b45de 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -10394,9 +10394,9 @@ This string contains the current output device (for
example,
@samp{utf8} or @samp{pdf}).
@endDefstr
-Although the following requests can be used to create strings, simply
-using (dereferencing) an undefined string will cause it to be defined as
-empty.
+The @code{ds} (or @code{ds1}) request creates a string and the @code{\*}
+escape retrieves (dereferences) its contents. Dereferencing an
+undefined string name defines it as empty.
@DefreqList {ds, name [@Var{string}]}
@DefreqItemx {ds1, name [@Var{string}]}
@@ -10417,9 +10417,9 @@ Define and access a string variable @var{name}
(one-character
name@tie{}@var{n}, two-character name @var{nm}). If @var{name} already
exists, @code{ds} overwrites the previous definition. The syntax form
using brackets accepts arguments that are handled as macro arguments
-are; unlike with macro calls, however, a closing bracket as an argument
-must be enclosed in double quotes. @xref{Request and Macro Arguments},
-and @ref{Parameters}.
+are; in contrast to macro calls, however, a closing bracket as an
+argument must be enclosed in double quotes. @xref{Request and Macro
+Arguments}, and @ref{Parameters}.
Example:
@@ -10430,33 +10430,42 @@ This is \*[foo nice].
@result{} This is a nice test.
@endExample
-The @code{\*} escape @dfn{interpolates} (expands in place) a
-previously-defined string variable. To be more precise, the stored
-string is pushed onto the input stack, which is then parsed by GNU
-@code{troff}. Similarly to number registers, it is possible to nest
-strings; i.e., string variables can be called within string variables.
+The @code{\*} escape @dfn{interpolates} (expands in place) a previously
+defined string variable. More precisely, the stored string is pushed
+onto the input stack, which is then parsed normally. Similarly to
+number registers, it is possible to nest strings; i.e., string variables
+can be called within string variables.
+
+@Example
+.ds a hairy
+.ds b \*[a] wildebeest
+.ds c big, \*[b]
+I see a \*[c].
+ @result{} I see a big, hairy wildebeest.
+@endExample
If the string named by the @code{\*} escape does not exist, it is
defined as empty, and a warning of type @samp{mac} is emitted (see
-@ref{Debugging} for more details).
+@ref{Debugging}).
-If @code{ds} is called with only one argument, @var{name} is explicitly
-defined as an empty string.
+If @code{ds} is called with only one argument, @var{name} is defined as
+an empty string.
@cindex comments, with @code{ds}
@cindex @code{ds} request, and comments
@strong{Caution:} Unlike other requests, the second argument to the
-@code{ds} request takes up the entire line including trailing spaces.
-This means that comments on a line with such a request can introduce
-unwanted space into a string.
+@code{ds} request consumes the remainder of the input line, including
+trailing spaces. This means that comments on a line with such a request
+can introduce unwanted space into a string when they are set off from
+the material they annotate, as is conventional.
@Example
.ds TeX T\h'-.2m'\v'.2m'E\v'-.2m'\h'-.1m'X \" Knuth's TeX
@endExample
@noindent
-Instead the comment should be put on another line or have the comment
-escape adjacent with the end of the string.
+Instead, place the comment on another line or put the comment escape
+immediately adjacent to the last character of the string.
@Example
.ds TeX T\h'-.2m'\v'.2m'E\v'-.2m'\h'-.1m'X\" Knuth's TeX
@@ -10478,15 +10487,15 @@ creeping into them during source document maintenance.
@cindex @code{ds} request, and leading spaces
To store leading space in a string, start it with a double quote. A
double quote is special only in that position; double quotes in any
-other location are included in the string. Consequently, no
-trailing quote is needed.
+other location are included in the string (the effect of escape
+sequences notwithstanding).
@c Examples should be more accessible than Unix nerd stuff like this,
@c but in general document authors shouldn't want to use "straight"
@c double quotes for ordinary prose anyway. Also, 56 chars is as fat
@c as these examples can get and not overrun the right margin in PDF.
@Example
-.ds saluatation " Yours in a white wine sauce,\"
+.ds salutation " Yours in a white wine sauce,\"
.ds c-var-defn " char build_date[]="2020-07-29";\"
.ds sucmd sudo sh -c "fdisk -l /dev/sda > partitions"\"
@endExample
@@ -10505,9 +10514,9 @@ text on multiple lines \
of input.
@endExample
-It is not possible to embed ``real'' newlines in a string. How breaking
-occurs depends on fill mode as usual, and also upon whether the string
-is interpolated as a string or a macro (see below).
+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 the @code{\*} escape to interpolate a macro instead.
@cindex name space, common, of macros, diversions, and strings
@cindex common name space of macros, diversions, and strings
@@ -10515,9 +10524,9 @@ is interpolated as a string or a macro (see below).
@cindex strings, shared name space with macros and diversions
@cindex diversions, shared name space with macros and strings
Strings, macros, and diversions (and boxes) share the same name space.
-Internally, the same mechanism is used to store them. This has some
-interesting consequences. For example, it is possible to call a macro
-with string syntax and vice versa.
+Internally, the same mechanism is used to store them. Thus it is
+possible to invoke a macro with string interpolation syntax and vice
+versa.
@Example
.de subject
@@ -10576,12 +10585,11 @@ is
@noindent
Note that the latter calling syntax doesn't change the value of
-@code{\$0}, which is then inherited from the calling macro.
+@code{\$0}, which is then inherited from the calling macro
+(@pxref{Parameters}).
-Diversions and boxes can be also called with string syntax.
-
-Another consequence is that you can copy one-line diversions or boxes to
-a string.
+Diversions and boxes can be also called with string syntax. It is
+sometimes convenient to copy one-line diversions or boxes to a string.
@Example
.di xxx
@@ -10644,13 +10652,13 @@ This is \*[xxx].
@result{} This is a funny test.
@endExample
-@xref{Gtroff Internals}, for more information.
+@xref{Gtroff Internals}.
@endDefreq
-The @code{ds1} request turns off compatibility mode while interpreting a
-string. To be more precise, a @dfn{compatibility save} input token is
-inserted at the beginning of the string, and a @dfn{compatibility
-restore} input token at the end.
+The @code{ds1} request defines a string such that compatibility mode is
+off when the string is later interpolated. To be more precise, a
+@dfn{compatibility save} input token is inserted at the beginning of the
+string, and a @dfn{compatibility restore} input token at the end.
@Example
.nr xxx 12345
@@ -10680,10 +10688,10 @@ with only one argument, no operation is performed.
@endExample
The @code{as1} request is similar to @code{as}, but compatibility mode
-is switched off while the appended string is interpreted. To be more
-precise, a @dfn{compatibility save} input token is inserted at the
-beginning of the appended string, and a @dfn{compatibility restore}
-input token at the end.
+is switched off while the appended portion of the string is
+interpolated. To be more precise, a @dfn{compatibility save} input
+token is inserted at the beginning of the appended string, and a
+@dfn{compatibility restore} input token at the end.
@endDefreq
Several requests exist to perform rudimentary string operations.
@@ -10691,15 +10699,15 @@ Strings can be queried (@code{length}) and modified
(@code{chop},
@code{substring}, @code{stringup}, @code{stringdown}), and their names
can be manipulated (@code{rn}, @code{rm}, @code{als}).
-@Defreq {length, reg str}
+@Defreq {length, reg anything}
@cindex length of a string (@code{length})
@cindex string, length of (@code{length})
@cindex @code{length} request, and copy-in mode
@cindex copy-in mode, and @code{length} request
@cindex mode, copy-in, and @code{length} request
-Compute the number of characters of @var{str} and return it in the
-number register @var{reg}. If @var{reg} doesn't exist, it is created.
-@code{str} is read in copy mode.
+Compute the number of characters of @var{anything} and store the count
+in the number register @var{reg}. If @var{reg} doesn't exist, it is
+created. @var{anything} is read in copy mode.
@Example
.ds xxx abcd\h'3i'efgh
@@ -10709,12 +10717,12 @@ number register @var{reg}. If @var{reg} doesn't
exist, it is created.
@endExample
@endDefreq
-@Defreq {chop, xx}
-Remove (chop) the last character from the macro, string, or diversion
-named @var{xx}. This is useful for removing the newline from the end of
-diversions that are to be interpolated as strings. This request can be
-used repeatedly; see @ref{Gtroff Internals}, for details on nodes
-inserted additionally by GNU @code{troff}.
+@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{Gtroff Internals},
+for details on nodes inserted additionally by GNU @code{troff}.
@endDefreq
@Defreq {substring, str start [@Var{end}]}
@@ -10722,10 +10730,9 @@ inserted additionally by GNU @code{troff}.
Replace the string named @var{str} with its substring bounded by the
indices @var{start} and @var{end}, inclusive. The first character in
the string has index@tie{}0. If @var{end} is omitted, it is implicitly
-set to the largest valid value (the string length minus one). If the
-index value @var{start} or @var{end} is negative, it is counted from the
-end of the string, going backwards: the last character has
-index@tie{}@minus{}1, the character before the last has
+set to the largest valid value (the string length minus one). Negative
+indices count backwards from the end of the string:@: the last character
+has index@tie{}@minus{}1, the character before the last has
index@tie{}@minus{}2, and so on.
@Example
@@ -10746,12 +10753,12 @@ index@tie{}@minus{}2, and so on.
@cindex lowercasing a string (@code{stringdown})
@cindex up-casing a string (@code{stringup})
@cindex down-casing a string (@code{stringdown})
-Change the string named @var{str} by replacing each of its bytes with
+Alter the string named @var{str} by replacing each of its bytes with
its lowercase (@code{stringdown}) or uppercase (@code{stringup}) version
-(if any). @code{groff} special characters (see the @cite{groff_char(7)}
-man page) can be used and the output will usually transform in the
-expected way due to the regular naming convention of the special
-character escapes.
+(if one exists). GNU @code{troff} special characters (see the
+@cite{groff_char(7)} man page) can be used and the output will usually
+transform in the expected way due to the regular naming convention of
+the special character escapes.
@Example
.ds resume R\['e]sum\['e]\"
@@ -10764,7 +10771,7 @@ character escapes.
@endExample
@endDefreq
-@Defreq {rn, xx yy}
+@Defreq {rn, old new}
@cindex renaming request (@code{rn})
@cindex request, renaming (@code{rn})
@cindex renaming macro (@code{rn})
@@ -10773,10 +10780,10 @@ character escapes.
@cindex string, renaming (@code{rn})
@cindex renaming diversion (@code{rn})
@cindex diversion, renaming (@code{rn})
-Rename the request, macro, diversion, or string @var{xx} to @var{yy}.
+Rename the request, macro, diversion, or string @var{old} to @var{new}.
@endDefreq
-@Defreq {rm, xx}
+@Defreq {rm, name}
@cindex removing request (@code{rm})
@cindex request, removing (@code{rm})
@cindex removing macro (@code{rm})
@@ -10785,8 +10792,8 @@ Rename the request, macro, diversion, or string
@var{xx} to @var{yy}.
@cindex string, removing (@code{rm})
@cindex removing diversion (@code{rm})
@cindex diversion, removing (@code{rm})
-Remove the request, macro, diversion, or string @var{xx}. GNU
-@code{troff} treats subsequent invocations as if the object had never
+Remove the request, macro, diversion, or string @var{name}. GNU
+@code{troff} treats subsequent invocations as if the name had never
been defined.
@endDefreq
@@ -10806,13 +10813,12 @@ diversion object named @var{old}, causing the names
to refer to the same
stored object. If @var{old} is undefined, a warning of type @samp{mac}
is generated and the request is ignored.
-To understand how the @code{als} request works it is probably best to
-think of two different storage pools: one for objects (macros, strings,
-etc.), and another for names. As soon as an object is defined, GNU
-@code{troff} adds it to the object pool, adds its name to the name pool,
-and creates a link between them. When @code{als} creates an alias, it
-adds a new name to the name pool that gets linked to the same object as
-the old name.
+To understand how the @code{als} request works, consider two different
+storage pools:@: one for objects (macros, strings, etc.), and another
+for names. As soon as an object is defined, GNU @code{troff} adds it to
+the object pool, adds its name to the name pool, and creates a link
+between them. When @code{als} creates an alias, it adds a new name to
+the name pool that gets linked to the same object as the old name.
Now consider this example.
diff --git a/man/groff.7.man b/man/groff.7.man
index 630e50b..246b851 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -1259,18 +1259,18 @@ Same as
but with compatibility mode switched off during macro expansion.
.
.TPx
-.REQ .as "stringvar \fR[\fPanything\fR]\fP"
+.REQ .as "name \fR[\fPstring\fR]\fP"
Append
-.I anything
-to
-.IR stringvar ;
+.I string
+to the string
+.IR name ;
no operation if
-.I anything
+.I string
is omitted.
.
.
.TPx
-.REQ .as1 "stringvar \fR[\fPanything\fR]\fP"
+.REQ .as1 "name \fR[\fPstring\fR]\fP"
Same as
.request .as
but with compatibility mode switched off during string expansion.
@@ -1418,8 +1418,11 @@ as string
.IR anything .
.
.TPx
-.REQ .chop "object"
-Chop the last character off macro, string, or diversion
+.REQ .chop object
+Remove the last character from the macro,
+string,
+or diversion
+named
.IR object .
.
.TPx
@@ -1617,18 +1620,18 @@ of
is interpreted.
.
.TPx
-.REQ .ds "stringvar \fR[\fPanything\fR]\fP"
-Set
-.I stringvar
-to
-.IR anything ,
-or to the empty string if
-.I anything
+.REQ .ds "name \fR[\fPstring\fR]\fP"
+Define a string variable
+.I name
+with contents
+.IR string ,
+or as empty if
+.I string
is omitted.
.
.
.TPx
-.REQ .ds1 "stringvar \fR[\fPanything\fR]\fP"
+.REQ .ds1 "name \fR[\fPstring\fR]\fP"
Same as
.request .ds
but with compatibility mode switched off during string expansion.
@@ -2012,11 +2015,12 @@ Set leader repetition glyph to\~\c
.IR c .
.
.TPx
-.REQ .length "register anything"
-Write the length of the string
+.REQ .length "reg anything"
+Compute the number of characters of
.I anything
-to
-.IR register .
+and store the count
+in the number register
+.IR reg .
.
.TPx
.REQ .linetabs
@@ -2538,15 +2542,18 @@ with font position
.IR n .
.
.TPx
-.REQ .substring "xx start \fR[\fPend\fR]\fP"
+.REQ .substring "str start \fR[\fPend\fR]\fP"
Replace the string named
-.I xx
+.I str
with its substring bounded by the indices
.I start
and
.IR end ,
inclusive.
.
+Negative indices count backwards from the end of the string.
+.
+.
.TPx
.REQ .sv
Save
@@ -3891,17 +3898,76 @@ or
.
.
.P
-Strings are defined by the
+The
.request .ds
-and
-.request .ds1
-requests and can be retrieved by the
+request creates a string and the
.esc *
-escape sequence.
+escape retrieves (dereferences) its contents.
.
-Simply using
-(dereferencing)
-an undefined string will cause it to be defined as empty.
+Dereferencing an undefined string name defines it as empty.
+.
+.
+.P
+The
+.request .as
+requests is similar to
+.request .ds
+but appends its arguments
+(after the first)
+to a string instead of redefining it.
+.
+If
+.request .as
+is called with only one argument,
+no operation is performed.
+.
+.
+.P
+The
+.request .ds1
+request defines a string such that compatibility mode is off when the
+string is later interpolated.
+.
+To be more precise,
+a
+.I compatibility save
+input token is inserted at the beginning of the string,
+and a
+.I compatibility restore
+input token at the end.
+.
+Likewise,
+the
+.request .as1
+request is similar to
+.request .as\c
+,
+but compatibility mode is switched off while the appended portion of the
+string is interpolated.
+.
+.
+.P
+.B Caution:
+Unlike other requests,
+the second argument to these requests consumes the remainder of the
+input line,
+including trailing spaces.
+.
+It is good style to end string definitions
+(and appendments)
+with a comment,
+even an empty one,
+to prevent unwanted space from creeping into them during source document
+maintenance.
+.
+.
+.P
+To store leading space in a string,
+start it with a double quote.
+.
+A double quote is special only in that position;
+double quotes in any other location are included in the string
+(the effect of escape sequences notwithstanding).
.
.
.P
@@ -3911,22 +3977,11 @@ and diversions
(and boxes)
share the same name space.
.
-Internally, the same mechanism is used to store them.
+Internally,
+the same mechanism is used to store them.
.
.
.P
-The
-.request .as
-and
-.request .as1
-requests are similar to
-.request .ds
-and
-.request .ds1 ,
-but append their arguments
-(after the first)
-to a string instead of redefining it.
-.
Several requests exist to perform rudimentary string operations.
.
Strings can be queried
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index fae6d65..43996ec 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -980,18 +980,20 @@ To be more precise,
a \[lq]compatibility save\[rq] token is inserted at the beginning,
and a \[lq]compatibility restore\[rq] token at the end.
.
-As a consequence, the requests
-.BR am ,
-.BR am1 ,
-.BR de ,
+As a consequence,
+the requests
+.BR .am ,
+.BR .am1 ,
+.BR .de ,
and
-.B de1
+.B .de1
can be intermixed freely since the compatibility save/\:restore tokens
only affect the macro parts defined by
.B .am1
and
.BR .ds1 .
.
+.
.TP
.BI .ami\~ xx\~yy
Append to macro indirectly.
@@ -1008,16 +1010,20 @@ request but compatibility mode is switched off during
execution.
.
.
.TP
-.BI .as1\~ xx\~yy
+.BI .as1\~ "name string"
Similar to
.BR .as ,
-but compatibility mode is switched off during expansion.
+but compatibility mode is switched off while the appended portion of the
+string is interpolated.
.
To be more precise,
-a \[lq]compatibility save\[rq] token is inserted at the beginning,
+a \[lq]compatibility save\[rq] token is inserted at the beginning of the
+appended string
+.IR string,
and a \[lq]compatibility restore\[rq] token at the end.
.
-As a consequence, the requests
+As a consequence,
+the requests
.BR as ,
.BR as1 ,
.BR ds ,
@@ -1390,12 +1396,27 @@ A glyph definition can be removed with the
.B rchar
request.
.
+.
.TP
-.BI .chop\~ xx
-Chop the last element off macro, string, or diversion
-.IR xx .
-This is useful for removing the newline from the end of diversions
-that are to be interpolated as strings.
+.BI .chop\~ object
+Remove the last character from the macro,
+string,
+or diversion
+named
+.IR 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
+.IR object ;
+see section \[lq]Gtroff Internals\[rq] in
+.IR "Groff: The GNU Implementation of troff" ,
+the
+.I groff
+Texinfo manual,
+for details on nodes inserted additionally by
+.IR groff .
.
.
.TP
@@ -1773,13 +1794,16 @@ as output.
.RE \" this "extra" RE avoids indentation of the remaining paragraphs
.
.TP
-.BI .ds1\~ xx\~yy
+.BI .ds1\~ "name string"
Similar to
.BR .ds ,
+but compatibility mode is switched off when the string is later
+interpolated.
but compatibility mode is switched off during expansion.
.
To be more precise,
-a \[lq]compatibility save\[rq] token is inserted at the beginning,
+a \[lq]compatibility save\[rq] token is inserted at the beginning of the
+string,
and a \[lq]compatibility restore\[rq] token at the end.
.
.
@@ -2349,12 +2373,30 @@ If
is non-zero or missing, enable pairwise kerning, otherwise disable it.
.
.TP
-.BI .length\~ xx\~string
-Compute the length of
-.I string
-and return it in the number register
-.I xx
-(which is not necessarily defined before).
+.BI .length\~ "reg anything"
+Compute the number of characters in
+.I anything
+and return the count in the number register
+.IR reg.
+.
+If
+.I reg
+doesn't exist,
+it is created.
+.
+.I anything
+is read in copy mode.
+.
+.RS
+.IP
+.EX
+.B .ds xxx abcd\eh\[aq]3i\[aq]efgh
+.B .length yyy \e*[xxx]
+.B \en[yyy]
+14
+.EE
+.RE
+.
.
.TP
.BI .linetabs\~ n
@@ -2783,17 +2825,18 @@ See
for warning types and control.
.
.TP
-.BI .stringdown \~stringvar
+.BI .stringdown \~str
.TQ
-.BI .stringup \~stringvar
-Change the string named
-.I stringvar
+.BI .stringup \~str
+Alter the string named
+.I str
by replacing each of its bytes with its
lowercase
.RB ( down )
or uppercase
.RB ( up )
-version (if any).
+version
+(if one exists).
.
.I groff
special characters
@@ -2807,11 +2850,11 @@ due to the regular naming convention of the special
character escapes.
.RS
.EX
\&.ds resume R\e['e]sum\e['e]\e"
-\e*[resume] \e# R['e]sum['e]
+\e*[resume] \e# R\['e]sum\['e]
\&.stringdown resume
-\e*[resume] \e# r['e]sum['e]
+\e*[resume] \e# r\['e]sum\['e]
\&.stringup resume
-\e*[resume] \e# R['E]SUM['E]
+\e*[resume] \e# R\['E]SUM\['E]
.EE
.RE
.RE
@@ -2864,9 +2907,10 @@ file controls which font positions (if any) are
initially associated
with styles rather than fonts.
.
.TP
-.BI .substring\~ xx\~start\~ [ end ]
+.BI .substring\~ "str start\~"\c
+.RI [ end ]
Replace the string named
-.I xx
+.I str
with its substring bounded by the indices
.I start
and
@@ -2881,13 +2925,7 @@ is omitted,
it is implicitly set to the largest valid value
(the string length minus one).
.
-If the index value
-.I start
-or
-.I end
-is negative,
-it is counted from the end of the string,
-going backwards:
+Negative indices count backwards from the end of the string:
the last character has index\~\-1,
the character before the last has index\~\-2,
and so on.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 04/04: Update string documentation (again).,
G. Branden Robinson <=