bug#14748: emacs: ses.el: ses is not self-documenting

[era eriksson <era+emacsbugs@iki.fi>]

[-- Attachment #1: Type: text/plain, Size: 423 bytes --]

On Thu, Oct 24, 2013, at 9:16, Glenn Morris wrote:
> Looks to me like your assignment is complete.
> Could you send the latest versions of the patch(es)?

Here goes, sorry for the delay.

I split this into two patches in case you want to review the second in
some more detail.  The changes in the second patch are to parts I am
less familiar with.

-- 
If this were a real .signature, it would suck less.  Well, maybe not.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-lisp-ses.el-import-patch-from-bug-report-14748.patch --]
[-- Type: text/x-patch; name="0001-lisp-ses.el-import-patch-from-bug-report-14748.patch", Size: 2375 bytes --]

From c431266427cd70964795e56a7c00f4bb7aec28f8 Mon Sep 17 00:00:00 2001
From: era <era@invalid>
Date: Thu, 10 Oct 2013 15:46:35 +0300
Subject: [PATCH 1/2] lisp/ses.el: import patch from bug report #14748

---
 lisp/ses.el |   36 +++++++++++++++++++++++++++++++++---
 1 files changed, 33 insertions(+), 3 deletions(-)

diff --git a/lisp/ses.el b/lisp/ses.el
index 5f48dd2..6ac57c3 100644
--- a/lisp/ses.el
+++ b/lisp/ses.el
@@ -1884,15 +1884,45 @@ Delete overlays, remove special text properties."
       (restore-buffer-modified-p nil))))
 
 ;;;###autoload
