spv-file-format: Improve documentation.

[pspp] / doc / variables.texi

diff --git a/doc/variables.texi b/doc/variables.texi
index cc13e784de2e9732d028b4fa03077e2f75096aad..a47de44afdcc471e93645da3b32fcb1b8b24b216 100644 (file)
--- a/doc/variables.texi
+++ b/doc/variables.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 Variable Attributes
 @chapter Manipulating variables
 
 @node Variable Attributes
 @chapter Manipulating variables
 


@@ -33,7 +42,7 @@ several utility functions for examining and adjusting them.
 @section ADD VALUE LABELS
 @vindex ADD VALUE LABELS
 
 @section ADD VALUE LABELS
 @vindex ADD VALUE LABELS
 

-@display 
+@display

 ADD VALUE LABELS
         /@var{var_list} @var{value} '@var{label}' [@var{value} '@var{label}']@dots{}
 @end display
 ADD VALUE LABELS
         /@var{var_list} @var{value} '@var{label}' [@var{value} '@var{label}']@dots{}
 @end display


@@ -111,7 +120,7 @@ Variables}).
 @item ATTRIBUTES
 @itemx @@ATTRIBUTES
 Datafile and variable attributes are displayed.
 @item ATTRIBUTES
 @itemx @@ATTRIBUTES
 Datafile and variable attributes are displayed.

-The first form of the command omits those attributes 
+The first form of the command omits those attributes

 whose names begin with @code{@@} or @code{$@@}.
 In the second for, all datafile and variable attributes are displayed.
 @end table
 whose names begin with @code{@@} or @code{$@@}.
 In the second for, all datafile and variable attributes are displayed.
 @end table


@@ -225,7 +234,7 @@ Specify a list of variables, followed by a list of their user-missing
 values in parentheses.  Up to three discrete values may be given, or,
 for numeric variables only, a range of values optionally accompanied by
 a single discrete value.  Ranges may be open-ended on one end, indicated
 values in parentheses.  Up to three discrete values may be given, or,
 for numeric variables only, a range of values optionally accompanied by
 a single discrete value.  Ranges may be open-ended on one end, indicated

-through the use of the 
+through the use of the

 keyword @subcmd{LO} or @subcmd{LOWEST} or @subcmd{HI} or @subcmd{HIGHEST}.
 
 The @cmd{MISSING VALUES} command takes effect immediately.  It is not
 keyword @subcmd{LO} or @subcmd{LOWEST} or @subcmd{HI} or @subcmd{HIGHEST}.
 
 The @cmd{MISSING VALUES} command takes effect immediately.  It is not


@@ -236,12 +245,12 @@ affected by conditional and looping constructs such as @cmd{DO IF} or
 @section MODIFY VARS
 @vindex MODIFY VARS
 
 @section MODIFY VARS
 @vindex MODIFY VARS
 

-@display 
+@display

 MODIFY VARS
         /REORDER=@{FORWARD,BACKWARD@} @{POSITIONAL,ALPHA@} (@var{var_list})@dots{}
         /RENAME=(@var{old_names}=@var{new_names})@dots{}
         /@{DROP,KEEP@}=@var{var_list}
 MODIFY VARS
         /REORDER=@{FORWARD,BACKWARD@} @{POSITIONAL,ALPHA@} (@var{var_list})@dots{}
         /RENAME=(@var{old_names}=@var{new_names})@dots{}
         /@{DROP,KEEP@}=@var{var_list}

-        /MAP    
+        /MAP

 @end display
 
 @cmd{MODIFY VARS} reorders, renames, and deletes variables in the
 @end display
 
 @cmd{MODIFY VARS} reorders, renames, and deletes variables in the


@@ -266,8 +275,10 @@ same number of old and new variable names.  Each old variable is renamed to
 the corresponding new variable name.  Multiple parenthesized groups of
 variables may be specified.
 
 the corresponding new variable name.  Multiple parenthesized groups of
 variables may be specified.
 

-The @subcmd{DROP} subcommand deletes a specified list of variables from the
-active dataset.
+The @subcmd{DROP} subcommand deletes a specified list of variables
+from the active dataset.  @cmd{MODIFY VARS} may not be used to delete
+all variables from the dictionary; use @cmd{NEW FILE} to do that
+(@pxref{NEW FILE}).

 
 The @subcmd{KEEP} subcommand keeps the specified list of variables in the active
 dataset.  Any unlisted variables are deleted from the active dataset.
 
 The @subcmd{KEEP} subcommand keeps the specified list of variables in the active
 dataset.  Any unlisted variables are deleted from the active dataset.


@@ -285,7 +296,7 @@ otherwise it is not.
 @vindex MRSETS
 
 @display
 @vindex MRSETS
 
 @display

-MRSETS 
+MRSETS

     /MDGROUP NAME=@var{name} VARIABLES=@var{var_list} VALUE=@var{value}
      [CATEGORYLABELS=@{VARLABELS,COUNTEDVALUES@}]
      [@{LABEL='@var{label}',LABELSOURCE=VARLABEL@}]
     /MDGROUP NAME=@var{name} VARIABLES=@var{var_list} VALUE=@var{value}
      [CATEGORYLABELS=@{VARLABELS,COUNTEDVALUES@}]
      [@{LABEL='@var{label}',LABELSOURCE=VARLABEL@}]


