doc examples

diff --git a/NEWS b/NEWS
index d6c30dd4f4b1dd01cf50aa229dd3636f0091dc47..61bbf1ff757523edd70171670718da7b214fdc75 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -7,6 +7,8 @@ Please send PSPP bug reports to bug-gnu-pspp@gnu.org.
 
 Changes after 1.6.2:
 
+ * The CTABLES command is now implemented.
+
  * Building from a Git repository, which previously required GIMP, now
    requires rsvg-convert from librsvg2 instead.
 

diff --git a/doc/automake.mk b/doc/automake.mk
index 13fd8fdd1564945dfe5d489e8e73a610d56f2452..8a59653e0d1c5130ab14c5a900db19d26d1826fc 100644 (file)
--- a/doc/automake.mk
+++ b/doc/automake.mk
@@ -147,6 +147,10 @@ FIGURE_SYNTAX = \
  doc/pspp-figures/ctables28.sps \
  doc/pspp-figures/ctables29.sps \
  doc/pspp-figures/ctables30.sps \
+ doc/pspp-figures/ctables31.sps \
+ doc/pspp-figures/ctables32.sps \
+ doc/pspp-figures/ctables33.sps \
+ doc/pspp-figures/ctables34.sps \
  doc/pspp-figures/crosstabs.sps \
  doc/pspp-figures/descriptives.sps \
  doc/pspp-figures/flip.sps \

diff --git a/doc/pspp-figures/ctables31.sps b/doc/pspp-figures/ctables31.sps
new file mode 100644 (file)
index 0000000..bde6fa5
--- /dev/null
+++ b/doc/pspp-figures/ctables31.sps
@@ -0,0 +1,3 @@
+GET FILE='nhtsa.sav'.
+CTABLES /TABLE=qns1.
+CTABLES /TABLE=qns1 /CATEGORIES VARIABLES=qns1 EMPTY=EXCLUDE.

diff --git a/doc/pspp-figures/ctables32.sps b/doc/pspp-figures/ctables32.sps
new file mode 100644 (file)
index 0000000..9ec814b
--- /dev/null
+++ b/doc/pspp-figures/ctables32.sps
@@ -0,0 +1,16 @@
+GET FILE='nhtsa.sav'.
+DATA LIST LIST NOTABLE /x y (F1.0) z (F10.0).
+VARIABLE LEVEL z (SCALE).
+MISSING VALUES x y (9).
+BEGIN DATA.
+1 1 1
+1 2 10
+1 9 100
+2 1 1000
+2 2 10000
+2 9 100000
+9 1 1000000
+9 2 10000000
+9 9 100000000
+END DATA.
+LIST.
\ No newline at end of file

diff --git a/doc/pspp-figures/ctables33.sps b/doc/pspp-figures/ctables33.sps
new file mode 100644 (file)
index 0000000..e7c9fa8
--- /dev/null
+++ b/doc/pspp-figures/ctables33.sps
@@ -0,0 +1,16 @@
+GET FILE='nhtsa.sav'.
+DATA LIST LIST NOTABLE /x y (F1.0) z (F10.0).
+VARIABLE LEVEL z (SCALE).
+MISSING VALUES x y (9).
+BEGIN DATA.
+1 1 1
+1 2 10
+1 9 100
+2 1 1000
+2 2 10000
+2 9 100000
+9 1 1000000
+9 2 10000000
+9 9 100000000
+END DATA.
+CTABLES /TABLE x > y > z [SUM].

diff --git a/doc/pspp-figures/ctables34.sps b/doc/pspp-figures/ctables34.sps
new file mode 100644 (file)
index 0000000..9e96ef1
--- /dev/null
+++ b/doc/pspp-figures/ctables34.sps
@@ -0,0 +1,18 @@
+GET FILE='nhtsa.sav'.
+DATA LIST LIST NOTABLE /x y (F1.0) z (F10.0).
+VARIABLE LEVEL z (SCALE).
+MISSING VALUES x y (9).
+BEGIN DATA.
+1 1 1
+1 2 10
+1 9 100
+2 1 1000
+2 2 10000
+2 9 100000
+9 1 1000000
+9 2 10000000
+9 9 100000000
+END DATA.
+CTABLES /TABLE x > y > z [SUM] /CATEGORIES VARIABLES=y MISSING=INCLUDE.
+CTABLES /TABLE x > y > z [SUM] /CATEGORIES VARIABLES=x y MISSING=INCLUDE.
+