+(defalias 'spreadsheet-mode 'ses-mode)
+;;;###autoload
 (defun ses-mode ()
   "Major mode for Simple Emacs Spreadsheet.
-See \"ses-example.ses\" (in `data-directory') for more info.
+
+When you invoke SES in a new buffer, it is divided into cells
+which you can enter data into.  You can navigate the cells with
+the arrow keys and add more cells with the tab key.  The contents
+of these cells can be numbers, text, or Lisp expressions. (To
+enter text, enclose it in double quotes.)
+
+In an expression, you can use cell coordinates to refer to the
+contents of another cell.  For example, you can sum a range of
+cells with `(+ A1 A2 A3)'.  There are specialized functions like
+`ses+' (addition for ranges with empty cells), `ses-average' for
+performing calculations on cells, and `ses-range' and `ses-select'
+for extracting ranges of cells.
+
+Each cell also has a print function which controls how it is
+displayed.
+
+Each SES buffer is divided into a print area and a data area.
+Normally, you should simply use SES to look at and manipulate the
+print area, and let SES manage the data area outside the visible
+region.
+
+See \"ses-example.ses\" (in `data-directory') for an example
+spreadsheeet and the Info documentation `(emacs) Ses.'
+
+Notice the separate keymaps for cell editing mode and print mode
+specifications, below.
 
 Key definitions:
 \\{ses-mode-map}
-These key definitions are active only in the print area (the visible part):
+These key definitions are active only in the print area (the visible
+part):
 \\{ses-mode-print-map}
-These are active only in the minibuffer, when entering or editing a formula:
+These are active only in the minibuffer, when entering or editing a
+formula:
 \\{ses-mode-edit-map}"
   (interactive)
   (unless (and (boundp 'ses--deferred-narrow)
-- 
1.7.2.5


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #3: 0002-doc-misc-ses.texi-add-whirlwind-intro-and-more-index.patch --]
[-- Type: text/x-patch; name="0002-doc-misc-ses.texi-add-whirlwind-intro-and-more-index.patch", Size: 6362 bytes --]

From e0fb8f5db36ae28cccf27471d271ab5e8bd20468 Mon Sep 17 00:00:00 2001
From: era <era@invalid>
Date: Fri, 11 Oct 2013 11:42:05 +0300
Subject: [PATCH 2/2] doc/misc/ses.texi: add whirlwind intro and more index keywords

---
 doc/misc/ses.texi |  146 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 145 insertions(+), 1 deletions(-)

diff --git a/doc/misc/ses.texi b/doc/misc/ses.texi
index a44d790..e60bbdb 100644
--- a/doc/misc/ses.texi
+++ b/doc/misc/ses.texi
@@ -66,6 +66,7 @@ To report bugs, use @kbd{M-x report-emacs-bug}.
 
 @menu
 * Sales Pitch::                 Why use @acronym{SES}?
+* Whirlwind Tutorial::          Very quick introduction
 * The Basics::                  Basic spreadsheet commands
 * Advanced Features::           Want to know more?
 * For Gurus::                   Want to know @emph{even more}?
@@ -98,6 +99,134 @@ To report bugs, use @kbd{M-x report-emacs-bug}.
 
 @c ===================================================================
 
+@node Whirlwind Tutorial
+@comment  node-name,  next,  previous,  up
+@chapter Whirlwind Tutorial
+@cindex whirlwind tutorial
+@cindex tutorial
+
+If you just want to get started quickly and think you know
+what to expect from a simple spreadsheet,
+perhaps you want to spend a few minutes on this chapter.
+
+First, create a new file with the `.ses' extension.
+You are presented with an empty spreadsheet with a single cell.
+
+Begin by inserting a headline: @code{"Income"} @key{RET}
+The double quotes indicate that this is a text cell.
+(You will notice that the closing double quote is already entered for you.)
+
+When you attempt to enter your first income, you can't,
+because the spreadsheet is not resized for you.
+Press @key{TAB} to add a new cell and navigate back up to it.
+Enter a number, such as 2.23.
+
+@smallexample
+@group
+A
+ Income
+   2.23
+@end group
+@smallexample
+
+Proceed to add a few more income entries.
+
+@smallexample
+@group
+A
+ Income
+   2.23
+   0.02
+  15.76
+  -4.00
+@end group
+@smallexample
+
+Time to sum it up.  For this, we enter a Lisp expression.
+
+@smallexample
+(+ A2 A3 A4 A5)
+@smallexample
+
+Maybe you want to add a cell to the right of A4 to explain
+why you have a negative entry.  Press @kbd{TAB} in that cell
+and you will see that a new whole column B is added
+where you can add a text note.
+
+The column is too narrow by default, but pressing @kbd{w}
+will allow you to resize it to accommodate your note.
+Make it 20 characters wide to make room for some longer text.
+Let's add legends for the other entries, too,
+so you know what's what.
+Maybe add a @code{"Total"} next to the sum as well.
+
+@smallexample
+@group
+A        B
+ Income
+   2.23       Consulting fee
+   0.02     Informed opinion
+  15.76       Lemonade stand
+     -4          Loan to Joe
+  14.01                Total
+@end group
+@end smallexample
+
+The labels in column B are right-justified.  To fix that,
+we enter a printer function for the whole column with @kbd{M-p}.
+As the value for the printer function, enter @code{("%s")}.
+
+For what it's worth,
+you can override the column's printer function
+in any individual cell with @kbd{p}.
+
+Now maybe Joe pays back his loan, so you blank the line:
+position the cursor in A5 and press @kbd{C-d} twice.
+
+Ooops! The total now displays @code{######}.
+That is because the regular `+' is not prepared to accept
+a range which contains some empty cells.
+Replacing the debt with an actual number zero would work
+as a quick workaround, and removing the empty line would
+also fix the problem, but we want to make the formula
+more robust.  Fortunately, there is a simple fix:
+Use the special function `ses+' instead of the regular `+':
+
+@smallexample
+(ses+ A2 A3 A4 A5)
+@end smallexample
+
+You might also want to make the formula robust against
+changes in the spreadsheet geometry.  Use the `ses-range'
+macro to refer to a range of cells by naming the corners:
+
+@smallexample
+(apply 'ses+ (ses-range A2 A5))
+@end smallexample
+
+As an aside,
+the `apply' is necessary because `ses-range' produces a list
+of values.
+This is slightly unattractive in this limited example,
+but opens up for a range of interesting possibilities
+as you learn more.
+
+Now, you can delete the empty row with @kbd{C-k},
+and end up with a simple, well-organized table.
+
+@smallexample
+@group
+A       B
+ Income
+   2.23 Consulting fee
+   0.02 Informed opinion
+  15.76 Lemonade stand
+  18.01 Total
+@end group
+@end smallexample
+
+@c ===================================================================
+
 @node The Basics
 @comment  node-name,  next,  previous,  up
 @chapter The Basics
@@ -117,6 +246,7 @@ A @dfn{cell identifier} is a symbol with a column letter and a row
 number.  Cell B7 is the 2nd column of the 7th row.  For very wide
 spreadsheets, there are two column letters: cell AB7 is the 28th
 column of the 7th row. Super wide spreadsheets get AAA1, etc.
+You move around with the regular Emacs movement commands.
 
 @table @kbd
 @item j
@@ -161,13 +291,17 @@ Highlight all cells (@code{mark-whole-buffer}).
 @section Cell formulas
 @cindex formulas
 @cindex formulas, entering
+@cindex values
+@cindex cell values
+@cindex editing cells
 @findex ses-read-cell
 @findex ses-read-symbol
 @findex ses-edit-cell
 @findex ses-recalculate-cell
 @findex ses-recalculate-all
 
-To enter a number into the current cell, just start typing:
+To insert a value into a cell, simply type a numeric expression,
+@code{"double-quoted text"}, or a Lisp expression.
 
 @table @kbd
 @item 0..9
@@ -213,6 +347,14 @@ Recalculate the entire spreadsheet (@code{ses-recalculate-all}).
 @node Resizing
 @section Resizing the spreadsheet
 @cindex resizing spreadsheets
+@cindex dimensions
+@cindex enlarge
+@cindex row, adding or removing
+@cindex column, adding or removing
+@cindex adding rows or columns
+@cindex inserting rows or columns
+@cindex removing rows or columns
+@cindex deleting rows or columns
 @findex ses-insert-row
 @findex ses-insert-column
 @findex ses-delete-row
@@ -269,6 +411,8 @@ Undo previous action (@code{(undo)}).
 @node Printer functions
 @section Printer functions
 @cindex printer functions
+@cindex cell formatting
+@cindex formatting cells
 @findex ses-read-cell-printer
 @findex ses-read-column-printer
 @findex ses-read-default-printer
-- 
1.7.2.5