doc: Improve documentation for macro support.

[pspp] / doc / flow-control.texi

diff --git a/doc/flow-control.texi b/doc/flow-control.texi
index d3235612b9fddb04ec0e42a1c697ae3e4afd0e17..2082e338037d40df5330ea00a5a6b1d84ffbc4d9 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
@@ -405,6 +411,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
 
@@ -578,6 +588,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/control/define.at:
 @example
 !NULL                        @expansion{} @r{empty}
 !QUOTE(!NULL)                @expansion{} ''
@@ -596,6 +608,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/control/define.at:
 @example
 !QUOTE(123.0)                @expansion{} '123.0'
 !QUOTE( 123 )                @expansion{} '123'
@@ -794,10 +808,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 +816,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 +1008,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}).