Improve error messages for missing subcommands.
[pspp] / doc / pspp-convert.texi
1 @c PSPP - a program for statistical analysis.
2 @c Copyright (C) 2017, 2020 Free Software Foundation, Inc.
3 @c Permission is granted to copy, distribute and/or modify this document
4 @c under the terms of the GNU Free Documentation License, Version 1.3
5 @c or any later version published by the Free Software Foundation;
6 @c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
7 @c A copy of the license is included in the section entitled "GNU
8 @c Free Documentation License".
9 @c
10 @node Invoking pspp-convert
11 @chapter Invoking @command{pspp-convert}
12 @cindex Invocation
13 @cindex @command{pspp-convert}
14
15 @command{pspp-convert} is a command-line utility accompanying
16 @pspp{}. It reads an SPSS or SPSS/PC+ system file or SPSS portable
17 file or encrypted SPSS syntax file @var{input} and
18 writes a copy of it to another @var{output} in a different format.
19 Synopsis:
20
21 @display
22 @t{pspp-convert} [@var{options}] @var{input} @var{output}
23
24 @t{pspp-convert -@w{-}help}
25
26 @t{pspp-convert -@w{-}version}
27 @end display
28
29 The format of @var{input} is automatically detected, when possible.
30 The character encoding of old SPSS system files cannot always be
31 guessed correctly, and SPSS/PC+ system files do not include any
32 indication of their encoding.  Use @code{-e @var{encoding}} to specify
33 the encoding in this case.
34
35 By default, the intended format for @var{output} is inferred based on its
36 extension:
37
38 @table @code
39 @item csv
40 @itemx txt
41 Comma-separated value.  Each value is formatted according to its
42 variable's print format.  The first line in the file contains variable
43 names.
44
45 @item sav
46 @item sys
47 SPSS system file.
48
49 @item por
50 SPSS portable file.
51
52 @item sps
53 SPSS syntax file.  (Only encrypted syntax files may be converted to
54 this format.)
55 @end table
56
57 @command{pspp-convert} can convert most input formats to most output
58 formats.  Encrypted SPSS file formats are exceptions: if the input
59 file is in an encrypted format, then the output file will be the same
60 format (decrypted).  To decrypt such a file, specify the encrypted
61 file as @var{input}.  The output will be the equivalent plaintext
62 file.  Options for the output format are ignored in this case.
63
64 The password for encrypted files can be specified a few different
65 ways.  If the password is known, use the @option{-p} option
66 (documented below) or allow @command{pspp-convert} to prompt for it.
67 If the password is unknown, use the @option{-a} and @option{-l}
68 options to specify how to search for it, or @option{--password-list}
69 to specify a file of passwords to try.
70
71 Use @code{-O @var{format}} to override the inferred format or to
72 specify the format for unrecognized extensions.
73
74 @command{pspp-convert} accepts the following general options:
75
76 @table @option
77 @item @option{-O @var{format}}
78 @itemx @option{--output-format=@var{format}}
79 Sets the output format, where @var{format} is one of the extensions
80 listed above, @i{e.g.}: @option{-O csv}.  Use @option{--help} to list
81 the supported output formats.
82
83 @item -c @var{maxcases}
84 @itemx --cases=@var{maxcases}
85 By default, all cases are copied from @var{input} to @var{output}.
86 Specifying this option to limit the number of cases written to
87 @var{output} to @var{maxcases}.
88
89 @item -e @var{charset}
90 @itemx --encoding=@var{charset}
91 Overrides the encoding in which character strings in @var{input} are
92 interpreted.  This option is necessary because old SPSS system files,
93 and SPSS/PC+ system files, do not self-identify their encoding.
94
95 @item -k @var{variable}@dots{}
96 @itemx --keep=@var{variable}@dots{}
97 By default, @command{pspp-convert} includes all the variables from the
98 input file.  Use this option to list specific variables to include;
99 any variables not listed will be dropped.  The variables in the output
100 file will also be reordered into the given order.  The variable list
101 may use @code{TO} in the same way as in PSPP syntax, @i{e.g.}@: if the
102 dictionary contains consecutive variables @code{a}, @code{b},
103 @code{c}, and @code{d}, then @option{--keep='a to d'} will include all
104 of them (and no others).
105
106 @item -d @var{variable}@dots{}
107 @itemx --drop=@var{variable}@dots{}
108 Drops the specified variables from the output.
109
110 When @option{--keep} and @option{--drop} are used together,
111 @option{--keep} is processed first.
112
113 @item -h
114 @itemx --help
115 Prints a usage message on stdout and exits.
116
117 @item -v
118 @itemx --version
119 Prints version information on stdout and exits.
120 @end table
121
122 The following options affect CSV output:
123
124 @table @option
125 @item --recode
126 By default, @command{pspp-convert} writes user-missing values to CSV
127 output files as their regular values.  With this option,
128 @command{pspp-convert} recodes them to system-missing values (which
129 are written as a single space).
130
131 @item --no-var-names
132 By default, @command{pspp-convert} writes the variable names as the
133 first line of output.  With this option, @command{pspp-convert} omits
134 this line.
135
136 @item --labels
137 By default, @command{pspp-convert} writes variables' values to CSV
138 output files.  With this option, @command{pspp-convert} writes value
139 labels.
140
141 @item --print-formats
142 By default, @command{pspp-convert} writes numeric variables as plain
143 numbers.  This option makes @command{pspp-convert} honor variables'
144 print formats.
145
146 @item --decimal=@var{decimal}
147 This option sets the character used as a decimal point in output.  The
148 default is @samp{.}.
149
150 @item --delimiter=@var{delimiter}
151 This option sets the character used to separate fields in output.  The
152 default is @samp{,}, unless the decimal point is @samp{,}, in which
153 case @samp{;} is used.
154
155 @item --qualifier=@var{qualifier}
156 The option sets the character used to quote fields that contain the
157 delimiter.  The default is @samp{"}.
158 @end table
159
160 The following options specify how to obtain the password for encrypted
161 files:
162
163 @table @option
164 @item -p @var{password}
165 @item --password=@var{password}
166 Specifies the password to use to decrypt an encrypted SPSS system file
167 or syntax file.  If this option is not specified,
168 @command{pspp-convert} will prompt interactively for the password as
169 necessary.
170
171 Be aware that command-line options, including passwords, may be
172 visible to other users on multiuser systems.
173
174 When used with @option{-a} (or @option{--password-alphabet}) and
175 @option{-l} (or @option{--password-length}), this option specifies the
176 starting point for the search.  This can be used to restart a search
177 that was interrupted.
178
179 @item -a @var{alphabet}
180 @item --password-alphabet=@var{alphabet}
181 Specifies the alphabet of symbols over which to search for an
182 encrypted file's password.  @var{alphabet} may include individual
183 characters and ranges delimited by @samp{-}.  For example, @option{-a
184 a-z} searches lowercase letters, @option{-a A-Z0-9} searches uppercase
185 letters and digits, and @option{-a ' -~'} searches all printable ASCII
186 characters.
187
188 @item -l @var{max-length}
189 @item --password-length=@var{max-length}
190 Specifies the maximum length of the passwords to try.
191
192 @item --password-list=@var{file}
193 Specifies a file to read containing a list of passwords to try, one
194 per line.  If @var{file} is @file{-}, reads from stdin.
195 @end table