X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Futilities.texi;h=da5b7b0daae7d3f5ae0e99f053b53e2d8c475af2;hb=refs%2Fheads%2Fpivot-table2;hp=7d4a7c343dae7291bbcfa5967dc149b4a8aacc22;hpb=1b1837591924226078c96db15888b68beec2ef6d;p=pspp diff --git a/doc/utilities.texi b/doc/utilities.texi index 7d4a7c343d..da5b7b0daa 100644 --- a/doc/utilities.texi +++ b/doc/utilities.texi @@ -25,6 +25,7 @@ encountered in the input. * HOST:: Temporarily return to the operating system. * INCLUDE:: Include a file within the current one. * INSERT:: Insert a file within the current one. +* OUTPUT:: Modify the appearance of the output. * PERMISSIONS:: Change permissions on a file. * PRESERVE and RESTORE:: Saving settings and restoring them later. * SET:: Adjust @pspp{} runtime parameters. @@ -107,7 +108,7 @@ 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 DOCUMENT keyword. +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. @@ -169,11 +170,11 @@ Use @cmd{ECHO} to write arbitrary text to the output stream. The text should be @vindex ERASE @display -ERASE FILE file_name. +ERASE FILE @var{file_name}. @end display @cmd{ERASE FILE} deletes a file from the local filesystem. -file_name must be quoted. +@var{file_name} must be quoted. This command cannot be used if the SAFER (@pxref{SET}) setting is active. @@ -305,7 +306,7 @@ environment variables, e.g.@: @env{LANG} or @env{LC_ALL}, determine the system locale. @item @var{charset_name} -One of the character set names listed by IANA at +One of the character set names listed by @acronym{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 @@ -314,26 +315,62 @@ systems support all character sets. @item @code{Auto,@var{encoding}} Automatically detects whether a syntax file is encoded in an Unicode encoding such as UTF-8, UTF-16, or UTF-32. If it is not, then @pspp{} -generally assumes that the file is encoded in @var{encoding} (an IANA +generally assumes that the file is encoded in @var{encoding} (an @acronym{IANA} character set name). However, if @var{encoding} is UTF-8, and the syntax file is not valid UTF-8, @pspp{} instead assumes that the file is encoded in @code{windows-1252}. -For best results, @var{encoding} should be an ASCII-compatible -encoding (the most common locale encodings are all ASCII-compatible), -because encodings that are not ASCII compatible cannot be +For best results, @var{encoding} should be an @acronym{ASCII}-compatible +encoding (the most common locale encodings are all @acronym{ASCII}-compatible), +because encodings that are not @acronym{ASCII} compatible cannot be automatically distinguished from UTF-8. @item @code{Auto} @item @code{Auto,Locale} Automatic detection, as above, with the default encoding taken from -the system locale or the setting on SET LOCALE. +the system locale or the setting on @subcmd{SET LOCALE}. @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 OUTPUT +@section OUTPUT +@vindex OUTPUT +@cindex precision, of output +@cindex decimal places + +@display +OUTPUT MODIFY + /SELECT TABLES + /TABLECELLS SELECT = [ @{SIGNIFICANCE, COUNT@} ] + FORMAT = @var{fmt_spec}. +@end display +@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. + +After running this command, the default table appearance parameters will have been modified and each +new output table generated will use 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: + +@table @asis +@item SIGNIFICANCE +Significance of tests (p-values). + +@item COUNT +Counts or sums of weights. +@end table + +The value of @var{fmt_spec} must be a valid output format (@pxref{Input and Output Formats}). +Note that not all possible formats are meaningful for all classes. + @node PERMISSIONS @section PERMISSIONS @vindex PERMISSIONS @@ -423,6 +460,7 @@ SET /MORE=@{ON,OFF@} /WIDTH=@{NARROW,WIDTH,@var{n_characters}@} /TNUMBERS=@{VALUES,LABELS,BOTH@} + /TVARS=@{NAMES,LABELS,BOTH@} (logging) /JOURNAL=@{ON,OFF@} ['@var{file_name}'] @@ -473,7 +511,7 @@ default. Any real value may be assigned. @item DECIMAL @anchor{SET DECIMAL} This value may be set to @subcmd{DOT} or @subcmd{COMMA}. -Setting it to DOT causes the decimal point character to be +Setting it to @subcmd{DOT} causes the decimal point character to be @samp{.} and the grouping character to be @samp{,}. Setting it to @subcmd{COMMA} causes the decimal point character to be @samp{,} and the grouping @@ -498,11 +536,11 @@ epoch. If @subcmd{AUTOMATIC} (the default) is specified, then the epoch begins @pspp{} extension to set the byte ordering (endianness) used for reading data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric -Formats}). In MSBFIRST ordering, the most-significant byte appears at -the left end of a IB or PIB field. In LSBFIRST ordering, the -least-significant byte appears at the left end. VAX ordering is like -MSBFIRST, except that each pair of bytes is in reverse order. NATIVE, -the default, is equivalent to MSBFIRST or LSBFIRST depending on the +Formats}). In @subcmd{MSBFIRST} ordering, the most-significant byte appears at +the left end of a IB or PIB field. In @subcmd{LSBFIRST} ordering, the +least-significant byte appears at the left end. @subcmd{VAX} ordering is like +@subcmd{MSBFIRST}, except that each pair of bytes is in reverse order. @subcmd{NATIVE}, +the default, is equivalent to @subcmd{MSBFIRST} or @subcmd{LSBFIRST} depending on the native format of the machine running @pspp{}. @item RRB @@ -580,9 +618,9 @@ execute. The syntax execution subcommands are @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. +general form @code{@var{language}_@var{country}.@var{encoding}}, where @var{language} +and @var{country} are 2-character language and country abbreviations, +respectively, and @var{encoding} is an @acronym{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). @@ -605,7 +643,7 @@ RANDOM, which will obtain an initial seed from the current time of day. Currently not used. @item WORKSPACE -The maximum amount of memory that @pspp{} will use to store data being processed. +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, @@ -631,8 +669,8 @@ Set up custom currency formats. @xref{Custom Currency Formats}, for details. @item DECIMAL -The default DOT setting causes the decimal point character to be -@samp{.}. A setting of COMMA causes the decimal point character to be +The default @subcmd{DOT} setting causes the decimal point character to be +@samp{.}. A setting of @subcmd{COMMA} causes the decimal point character to be @samp{,}. @item FORMAT @@ -644,11 +682,11 @@ default is F8.2. @xref{Input and Output Formats}. @pspp{} extension to set the byte ordering (endianness) used for writing data in IB or PIB format (@pxref{Binary and Hexadecimal Numeric -Formats}). In MSBFIRST ordering, the most-significant byte appears at -the left end of a IB or PIB field. In LSBFIRST ordering, the -least-significant byte appears at the left end. VAX ordering is like -MSBFIRST, except that each pair of bytes is in reverse order. NATIVE, -the default, is equivalent to MSBFIRST or LSBFIRST depending on the +Formats}). In @subcmd{MSBFIRST} ordering, the most-significant byte appears at +the left end of a IB or PIB field. In @subcmd{LSBFIRST} ordering, the +least-significant byte appears at the left end. @subcmd{VAX} ordering is like +@subcmd{MSBFIRST}, except that each pair of bytes is in reverse order. @subcmd{NATIVE}, +the default, is equivalent to @subcmd{MSBFIRST} or @subcmd{LSBFIRST} depending on the native format of the machine running @pspp{}. @item WRB @@ -656,7 +694,7 @@ native format of the machine running @pspp{}. @pspp{} extension to set the floating-point format used for writing data in RB format (@pxref{Binary and Hexadecimal Numeric Formats}). The choices -are the same as SET RIB. The default is NATIVE. +are the same as @subcmd{SET RIB}. The default is @subcmd{NATIVE}. @end table In the @pspp{} text-based interface, the output routing subcommands @@ -685,18 +723,18 @@ These output routing subcommands are: @table @asis @item ERRORS -Applies to error and warning messages. The default is BOTH. +Applies to error and warning messages. The default is @subcmd{BOTH}. @item MESSAGES -Applies to notes. The default is BOTH. +Applies to notes. The default is @subcmd{BOTH}. @item PRINTBACK Determines whether the syntax used for input is printed back as part -of the output. The default is NONE. +of the output. The default is @subcmd{NONE}. @item RESULTS Applies to everything not in one of the above categories, such as the -results of statistical procedures. The default is BOTH. +results of statistical procedures. The default is @subcmd{BOTH}. @end table These subcommands have no effect on output in the @pspp{} GUI @@ -711,15 +749,24 @@ subcommands are @itemx MORE @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 +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 (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. +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 TNUMBERS is set to BOTH, then values will be displayed with both their label -(if any) and their literal value in parenthesis. +If @subcmd{TNUMBERS} is set to @subcmd{BOTH}, then values will be 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. +(@xref{VARIABLE LABELS}.) +If @subcmd{TVARS} is set to @subcmd{BOTH}, then variables will be displayed with both their label +(if any) and their name in parentheses. @end table @cindex headers @@ -737,10 +784,10 @@ files. These subcommands are @item JOURNAL @itemx LOG These subcommands, which are synonyms, control the journal. The -default is ON, which causes commands entered interactively to be +default is @subcmd{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 +written to the journal file, prefixed by @samp{>}. @subcmd{OFF} disables use of the journal. The journal is named @file{pspp.jnl} by default. A different name may @@ -756,7 +803,7 @@ Not currently used. @item SCOMPRESSION Whether system files created by @cmd{SAVE} or @cmd{XSAVE} are -compressed by default. The default is ON. +compressed by default. The default is @subcmd{ON}. @end table Security subcommands affect the operations that commands are allowed to @@ -835,6 +882,7 @@ SHOW [MXERRS] [MXLOOPS] [MXWARNS] + [N] [SCOMPRESSION] [TEMPDIR] [UNDEFINED] @@ -850,15 +898,18 @@ parameters. Parameters that can be changed using @cmd{SET} with the same name. @cmd{SHOW} supports the following additional subcommands: -@table @bullet +@table @asis @item @subcmd{ALL} Show all settings. @item @subcmd{CC} -Show all custom currency settings (CCA through CCE). +Show all custom currency settings (@subcmd{CCA} through @subcmd{CCE}). @item @subcmd{DIRECTORY} Shows the current working directory. @item @subcmd{ENVIRONMENT} 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. @item @subcmd{TEMPDIR} Shows the path of the directory where temporary files will be stored. @item @subcmd{VERSION}