X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Futilities.texi;h=3779615a6739ebf67e803fdde1bb672f7e88421b;hb=5cdb1f83c37674ee6d588bb0104729d564012ecb;hp=6882aa2165f525aa2b12ae466da5d762eabe95af;hpb=14aac9fe7a7efbb6c9bded2ed5969a643cb76645;p=pspp-builds.git diff --git a/doc/utilities.texi b/doc/utilities.texi index 6882aa21..3779615a 100644 --- a/doc/utilities.texi +++ b/doc/utilities.texi @@ -9,22 +9,24 @@ they take effect only once, unconditionally, at the time that they are encountered in the input. @menu -* ADD DOCUMENT:: Add documentary text to the active file. +* ADD DOCUMENT:: Add documentary text to the active dataset. +* CACHE:: Ignored for compatibility. * CD:: Change the current directory. * COMMENT:: Document your syntax file. -* DOCUMENT:: Document the active file. -* DISPLAY DOCUMENTS:: Display active file documents. -* DISPLAY FILE LABEL:: Display the active file label. -* DROP DOCUMENTS:: Remove documents from the active file. +* DOCUMENT:: Document the active dataset. +* DISPLAY DOCUMENTS:: Display active dataset documents. +* DISPLAY FILE LABEL:: Display the active dataset label. +* DROP DOCUMENTS:: Remove documents from the active dataset. * ECHO:: Write a string to the output stream. * ERASE:: Erase a file. * EXECUTE:: Execute pending transformations. -* FILE LABEL:: Set the active file's label. +* FILE LABEL:: Set the active dataset's label. * 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. +* PRESERVE and RESTORE:: Saving settings and restoring them later. * SET:: Adjust PSPP runtime parameters. * SHOW:: Display runtime parameters. * SUBTITLE:: Provide a document subtitle. @@ -43,14 +45,24 @@ ADD DOCUMENT @cmd{ADD DOCUMENT} adds one or more lines of descriptive commentary to -the active file. Documents added in this way are saved to system files. +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 file with @cmd{DROP +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 may not be more than 80 bytes long. @xref{DOCUMENT}. +@node CACHE +@section CACHE +@vindex CACHE + +@display +CACHE. +@end display + +This command is accepted, for compatibility, but it has no effect. + @node CD @section CD @vindex CD @@ -91,9 +103,9 @@ DOCUMENT @var{documentary_text}. @end display @cmd{DOCUMENT} adds one or more lines of descriptive commentary to the -active file. Documents added in this way are saved to system files. +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 file with @cmd{DROP +DOCUMENTS}. They can be removed from the active dataset with @cmd{DROP DOCUMENTS}. Specify the @var{documentary text} following the DOCUMENT keyword. @@ -111,7 +123,7 @@ the command with a dot or a blank line. @xref{ADD DOCUMENT}. DISPLAY DOCUMENTS. @end display -@cmd{DISPLAY DOCUMENTS} displays the documents in the active file. Each +@cmd{DISPLAY DOCUMENTS} displays the documents in the active dataset. Each document is preceded by a line giving the time and date that it was added. @xref{DOCUMENT}. @@ -124,7 +136,7 @@ DISPLAY FILE LABEL. @end display @cmd{DISPLAY FILE LABEL} displays the file label contained in the -active file, +active dataset, if any. @xref{FILE LABEL}. This command is a PSPP extension. @@ -137,10 +149,10 @@ This command is a PSPP extension. DROP DOCUMENTS. @end display -@cmd{DROP DOCUMENTS} removes all documents from the active file. +@cmd{DROP DOCUMENTS} removes all documents from the active dataset. New documents can be added with @cmd{DOCUMENT} (@pxref{DOCUMENT}). -@cmd{DROP DOCUMENTS} changes only the active file. It does not modify any +@cmd{DROP DOCUMENTS} changes only the active dataset. It does not modify any system files stored on disk. @node ECHO @@ -175,7 +187,7 @@ This command cannot be used if the SAFER setting is active. EXECUTE. @end display -@cmd{EXECUTE} causes the active file to be read and all pending +@cmd{EXECUTE} causes the active dataset to be read and all pending transformations to be executed. @node FILE LABEL @@ -186,7 +198,7 @@ transformations to be executed. FILE LABEL file_label. @end display -@cmd{FILE LABEL} provides a title for the active file. This +@cmd{FILE LABEL} provides a title for the active dataset. This title will be saved into system files and portable files that are created during this PSPP run. @@ -211,19 +223,26 @@ control to the operating system. @display HOST. +HOST COMMAND=['command'...]. @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 setting is active. +If the 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. + +If no subcommands are specified, then PSPP invokes an interactive +subshell. @node INCLUDE @section INCLUDE @vindex INCLUDE @display - INCLUDE [FILE=]'file-name'. + INCLUDE [FILE=]'file-name' [ENCODING='encoding']. @end display @cmd{INCLUDE} causes the PSPP command processor to read an @@ -234,19 +253,11 @@ 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}) is a more flexible +alternative to @cmd{INCLUDE}. An INCLUDE command acts the same as +INSERT with ERROR=STOP CD=NO SYNTAX=BATCH specified. -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 - +The optional ENCODING subcommand has the same meaning as on INSERT. @node INSERT @section INSERT @@ -256,7 +267,8 @@ INSERT FILE=@var{file-name} ERROR=STOP CD=NO SYNTAX=BATCH. INSERT [FILE=]'file-name' [CD=@{NO,YES@}] [ERROR=@{CONTINUE,STOP@}] - [SYNTAX=@{BATCH,INTERACTIVE@}]. + [SYNTAX=@{BATCH,INTERACTIVE@}] + [ENCODING='encoding']. @end display @cmd{INSERT} is similar to @cmd{INCLUDE} (@pxref{INCLUDE}) @@ -284,6 +296,37 @@ the included file must conform to interactive syntax conventions. @xref{Syntax Variants}. The default setting is @samp{SYNTAX=BATCH}. +ENCODING optionally specifies the character set used by the included +file. Its argument, which is not case-sensitive, must be in one of +the following forms: + +@table @asis +@item @code{Locale} +The encoding used by the system locale, or as overridden by the SET +LOCALE command (@pxref{SET}). On Unix systems, environment variables, +e.g.@: @env{LANG} or @env{LC_ALL}, determine the system locale. + +@item IANA character set name +One of the character set names listed by IANA at +@uref{http://www.iana.org/assignments/character-sets}. Some examples +are @code{ASCII} (United States), @code{ISO-8859-1} (western Europe), +@code{EUC-JP} (Japan), and @code{windows-1252} (Windows). Not all +systems support all character sets. + +@item @code{Auto} +@item @code{Auto,@var{encoding}} +Automatically detects whether a syntax file is encoded in +@var{encoding} or in a Unicode encoding such as UTF-8, UTF-16, or +UTF-32. The @var{encoding} may be an IANA character set name or +@code{Locale} (the default). Only ASCII compatible encodings can +automatically be distinguished from UTF-8 (the most common locale +encodings are all ASCII-compatible). +@end table + +When ENCODING is not specified, the default is taken from the +@option{--syntax-encoding} command option, if it was specified, and +otherwise it is @code{Auto}. + @node PERMISSIONS @section PERMISSIONS @vindex PERMISSIONS @@ -308,6 +351,22 @@ unchanged. This command cannot be used if the SAFER setting is active. +@node PRESERVE and RESTORE +@section PRESERVE and RESTORE +@vindex PRESERVE +@vindex RESTORE + +@display +PRESERVE. +@dots{} +RESTORE. +@end display + +@cmd{PRESERVE} saves all of the settings that @cmd{SET} (@pxref{SET}) +can adjust. A later @cmd{RESTORE} command restores those settings. + +@cmd{PRESERVE} can be nested up to five levels deep. + @node SET @section SET @vindex SET @@ -323,20 +382,13 @@ SET /RIB=@{NATIVE,MSBFIRST,LSBFIRST,VAX@} /RRB=@{NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL@} -(program input) - /ENDCMD='.' - /NULLINE=@{ON,OFF@} - (interaction) - /CPROMPT='cprompt_string' - /DPROMPT='dprompt_string' - /ERRORBREAK=@{OFF,ON@} /MXERRS=max_errs /MXWARNS=max_warnings - /PROMPT='prompt' /WORKSPACE=workspace_size -(program execution) +(syntax execution) + /LOCALE='locale' /MEXPAND=@{ON,OFF@} /MITERATE=max_iterations /MNEST=max_nest @@ -353,19 +405,17 @@ SET /WRB=@{NATIVE,ISL,ISB,IDL,IDB,VF,VD,VG,ZS,ZL@} (output routing) - /ECHO=@{ON,OFF@} /ERRORS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@} - /INCLUDE=@{ON,OFF@} /MESSAGES=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@} - /PRINTBACK=@{ON,OFF@} + /PRINTBACK=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@} /RESULTS=@{ON,OFF,TERMINAL,LISTING,BOTH,NONE@} (output driver options) /HEADERS=@{NO,YES,BLANK@} /LENGTH=@{NONE,length_in_lines@} - /LISTING=@{ON,OFF,'file-name'@} /MORE=@{ON,OFF@} /WIDTH=@{NARROW,WIDTH,n_characters@} + /TNUMBERS=@{VALUES,LABELS,BOTH@} (logging) /JOURNAL=@{ON,OFF@} ['file-name'] @@ -383,7 +433,6 @@ SET /BOXSTRING=@{'xxx','xxxxxxxxxxx'@} /CASE=@{UPPER,UPLOW@} /CPI=cpi_value - /DISK=@{ON,OFF@} /HIGHRES=@{ON,OFF@} /HISTOGRAM='c' /LOWRES=@{AUTO,ON,OFF@} @@ -500,50 +549,37 @@ formats are only for use with very old input files. The default is NATIVE. @end table -Program input subcommands affect the way that programs are parsed when -they are typed interactively or run from a command file. They are - -@table @asis -@item ENDCMD -This is a single character indicating the end of a command. The default -is @samp{.}. Don't change this. - -@item NULLINE -Whether a blank line is interpreted as ending the current command. The -default is ON. -@end table - Interaction subcommands affect the way that PSPP interacts with an online user. The interaction subcommands are @table @asis -@item CPROMPT -The command continuation prompt. The default is @samp{ > }. - -@item DPROMPT -Prompt used when expecting data input within @cmd{BEGIN DATA} (@pxref{BEGIN -DATA}). The default is @samp{data> }. - -@item ERRORBREAK -Whether an error causes PSPP to stop processing the current command -file after finishing the current command. The default is OFF. - @item MXERRS The maximum number of errors before PSPP halts processing of the current command file. The default is 50. @item MXWARNS The maximum number of warnings + errors before PSPP halts processing the -current command file. The default is 100. - -@item PROMPT -The command prompt. The default is @samp{PSPP> }. +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 +that warnings will not be given. +The default value is 100. @end table -Program execution subcommands control the way that PSPP commands -execute. The program execution subcommands are +Syntax execution subcommands control the way that PSPP commands +execute. The syntax execution subcommands are @table @asis +@item LOCALE +Overrides the system locale for the purpose of reading and writing +syntax and data files. The argument should be a locale name in the +general form @code{language_country.encoding}, where @code{language} +and @code{country} are 2-character language and country abbreviations, +respectively, and @code{encoding} is an IANA character set name. +Example locales are @code{en_US.UTF-8} (UTF-8 encoded English as +spoken in the United States) and @code{ja_JP.EUC-JP} (EUC-JP encoded +Japanese as spoken in Japan). + @item MEXPAND @itemx MITERATE @itemx MNEST @@ -552,6 +588,7 @@ Currently not used. @item MXLOOPS The maximum number of iterations for an uncontrolled loop (@pxref{LOOP}). +The default MXLOOPS is 40. @item SEED The initial pseudo-random number seed. Set to a real number or to @@ -615,41 +652,75 @@ RB format (@pxref{Binary and Hexadecimal Numeric Formats}). The choices are the same as SET RIB. The default is NATIVE. @end table -Output routing subcommands affect where the output of transformations -and procedures is sent. These subcommands are +In the PSPP text-based interface, the output routing subcommands +affect where output is sent. The following values are allowed for +each of these subcommands: @table @asis -@item ECHO +@item OFF +@item NONE +Discard this kind of output. + +@item TERMINAL +Write this output to the terminal, but not to listing files and other +output devices. + +@item LISTING +Write this output to listing files and other output devices, but not +to the terminal. -If turned on, commands are written to the listing file as they are read -from command files. The default is OFF. +@item ON +@itemx BOTH +Write this type of output to all output devices. +@end table + +These output routing subcommands are: + +@table @asis +@item ERRORS +Applies to error and warning messages. The default is BOTH. + +@item MESSAGES +Applies to notes. The default is BOTH. -@itemx ERRORS -@itemx INCLUDE -@itemx MESSAGES @item PRINTBACK +Determines whether the syntax used for input is printed back as part +of the output. The default is NONE. + @item RESULTS -Currently not used. +Applies to everything not in one of the above categories, such as the +results of statistical procedures. The default is BOTH. @end table +These subcommands have no effect on output in the PSPP GUI +environment. + Output driver option subcommands affect output drivers' settings. These subcommands are @table @asis @item HEADERS @itemx LENGTH -@itemx LISTING @itemx MORE -@itemx PAGER @itemx WIDTH +@itemx TNUMBERS +The TNUMBERS option sets the way in which values are displayed in output tables. +The valid settings are VALUES, LABELS and BOTH. +If TNUMBERS is set to 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 TNUMBERS is set to 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 TNUMBERS is set to BOTH, then values will be displayed with both their label +(if any) and their literal value in parenthesis. @end table @cindex headers @cindex length -@cindex listing @cindex more @cindex pager @cindex width +@cindex tnumbers Logging subcommands affect logging of commands executed to external @@ -753,7 +824,6 @@ SHOW [CCE] [COPYING] [DECIMALS] - [ENDCMD] [FORMAT] [LENGTH] [MXERRS]