!LET

[pspp] / doc / flow-control.texi

diff --git a/doc/flow-control.texi b/doc/flow-control.texi
index 27955800e6d228ca4d169776dced683871d3894e..0b3cd2786606226199f49c9d75fc5abc83d423bb 100644 (file)
--- a/doc/flow-control.texi
+++ b/doc/flow-control.texi
@@ -363,7 +363,8 @@ results visible.
 @deffn {Macro Function} !CONCAT (arg@dots{})
 Expands to the concatenation of all of the arguments.  Before
 concatenation, each quoted string argument is unquoted, as if
-@code{!UNQUOTE} were applied.
+@code{!UNQUOTE} were applied.  This allows for ``token pasting'',
+combining two (or more) tokens into a single one:
 
 @c Keep these examples in sync with the test for !CONCAT in
 @c tests/language/control/define.at:
@@ -373,6 +374,29 @@ concatenation, each quoted string argument is unquoted, as if
 !CONCAT(12, 34)              @expansion{} 1234
 !CONCAT(!NULL, 123)          @expansion{} 123
 @end example
+
+@code{!CONCAT} is often used for constructing a series of similar
+variable names from a prefix followed by a number and perhaps a
+suffix.  For example:
+
+@c Keep these examples in sync with the test for !CONCAT in
+@c tests/language/control/define.at:
+@example
+!CONCAT(x, 0)                @expansion{} x0
+!CONCAT(x, 0, y)             @expansion{} x0y
+@end example
+
+An identifier token must begin with a letter (or @samp{#} or
+@samp{@@}), which means that attempting to use a number as the first
+part of an identifier will produce a pair of distinct tokens rather
+than a single one.  For example:
+
+@c Keep these examples in sync with the test for !CONCAT in
+@c tests/language/control/define.at:
+@example
+!CONCAT(0, x)                @expansion{} 0 x
+!CONCAT(0, x, y)             @expansion{} 0 xy
+@end example
 @end deffn
 
 @deffn {Macro Function} !EVAL (arg)