Documentation: Add an example for SORT CASES

diff --git a/doc/automake.mk b/doc/automake.mk
index 7cbb819db364361a9bd5fa954093760e706deeed..5cabeae1d19279e80a81c64d5c3cfae90d81f830 100644 (file)
--- a/doc/automake.mk
+++ b/doc/automake.mk
@@ -124,6 +124,7 @@ doc/pspp-figures/autorecode.sps \
  doc/pspp-figures/independent-samples-t.sps \
  doc/pspp-figures/reliability.sps \
  doc/pspp-figures/select-if.sps \
+ doc/pspp-figures/sort-cases.sps \
  doc/pspp-figures/split.sps \
  doc/pspp-figures/temporary.sps \
  doc/pspp-figures/tutorial1.sps \

diff --git a/doc/pspp-figures/sort-cases.sps b/doc/pspp-figures/sort-cases.sps
new file mode 100644 (file)
index 0000000..83c8b2b
--- /dev/null
+++ b/doc/pspp-figures/sort-cases.sps
@@ -0,0 +1,3 @@
+get file='physiology.sav'.
+sort cases by sex (D) temperature(A).
+list.

diff --git a/doc/transformation.texi b/doc/transformation.texi
index 5161df224ebcb5c63fcb684e347b6791d7765b95..d33f71bfcab9a521b80c193c3870119fcf8a16c8 100644 (file)
--- a/doc/transformation.texi
+++ b/doc/transformation.texi
@@ -841,10 +841,33 @@ cases.
 @cmd{SORT CASES} is a procedure.  It causes the data to be read.
 
 @cmd{SORT CASES} attempts to sort the entire active dataset in main memory.
-If workspace is exhausted, it falls back to a merge sort algorithm that
-involves creates numerous temporary files.
+If workspace is exhausted, it falls back to a merge sort algorithm which
+creates numerous temporary files.
 
 @cmd{SORT CASES} may not be specified following @cmd{TEMPORARY}.
 
 @subsection Sorting Example
 
+In @ref{sort-cases:ex} the data from the file @file {physiology.sav} is sorted
+by two variables, @i{viz@:} @exvar{sex} in descending order and @exvar{temperature} in
+ascending order.
+
+@float Example, sort-cases:ex
+@psppsyntax {sort-cases.sps}
+@caption {Sorting cases  by two variables.}
+@end float
+
+In @ref{sort-cases:res} you can see that all the cases with a @exvar{sex} of
+@samp{1} (female) appear before those with a sex of @samp{0} (male).
+This is because they have been sorted in descending order.
+Within each sex, the data is sorted on the @exvar{temperature} variable,
+this time in ascending order.
+
+@float Results, sort-cases:res
+@psppoutput {sort-cases}
+@caption {The @file{physiology.sav} file after sorting.}
+@end float
+
+Note that @cmd{SORT CASES}, like all other transformations, affects only the active file.
+It does not have any effect upon the @file{physiology.sav} file itself. For that, you
+would have to rewrite the file using the @cmd{SAVE} command (@pxref{SAVE}).