doc: Generate output for tutorial examples at build time too.
authorBen Pfaff <blp@cs.stanford.edu>
Sun, 25 Oct 2020 06:07:28 +0000 (23:07 -0700)
committerBen Pfaff <blp@cs.stanford.edu>
Sun, 25 Oct 2020 06:07:28 +0000 (23:07 -0700)
The trickiest part here is that the final example should only include part
of the output, the coefficients tables only.  For that, we can use the
pspp-output utility to pull just those tables from the output file.

doc/automake.mk
doc/examples/tutorial1.sps [new file with mode: 0644]
doc/examples/tutorial2.sps [new file with mode: 0644]
doc/examples/tutorial3.sps [new file with mode: 0644]
doc/examples/tutorial4.sps [new file with mode: 0644]
doc/examples/tutorial5.sps [new file with mode: 0644]
doc/examples/tutorial6.sps [new file with mode: 0644]
doc/examples/tutorial7.sps [new file with mode: 0644]
doc/tutorial.texi

index 5e09c6cbfbfc06f85f297839e45e3cd8a5d0e2b8..8a9df0543a7e2f89a31ed4b84d8a08fc191df44e 100644 (file)
@@ -124,14 +124,23 @@ EXAMPLE_SYNTAX = \
  doc/examples/independent-samples-t.sps \
  doc/examples/reliability.sps \
  doc/examples/split.sps \
+ doc/examples/tutorial1.sps \
+ doc/examples/tutorial2.sps \
+ doc/examples/tutorial3.sps \
+ doc/examples/tutorial4.sps \
+ doc/examples/tutorial5.sps \
+ doc/examples/tutorial6.sps \
+ doc/examples/tutorial7.sps \
  doc/examples/weight.sps
 
 
 EXTRA_DIST += $(EXAMPLE_SYNTAX)
 
+EXAMPLE_SPVS = $(EXAMPLE_SYNTAX:.sps=.spv) doc/examples/tutorial7b.spv
 EXAMPLE_OUTPUTS = $(EXAMPLE_SYNTAX:.sps=.out)
 EXAMPLE_HTML = $(EXAMPLE_SYNTAX:.sps=.html)
 
+example-spv: $(EXAMPLE_SPVS)
 example-outputs: $(EXAMPLE_OUTPUTS)
 example-html: $(EXAMPLE_HTML)
 PHONY += example-outputs example-html
@@ -148,22 +157,30 @@ pspp = $(abs_top_builddir)/src/ui/terminal/pspp
 $(EXAMPLE_OUTPUTS): $(pspp)
 $(EXAMPLE_HTML): $(pspp)
 
-CLEANFILES += $(EXAMPLE_OUTPUTS)
+CLEANFILES += $(EXAMPLE_OUTPUTS) $(EXAMPLE_SPVS)
 
 SUFFIXES: .sps
 
-# use pspp to process a syntax file and reap the output into a text file
-.sps.out:
+# Use pspp to process a syntax file into an output file.
+.sps.spv:
        $(AM_V_GEN)(cd $(top_srcdir)/examples \
-         && $(pspp) ../doc/examples/$(<F) -o -) > $@.tmp && mv $@.tmp $@
-
-# Use pspp to process a syntax file and reap the output into a html file
-# Then, use sed to delete everything up to and including <body> and
-# everything after and including </body>
-.sps.html:
-       $(AM_V_GEN)(cd $(top_srcdir)/examples \
-         && $(pspp) ../doc/examples/$(<F) -o - -O format=html) \
-       | $(SED) -e '\%</body%,$$d' -e '0,/<body/d' > $@.tmp && mv $@.tmp $@
+         && $(pspp) ../doc/examples/$(<F) -o - -O format=spv) > $@.tmp
+       $(AM_V_at)mv $@.tmp $@
+
+# The tutorial only wants some parts of the output here.
+pspp_output = utilities/pspp-output
+doc/examples/tutorial7b.spv: doc/examples/tutorial7.spv $(pspp_output)
+       $(AM_V_GEN)$(pspp_output) convert --subtypes=coefficients $< $@
+
+# Convert an output file into a text file or HTML file.
+#
+# (For HTML, use sed to include only the contents of <body>.)
+.spv.out:
+       $(AM_V_GEN)utilities/pspp-output convert $< $@
+.spv.html:
+       $(AM_V_GEN)utilities/pspp-output convert $< - -O format=html \
+       | $(SED) -e '\%</body%,$$d' -e '0,/<body/d' > $@.tmp
+       $(AM_V_at)mv $@.tmp $@
 
 # Insert the link tag for the cascading style sheet.
 # But make sure these operations are idempotent.
