X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Fpspp-convert.texi;h=b780a1e52c29c8c48c6b03493b76a8fad79f9d7a;hb=refs%2Fheads%2Fctables10;hp=328e9caa02f6dc13dececdc6bec49cb1e973e9f6;hpb=e2da62d735c597afeef2e0e9b36e5a4a83d7da94;p=pspp diff --git a/doc/pspp-convert.texi b/doc/pspp-convert.texi index 328e9caa02..b780a1e52c 100644 --- a/doc/pspp-convert.texi +++ b/doc/pspp-convert.texi @@ -1,10 +1,20 @@ +@c PSPP - a program for statistical analysis. +@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; +@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. +@c A copy of the license is included in the section entitled "GNU +@c Free Documentation License". +@c @node Invoking pspp-convert @chapter Invoking @command{pspp-convert} @cindex Invocation @cindex @command{pspp-convert} @command{pspp-convert} is a command-line utility accompanying -@pspp{}. It reads an SPSS system or portable file @var{input} and +@pspp{}. It reads an SPSS or SPSS/PC+ system file or SPSS portable +file or encrypted SPSS syntax file @var{input} and writes a copy of it to another @var{output} in a different format. Synopsis: @@ -16,10 +26,11 @@ Synopsis: @t{pspp-convert -@w{-}version} @end display -The format of @var{Iinput} is automatically detected, except that the -character encoding of old system files cannot always be guessed -correctly. Use @code{-e @var{encoding}} to specify the encoding in this -case. +The format of @var{input} is automatically detected, when possible. +The character encoding of old SPSS system files cannot always be +guessed correctly, and SPSS/PC+ system files do not include any +indication of their encoding. Use @code{-e @var{encoding}} to specify +the encoding in this case. By default, the intended format for @var{output} is inferred based on its extension: @@ -37,19 +48,37 @@ SPSS system file. @item por SPSS portable file. + +@item sps +SPSS syntax file. (Only encrypted syntax files may be converted to +this format.) @end table -Use @code{-O @var{extension}} to override the inferred format or to +@command{pspp-convert} can convert most input formats to most output +formats. Encrypted SPSS file formats are exceptions: if the input +file is in an encrypted format, then the output file will be the same +format (decrypted). To decrypt such a file, specify the encrypted +file as @var{input}. The output will be the equivalent plaintext +file. Options for the output format are ignored in this case. + +The password for encrypted files can be specified a few different +ways. If the password is known, use the @option{-p} option +(documented below) or allow @command{pspp-convert} to prompt for it. +If the password is unknown, use the @option{-a} and @option{-l} +options to specify how to search for it, or @option{--password-list} +to specify a file of passwords to try. + +Use @code{-O @var{format}} to override the inferred format or to specify the format for unrecognized extensions. -The following options are accepted: +@command{pspp-convert} accepts the following general options: -@table @code -@item -O @var{format} -@itemx --output-format=@var{format} -Specifies the desired output format. @var{format} must be one of the -extensions listed above, e.g. @code{-O csv} requests comma-separated -value output. +@table @option +@item @option{-O @var{format}} +@itemx @option{--output-format=@var{format}} +Sets the output format, where @var{format} is one of the extensions +listed above, @i{e.g.}: @option{-O csv}. Use @option{--help} to list +the supported output formats. @item -c @var{maxcases} @itemx --cases=@var{maxcases} @@ -60,8 +89,26 @@ Specifying this option to limit the number of cases written to @item -e @var{charset} @itemx --encoding=@var{charset} Overrides the encoding in which character strings in @var{input} are -interpreted. This option is necessary because old SPSS system files -do not self-identify their encoding. +interpreted. This option is necessary because old SPSS system files, +and SPSS/PC+ system files, do not self-identify their encoding. + +@item -k @var{variable}@dots{} +@itemx --keep=@var{variable}@dots{} +By default, @command{pspp-convert} includes all the variables from the +input file. Use this option to list specific variables to include; +any variables not listed will be dropped. The variables in the output +file will also be reordered into the given order. The variable list +may use @code{TO} in the same way as in PSPP syntax, @i{e.g.}@: if the +dictionary contains consecutive variables @code{a}, @code{b}, +@code{c}, and @code{d}, then @option{--keep='a to d'} will include all +of them (and no others). + +@item -d @var{variable}@dots{} +@itemx --drop=@var{variable}@dots{} +Drops the specified variables from the output. + +When @option{--keep} and @option{--drop} are used together, +@option{--keep} is processed first. @item -h @itemx --help @@ -71,3 +118,78 @@ Prints a usage message on stdout and exits. @itemx --version Prints version information on stdout and exits. @end table + +The following options affect CSV output: + +@table @option +@item --recode +By default, @command{pspp-convert} writes user-missing values to CSV +output files as their regular values. With this option, +@command{pspp-convert} recodes them to system-missing values (which +are written as a single space). + +@item --no-var-names +By default, @command{pspp-convert} writes the variable names as the +first line of output. With this option, @command{pspp-convert} omits +this line. + +@item --labels +By default, @command{pspp-convert} writes variables' values to CSV +output files. With this option, @command{pspp-convert} writes value +labels. + +@item --print-formats +By default, @command{pspp-convert} writes numeric variables as plain +numbers. This option makes @command{pspp-convert} honor variables' +print formats. + +@item --decimal=@var{decimal} +This option sets the character used as a decimal point in output. The +default is @samp{.}. + +@item --delimiter=@var{delimiter} +This option sets the character used to separate fields in output. The +default is @samp{,}, unless the decimal point is @samp{,}, in which +case @samp{;} is used. + +@item --qualifier=@var{qualifier} +The option sets the character used to quote fields that contain the +delimiter. The default is @samp{"}. +@end table + +The following options specify how to obtain the password for encrypted +files: + +@table @option +@item -p @var{password} +@item --password=@var{password} +Specifies the password to use to decrypt an encrypted SPSS system file +or syntax file. If this option is not specified, +@command{pspp-convert} will prompt interactively for the password as +necessary. + +Be aware that command-line options, including passwords, may be +visible to other users on multiuser systems. + +When used with @option{-a} (or @option{--password-alphabet}) and +@option{-l} (or @option{--password-length}), this option specifies the +starting point for the search. This can be used to restart a search +that was interrupted. + +@item -a @var{alphabet} +@item --password-alphabet=@var{alphabet} +Specifies the alphabet of symbols over which to search for an +encrypted file's password. @var{alphabet} may include individual +characters and ranges delimited by @samp{-}. For example, @option{-a +a-z} searches lowercase letters, @option{-a A-Z0-9} searches uppercase +letters and digits, and @option{-a ' -~'} searches all printable ASCII +characters. + +@item -l @var{max-length} +@item --password-length=@var{max-length} +Specifies the maximum length of the passwords to try. + +@item --password-list=@var{file} +Specifies a file to read containing a list of passwords to try, one +per line. If @var{file} is @file{-}, reads from stdin. +@end table