* Smake (GNULIB_MODULES): Don't depend on memmem module, because

[pspp-builds.git] / doc / utilities.texi

diff --git a/doc/utilities.texi b/doc/utilities.texi
index 116c49fa8cb6b5a6ca4dc359bbad58108798f587..314c435e37d1a1985202f4738ea5bf007815ad24 100644 (file)
--- a/doc/utilities.texi
+++ b/doc/utilities.texi
@@ -10,6 +10,7 @@ encountered in the input.
 
 @menu
 * ADD DOCUMENT::                Add documentary text to the active file.
+* CD::                          Change the current directory.
 * COMMENT::                     Document your syntax file.
 * DOCUMENT::                    Document the active file.
 * DISPLAY DOCUMENTS::           Display active file documents.
@@ -22,6 +23,7 @@ encountered in the input.
 * FINISH::                      Terminate the PSPP session.
 * HOST::                        Temporarily return to the operating system.
 * INCLUDE::                     Include a file within the current one.
+* INSERT::                      Insert a file within the current one.
 * PERMISSIONS::                 Change permissions on a file.
 * SET::                         Adjust PSPP runtime parameters.
 * SHOW::                        Display runtime parameters.
@@ -29,7 +31,7 @@ encountered in the input.
 * TITLE::                       Provide a document title.
 @end menu
 
-@node ADD DOCUMENT, COMMENT, Utilities, Utilities
+@node ADD DOCUMENT
 @comment  node-name,  next,  previous,  up
 @section ADD DOCUMENT
 @vindex  ADD DOCUMENT
@@ -49,7 +51,17 @@ DOCUMENTS}.
 Each line of documentary text must be enclosed in quotation marks, and 
 may not be more than 80 bytes long. @xref{DOCUMENT}.
 
+@node CD
+@section CD
+@vindex CD
+@cindex directory
+@cindex changing directory
 
+@display
+CD 'new directory' .
+@end display 
+
+@cmd{CD} changes the current directory.  The new directory will become that specified by the command.
 
 @node COMMENT
 @section COMMENT
@@ -209,23 +221,70 @@ This command cannot be used if the SAFER setting is active.
 @node INCLUDE
 @section INCLUDE
 @vindex INCLUDE
-@vindex @@
 
 @display
-Two possible syntaxes:
-        INCLUDE 'file-name'.
-        @@file-name.
+        INCLUDE [FILE=]'file-name'.
 @end display
 
 @cmd{INCLUDE} causes the PSPP command processor to read an
 additional command file as if it were included bodily in the current
 command file.
-
+If errors are encountered in the included file, then command processing will 
+stop and no more commands will be processed.
 Include files may be nested to any depth, up to the limit of available
 memory.
 
+
+The @cmd{INSERT} command (@pxref{INSERT}) may be used instead of
+@cmd{INCLUDE} if you require more flexible options.
+The syntax 
+@example
+INCLUDE FILE=@var{file-name}.
+@end example
+@noindent 
+functions identically to 
+@example
+INSERT FILE=@var{file-name} ERROR=STOP CD=NO SYNTAX=BATCH.
+@end example
+
+
+@node INSERT
+@section INSERT
+@vindex INSERT
+
+@display
+     INSERT [FILE=]'file-name'
+        [CD=@{NO,YES@}]
+        [ERROR=@{CONTINUE,STOP@}]
+        [SYNTAX=@{BATCH,INTERACTIVE@}].
+@end display
+
+@cmd{INSERT} is similar to @cmd{INCLUDE} (@pxref{INCLUDE}) 
+but somewhat more flexible.
+It causes the command processor to read a file as if it were embedded in the 
+current command file.
+
+If @samp{CD=YES} is specified, then before including the file, the
+current directory  will be changed to the directory of the included
+file.  
+The default setting is @samp{CD=NO}.
+Note that this directory will remain current until it is
+changed explicitly (with the @cmd{CD} command, or a subsequent
+@cmd{INSERT} command with the @samp{CD=YES} option).
+It will not revert to its original setting even after the included
+file is finished processing.
+
+If @samp{ERROR=STOP} is specified, errors encountered in the
+inserted file will cause processing to immediately cease.
+Otherwise processing will continue at the next command.
+The default setting is @samp{ERROR=CONTINUE}.
+
+If @samp{SYNTAX=INTERACTIVE} is specified then the syntax contained in
+the included file must conform to interactive syntax
+conventions. @xref{Syntax Variants}.
+The default setting is @samp{SYNTAX=BATCH}.
+
 @node PERMISSIONS
-@comment  node-name,  next,  previous,  up
 @section PERMISSIONS
 @vindex PERMISSIONS
 @cindex mode
@@ -347,6 +406,7 @@ files.  The data input subcommands are
 
 @table @asis
 @item BLANKS
+@anchor{SET BLANKS}
 This is the value assigned to an item data item that is empty or
 contains only white space.  An argument of SYSMIS or '.' will cause the
 system-missing value to be assigned to null items.  This is the
@@ -581,8 +641,16 @@ files.  These subcommands are
 
 @table @asis
 @item JOURNAL
-@item LOG
-Not currently used.
+@itemx LOG
+These subcommands, which are synonyms, control the journal.  The
+default is ON, which causes commands entered interactively to be
+written to the journal file.  Commands included from syntax files that
+are included interactively and error messages printed by PSPP are also
+written to the journal file, prefixed by @samp{>}.  OFF disables use
+of the journal.
+
+The journal is named @file{pspp.jnl} by default.  A different name may
+be specified.
 @end table
 
 System file subcommands affect the default format of system files