diff --git a/doc/examples/tutorial1.sps b/doc/examples/tutorial1.sps
new file mode 100644 (file)
index 0000000..3fc7fbc
--- /dev/null
@@ -0,0 +1,8 @@
+data list list notable /forename (A12) height.
+begin data.
+Ahmed 188
+Bertram 167
+Catherine 134.231
+David 109.1
+end data
+list /format=numbered.
\ No newline at end of file
diff --git a/doc/examples/tutorial2.sps b/doc/examples/tutorial2.sps
new file mode 100644 (file)
index 0000000..0df4cb0
--- /dev/null
@@ -0,0 +1,2 @@
+get file='physiology.sav'.
+descriptives sex, weight, height.
diff --git a/doc/examples/tutorial3.sps b/doc/examples/tutorial3.sps
new file mode 100644 (file)
index 0000000..757fcf3
--- /dev/null
@@ -0,0 +1,2 @@
+get file='physiology.sav'.
+examine height, weight /statistics=extreme(3).
\ No newline at end of file
diff --git a/doc/examples/tutorial4.sps b/doc/examples/tutorial4.sps
new file mode 100644 (file)
index 0000000..8e7942f
--- /dev/null
@@ -0,0 +1,5 @@
+get file='hotel.sav'.
+* recode negatively worded questions.
+compute v3 = 6 - v3.
+compute v5 = 6 - v5.
+reliability variables=v1, v3, v4.
diff --git a/doc/examples/tutorial5.sps b/doc/examples/tutorial5.sps
new file mode 100644 (file)
index 0000000..ced90da
--- /dev/null
@@ -0,0 +1,6 @@
+get file='repairs.sav'.
+examine mtbf
+ /statistics=descriptives.
+compute mtbf_ln = ln (mtbf).
+examine mtbf_ln
+ /statistics=descriptives.
diff --git a/doc/examples/tutorial6.sps b/doc/examples/tutorial6.sps
new file mode 100644 (file)
index 0000000..889f77f
--- /dev/null
@@ -0,0 +1,3 @@
+get file='physiology.sav'.
+recode height (179 = SYSMIS).
+t-test group=sex(0,1) /variables = height temperature.
diff --git a/doc/examples/tutorial7.sps b/doc/examples/tutorial7.sps
new file mode 100644 (file)
index 0000000..07858d2
--- /dev/null
@@ -0,0 +1,3 @@
+get file='repairs.sav'.
+regression /variables = mtbf duty_cycle /dependent = mttr.
+regression /variables = mtbf /dependent = mttr.
index 2071d2a59df384dc38c01d6dd0fcf3631e249419..285c3f3ff9ba136902dd413df52415c879f44b4f 100644 (file)
@@ -195,19 +195,7 @@ to list the data.
 The optional text @samp{/format=numbered} requests the case numbers to be
 shown along with the data.
 It should show the following output:
-@example
-@group
-           Data List
-+-----------+---------+------+
-|Case Number| forename|height|
-+-----------+---------+------+
-|1          |Ahmed    |188.00|
-|2          |Bertram  |167.00|
-|3          |Catherine|134.23|
-|4          |David    |109.10|
-+-----------+---------+------+
-@end group
-@end example
+@psppoutput {tutorial1}
 @noindent
 Note that the numeric variable @exvar{height} is displayed to 2 decimal
 places, because the format for that variable is @samp{F8.2}.
@@ -352,18 +340,7 @@ data and identify the erroneous values.
 @end example
 
 Output:
-@example
-                  Descriptive Statistics
-+---------------------+--+-------+-------+-------+-------+
-|                     | N|  Mean |Std Dev|Minimum|Maximum|
-+---------------------+--+-------+-------+-------+-------+
-|Sex of subject       |40|    .45|    .50|Male   |Female |
-|Weight in kilograms  |40|  72.12|  26.70|  -55.6|   92.1|
-|Height in millimeters|40|1677.12| 262.87|    179|   1903|
-|Valid N (listwise)   |40|       |       |       |       |
-|Missing N (listwise) | 0|       |       |       |       |
-+---------------------+--+-------+-------+-------+-------+
-@end example
+@psppoutput {tutorial2}
 @end cartouche
 @caption{Using the @cmd{DESCRIPTIVES} command to display simple
 summary information about the data.
@@ -526,25 +503,7 @@ negatively scaled variables) requests reliability statistics for
 @end example
 
 Output (dictionary information omitted for clarity):