diff --git a/doc/statistics.texi b/doc/statistics.texi
index 0cfceb225afa5d59988a7a426f5042866d0291a2..b79997bc15edf71ce6b84e7c71613c16c390b2e8 100644 (file)
--- a/doc/statistics.texi
+++ b/doc/statistics.texi
@@ -1781,7 +1781,15 @@ categories, they include all the values listed individually and all
 values with value labels that are covered by ranges or @code{MISSING}
 or @code{OTHERNM}.
 
-@c TODO
+The following example syntax and output show the effect of
+@code{EMPTY=EXCLUDE} for the @code{qns1} variable, in which 0 is labeled
+``None'' but no cases exist with that value:
+
+@example
+CTABLES /TABLE=qns1.
+CTABLES /TABLE=qns1 /CATEGORIES VARIABLES=qns1 EMPTY=EXCLUDE.
+@end example
+@psppoutput {ctables31}
 
 @node CTABLES Titles
 @subsection Titles
@@ -1820,8 +1828,6 @@ The expression specified on the @code{TABLE} command.  Summary
 and measurement level specifications are omitted, and variable labels are used in place of variable names.
 @end table
 
-@c TODO example
-
 @node CTABLES Table Formatting
 @subsection Table Formatting
 
@@ -1891,8 +1897,6 @@ Show variable name and label.
 Show nothing.
 @end table
 
-@c TODO example
-
 @node CTABLES Missing Value Treatment
 @subsection Missing Value Treatment
 
@@ -1900,26 +1904,40 @@ The @code{TABLE} subcommand on @code{CTABLES} specifies two different
 kinds of variables: variables that divide tables into cells (which are
 always categorical) and variables being summarized (which may be
 categorical or scale).  @pspp{} treats missing values differently in
-each kind of variable:
+each kind of variable, as described in the sections below.
+
+@node CTABLES Missing Values for Cell-Defining Variables
+@subsubsection Missing Values for Cell-Defining Variables
 
-@itemize @bullet
-@item
 For variables that divide tables into cells, per-variable category
-options determine which data is analyzed.  If any of the categories
-for such a variable would exclude a case, then that case is not
-included.
+options, as described in @ref{CTABLES Per-Variable Category Options},
+determine which data is analyzed.  If any of the categories for such a
+variable would exclude a case, then that case is not included.
 
-@item
-The treatment of missing values in variables being summarized varies
-between scale and scale and categorical variables.  The following
-section describes their treatment in detail.
+As an example, consider the following entirely artificial dataset, in
+which @samp{x} and @samp{y} are categorical variables with missing
+value 9, and @samp{z} is scale:
 
-By default, each summarized variable is considered separately for
-missing value treatment.  A section below describes how to consider
-missing values listwise for summarizing scale variables.
-@end itemize
+@psppoutput{ctables32}
 
-@c TODO example
+Using @samp{x} and @samp{y} to define cells, and summarizing @samp{z},
+by default @pspp{} omits all the cases that have @samp{x} or @samp{y} (or both)
+missing:
+
+@example
+CTABLES /TABLE x > y > z [SUM].
+@end example
+@psppoutput{ctables33}
+
+If, however, we add @code{CATEGORIES} specifications to include
+missing values for @samp{y} or for @samp{x} and @samp{y}, the output
+table includes them, like so:
+
+@example
+CTABLES /TABLE x > y > z [SUM] /CATEGORIES VARIABLES=y MISSING=INCLUDE.
+CTABLES /TABLE x > y > z [SUM] /CATEGORIES VARIABLES=x y MISSING=INCLUDE.
+@end example
+@psppoutput{ctables34}
 
 @node CTABLES Missing Values for Summary Variables
 @subsubsection Missing Values for Summary Variables