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.