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

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

[era]

Package: emacs
Version: 24.3
Severity: minor
Tags: patch
X-Debbugs-Cc: era+emacsbugs@iki.fi

As a long-time user of Emacs, but a total newcomer to SES, I had been
hoping the barrier to entry for new users would have been a little
lower. I was basically unable to do anything useful at all until I had
browsed the better parts of the manual (which as such is good, but
again, not very geared towards new users) way into the "advanced"
chapter.

I have collected some notes in
http://unix.stackexchange.com/questions/81105/ but at this point, my
proposal for a quick and unintrusive fix would amount to the following;

1. Create an (autoloading) alias "spreadsheet-mode" so that ses-mode is
easier to discover (included below).

2. Expand the ses-mode documentation string.

My proposal follows in-line, but please accept this as (a draft for) a
patch against lisp/ses.el starting at line 1888 of the current trunk
version.

;;;###autoload
(defalias 'spreadsheet-mode 'ses-mode)
;;;###autoload
(defun ses-mode ()
  "Major mode for Simple Emacs Spreadsheet.

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):
\\{ses-mode-print-map}
These are active only in the minibuffer, when entering or editing a
formula:
\\{ses-mode-edit-map}"

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

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

[Glenn Morris]

era wrote:

> 2. Expand the ses-mode documentation string.

Thank you. Would you be willing to complete an FSF copyright assignment
so that we can apply this patch to Emacs?

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

[era eriksson]

On Tue, Jul 2, 2013, at 18:54, Glenn Morris wrote:
> era wrote:
> > 2. Expand the ses-mode documentation string.
> Thank you. Would you be willing to complete an FSF copyright assignment
> so that we can apply this patch to Emacs?

For the record, I finally got the final remaining paperwork from my
employer's solicitor yesterday.  Depending on how reliable paper mail is
in your country (I hope the USPS is not affected by the furlough?) you
should have it in a couple of weeks.

/* era */

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

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

[Stefan Monnier]

>> > 2. Expand the ses-mode documentation string.
>> Thank you. Would you be willing to complete an FSF copyright assignment
>> so that we can apply this patch to Emacs?
> For the record, I finally got the final remaining paperwork from my
> employer's solicitor yesterday.  Depending on how reliable paper mail is
> in your country (I hope the USPS is not affected by the furlough?) you
> should have it in a couple of weeks.

Great, thank you,


        Stefan

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

[era eriksson]

> > 2. Expand the ses-mode documentation string.
> Thank you. Would you be willing to complete an FSF copyright assignment
> so that we can apply this patch to Emacs?

With the paperwork out of the way on my side, I have uploaded a slightly
revised patch to GitHub [0].

[0]: https://github.com/tripleee/emacs

There are two branches with fixes: bug14748 [1] contains the slightly
revised patch from before, and bug14748bis [2] contains a slightly more
intrusive -- and, regrettably, for the time being, untested -- patch for
the Info documentation.

Should I file a separate bug for the latter, or are you prepared to pull
them both in one go?

/* era */

[1]: https://github.com/tripleee/emacs/tree/bug14748
[2]: https://github.com/tripleee/emacs/tree/bug14748bis

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

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

[Glenn Morris]

era eriksson wrote:

> With the paperwork out of the way on my side,

It still needs to be received and acknowledged by the FSF. IIRC they
inform you when this happens - let us know when you hear.

> There are two branches with fixes: bug14748 [1] contains the slightly
> revised patch from before, and bug14748bis [2] contains a slightly more
> intrusive -- and, regrettably, for the time being, untested -- patch for
> the Info documentation.
>
> Should I file a separate bug for the latter, or are you prepared to pull
> them both in one go?

Please do test it, and when you are finished send both patches here.
Thanks.

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

[Glenn Morris]

Looks to me like your assignment is complete.
Could you send the latest versions of the patch(es)?

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

[era eriksson]

[-- 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

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

[Glenn Morris]

Version: 24.4

Thanks. Applied w. tweaks (e.g. the texinfo did not even compile, which
was disappointing.)

(Also; please send things to the bug address rather than just to me.)