spv-file-format: Improve description of structure member format.
[pspp] / doc / pspp-convert.texi
1 @c PSPP - a program for statistical analysis.
2 @c Copyright (C) 2017 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 system file and syntax files are exceptions: if
59 the input file is in an encrypted format, then the output file must be
60 the same format (decrypted).  To decrypt such a file, specify the
61 encrypted file as @var{input}.  The output will be the equivalent
62 plaintext file.  You will be prompted for the password (or use
63 @option{-p}, documented below).
64
65 Use @code{-O @var{extension}} to override the inferred format or to
66 specify the format for unrecognized extensions.
67
68 The following options are accepted:
69
70 @table @option
71 @item -O @var{format}
72 @itemx --output-format=@var{format}
73 Specifies the desired output format.  @var{format} must be one of the
74 extensions listed above, e.g. @code{-O csv} requests comma-separated
75 value output.
76
77 @item -c @var{maxcases}
78 @itemx --cases=@var{maxcases}
79 By default, all cases are copied from @var{input} to @var{output}.
80 Specifying this option to limit the number of cases written to
81 @var{output} to @var{maxcases}.
82
83 @item -e @var{charset}
84 @itemx --encoding=@var{charset}
85 Overrides the encoding in which character strings in @var{input} are
86 interpreted.  This option is necessary because old SPSS system files,
87 and SPSS/PC+ system files, do not self-identify their encoding.
88
89 @item -p @var{password}
90 @item --password=@var{password}
91 Specifies the password to use to decrypt an encrypted SPSS system file
92 or syntax file.  If this option is not specified,
93 @command{pspp-convert} will prompt interactively for the password as
94 necessary.
95
96 Be aware that command-line options, including passwords, may be
97 visible to other users on multiuser systems.
98
99 @item -h
100 @itemx --help
101 Prints a usage message on stdout and exits.
102
103 @item -v
104 @itemx --version
105 Prints version information on stdout and exits.
106 @end table