From ccb471cbec2ba23978e3603e19f7bda5aef12eaf Mon Sep 17 00:00:00 2001
From: John Darrington <john@darrington.wattle.id.au>
Date: Sun, 18 Dec 2011 20:15:03 +0100
Subject: [PATCH] Added rudimentary examples documenting the GUI and mods to the build system to suit.

This change is somewhat experimental.  It shows one way that the user manual can
document the gui.  Three dialog boxes are documented: Sort Cases, Rank and
Descriptives.  Clicking on the Help buttons for those dialogs will activate the
appropriate page of the user manual.
---
 doc/automake.mk      |   43 ++++++++++++++++++++++++++++++++--
 doc/descriptives.xwd |  Bin 0 -> 793521 bytes
 doc/invoking.texi    |   62 +++++++++++++++++++++++++++++++++++++++++++++++++-
 doc/rank-cases.xwd   |  Bin 0 -> 646119 bytes
 doc/sort-cases.xwd   |  Bin 0 -> 924103 bytes
 doc/texi-dep.sh      |   36 +++++++++++++++++++++++++++++
 6 files changed, 137 insertions(+), 4 deletions(-)
 create mode 100644 doc/descriptives.xwd
 create mode 100644 doc/rank-cases.xwd
 create mode 100644 doc/sort-cases.xwd
 create mode 100644 doc/texi-dep.sh

diff --git a/doc/automake.mk b/doc/automake.mk
index fe8abd7..b5cdd59 100644
--- a/doc/automake.mk
+++ b/doc/automake.mk
@@ -1,5 +1,7 @@
 ## Process this file with automake to produce Makefile.in  -*- makefile -*-
 
+export TEXINPUTS=$(top_builddir)/doc
+
 info_TEXINFOS = doc/pspp.texinfo doc/pspp-dev.texinfo
 
 doc_pspp_TEXINFOS = doc/version.texi \
@@ -40,6 +42,8 @@ doc_pspp_dev_TEXINFOS = doc/version-dev.texi \
 	doc/dev/portable-file-format.texi \
 	doc/dev/q2c.texi
 
+
+
 EXTRA_DIST += doc/pspp.man \
 	doc/get-commands.pl
 
@@ -55,6 +59,7 @@ $(srcdir)/doc/tut.texi:
 $(srcdir)/doc/pspp.xml: doc/pspp.texinfo $(doc_pspp_TEXINFOS)
 	@$(MKDIR_P)  doc
 	$(MAKEINFO) $(AM_MAKEINFOFLAGS) --docbook -I $(top_srcdir) \
+		-I $(top_builddir)/doc \
 		$(top_srcdir)/doc/pspp.texinfo -o - \
 		| $(SED) -e 's/Time-&-Date/Time-\&amp;-Date/g' \
 		-e 's/&ldquo;/\&#8220;/g' \
@@ -72,7 +77,39 @@ $(srcdir)/doc/pspp.xml: doc/pspp.texinfo $(doc_pspp_TEXINFOS)
 	$(XMLLINT) --output /dev/null $@ 2>&1 2> /dev/null || ( $(RM) $@ && false )
 
 docbookdir = $(docdir)
-dist_docbook_DATA = doc/pspp.xml
 
-EXTRA_DIST += doc/OChangeLog
-CLEANFILES += pspp-dev.dvi $(docbook_DATA)
+doc_pspp_images = doc/sort-cases.xwd  \
+	doc/rank-cases.xwd \
+	doc/descriptives.xwd
+
+dist_docbook_DATA = doc/pspp.xml \
+	doc/sort-cases.jpg  \
+	doc/rank-cases.jpg \
+	doc/descriptives.jpg
+
+
+.xwd.png:
+	convert $< $@
+
+.xwd.eps:
+	convert $< $@
+
+.xwd.jpg:
+	convert $< $@
+
+.xwd.txt:
+	echo 'Image of '$< > $@
+
+doc/texi_deps:
+	@$(MKDIR_P) doc
+	$(SHELL) $(top_srcdir)/doc/texi-dep.sh doc/pspp.dvi  $(top_srcdir)/doc   > $@
+	$(SHELL) $(top_srcdir)/doc/texi-dep.sh doc/pspp.xml  $(top_srcdir)/doc  >> $@
+	$(SHELL) $(top_srcdir)/doc/texi-dep.sh doc/pspp.info $(top_srcdir)/doc  >> $@
+	$(SHELL) $(top_srcdir)/doc/texi-dep.sh doc/pspp.ps   $(top_srcdir)/doc  >> $@
+	$(SHELL) $(top_srcdir)/doc/texi-dep.sh doc/pspp.pdf  $(top_srcdir)/doc  >> $@
+
+include $(top_builddir)/doc/texi_deps
+
+EXTRA_DIST += doc/OChangeLog doc/texi-dep.sh $(doc_pspp_images)
+CLEANFILES += pspp-dev.dvi $(patsubst %.xwd,%.eps,$(doc_pspp_images)) doc/texi_deps
+
diff --git a/doc/descriptives.xwd b/doc/descriptives.xwd
new file mode 100644
index 0000000000000000000000000000000000000000..4a12d1fecf9a5c233d2c0edf76f35f57cbce665b
GIT binary patch
diff --git a/doc/invoking.texi b/doc/invoking.texi
index 08a187e..e9a36ca 100644
--- a/doc/invoking.texi
+++ b/doc/invoking.texi
@@ -438,7 +438,6 @@ Successive output items are separated by a blank line.
 
 @node Invoking PSPPIRE
 @chapter Invoking @command{psppire}
