work on SAVE DATA COLLECTION

[pspp] / doc / files.texi

diff --git a/doc/files.texi b/doc/files.texi
index e3d2398eb9973d69587afed316c9c1d92bb607c3..ffbb685c89c955fdb852923850c3eff37e3b0010 100644 (file)
--- a/doc/files.texi
+++ b/doc/files.texi
@@ -1,3 +1,12 @@
+@c PSPP - a program for statistical analysis.
+@c Copyright (C) 2017 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 System and Portable File IO
 @chapter System and Portable File I/O
 
@@ -11,6 +20,7 @@ portable files.
 * GET DATA::                    Read from foreign files.
 * IMPORT::                      Read from a portable file.
 * SAVE::                        Write to a system file.
+* SAVE DATA COLLECTION::        Write to a system file and metadata file.
 * SAVE TRANSLATE::              Write data in foreign file formats.
 * SYSFILE INFO::                Display system file dictionary.
 * XEXPORT::                     Write to a portable file, as a transformation.
@@ -761,6 +771,44 @@ The @subcmd{NAMES} and @subcmd{MAP} subcommands are currently ignored.
 
 @cmd{SAVE} causes the data to be read.  It is a procedure.
 
+@node SAVE DATA COLLECTION
+@section SAVE DATA COLLECTION
+@vindex SAVE DATA COLLECTION
+
+@display
+SAVE DATA COLLECTION
+        /OUTFILE=@{'@var{file_name}',@var{file_handle}@}
+        /METADATA=@{'@var{file_name}',@var{file_handle}@}
+        /@{UNCOMPRESSED,COMPRESSED,ZCOMPRESSED@}
+        /PERMISSIONS=@{WRITEABLE,READONLY@}
+        /DROP=@var{var_list}
+        /KEEP=@var{var_list}
+        /VERSION=@var{version}
+        /RENAME=(@var{src_names}=@var{target_names})@dots{}
+        /NAMES
+        /MAP
+@end display
+
+Like @cmd{SAVE}, @cmd{SAVE DATA COLLECTION} writes the dictionary and
+data in the active dataset to a system file.  In addition, it writes
+metadata to an additional XML metadata file.
+
+OUTFILE is required.  Specify the system file to be written as a
+string file name or a file handle (@pxref{File Handles}).
+
+METADATA is also required.  Specify the metadata file to be written as
+a string file name or a file handle.  Metadata files customarily use a
+@file{.mdd} extension.
+
+The current implementation of this command only outputs an
+approximation of the metadata file format.  Please report bugs.
+
+Other subcommands are optional.  They have the same meanings as in the
+@cmd{SAVE} command.
+
+@cmd{SAVE DATA COLLECTION} causes the data to be read.  It is a
+procedure.
+
 @node SAVE TRANSLATE
 @section SAVE TRANSLATE
 @vindex SAVE TRANSLATE
@@ -805,13 +853,15 @@ values as if they were not missing.  Specify MISSING=RECODE to output
 numeric user-missing values like system-missing values and string
 user-missing values as all spaces.
 
-By default, all the variables in the active dataset dictionary are saved
-to the system file, but @subcmd{DROP} or @subcmd{KEEP} can select a subset of variable
-to save.  The @subcmd{RENAME} subcommand can also be used to change the names
-under which variables are saved.  @subcmd{UNSELECTED} determines whether cases
-filtered out by the @cmd{FILTER} command are written to the output file.
-These subcommands have the same syntax and meaning as on the
-@cmd{SAVE} command (@pxref{SAVE}).
+By default, all the variables in the active dataset dictionary are
+saved to the system file, but @subcmd{DROP} or @subcmd{KEEP} can
+select a subset of variable to save.  The @subcmd{RENAME} subcommand
+can also be used to change the names under which variables are saved;
+because they are used only in the output, these names do not have to
+conform to the usual PSPP variable naming rules.  @subcmd{UNSELECTED}
+determines whether cases filtered out by the @cmd{FILTER} command are
+written to the output file.  These subcommands have the same syntax
+and meaning as on the @cmd{SAVE} command (@pxref{SAVE}).
 
 Each supported file type has additional subcommands, explained in
 separate sections below.