work on monolithic output and outer borders

[pspp] / doc / flow-control.texi

diff --git a/doc/flow-control.texi b/doc/flow-control.texi
index d3235612b9fddb04ec0e42a1c697ae3e4afd0e17..7a2c84b4178e6e20fa6e8bc4672b160a8452e7e7 100644 (file)
--- a/doc/flow-control.texi
+++ b/doc/flow-control.texi
@@ -45,6 +45,7 @@ BREAK.
 @vindex DEFINE
 @cindex macro
 
+@node Macro Overview
 @subsection Overview
 
 @display
@@ -53,20 +54,23 @@ BREAK.
 @t{!ENDDEFINE.}
 @end display
 
+@noindent
 Each @i{argument} takes the following form:
 @display
-@r{@{}@i{!arg_name} @t{=},@t{!POSITIONAL}@r{@}}
+@r{@{}@i{!arg_name}@t{=} @math{|} @t{!POSITIONAL}@r{@}}
 @r{[}@t{!DEFAULT(}@i{default}@t{)}@r{]}
 @r{[}@t{!NOEXPAND}@r{]}
-@r{@{}@t{!TOKENS(}@i{count}@t{)},@t{!CHAREND('}@i{token}@t{')},@t{!ENCLOSE('}@i{start}@t{','}@i{end}@t{')},@t{!CMDEND}@}
+@r{@{}@t{!TOKENS(}@i{count}@t{)} @math{|} @t{!CHAREND('}@i{token}@t{')} @math{|} @t{!ENCLOSE('}@i{start}@t{' @math{|} '}@i{end}@t{')} @math{|} @t{!CMDEND}@}
 @end display
 
+@noindent
 The following directives may be used within @i{body}:
 @example
 !OFFEXPAND
 !ONEXPAND
 @end example
 
+@noindent
 The following functions may be used within the body:
 @display
 @t{!BLANKS(}@i{count}@t{)}
@@ -83,6 +87,7 @@ The following functions may be used within the body:
 @t{!UPCASE(}@i{arg}@t{)}
 @end display
 
+@noindent
 The body may also include the following constructs:
 @display
 @t{!IF (}@i{condition}@t{) !THEN} @i{true-expansion} @t{!ENDIF}
@@ -98,6 +103,7 @@ The body may also include the following constructs:
 @t{!LET} @i{!var} @t{=} @i{expression}
 @end display
 
+@node Macro Introduction
 @subsection Introduction
 
 The DEFINE command creates a @dfn{macro}, which is a name for a
@@ -188,10 +194,11 @@ DESCRIPTIVES !vars.
 FREQUENCIES /VARIABLES=!vars.
 !ENDDEFINE.
 
+* Initially define the 'vars' macro to analyze v1...v3.
 DEFINE !vars() v1 v2 v3 !ENDDEFINE.
 !commands
 
-* We can redefine the variables macro to analyze different variables:
+* Redefine 'vars' macro to analyze different variables.
 DEFINE !vars() v4 v5 !ENDDEFINE.
 !commands
 @end example
@@ -405,6 +412,10 @@ These rules apply to macro calls, not to uses within a macro body of
 macro functions, macro arguments, and macro variables created by
 @code{!DO} or @code{!LET}, which are always expanded.
 
+@code{SET MEXPAND} may appear within the body of a macro, but it will
+not affect expansion of the macro that it appears in.  Use
+@code{!OFFEXPAND} and @code{!ONEXPAND} instead.
+
 @node Macro Functions
 @subsection Macro Functions
 
@@ -448,7 +459,7 @@ In the examples below, @samp{_} stands in for a space to make the
 results visible.
 
 @c Keep these examples in sync with the test for !BLANKS in
-@c tests/language/control/define.at:
+@c tests/language/commands/define.at:
 @example
 !BLANKS(0)                  @expansion{} @r{empty}
 !BLANKS(1)                  @expansion{} _
@@ -464,7 +475,7 @@ concatenation, each quoted string argument is unquoted, as if
 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:
+@c tests/language/commands/define.at:
 @example
 !CONCAT(x, y)                @expansion{} xy
 !CONCAT('x', 'y')            @expansion{} xy
@@ -477,7 +488,7 @@ 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:
+@c tests/language/commands/define.at:
 @example
 !CONCAT(x, 0)                @expansion{} x0
 !CONCAT(x, 0, y)             @expansion{} x0y
@@ -489,7 +500,7 @@ 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:
+@c tests/language/commands/define.at:
 @example
 !CONCAT(0, x)                @expansion{} 0 x
 !CONCAT(0, x, y)             @expansion{} 0 xy
@@ -578,6 +589,8 @@ Expands to a number token representing the number of characters in
 @deffn {Macro Function} !NULL
 Expands to an empty character sequence.
 
+@c Keep these examples in sync with the test for !NULL in
+@c tests/language/commands/define.at:
 @example
 !NULL                        @expansion{} @r{empty}
 !QUOTE(!NULL)                @expansion{} ''
@@ -596,6 +609,8 @@ to the string's contents, with the quotes removed and any doubled
 quote marks reduced to singletons.  If the argument was not a quoted
 string, @code{!UNQUOTE} expands to the argument unchanged.
 
+@c Keep these examples in sync with the test for !QUOTE and !UNQUOTE in
+@c tests/language/commands/define.at:
 @example
 !QUOTE(123.0)                @expansion{} '123.0'
 !QUOTE( 123 )                @expansion{} '123'
@@ -794,10 +809,6 @@ a macro that calls itself.
 MITERATE (@pxref{SET MITERATE}) limits the number of iterations in a
 @code{!DO} construct.  The default is 1000.
 
-PRESERVE...RESTORE
-
-SET MEXPAND, etc. doesn't work inside macro bodies.
-
 @node Macro Notes
 @subsection Additional Notes
 
@@ -806,9 +817,9 @@ SET MEXPAND, etc. doesn't work inside macro bodies.
 If the body of macro A includes a call to macro B, the call can use
 macro arguments (including @code{!*}) and macro variables as part of
 arguments to B.  For @code{!TOKENS} arguments, the argument or
-variable name counts as one token regardless of the number that
-expands into, for @code{!CHAREND} and @code{!ENCLOSE} arguments the
-delimiters come only from the call, not the expansions, and
+variable name counts as one token regardless of the number that it
+expands into; for @code{!CHAREND} and @code{!ENCLOSE} arguments, the
+delimiters come only from the call, not the expansions; and
 @code{!CMDEND} ends at the calling command, not any end of command
 within an argument or variable.
 
@@ -998,11 +1009,9 @@ code block is executed.  The condition is evaluated at the end of the
 loop, not at the beginning, so that the body of a loop with only a
 condition on @cmd{END LOOP} will always execute at least once.
 
-If the index clause is not
-present, then the loop is executed at most @var{max_loops} (@pxref{SET}) times
-(but possibly fewer, if a condition clause evaluates to false or if
-@cmd{BREAK} executes).
-The default value of @var{max_loops} is 40.
+If the index clause is not present, then the global @code{MXLOOPS}
+setting, which defaults to 40, limits the number of iterations
+(@pxref{SET MXLOOPS}).
 
 @cmd{BREAK} also terminates @cmd{LOOP} execution (@pxref{BREAK}).