-@section The graphic user interface
 @cindex Graphic user interface
 @cindex PSPPIRE
 
@@ -454,3 +453,64 @@ from which @command{psppire} can be started by a series of mouse clicks.
 Once the principles of the PSPP system are understood, 
 the graphic user interface is designed to be largely intuitive, and
 for this reason is covered only very briefly by this manual.
+
+@menu
+* sort-cases-dialog::
+* rank-dialog::
+* descriptives-dialog::
+@end menu
+
+
+@node sort-cases-dialog
+@section sort-cases-dialog
+
+You can sort cases, by clicking @clicksequence{Data @click{} Sort Cases}, which
+calls the Sort Cases dialog:
+
+@example Screenshot, sort-dialog
+@image{sort-cases,14cm}
+@end example
+
+On the left is the list of variables upon which the data can be sorted.
+On the right is the list currently chosen.  You can add more variables to this
+list by double clicking on their names, or by using the button between the 
+two lists.
+
+The @samp{Sort Order} box allows you to specify either Ascending or Descending.
+When you are satisfied with the settings, click @clicksequence{OK} and the
+cases will be immediately sorted by the order you specified.
+
+
+@node rank-dialog
+@section rank-dialog
+
+Sometimes it's usefull to be able to associate a rank to cases --- that is to say --- to 
+indicate the order they would appear, without actually sorting them.
+This can be done, by clicking @clicksequence{Transform @click{} Rank Cases}, which
+calls the following dialog:
+
+@example Screenshot, rank-cases
+@image{rank-cases,14cm}
+@end example
+
+On the left is the list of available variables.
+On the right is the list currently chosen.  You can add more variables to this
+list by double clicking on their names, or by using the button between the 
+two lists.  There is also a box labeled @samp{By}.  Variables entered in this box
+are treated as categorical variables; cases with the same values for these variables will
+be considered to occupy the same rank.
+
+Like other commands, Rank can be run manually using using its syntax. @xref{RANK}, for details.
+
+
+@node descriptives-dialog
+@section descriptives-dialog
+
+Descriptive statistics such as Mean and Variance are available from the Descriptives command.
+Click on  @clicksequence{Analyze @click{} Descriptives}, to activate this dialog.
+
+@example Screenshot, descriptives-dialog
+@image{descriptives,14cm}
+@end example
+
+You can select many options to be included.
diff --git a/doc/rank-cases.xwd b/doc/rank-cases.xwd
new file mode 100644
index 0000000000000000000000000000000000000000..4429a334abfaad38b7f94056625821536955474e
GIT binary patch
diff --git a/doc/sort-cases.xwd b/doc/sort-cases.xwd
new file mode 100644
index 0000000000000000000000000000000000000000..b7f7c1811b73b9dc7914afa7ea05b7405a7e43de
GIT binary patch
diff --git a/doc/texi-dep.sh b/doc/texi-dep.sh
new file mode 100644
index 0000000..58bddf9
--- /dev/null
+++ b/doc/texi-dep.sh
@@ -0,0 +1,36 @@
+#!/bin/sh
+
+# This script generates the dependencies for the various
+# Texinfo targets
+
+if test $# -ne 2 ; then
+    echo 'Usage: texi-dep <target> <doc-source-dir>' >&2
+    exit 1;
+fi
+
+target=$1
+docdir=$2
+
+
+target_base=${target%%.*}
+target_ext=${target#$target_base.}
+
+printf "$target:"
+case $target_ext in
+    pdf) ext=png ;;
+    dvi) ext=eps ;;
+    info) ext=txt ;;
+    xml) ext=jpg ;;
+    ps) ext=eps ;;
+    *) echo Unsupported extension $target_text; exit 1; ;;
+esac
+
+echo $docdir/*.texi | while read f; do
+    cat $f | grep @image | while read d; do
+	dependent=`echo $d | sed -e 's/@image{\([^},]*\).*/\1/g'` ;
+	printf " doc/$dependent.$ext"
+    done
+done
+printf "\n"
+
+exit 0
-- 
1.7.2.5

