X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Futilities.texi;h=314c435e37d1a1985202f4738ea5bf007815ad24;hb=45eea3ba2455d9aebd471bbe9396581d255c266e;hp=009706e22584dc8591508992813cd6d4ff08cd9d;hpb=fad7434e2db08ed248228e03533b314b8335ef2f;p=pspp-builds.git diff --git a/doc/utilities.texi b/doc/utilities.texi index 009706e2..314c435e 100644 --- a/doc/utilities.texi +++ b/doc/utilities.texi @@ -1,4 +1,4 @@ -@node Utilities, Not Implemented, Statistics, Top +@node Utilities @chapter Utilities Commands that don't fit any other category are placed here. @@ -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,9 +51,19 @@ 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, DOCUMENT, ADD DOCUMENT, Utilities +@node COMMENT @section COMMENT @vindex COMMENT @vindex * @@ -70,7 +82,7 @@ terminate it with a dot or a blank line. -@node DOCUMENT, DISPLAY DOCUMENTS, COMMENT, Utilities +@node DOCUMENT @section DOCUMENT @vindex DOCUMENT @@ -91,7 +103,7 @@ You can extend the documentary text over as many lines as necessary. Lines are truncated at 80 bytes. Don't forget to terminate the command with a dot or a blank line. @xref{ADD DOCUMENT}. -@node DISPLAY DOCUMENTS, DISPLAY FILE LABEL, DOCUMENT, Utilities +@node DISPLAY DOCUMENTS @section DISPLAY DOCUMENTS @vindex DISPLAY DOCUMENTS @@ -103,7 +115,7 @@ DISPLAY DOCUMENTS. document is preceded by a line giving the time and date that it was added. @xref{DOCUMENT}. -@node DISPLAY FILE LABEL, DROP DOCUMENTS, DISPLAY DOCUMENTS, Utilities +@node DISPLAY FILE LABEL @section DISPLAY FILE LABEL @vindex DISPLAY FILE LABEL @@ -117,7 +129,7 @@ if any. @xref{FILE LABEL}. This command is a PSPP extension. -@node DROP DOCUMENTS, ECHO, DISPLAY FILE LABEL, Utilities +@node DROP DOCUMENTS @section DROP DOCUMENTS @vindex DROP DOCUMENTS @@ -131,7 +143,7 @@ New documents can be added with @cmd{DOCUMENT} (@pxref{DOCUMENT}). @cmd{DROP DOCUMENTS} changes only the active file. It does not modify any system files stored on disk. -@node ECHO, ERASE, DROP DOCUMENTS, Utilities +@node ECHO @section ECHO @vindex ECHO @@ -141,7 +153,7 @@ ECHO 'arbitrary text' . Use @cmd{ECHO} to write arbitrary text to the output stream. The text should be enclosed in quotation marks following the normal rules for string tokens (@pxref{Tokens}). -@node ERASE, EXECUTE, ECHO, Utilities +@node ERASE @comment node-name, next, previous, up @section ERASE @vindex ERASE @@ -155,7 +167,7 @@ file_name must be quoted. This command cannot be used if the SAFER setting is active. -@node EXECUTE, FILE LABEL, ERASE, Utilities +@node EXECUTE @section EXECUTE @vindex EXECUTE @@ -166,7 +178,7 @@ EXECUTE. @cmd{EXECUTE} causes the active file to be read and all pending transformations to be executed. -@node FILE LABEL, FINISH, EXECUTE, Utilities +@node FILE LABEL @section FILE LABEL @vindex FILE LABEL @@ -181,7 +193,7 @@ created during this PSPP run. file_label need not be quoted. If quotes are included, they become part of the file label. -@node FINISH, HOST, FILE LABEL, Utilities +@node FINISH @section FINISH @vindex FINISH @@ -192,7 +204,7 @@ FINISH. @cmd{FINISH} terminates the current PSPP session and returns control to the operating system. -@node HOST, INCLUDE, FINISH, Utilities +@node HOST @comment node-name, next, previous, up @section HOST @vindex HOST @@ -206,26 +218,73 @@ to the operating system. This command cannot be used if the SAFER setting is active. -@node INCLUDE, PERMISSIONS, HOST, Utilities +@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. -@node PERMISSIONS, SET, INCLUDE, Utilities -@comment node-name, next, previous, up + +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 @section PERMISSIONS @vindex PERMISSIONS @cindex mode @@ -249,7 +308,7 @@ unchanged. This command cannot be used if the SAFER setting is active. -@node SET, SHOW, PERMISSIONS, Utilities +@node SET @section SET @vindex SET @@ -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 @@ -621,7 +689,7 @@ When set, this setting cannot be reset during the same session, for obvious security reasons. @end table -@node SHOW, SUBTITLE, SET, Utilities +@node SHOW @comment node-name, next, previous, up @section SHOW @vindex SHOW @@ -670,7 +738,7 @@ Display the terms of PSPP's copyright licence (@pxref{License}). Specifying @cmd{SHOW} without any subcommands is equivalent to SHOW ALL. -@node SUBTITLE, TITLE, SHOW, Utilities +@node SUBTITLE @section SUBTITLE @vindex SUBTITLE @@ -688,7 +756,7 @@ Specify a subtitle as a string in quotes. The alternate syntax that did not require quotes is now obsolete. If it is used then the subtitle is converted to all uppercase. -@node TITLE, , SUBTITLE, Utilities +@node TITLE @section TITLE @vindex TITLE