* bug#14748: emacs: ses.el: ses is not self-documenting
2013-10-24 7:16 ` Glenn Morris
@ 2013-11-19 12:17 ` era eriksson
2013-11-20 8:58 ` Glenn Morris
0 siblings, 1 reply; 9+ messages in thread
From: era eriksson @ 2013-11-19 12:17 UTC (permalink / raw)
To: Glenn Morris
[-- 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
^ permalink raw reply related [flat|nested] 9+ messages in thread