+@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:
@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:
@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}
@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
@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
projects / pspp / blobdiff