-@example
-Scale: ANY
-
-Case Processing Summary
-+--------+--+-------+
-|Cases   | N|Percent|
-+--------+--+-------+
-|Valid   |17| 100.0%|
-|Excluded| 0|    .0%|
-|Total   |17| 100.0%|
-+--------+--+-------+
-
-    Reliability Statistics
-+----------------+----------+
-|Cronbach's Alpha|N of Items|
-+----------------+----------+
-|             .81|         3|
-+----------------+----------+
-@end example
+@psppoutput {tutorial4}
 @end cartouche
 @caption{Recoding negatively scaled variables, and testing for
 reliability with the @cmd{RELIABILITY} command. The Cronbach Alpha
@@ -611,68 +570,7 @@ an appropriate non-parametric test instead of a linear one.
 @end example
 
 Output:
-@example
-                       Case Processing Summary
-+-----------------------------------+-------------------------------+
-|                                   |             Cases             |
-|                                   +----------+---------+----------+
-|                                   |   Valid  | Missing |   Total  |
-|                                   | N|Percent|N|Percent| N|Percent|
-+-----------------------------------+--+-------+-+-------+--+-------+
-|Mean time between failures (months)|15| 100.0%|0|    .0%|15| 100.0%|
-+-----------------------------------+--+-------+-+-------+--+-------+
-
-                                  Descriptives
-+----------------------------------------------------------+---------+--------+
-|                                                          |         |  Std.  |
-|                                                          |Statistic|  Error |
-+----------------------------------------------------------+---------+--------+
-|Mean time between        Mean                             |     8.32|    1.62|
-|failures (months)        95% Confidence Interval Lower    |     4.85|        |
-|                         for Mean                Bound    |         |        |
-|                                                 Upper    |    11.79|        |
-|                                                 Bound    |         |        |
-|                         5% Trimmed Mean                  |     7.69|        |
-|                         Median                           |     8.12|        |
-|                         Variance                         |    39.21|        |
-|                         Std. Deviation                   |     6.26|        |
-|                         Minimum                          |     1.63|        |
-|                         Maximum                          |    26.47|        |
-|                         Range                            |    24.84|        |
-|                         Interquartile Range              |     5.83|        |
-|                         Skewness                         |     1.85|     .58|
-|                         Kurtosis                         |     4.49|    1.12|
-+----------------------------------------------------------+---------+--------+
-
-         Case Processing Summary
-+-------+-------------------------------+
-|       |             Cases             |
-|       +----------+---------+----------+
-|       |   Valid  | Missing |   Total  |
-|       | N|Percent|N|Percent| N|Percent|
-+-------+--+-------+-+-------+--+-------+
-|mtbf_ln|15| 100.0%|0|    .0%|15| 100.0%|
-+-------+--+-------+-+-------+--+-------+
-
-                                Descriptives
-+----------------------------------------------------+---------+----------+
-|                                                    |Statistic|Std. Error|
-+----------------------------------------------------+---------+----------+
-|mtbf_ln Mean                                        |     1.88|       .19|
-|        95% Confidence Interval for Mean Lower Bound|     1.47|          |
-|                                         Upper Bound|     2.29|          |
-|        5% Trimmed Mean                             |     1.88|          |
-|        Median                                      |     2.09|          |
-|        Variance                                    |      .54|          |
-|        Std. Deviation                              |      .74|          |
-|        Minimum                                     |      .49|          |
-|        Maximum                                     |     3.28|          |
-|        Range                                       |     2.79|          |
-|        Interquartile Range                         |      .92|          |
-|        Skewness                                    |     -.16|       .58|
-|        Kurtosis                                    |     -.09|      1.12|
-+----------------------------------------------------+---------+----------+
-@end example
+@psppoutput {tutorial5}
 @end cartouche
 @caption{Testing for normality using the @cmd{EXAMINE} command and applying
 a logarithmic transformation.
@@ -780,84 +678,7 @@ suggest that the body temperature of male and female persons are different.
 @prompt{PSPP>} t-test group=sex(0,1) /variables = height temperature.
 @end example
 Output:
-@example
-                                Group Statistics
-+-------------------------------------------+--+-------+-------------+--------+
-|                                           |  |       |     Std.    |  S.E.  |
-|                                     Group | N|  Mean |  Deviation  |  Mean  |
-+-------------------------------------------+--+-------+-------------+--------+
-|Height in millimeters                Male  |22|1796.49|        49.71|   10.60|
-|                                     Female|17|1610.77|        25.43|    6.17|
-+-------------------------------------------+--+-------+-------------+--------+
-|Internal body temperature in degrees Male  |22|  36.68|         1.95|     .42|
-|Celcius                              Female|18|  37.43|         1.61|     .38|
-+-------------------------------------------+--+-------+-------------+--------+
-
-                          Independent Samples Test
-+---------------------+-----------------------------------------------------
-|                     | Levene's
-|                     | Test for
-|                     | Equality
-|                     |    of
-|                     | Variances               T-Test for Equality of Means
-|                     +----+-----+-----+-----+-------+----------+----------+
-|                     |    |     |     |     |       |          |          |
-|                     |    |     |     |     |       |          |          |
-|                     |    |     |     |     |       |          |          |
-|                     |    |     |     |     |       |          |          |
-|                     |    |     |     |     |  Sig. |          |          |
-|                     |    |     |     |     |  (2-  |   Mean   |Std. Error|
-|                     |  F | Sig.|  t  |  df |tailed)|Difference|Difference|
-+---------------------+----+-----+-----+-----+-------+----------+----------+
-|Height in   Equal    | .97| .331|14.02|37.00|   .000|    185.72|     13.24|
-|millimeters variances|    |     |     |     |       |          |          |
-|            assumed  |    |     |     |     |       |          |          |
-|            Equal    |    |     |15.15|32.71|   .000|    185.72|     12.26|
-|            variances|    |     |     |     |       |          |          |
-|            not      |    |     |     |     |       |          |          |
-|            assumed  |    |     |     |     |       |          |          |
-+---------------------+----+-----+-----+-----+-------+----------+----------+
-|Internal    Equal    | .31| .581|-1.31|38.00|   .198|      -.75|       .57|
-|body        variances|    |     |     |     |       |          |          |
-|temperature assumed  |    |     |     |     |       |          |          |
-|in degrees  Equal    |    |     |-1.33|37.99|   .190|      -.75|       .56|
-|Celcius     variances|    |     |     |     |       |          |          |
-|            not      |    |     |     |     |       |          |          |
-|            assumed  |    |     |     |     |       |          |          |
-+---------------------+----+-----+-----+-----+-------+----------+----------+
-
-+---------------------+-------------+
-|                     |             |
-|                     |             |
-|                     |             |
-|                     |             |
-|                     |             |
-|                     +-------------+
-|                     |     95%     |
-|                     |  Confidence |
-|                     | Interval of |
-|                     |     the     |
-|                     |  Difference |
-|                     +------+------+
-|                     | Lower| Upper|
-+---------------------+------+------+
-|Height in   Equal    |158.88|212.55|
-|millimeters variances|      |      |
-|            assumed  |      |      |
-|            Equal    |160.76|210.67|
-|            variances|      |      |
-|            not      |      |      |
-|            assumed  |      |      |
-+---------------------+------+------+
-|Internal    Equal    | -1.91|   .41|
-|body        variances|      |      |
-|temperature assumed  |      |      |
-|in degrees  Equal    | -1.89|   .39|
-|Celcius     variances|      |      |
-|            not      |      |      |
-|            assumed  |      |      |
-+---------------------+------+------+
-@end example
+@psppoutput {tutorial6}
 @end cartouche
 @caption{The @cmd{T-TEST} command tests for differences of means.
 Here, the @exvar{height} variable's two tailed significance is less than
@@ -900,33 +721,7 @@ identifies the potential linear relationship. @xref{REGRESSION}.
 @prompt{PSPP>} regression /variables = mtbf /dependent = mttr.
 @end example
 Output (excerpts):
-@example
-                  Coefficients (Mean time to repair (hours) )
-+------------------------+-----------------------------------------+-----+----+
-|                        |    Unstandardized        Standardized   |     |    |
-|                        |     Coefficients         Coefficients   |     |    |
-|                        +---------+-----------+-------------------+     |    |
-|                        |    B    | Std. Error|        Beta       |  t  |Sig.|
-+------------------------+---------+-----------+-------------------+-----+----+
-|(Constant)              |     9.81|       1.50|                .00| 6.54|.000|
-|Mean time between       |     3.10|        .10|                .99|32.43|.000|
-|failures (months)       |         |           |                   |     |    |
-|Ratio of working to non-|     1.09|       1.78|                .02|  .61|.552|
-|working time            |         |           |                   |     |    |
-+------------------------+---------+-----------+-------------------+-----+----+
-
-                  Coefficients (Mean time to repair (hours) )
-+-----------------------+------------------------------------------+-----+----+
-|                       |    Unstandardized         Standardized   |     |    |
-|                       |     Coefficients          Coefficients   |     |    |
-|                       +---------+------------+-------------------+     |    |
-|                       |    B    | Std. Error |        Beta       |  t  |Sig.|
-+-----------------------+---------+------------+-------------------+-----+----+
-|(Constant)             |    10.50|         .96|                .00|10.96|.000|
-|Mean time between      |     3.11|         .09|                .99|33.39|.000|
-|failures (months)      |         |            |                   |     |    |
-+-----------------------+---------+------------+-------------------+-----+----+
-@end example
+@psppoutput {tutorial7b}
 @end cartouche
 @caption{Linear regression analysis to find a predictor for
 @exvar{mttr}.