X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Futilities.texi;h=a5db44b5a6312b94a8c97641a663e2f961f2168e;hb=d1baacabfbff9bfc0178b2dd2ac82c245ba831cf;hp=f229f0ee7fb8df70538582d5094bb31272ffa142;hpb=937311ef101f8109bb1baf3839aad6b42d871b75;p=pspp diff --git a/doc/utilities.texi b/doc/utilities.texi index f229f0ee7f..a5db44b5a6 100644 --- a/doc/utilities.texi +++ b/doc/utilities.texi @@ -1,5 +1,5 @@ @c PSPP - a program for statistical analysis. -@c Copyright (C) 2017 Free Software Foundation, Inc. +@c Copyright (C) 2017, 2020 Free Software Foundation, Inc. @c Permission is granted to copy, distribute and/or modify this document @c under the terms of the GNU Free Documentation License, Version 1.3 @c or any later version published by the Free Software Foundation; @@ -48,18 +48,18 @@ encountered in the input. @vindex ADD DOCUMENT @display -ADD DOCUMENT +ADD DOCUMENT 'line one' 'line two' @dots{} 'last line' . @end display -@cmd{ADD DOCUMENT} adds one or more lines of descriptive commentary to +@cmd{ADD DOCUMENT} adds one or more lines of descriptive commentary to the active dataset. Documents added in this way are saved to system files. They can be viewed using @cmd{SYSFILE INFO} or @cmd{DISPLAY DOCUMENTS}. They can be removed from the active dataset with @cmd{DROP DOCUMENTS}. -Each line of documentary text must be enclosed in quotation marks, and +Each line of documentary text must be enclosed in quotation marks, and may not be more than 80 bytes long. @xref{DOCUMENT}. @node CACHE @@ -80,28 +80,36 @@ This command is accepted, for compatibility, but it has no effect. @display CD 'new directory' . -@end display +@end display -@cmd{CD} changes the current directory. The new directory will become that specified by the command. +@cmd{CD} changes the current directory. The new directory becomes +that specified by the command. @node COMMENT @section COMMENT @vindex COMMENT @vindex * -@display -Two possibles syntaxes: - COMMENT comment text @dots{} . - *comment text @dots{} . +@display +Comment commands: + COMMENT comment text @dots{} . + *comment text @dots{} . + +Comments within a line of syntax: + FREQUENCIES /VARIABLES=v0 v1 v2. /* All our categorical variables. @end display @cmd{COMMENT} is ignored. It is used to provide information to -the author and other readers of the @pspp{} syntax file. - -@cmd{COMMENT} can extend over any number of lines. Don't forget to -terminate it with a dot or a blank line. +the author and other readers of the @pspp{} syntax file. +@cmd{COMMENT} can extend over any number of lines. It ends at a dot +at the end of a line or a blank line. The comment may contain any +characters. +PSPP also supports comments within a line of syntax, introduced with +@samp{/*}. These comments end at the first @samp{*/} or at the end of +the line, whichever comes first. A line that contains just this kind +of comment is considered blank and ends the current command. @node DOCUMENT @section DOCUMENT @@ -117,12 +125,13 @@ They can be viewed using @cmd{SYSFILE INFO} or @cmd{DISPLAY DOCUMENTS}. They can be removed from the active dataset with @cmd{DROP DOCUMENTS}. -Specify the @var{documentary text} following the @subcmd{DOCUMENT} keyword. -It is interpreted literally --- any quotes or other punctuation marks -will be included in the file. -You can extend the documentary text over as many lines as necessary. +Specify the @var{documentary text} following the @subcmd{DOCUMENT} keyword. +It is interpreted literally---any quotes or other punctuation marks +are included in the file. +You can extend the documentary text over as many lines as necessary, +including blank lines to separate paragraphs. Lines are truncated at 80 bytes. Don't forget to terminate -the command with a dot or a blank line. @xref{ADD DOCUMENT}. +the command with a dot at the end of a line. @xref{ADD DOCUMENT}. @node DISPLAY DOCUMENTS @section DISPLAY DOCUMENTS @@ -168,7 +177,7 @@ system files stored on disk. @section ECHO @vindex ECHO -@display +@display ECHO 'arbitrary text' . @end display @@ -182,7 +191,7 @@ Use @cmd{ECHO} to write arbitrary text to the output stream. The text should be ERASE FILE @var{file_name}. @end display -@cmd{ERASE FILE} deletes a file from the local filesystem. +@cmd{ERASE FILE} deletes a file from the local file system. @var{file_name} must be quoted. This command cannot be used if the SAFER (@pxref{SET}) setting is active. @@ -207,7 +216,7 @@ FILE LABEL @var{file_label}. @end display @cmd{FILE LABEL} provides a title for the active dataset. This -title will be saved into system files and portable files that are +title is saved into system files and portable files that are created during this @pspp{} run. @var{file_label} should not be quoted. @@ -228,21 +237,51 @@ control to the operating system. @section HOST @vindex HOST +In the syntax below, the square brackets must be included in the +command syntax and do not indicate that that their contents are +optional. + @display -HOST. -HOST COMMAND=['@var{command}'...]. +HOST COMMAND=['@var{command}'...] + TIMELIMIT=@var{secs}. @end display -@cmd{HOST} suspends the current @pspp{} session and temporarily returns control -to the operating system. -This command cannot be used if the SAFER (@pxref{SET}) setting is active. +@cmd{HOST} executes one or more commands, each provided as a string in +the required @subcmd{COMMAND} subcommand, in the shell of the +underlying operating system. PSPP runs each command in a separate +shell process and waits for it to finish before running the next one. +If a command fails (with a nonzero exit status, or because it is +killed by a signal), then PSPP does not run any remaining commands. + +PSPP provides @file{/dev/null} as the shell's standard input. If a +process needs to read from stdin, redirect from a file or device, or +use a pipe. -If the @subcmd{COMMAND} subcommand is specified, as a sequence of shell -commands as quoted strings within square brackets, then @pspp{} executes -them together in a single subshell. +PSPP displays the shell's standard output and standard error as PSPP +output. Redirect to a file or @code{/dev/null} or another device if +this is not desired. -If no subcommands are specified, then @pspp{} invokes an interactive -subshell. +The following example runs @code{rsync} to copy a file from a remote +server to the local file @file{data.txt}, writing @code{rsync}'s own +output to @file{rsync-log.txt}. PSPP displays the command's error +output, if any. If @code{rsync} needs to prompt the user (@i{e.g.}@: to +obtain a password), the command fails. Only if the @code{rsync} +succeeds, PSPP then runs the @code{sha512sum} command. + +@example +HOST COMMAND=['rsync remote:data.txt data.txt > rsync-log.txt' + 'sha512sum -c data.txt.sha512sum]. +@end example + +By default, PSPP waits as long as necessary for the series of commands +to complete. Use the optional @subcmd{TIMELIMIT} subcommand to limit +the execution time to the specified number of seconds. + +PSPP built for mingw does not support all the features of +@subcmd{HOST}. + +PSPP rejects this command if the SAFER (@pxref{SET}) setting is +active. @node INCLUDE @section INCLUDE @@ -255,8 +294,8 @@ subshell. @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. +If errors are encountered in the included file, then command +processing stops and no more commands are processed. Include files may be nested to any depth, up to the limit of available memory. @@ -278,24 +317,24 @@ The optional @subcmd{ENCODING} subcommand has the same meaning as with @cmd{INSE [ENCODING=@{LOCALE, '@var{charset_name}'@}]. @end display -@cmd{INSERT} is similar to @cmd{INCLUDE} (@pxref{INCLUDE}) +@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 +It causes the command processor to read a file as if it were embedded in the current command file. If @subcmd{CD=YES} is specified, then before including the file, the -current directory will be changed to the directory of the included -file. +current directory becomes the directory of the included +file. The default setting is @samp{CD=NO}. -Note that this directory will remain current until it is +Note that this directory remains 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 +It does not revert to its original setting even after the included file is finished processing. If @subcmd{ERROR=STOP} is specified, errors encountered in the -inserted file will cause processing to immediately cease. -Otherwise processing will continue at the next command. +inserted file causes processing to immediately cease. +Otherwise processing continues at the next command. The default setting is @subcmd{ERROR=CONTINUE}. If @subcmd{SYNTAX=INTERACTIVE} is specified then the syntax contained in @@ -309,9 +348,9 @@ the following forms: @table @asis @item @subcmd{LOCALE} -The encoding used by the system locale, or as overridden by the +The encoding used by the system locale, or as overridden by the @cmd{SET} command (@pxref{SET}). On GNU/Linux and other Unix-like systems, -environment variables, e.g.@: @env{LANG} or @env{LC_ALL}, determine the +environment variables, @i{e.g.}@: @env{LANG} or @env{LC_ALL}, determine the system locale. @item @var{charset_name} @@ -359,15 +398,17 @@ OUTPUT MODIFY @note{In the above synopsis the characters @samp{[} and @samp{]} are literals. They must appear in the syntax to be interpreted.} -@cmd{OUTPUT} changes the appearance of the tables in which results are printed. -In particular, it can be used to set the format and precision to which results are displayed. +@cmd{OUTPUT} changes the appearance of the tables in which results are +printed. In particular, it can be used to set the format and precision +to which results are displayed. -After running this command, the default table appearance parameters will have been modified and each -new output table generated will use the new parameters. +After running this command, the default table appearance parameters +will have been modified and each new output table generated uses +the new parameters. -Following @code{/TABLECELLS SELECT =} a list of cell classes must appear, enclosed in square -brackets. This list determines the classes of values should be selected for modification. -Each class can be: +Following @code{/TABLECELLS SELECT =} a list of cell classes must +appear, enclosed in square brackets. This list determines the classes +of values should be selected for modification. Each class can be: @table @asis @item RESIDUAL @@ -407,15 +448,15 @@ PERMISSIONS /PERMISSIONS = @{READONLY,WRITEABLE@}. @end display -@cmd{PERMISSIONS} changes the permissions of a file. +@cmd{PERMISSIONS} changes the permissions of a file. There is one mandatory subcommand which specifies the permissions to -which the file should be changed. -If you set a file's permission to @subcmd{READONLY}, then the file will become -unwritable either by you or anyone else on the system. -If you set the permission to @subcmd{WRITEABLE}, then the file will become -writeable by you; the permissions afforded to others will be -unchanged. -This command cannot be used if the @subcmd{SAFER} (@pxref{SET}) setting is active. +which the file should be changed. +If you set a file's permission to @subcmd{READONLY}, then the file +will become unwritable either by you or anyone else on the system. +If you set the permission to @subcmd{WRITEABLE}, then the file becomes +writeable by you; the permissions afforded to others are unchanged. +This command cannot be used if the @subcmd{SAFER} (@pxref{SET}) +setting is active. @node PRESERVE and RESTORE @@ -515,9 +556,9 @@ SET @cmd{SET} allows the user to adjust several parameters relating to @pspp{}'s execution. Since there are many subcommands to this command, its -subcommands will be examined in groups. +subcommands are examined in groups. -For subcommands that take boolean values, @subcmd{ON} and @subcmd{YES} are synonymous, +For subcommands that take boolean values, @subcmd{ON} and @subcmd{YES} are synonymous, as are @subcmd{OFF} and @subcmd{NO}, when used as subcommand values. The data input subcommands affect the way that data is read from data @@ -527,7 +568,7 @@ files. The data input subcommands are @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 +contains only white space. An argument of SYSMIS or '.' causes the system-missing value to be assigned to null items. This is the default. Any real value may be assigned. @@ -539,7 +580,7 @@ Setting it to @subcmd{DOT} causes the decimal point character to be Setting it to @subcmd{COMMA} causes the decimal point character to be @samp{,} and the grouping character to be @samp{.}. -If the setting is @subcmd{COMMA}, then @samp{,} will not be treated +If the setting is @subcmd{COMMA}, then @samp{,} is not treated as a field separator in the @cmd{DATA LIST} command (@pxref{DATA LIST}). The default value is determined from the system locale. @@ -558,7 +599,7 @@ epoch. If @subcmd{AUTOMATIC} (the default) is specified, then the epoch begins 69 years before the current date. @item RIB -@anchor{SET RIB} +@anchor{SET RIB} @pspp{} extension to set the byte ordering (endianness) used for reading data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric @@ -608,7 +649,7 @@ order. @item ZS 32-bit IBM Z architecture short format hexadecimal floating point, in -big-endian byte order. +big-endian byte order. @item ZL 64-bit IBM Z architecture long format hexadecimal floating point, in @@ -630,9 +671,9 @@ command file. The default is 50. @item MXWARNS The maximum number of warnings + errors before @pspp{} halts processing the -current command file. +current command file. The special value of zero means that all warning situations should be ignored. -No warnings will be issued, except a single initial warning advising the user +No warnings are issued, except a single initial warning advising you that warnings will not be given. The default value is 100. @end table @@ -662,8 +703,8 @@ The maximum number of iterations for an uncontrolled loop (@pxref{LOOP}). The default @var{max_loops} is 40. @item SEED -The initial pseudo-random number seed. Set to a real number or to -RANDOM, which will obtain an initial seed from the current time of day. +The initial pseudo-random number seed. Set it to a real number or to +RANDOM, to obtain an initial seed from the current time of day. @item UNDEFINED Currently not used. @@ -676,13 +717,13 @@ possibilities for rounding with the RND operator (@pxref{Miscellaneous Mathematics}). The default @var{fuzzbits} is 6. @item WORKSPACE -The maximum amount of memory (in kilobytes) that @pspp{} will use to store data being processed. -If memory in excess of the workspace size is required, then @pspp{} will start -to use temporary files to store the data. -Setting a higher value will, in general, mean procedures will run faster, -but may cause other applications to run slower. -On platforms without virtual memory management, setting a very large workspace -may cause @pspp{} to abort. +The maximum amount of memory (in kilobytes) that @pspp{} uses to +store data being processed. If memory in excess of the workspace size +is required, then @pspp{} starts to use temporary files to store +the data. Setting a higher value means that procedures +run faster, but may cause other applications to run slower. +On platforms without virtual memory management, setting a very large +workspace may cause @pspp{} to abort. @cindex workspace @cindex memory, amount used to store cases @end table @@ -711,7 +752,7 @@ Allows the default numeric input/output format to be specified. The default is F8.2. @xref{Input and Output Formats}. @item WIB -@anchor{SET WIB} +@anchor{SET WIB} @pspp{} extension to set the byte ordering (endianness) used for writing data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric @@ -783,27 +824,27 @@ subcommands are @itemx TNUMBERS The @subcmd{TNUMBERS} option sets the way in which values are displayed in output tables. The valid settings are @subcmd{VALUES}, @subcmd{LABELS} and @subcmd{BOTH}. -If @subcmd{TNUMBERS} is set to @subcmd{VALUES}, then all values are displayed with their literal value +If @subcmd{TNUMBERS} is set to @subcmd{VALUES}, then all values are displayed with their literal value (which for a numeric value is a number and for a string value an alphanumeric string). If @subcmd{TNUMBERS} is set to @subcmd{LABELS}, then values are displayed using their assigned labels if any. (@xref{VALUE LABELS}.) -If the a value has no label, then it will be displayed using its literal value. -If @subcmd{TNUMBERS} is set to @subcmd{BOTH}, then values will be displayed with both their label +If the value has no label, then the literal value is used for display. +If @subcmd{TNUMBERS} is set to @subcmd{BOTH}, then values are displayed with both their label (if any) and their literal value in parentheses. @item TVARS The @subcmd{TVARS} option sets the way in which variables are displayed in output tables. The valid settings are @subcmd{NAMES}, @subcmd{LABELS} and @subcmd{BOTH}. If @subcmd{TVARS} is set to @subcmd{NAMES}, then all variables are displayed using their names. If @subcmd{TVARS} is set to @subcmd{LABELS}, then variables are displayed using their label if one -has been set. If no label has been set, then the name will be used. +has been set. If no label has been set, then the name is used. (@xref{VARIABLE LABELS}.) -If @subcmd{TVARS} is set to @subcmd{BOTH}, then variables will be displayed with both their label +If @subcmd{TVARS} is set to @subcmd{BOTH}, then variables are displayed with both their label (if any) and their name in parentheses. @end table @cindex headers @cindex length -@cindex pager +@cindex pager @cindex width @cindex tnumbers @@ -867,11 +908,11 @@ This item is used to set the default character encoding. The encoding may be specified either as an encoding name or alias (see @url{http://www.iana.org/assignments/character-sets}), or as a locale name. -If given as a locale name, only the character encoding of the +If given as a locale name, only the character encoding of the locale is relevant. -System files written by @pspp{} will use this encoding. -System files read by @pspp{}, for which the encoding is unknown, will be +System files written by @pspp{} use this encoding. +System files read by @pspp{}, for which the encoding is unknown, are interpreted using this encoding. The full list of valid encodings and locale names/alias are operating system @@ -886,7 +927,7 @@ SET LOCALE='ru_RU.cp1251'. SET LOCALE='japanese'. @end example -Contrary to intuition, this command does not affect any aspect +Contrary to intuition, this command does not affect any aspect of the system's locale. @end table @@ -941,9 +982,9 @@ Shows the current working directory. Shows the operating system details. @item @subcmd{N} Reports the number of cases in the active dataset. The reported number is not -weighted. If no dataset is defined, then @samp{Unknown} will be reported. +weighted. If no dataset is defined, then @samp{Unknown} is reported. @item @subcmd{TEMPDIR} -Shows the path of the directory where temporary files will be stored. +Shows the path of the directory where temporary files are stored. @item @subcmd{VERSION} Shows the version of this installation of @pspp{}. @item @subcmd{WARRANTY}