From adb05b9a13e7cd677a4fef52163eba05cb56d37f Mon Sep 17 00:00:00 2001
From: John Darrington <john@darrington.wattle.id.au>
Date: Sat, 28 Nov 2020 11:22:41 +0100
Subject: [PATCH] Documentation: Add an example showing the use of SELECT IF.

---
 doc/automake.mk                |   1 +
 doc/data-selection.texi        |  27 +++++++++++++++++++++++++++
 doc/pspp-figures/select-if.sps |   8 ++++++++
 examples/personnel.sav         | Bin 4209 -> 4209 bytes
 4 files changed, 36 insertions(+)
 create mode 100644 doc/pspp-figures/select-if.sps

diff --git a/doc/automake.mk b/doc/automake.mk
index 2325e236a5..9800d5849d 100644
--- a/doc/automake.mk
+++ b/doc/automake.mk
@@ -122,6 +122,7 @@ FIGURE_SYNTAX = \
  doc/pspp-figures/one-sample-t.sps \
  doc/pspp-figures/independent-samples-t.sps \
  doc/pspp-figures/reliability.sps \
+ doc/pspp-figures/select-if.sps \
  doc/pspp-figures/split.sps \
  doc/pspp-figures/temporary.sps \
  doc/pspp-figures/tutorial1.sps \
diff --git a/doc/data-selection.texi b/doc/data-selection.texi
index 17c039c88d..17d5d0e41c 100644
--- a/doc/data-selection.texi
+++ b/doc/data-selection.texi
@@ -156,11 +156,38 @@ deleted from the data stream.
 Place @cmd{SELECT IF} as early in the command file as
 possible.  Cases that are deleted early can be processed more
 efficiently in time and space.
+Once cases have been deleted from the active dataset using @cmd{SELECT IF} they
+cannot be re-instated.
+If you want to be able to re-instate cases, then use @cmd{FILTER} (@pxref{FILTER})
+instead.
 
 When @cmd{SELECT IF} is specified following @cmd{TEMPORARY}
 (@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
 (@pxref{LAG}).
 
+@subsection Example Select-If
+
+A shop steward is interested in the salaries of younger personnel in a firm.
+The file @file{personnel.sav} provides the salaries of all the workers and their
+dates of birth.  The syntax in @ref{select-if:ex} shows how @cmd{SELECT IF} can
+be used to limit analysis only to those persons born after December 31, 1999.
+
+@float Example, select-if:ex
+@psppsyntax {select-if.sps}
+@caption {Using @cmd{SELECT IF} to select persons born on or after a certain date.}
+@end float
+
+From @ref{select-if:res} one can see that there are 56 persons listed in the dataset,
+and 17 of them were born after December 31, 1999.
+
+@float Result, select-if:res
+@psppoutput {select-if}
+@caption {Salary descriptives before and after the @cmd{SELECT IF} transformation.}
+@end float
+
+Note that the @file{personnel.sav} file from which the data were read is unaffected.
+The transformation affects only the active file.
+
 @node SPLIT FILE
 @section SPLIT FILE
 @vindex SPLIT FILE
diff --git a/doc/pspp-figures/select-if.sps b/doc/pspp-figures/select-if.sps
new file mode 100644
index 0000000000..e6e98be2fd
--- /dev/null
+++ b/doc/pspp-figures/select-if.sps
@@ -0,0 +1,8 @@
+get file = 'personnel.sav'.
+
+echo 'Salaries of all personnel'.
+descriptives salary.
+
+echo 'Salaries of personnel born after December 31 1999'.
+select if dob > date.dmy (31,12,1999).
+descriptives salary.
diff --git a/examples/personnel.sav b/examples/personnel.sav
index 6b4b7168ee927069907f67230e222e051fa8bc14..ba4c599de89c9eaa127f4ab5b5340909dbdeb673 100644
GIT binary patch
delta 59
zcmeyU@KIrcGNb846$?Q_3kARYG6f?8LsKgwATpa+Xfv^aW#ii4jEt<CS2C$^Gc!2e
O-h6>~9uu?IV+Q~!z7p^N

delta 59
zcmV-B0L1_CAn_oOBLOs#BsdW=Fd$Q9a3C@;F*Q0eF*-6Zk#RhcfCRCv`vCz2v#A0k
R3j?4}=(Erbo&p0p<v=Z#6Mp~z

-- 
2.30.2