@@ -350,7 +361,7 @@ variable labels, variable names.  @pspp{} warns if two variables have the
 same variable label, since these categories cannot be distinguished in
 output.
 
 same variable label, since these categories cannot be distinguished in
 output.
 

-@item 
+@item

 @subcmd{COUNTEDVALUES} instead uses each variable's value label for the counted
 value.  @pspp{} warns if two variables have the same value label for the
 counted value or if one of the variables lacks a value label, since
 @subcmd{COUNTEDVALUES} instead uses each variable's value label for the counted
 value.  @pspp{} warns if two variables have the same value label for the
 counted value or if one of the variables lacks a value label, since


@@ -393,15 +404,15 @@ response sets are currently used only by third party software.
 @vindex NUMERIC
 
 @display
 @vindex NUMERIC
 
 @display

-NUMERIC /@var{var_list} [(@var{fmt_spec})].
+NUMERIC @var{var_list} [(@var{fmt_spec})] [/@var{var_list} [(@var{fmt_spec})]]@dots{}

 @end display
 
 @cmd{NUMERIC} explicitly declares new numeric variables, optionally
 setting their output formats.
 
 @end display
 
 @cmd{NUMERIC} explicitly declares new numeric variables, optionally
 setting their output formats.
 

-Specify a slash (@samp{/}), followed by the names of the new numeric
-variables.  If you wish to set their output formats, follow their names
-by an output format specification in parentheses (@pxref{Input and Output
+Specify the names of the new numeric variables as @var{var_list}.  If
+you wish to set the variables' output formats, follow their names by
+an output format specification in parentheses (@pxref{Input and Output

 Formats}); otherwise, the default is F8.2.
 
 Variables created with @cmd{NUMERIC} are initialized to the
 Formats}); otherwise, the default is F8.2.
 
 Variables created with @cmd{NUMERIC} are initialized to the


@@ -524,7 +535,7 @@ Specify @code{(D)} to reverse the sort order.
 @section VALUE LABELS
 @vindex VALUE LABELS
 
 @section VALUE LABELS
 @vindex VALUE LABELS
 

-@display 
+@display

 VALUE LABELS
         /@var{var_list} @var{value} '@var{label}' [@var{value} '@var{label}']@dots{}
 @end display
 VALUE LABELS
         /@var{var_list} @var{value} '@var{label}' [@var{value} '@var{label}']@dots{}
 @end display


@@ -564,7 +575,7 @@ transformations.
 
 Specify a list of names for the variable you want to create,
 followed by the desired output format specification in
 
 Specify a list of names for the variable you want to create,
 followed by the desired output format specification in

-parentheses (@pxref{Input and Output Formats}).  
+parentheses (@pxref{Input and Output Formats}).

 Variable widths are
 implicitly derived from the specified output formats.
 The created variables will be initialized to spaces.
 Variable widths are
 implicitly derived from the specified output formats.
 The created variables will be initialized to spaces.


@@ -657,7 +668,7 @@ by conditional and looping structures such as @cmd{DO IF} or
 
 @display
 VARIABLE LABELS
 
 @display
 VARIABLE LABELS

-        @var{var_list} '@var{var_label}' 
+        @var{var_list} '@var{var_label}'

         [ /@var{var_list} '@var{var_label}']
         .
         .
         [ /@var{var_list} '@var{var_label}']
         .
         .


@@ -669,9 +680,9 @@ VARIABLE LABELS
 with variables.  This name, called a @dfn{variable label}, is displayed by
 statistical procedures.
 
 with variables.  This name, called a @dfn{variable label}, is displayed by
 statistical procedures.
 

-To assign a variable label to a group of variables, specify a 
+To assign a variable label to a group of variables, specify a

 list of variable names and the variable label as a string.
 list of variable names and the variable label as a string.

-To assign different labels to different variables in the same command, 
+To assign different labels to different variables in the same command,

 precede the subsequent variable list with a slash (@samp{/}).
 
 
 precede the subsequent variable list with a slash (@samp{/}).
 
 


@@ -689,8 +700,8 @@ VARIABLE ALIGNMENT
         [ /@var{var_list} ( LEFT | RIGHT | CENTER ) ]
 @end display
 
         [ /@var{var_list} ( LEFT | RIGHT | CENTER ) ]
 @end display
 

-@cmd{VARIABLE ALIGNMENT} sets the alignment of variables for display editing 
-purposes.   This only has effect for third party software.  It does not affect 
+@cmd{VARIABLE ALIGNMENT} sets the alignment of variables for display editing
+purposes.   This only has effect for third party software.  It does not affect

 the display of variables in the @pspp{} output.
 
 
 the display of variables in the @pspp{} output.
 
 


@@ -702,15 +713,15 @@ the display of variables in the @pspp{} output.
 @display
 VARIABLE WIDTH
         @var{var_list} (width)
 @display
 VARIABLE WIDTH
         @var{var_list} (width)

-        [ /@var{var_list} (width) ] 
+        [ /@var{var_list} (width) ]

         .
         .
         .
         .
         .
         .

-        [ /@var{var_list} (width) ] 
+        [ /@var{var_list} (width) ]

 @end display
 
 @cmd{VARIABLE WIDTH} sets the column width of variables for display editing
 @end display
 
 @cmd{VARIABLE WIDTH} sets the column width of variables for display editing

-purposes.   This only affects third party software.  It does not affect 
+purposes.   This only affects third party software.  It does not affect

 the display of variables in the @pspp{} output.
 
 
 the display of variables in the @pspp{} output.