Add READMEs for new examples, compress large one, update docs

NEWS

@@ -3,8 +3,10 @@ a spread sheet program for UNIX.
 
 The changes compared to 2.3.0 are:
 
-o computed styles for cells with an additional expression per cell
-o New token types: style and bool
+o Added examples updating the life simulation to illustrate the color and
+  computed style features.
+o You can compute the styles for cells, with an additional expression per cell.
+o New token types: style and bool.
 o Comparison operators return bool rather than int (Note this can be a breaking
   change; you may need to wrap comparisons in int() if you are using the result
   in a numerical computation.)

doc/teapot.lyx

@@ -9848,6 +9848,21 @@ macros
 Frequently Asked Questions
 \end_layout
 
+\begin_layout Subsection
+Can I see some examples of teapot in action?
+\end_layout
+
+\begin_layout Standard
+Sure, the standard distribution comes with an examples folder containing
+ several spreadsheet files illustrating some of 
+\noun on
+teapot
+\noun default
+'s features.
+ Each sheet is accompanied by a README file with a brief explanation of
+ what is going on in the file.
+\end_layout
+
 \begin_layout Subsection
 Why is 1.0 unequal 1.0?
 \end_layout

examples/blink.README

@@ -0,0 +1,5 @@
+The top left three cells on layer 0 contain two 0 values and one 1. When the
+sheet is clocked, the 1 moves around cyclically among the three cells.
+
+However, you don't see any changes taking place until you interrupt this
+infinite recalculation loop explicitly.

examples/counter.README

@@ -1,3 +1,7 @@
 This sheet shows how to use clock() to model a counter which
 automatically counts up to 1000 once the sheet gets clocked with
-control-s.
+control-s/Shift-TAB (depending on teapot/fteapot).
+
+Note that the intermediate iterations are not displayed, so you will not see
+any change to the spreadsheet other than the cell becoming 1000. (In fteapot,
+if you move around while it is updating, you will see some intermediate values.)

examples/life.README

@@ -1,4 +1,10 @@
-This is a sheet which contains the well known game of life.  Load it and
-clock the sheet with control-s a few times, and you will see the glider
-moving.  Layer 0 contains the grid and layer 1 contains some help
-formulas.
+This file is maintained here as a test of reading the legacy XDR format. Because
+of changes to the value of comparison operator (it now returns Bool rather than
+int), some of the formulas would need slight tweaking for the sheet to operate
+as formerly described below in brackets.
+
+[This is a sheet which contains the well known game of life devised by
+John Conway.  Load it and clock the sheet with control-s/Shift-TAB a few
+times, and you will see the glider moving.  Layer 0 contains the grid and
+layer 1 contains some help formulas.]
+

examples/lifeby.README

@@ -0,0 +1,14 @@
+The two files lifebyclock.tpa and lifebylayer.tpa (which needs to be gnu-
+unzipped from the distribution) update the former life.tp example to display
+teapot's color and computed style capabilities.
+
+In both files, all of the data and helper formulas are on layer 0.
+
+In lifebylayer.tpa, you can enter whatever live cells you like with the cell
+contents "1" on layer 1, making sure all non-live cells have empty contents,
+and the next 36 generations of development will be calculated on the
+succeeding layers.
+
+In lifebyclock.tpa, you can enter whatever live/non-live cells you want in the
+same fashion. However, now clocking the cell will advance the life simulation
+by one generation per iteration, for an arbitrary number of iterations.

examples/sqrt.README

@@ -1,3 +1,3 @@
 This sheet calculates the square root of x if you clock it a few times
-with control-s.  It is a nice introductional example of how to use
+with control-s/Shift-TAB.  It is a simple introductory example of how to use
 clocked expressions.