47667
|
1 \input texinfo @c -*-texinfo-*-
|
|
2 @c %**start of header
|
|
3 @setfilename ../info/ses
|
|
4 @settitle SES: Simple Emacs Spreadsheet
|
|
5 @setchapternewpage off
|
65220
|
6 @syncodeindex fn cp
|
|
7 @syncodeindex vr cp
|
|
8 @syncodeindex ky cp
|
47667
|
9 @c %**end of header
|
|
10
|
47737
|
11 @copying
|
47667
|
12 This file documents SES: the Simple Emacs Spreadsheet.
|
|
13
|
75348
|
14 Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007
|
|
15 Free Software Foundation, Inc.
|
47667
|
16
|
47737
|
17 @quotation
|
47667
|
18 Permission is granted to copy, distribute and/or modify this document
|
65555
|
19 under the terms of the GNU Free Documentation License, Version 1.2 or
|
47667
|
20 any later version published by the Free Software Foundation; with no
|
|
21 Invariant Sections, with the Front-Cover texts being ``A GNU
|
|
22 Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the
|
|
23 license is included in the section entitled ``GNU Free Documentation
|
|
24 License'' in the Emacs manual.
|
|
25
|
|
26 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
|
|
27 this GNU Manual, like GNU software. Copies published by the Free
|
|
28 Software Foundation raise funds for GNU development.''
|
|
29
|
|
30 This document is part of a collection distributed under the GNU Free
|
|
31 Documentation License. If you want to distribute this document
|
|
32 separately from the collection, you can do so by adding a copy of the
|
|
33 license to the document, as described in section 6 of the license.
|
47737
|
34 @end quotation
|
|
35 @end copying
|
|
36
|
|
37 @dircategory Emacs
|
|
38 @direntry
|
|
39 * SES: (ses). Simple Emacs Spreadsheet
|
|
40 @end direntry
|
47667
|
41
|
|
42 @finalout
|
|
43
|
|
44 @titlepage
|
|
45 @title SES
|
|
46 @subtitle Simple Emacs Spreadsheet
|
|
47 @author Jonathan A. Yavner
|
55365
|
48 @author @email{jyavner@@member.fsf.org}
|
47667
|
49
|
|
50 @page
|
|
51 @vskip 0pt plus 1filll
|
47737
|
52 @insertcopying
|
47667
|
53 @end titlepage
|
|
54
|
|
55 @contents
|
|
56
|
|
57 @c ===================================================================
|
|
58
|
|
59 @ifnottex
|
47668
bcc91f26d220
Fix Texinfo build failure by running `texinfo-all-menus-update'.
Robert J. Chassell <bob@rattlesnake.com>
diff
changeset
|
60 @node Top, Sales Pitch, (dir), (dir)
|
47667
|
61 @comment node-name, next, previous, up
|
|
62 @top SES: Simple Emacs Spreadsheet
|
|
63
|
|
64 @display
|
|
65 SES is a major mode for GNU Emacs to edit spreadsheet files, which
|
|
66 contain a rectangular grid of cells. The cells' values are specified
|
|
67 by formulas that can refer to the values of other cells.
|
|
68 @end display
|
|
69 @end ifnottex
|
|
70
|
52042
|
71 To report bugs, send email to @email{jyavner@@member.fsf.org}.
|
47667
|
72
|
|
73 @menu
|
47668
bcc91f26d220
Fix Texinfo build failure by running `texinfo-all-menus-update'.
Robert J. Chassell <bob@rattlesnake.com>
diff
changeset
|
74 * Sales Pitch:: Why use SES?
|
bcc91f26d220
Fix Texinfo build failure by running `texinfo-all-menus-update'.
Robert J. Chassell <bob@rattlesnake.com>
diff
changeset
|
75 * The Basics:: Basic spreadsheet commands
|
bcc91f26d220
Fix Texinfo build failure by running `texinfo-all-menus-update'.
Robert J. Chassell <bob@rattlesnake.com>
diff
changeset
|
76 * Advanced Features:: Want to know more?
|
bcc91f26d220
Fix Texinfo build failure by running `texinfo-all-menus-update'.
Robert J. Chassell <bob@rattlesnake.com>
diff
changeset
|
77 * For Gurus:: Want to know @emph{even more}?
|
60140
|
78 * Index:: Concept, Function and Variable Index
|
47668
bcc91f26d220
Fix Texinfo build failure by running `texinfo-all-menus-update'.
Robert J. Chassell <bob@rattlesnake.com>
diff
changeset
|
79 * Acknowledgements:: Acknowledgements
|
47667
|
80 @end menu
|
|
81
|
|
82 @c ===================================================================
|
|
83
|
|
84 @node Sales Pitch, The Basics, Top, Top
|
|
85 @comment node-name, next, previous, up
|
|
86 @chapter Sales Pitch
|
60140
|
87 @cindex features
|
47667
|
88
|
|
89 @itemize @bullet
|
|
90 @item Create and edit simple spreadsheets with a minimum of fuss.
|
|
91 @item Full undo/redo/autosave.
|
|
92 @item Immune to viruses in spreadsheet files.
|
|
93 @item Cell formulas are straight Emacs Lisp.
|
|
94 @item Printer functions for control of cell appearance.
|
|
95 @item Intuitive keystroke commands: C-o = insert row, M-o = insert column, etc.
|
|
96 @item ``Spillover'' of lengthy cell values into following blank cells.
|
|
97 @item Header line shows column letters or a selected row.
|
|
98 @item Completing-read for entering symbols as cell values.
|
|
99 @item Cut, copy, and paste can transfer formulas and printer functions.
|
|
100 @item Import and export of tab-separated values or tab-separated formulas.
|
|
101 @item Plaintext, easily-hacked file format.
|
|
102 @end itemize
|
|
103
|
|
104 @c ===================================================================
|
|
105
|
|
106 @node The Basics, Advanced Features, Sales Pitch, Top
|
|
107 @comment node-name, next, previous, up
|
|
108 @chapter The Basics
|
60140
|
109 @cindex basic commands
|
|
110 @findex ses-jump
|
|
111 @findex ses-mark-row
|
|
112 @findex ses-mark-column
|
|
113 @findex ses-mark-whole-buffer
|
|
114 @findex set-mark-command
|
|
115 @findex keyboard-quit
|
47667
|
116
|
|
117 A @dfn{cell identifier} is a symbol with a column letter and a row
|
|
118 number. Cell B7 is the 2nd column of the 7th row. For very wide
|
|
119 spreadsheets, there are two column letters: cell AB7 is the 28th
|
|
120 column of the 7th row.
|
|
121
|
|
122 @table @kbd
|
|
123 @item j
|
|
124 Moves point to cell, specified by identifier (@code{ses-jump}).
|
|
125 @end table
|
|
126
|
|
127 Point is always at the left edge of a cell, or at the empty endline.
|
|
128 When mark is inactive, the current cell is underlined. When mark is
|
|
129 active, the range is the highlighted rectangle of cells (SES always
|
|
130 uses transient mark mode). Drag the mouse from A1 to A3 to create the
|
|
131 range A1-A2. Many SES commands operate only on single cells, not
|
|
132 ranges.
|
|
133
|
|
134 @table @kbd
|
|
135 @item C-SPC
|
|
136 @itemx C-@@
|
|
137 Set mark at point (@code{set-mark-command}).
|
|
138
|
|
139 @item C-g
|
|
140 Turn off the mark (@code{keyboard-quit}).
|
|
141
|
|
142 @item M-h
|
|
143 Highlight current row (@code{ses-mark-row}).
|
|
144
|
|
145 @item S-M-h
|
|
146 Highlight current column (@code{ses-mark-column}).
|
|
147
|
|
148 @item C-x h
|
|
149 Highlight all cells (@code{mark-whole-buffer}).
|
|
150 @end table
|
|
151
|
|
152 @menu
|
|
153 * Formulas::
|
|
154 * Resizing::
|
|
155 * Printer functions::
|
|
156 * Clearing cells::
|
|
157 * Copy/cut/paste::
|
|
158 * Customizing SES::
|
|
159 @end menu
|
|
160
|
|
161 @node Formulas, Resizing, The Basics, The Basics
|
|
162 @section Cell formulas
|
60140
|
163 @cindex formulas
|
|
164 @cindex formulas, entering
|
|
165 @findex ses-read-cell
|
|
166 @findex ses-read-symbol
|
|
167 @findex ses-edit-cell
|
|
168 @findex ses-recalculate-cell
|
|
169 @findex ses-recalculate-all
|
47667
|
170
|
|
171 To enter a number into the current cell, just start typing:
|
|
172
|
|
173 @table @kbd
|
|
174 @item 0..9
|
|
175 Self-insert a digit (@code{ses-read-cell}).
|
|
176
|
|
177 @item -
|
|
178 Self-insert a negative number (@code{ses-read-cell}).
|
|
179
|
|
180 @item .
|
|
181 Self-insert a fractional number (@code{ses-read-cell}).
|
|
182
|
|
183 @item "
|
|
184 Self-insert a quoted string. The ending double-quote
|
|
185 is inserted for you (@code{ses-read-cell}).
|
|
186
|
|
187 @item (
|
|
188 Self-insert an expression. The right-parenthesis is inserted for you
|
|
189 (@code{ses-read-cell}). To access another cell's value, just use its
|
|
190 identifier in your expression. Whenever the other cell is changed,
|
|
191 this cell's formula will be reevaluated. While typing in the
|
68313
|
192 expression, you can use @kbd{M-@key{TAB}} to complete symbol names.
|
47667
|
193
|
|
194 @item ' @r{(apostrophe)}
|
|
195 Enter a symbol (ses-read-symbol). SES remembers all symbols that have
|
|
196 been used as formulas, so you can type just the beginning of a symbol
|
68313
|
197 and use @kbd{@key{SPC}}, @kbd{@key{TAB}}, and @kbd{?} to complete it.
|
47667
|
198 @end table
|
|
199
|
|
200 To enter something else (e.g., a vector), begin with a digit, then
|
|
201 erase the digit and type whatever you want.
|
|
202
|
|
203 @table @kbd
|
|
204 @item RET
|
|
205 Edit the existing formula in the current cell (@code{ses-edit-cell}).
|
|
206
|
|
207 @item C-c C-c
|
|
208 Force recalculation of the current cell or range (@code{ses-recalculate-cell}).
|
|
209
|
|
210 @item C-c C-l
|
|
211 Recalculate the entire spreadsheet (@code{ses-recalculate-all}).
|
|
212 @end table
|
|
213
|
|
214 @node Resizing, Printer functions, Formulas, The Basics
|
|
215 @section Resizing the spreadsheet
|
60140
|
216 @cindex resizing spreadsheets
|
|
217 @findex ses-insert-row
|
|
218 @findex ses-insert-column
|
|
219 @findex ses-delete-row
|
|
220 @findex ses-delete-column
|
|
221 @findex ses-set-column-width
|
|
222 @findex ses-forward-or-insert
|
|
223 @findex ses-append-row-jump-first-column
|
|
224
|
47667
|
225
|
|
226 Basic commands:
|
|
227
|
|
228 @table @kbd
|
|
229 @item C-o
|
|
230 (@code{ses-insert-row})
|
|
231
|
|
232 @item M-o
|
|
233 (@code{ses-insert-column})
|
|
234
|
|
235 @item C-k
|
|
236 (@code{ses-delete-row})
|
|
237
|
|
238 @item M-k
|
|
239 (@code{ses-delete-column})
|
|
240
|
|
241 @item w
|
|
242 (@code{ses-set-column-width})
|
|
243
|
|
244 @item TAB
|
|
245 Moves point to the next rightward cell, or inserts a new column if
|
|
246 already at last cell on line, or inserts a new row if at endline
|
|
247 (@code{ses-forward-or-insert}).
|
|
248
|
|
249 @item C-j
|
|
250 Linefeed inserts below the current row and moves to column A
|
|
251 (@code{ses-append-row-jump-first-column}).
|
|
252 @end table
|
|
253
|
|
254 Resizing the spreadsheet (unless you're just changing a column width)
|
|
255 relocates all the cell-references in formulas so they still refer to
|
|
256 the same cells. If a formula mentioned B1 and you insert a new first
|
|
257 row, the formula will now mention B2.
|
|
258
|
|
259 If you delete a cell that a formula refers to, the cell-symbol is
|
|
260 deleted from the formula, so @code{(+ A1 B1 C1)} after deleting the third
|
|
261 column becomes @code{(+ A1 B1)}. In case this is not what you wanted:
|
|
262
|
|
263 @table @kbd
|
|
264 @item C-_
|
|
265 @itemx C-x u
|
|
266 Undo previous action (@code{(undo)}).
|
|
267 @end table
|
|
268
|
|
269
|
|
270 @node Printer functions, Clearing cells, Resizing, The Basics
|
|
271 @section Printer functions
|
60140
|
272 @cindex printer functions
|
|
273 @findex ses-read-cell-printer
|
|
274 @findex ses-read-column-printer
|
|
275 @findex ses-read-default-printer
|
|
276 @findex ses-center
|
|
277 @findex ses-center-span
|
|
278 @findex ses-dashfill
|
|
279 @findex ses-dashfill-span
|
|
280 @findex ses-tildefill-span
|
|
281
|
47667
|
282
|
|
283 Printer functions convert binary cell values into the print forms that
|
|
284 Emacs will display on the screen.
|
|
285
|
|
286 A printer can be a format string, like @samp{"$%.2f"}. The result
|
|
287 string is right-aligned within the print cell. To get left-alignment,
|
|
288 use parentheses: @samp{("$%.2f")}. A printer can also be a
|
|
289 one-argument function (a symbol or a lambda), whose result is a string
|
|
290 (right-aligned) or list of one string (left-aligned). While typing in
|
68313
|
291 a lambda, you can use @kbd{M-@key{TAB}} to complete the names of symbols.
|
47667
|
292
|
56279
|
293 Each cell has a printer. If @code{nil}, the column-printer for the cell's
|
|
294 column is used. If that is also @code{nil}, the default-printer for the
|
47667
|
295 spreadsheet is used.
|
|
296
|
|
297 @table @kbd
|
|
298 @item p
|
|
299 Enter a printer for current cell or range (@code{ses-read-cell-printer}).
|
|
300
|
|
301 @item M-p
|
|
302 Enter a printer for the current column (@code{ses-read-column-printer}).
|
|
303
|
|
304 @item C-c C-p
|
|
305 Enter the default printer for the spreadsheet
|
|
306 (@code{ses-read-default-printer}).
|
|
307 @end table
|
|
308
|
|
309 The @code{ses-read-@r{XXX}-printer} commands have their own minibuffer
|
|
310 history, which is preloaded with the set of all printers used in this
|
|
311 spreadsheet, plus the standard printers.
|
|
312
|
|
313 The standard printers are suitable only for cells, not columns or
|
|
314 default, because they format the value using the column-printer (or
|
56279
|
315 default-printer if @code{nil}) and then center the result:
|
47667
|
316
|
|
317 @table @code
|
|
318 @item ses-center
|
|
319 Just centering.
|
|
320
|
|
321 @item ses-center-span
|
|
322 Centering with spill-over to following blank cells.
|
|
323
|
|
324 @item ses-dashfill
|
|
325 Centering using dashes (-) instead of spaces.
|
|
326
|
|
327 @item ses-dashfill-span
|
|
328 Centering with dashes and spill-over.
|
|
329
|
|
330 @item ses-tildefill-span
|
|
331 Centering with tildes (~) and spill-over.
|
|
332 @end table
|
|
333
|
|
334
|
|
335 @node Clearing cells, Copy/cut/paste, Printer functions, The Basics
|
|
336 @section Clearing cells
|
60140
|
337 @cindex clearing commands
|
|
338 @findex ses-clear-cell-backward
|
|
339 @findex ses-clear-cell-forward
|
47667
|
340
|
56279
|
341 These commands set both formula and printer to @code{nil}:
|
47667
|
342
|
|
343 @table @kbd
|
|
344 @item DEL
|
|
345 Clear cell and move left (@code{ses-clear-cell-backward}).
|
|
346
|
|
347 @item C-d
|
|
348 Clear cell and move right (@code{ses-clear-cell-forward}).
|
|
349 @end table
|
|
350
|
|
351
|
|
352 @node Copy/cut/paste, Customizing SES, Clearing cells, The Basics
|
|
353 @section Copy, cut, and paste
|
60140
|
354 @cindex copy
|
|
355 @cindex cut
|
|
356 @cindex paste
|
|
357 @findex kill-ring-save
|
|
358 @findex mouse-set-region
|
|
359 @findex mouse-set-secondary
|
|
360 @findex ses-kill-override
|
|
361 @findex yank
|
|
362 @findex clipboard-yank
|
|
363 @findex mouse-yank-at-click
|
|
364 @findex mouse-yank-at-secondary
|
|
365 @findex ses-yank-pop
|
47667
|
366
|
|
367 The copy functions work on rectangular regions of cells. You can paste the
|
|
368 copies into non-SES buffers to export the print text.
|
|
369
|
|
370 @table @kbd
|
|
371 @item M-w
|
|
372 @itemx [copy]
|
|
373 @itemx [C-insert]
|
|
374 Copy the highlighted cells to kill ring and primary clipboard
|
|
375 (@code{kill-ring-save}).
|
|
376
|
|
377 @item [drag-mouse-1]
|
|
378 Mark a region and copy it to kill ring and primary clipboard
|
|
379 (@code{mouse-set-region}).
|
|
380
|
|
381 @item [M-drag-mouse-1]
|
|
382 Mark a region and copy it to kill ring and secondary clipboard
|
|
383 (@code{mouse-set-secondary}).
|
|
384
|
|
385 @item C-w
|
|
386 @itemx [cut]
|
|
387 @itemx [S-delete]
|
56279
|
388 The cut functions do not actually delete rows or columns---they copy
|
47667
|
389 and then clear (@code{ses-kill-override}).
|
|
390
|
|
391 @item C-y
|
|
392 @itemx [S-insert]
|
|
393 Paste from kill ring (@code{yank}). The paste functions behave
|
|
394 differently depending on the format of the text being inserted:
|
|
395 @itemize @bullet
|
|
396 @item
|
|
397 When pasting cells that were cut from a SES buffer, the print text is
|
|
398 ignored and only the attached formula and printer are inserted; cell
|
|
399 references in the formula are relocated unless you use @kbd{C-u}.
|
|
400 @item
|
|
401 The pasted text overwrites a rectangle of cells whose top left corner
|
|
402 is the current cell. If part of the rectangle is beyond the edges of
|
|
403 the spreadsheet, you must confirm the increase in spreadsheet size.
|
|
404 @item
|
|
405 Non-SES text is usually inserted as a replacement formula for the
|
|
406 current cell. If the formula would be a symbol, it's treated as a
|
|
407 string unless you use @kbd{C-u}. Pasted formulas with syntax errors
|
|
408 are always treated as strings.
|
|
409 @end itemize
|
|
410
|
|
411 @item [paste]
|
|
412 Paste from primary clipboard or kill ring (@code{clipboard-yank}).
|
|
413
|
|
414 @item [mouse-2]
|
|
415 Set point and paste from primary clipboard (@code{mouse-yank-at-click}).
|
|
416
|
|
417 @item [M-mouse-2]
|
|
418 Set point and paste from secondary clipboard (@code{mouse-yank-secondary}).
|
|
419
|
|
420 @item M-y
|
|
421 Immediately after a paste, you can replace the text with a preceding
|
|
422 element from the kill ring (@code{ses-yank-pop}). Unlike the standard
|
|
423 Emacs yank-pop, the SES version uses @code{undo} to delete the old
|
|
424 yank. This doesn't make any difference?
|
|
425 @end table
|
|
426
|
|
427 @node Customizing SES, , Copy/cut/paste, The Basics
|
|
428 @section Customizing SES
|
60140
|
429 @cindex customizing
|
|
430 @vindex enable-local-eval
|
|
431 @vindex ses-mode-hook
|
|
432 @vindex safe-functions
|
|
433 @vindex enable-local-eval
|
|
434
|
47667
|
435
|
|
436 By default, a newly-created spreadsheet has 1 row and 1 column. The
|
|
437 column width is 7 and the default printer is @samp{"%.7g"}. Each of these
|
|
438 can be customized. Look in group ``ses''.
|
|
439
|
|
440 After entering a cell value, point normally moves right to the next
|
|
441 cell. You can customize @code{ses-after-entry-functions} to move left or
|
|
442 up or down. For diagonal movement, select two functions from the
|
|
443 list.
|
|
444
|
|
445 @code{ses-mode-hook} is a normal mode hook (list of functions to
|
|
446 execute when starting SES mode for a buffer).
|
|
447
|
54771
|
448 The variable @code{safe-functions} is a list of possibly-unsafe
|
47667
|
449 functions to be treated as safe when analysing formulas and printers.
|
|
450 @xref{Virus protection}. Before customizing @code{safe-functions},
|
|
451 think about how much you trust the person who's suggesting this
|
54771
|
452 change. The value @code{t} turns off all anti-virus protection. A
|
47667
|
453 list-of-functions value might enable a ``gee whiz'' spreadsheet, but it
|
|
454 also creates trapdoors in your anti-virus armor. In order for virus
|
|
455 protection to work, you must always press @kbd{n} when presented with
|
|
456 a virus warning, unless you understand what the questionable code is
|
|
457 trying to do. Do not listen to those who tell you to customize
|
|
458 @code{enable-local-eval}---this variable is for people who don't wear
|
|
459 safety belts!
|
|
460
|
|
461
|
|
462 @c ===================================================================
|
|
463
|
|
464 @node Advanced Features, For Gurus, The Basics, Top
|
|
465 @chapter Advanced Features
|
60140
|
466 @cindex advanced features
|
|
467 @findex ses-read-header-row
|
|
468
|
47667
|
469
|
|
470 @table @kbd
|
|
471 @item C-c M-C-h
|
53945
|
472 (@code{ses-set-header-row}). The header line at the top of the SES
|
47667
|
473 window normally shows the column letter for each column. You can set
|
|
474 it to show a copy of some row, such as a row of column titles, so that
|
53945
|
475 row will always be visible. Default is to set the current row as the
|
|
476 header; use C-u to prompt for header row. Set the header to row 0 to
|
|
477 show column letters again.
|
|
478 @item [header-line mouse-3]
|
|
479 Pops up a menu to set the current row as the header, or revert to
|
|
480 column letters.
|
47667
|
481 @end table
|
|
482
|
|
483 @menu
|
|
484 * The print area::
|
|
485 * Ranges in formulas::
|
|
486 * Sorting by column::
|
|
487 * Standard formula functions::
|
|
488 * More on cell printing::
|
|
489 * Import and export::
|
|
490 * Virus protection::
|
|
491 * Spreadsheets with details and summary::
|
|
492 @end menu
|
|
493
|
|
494 @node The print area, Ranges in formulas, Advanced Features, Advanced Features
|
|
495 @section The print area
|
60140
|
496 @cindex print area
|
|
497 @findex widen
|
|
498 @findex ses-renarrow-buffer
|
|
499 @findex ses-reprint-all
|
47667
|
500
|
|
501 A SES file consists of a print area and a data area. Normally the
|
|
502 buffer is narrowed to show only the print area. The print area is
|
|
503 read-only except for special SES commands; it contains cell values
|
|
504 formatted by printer functions. The data area records the formula and
|
|
505 printer functions, etc.
|
|
506
|
|
507 @table @kbd
|
|
508 @item C-x n w
|
|
509 Show print and data areas (@code{widen}).
|
|
510
|
47668
bcc91f26d220
Fix Texinfo build failure by running `texinfo-all-menus-update'.
Robert J. Chassell <bob@rattlesnake.com>
diff
changeset
|
511 @item C-c C-n
|
47667
|
512 Show only print area (@code{ses-renarrow-buffer}).
|
|
513
|
|
514 @item S-C-l
|
|
515 @itemx M-C-l
|
|
516 Recreate print area by reevaluating printer functions for all cells
|
|
517 (@code{ses-reprint-all}).
|
|
518 @end table
|
|
519
|
|
520 @node Ranges in formulas, Sorting by column, The print area, Advanced Features
|
|
521 @section Ranges in formulas
|
60140
|
522 @cindex ranges
|
|
523 @findex ses-insert-range-click
|
|
524 @findex ses-insert-range
|
|
525 @findex ses-insert-ses-range-click
|
|
526 @findex ses-insert-ses-range
|
|
527 @vindex from
|
|
528 @vindex to
|
47667
|
529
|
|
530 A formula like
|
|
531 @lisp
|
|
532 (+ A1 A2 A3)
|
|
533 @end lisp
|
|
534 is the sum of three specific cells. If you insert a new second row,
|
|
535 the formula becomes
|
|
536 @lisp
|
|
537 (+ A1 A3 A4)
|
|
538 @end lisp
|
|
539 and the new row is not included in the sum.
|
|
540
|
65220
|
541 The macro @code{(ses-range @var{from} @var{to})} evaluates to a list of
|
47667
|
542 the values in a rectangle of cells. If your formula is
|
|
543 @lisp
|
|
544 (apply '+ (ses-range A1 A3))
|
|
545 @end lisp
|
|
546 and you insert a new second row, it becomes
|
|
547 @lisp
|
|
548 (apply '+ (ses-range A1 A4))
|
|
549 @end lisp
|
|
550 and the new row is included in the sum.
|
|
551
|
|
552 While entering or editing a formula in the minibuffer, you can select
|
|
553 a range in the spreadsheet (using mouse or keyboard), then paste a
|
|
554 representation of that range into your formula. Suppose you select
|
|
555 A1-C1:
|
|
556
|
|
557 @table @kbd
|
|
558 @item [S-mouse-3]
|
|
559 Inserts "A1 B1 C1" @code{(ses-insert-range-click})
|
|
560
|
|
561 @item C-c C-r
|
|
562 Keyboard version (@code{ses-insert-range}).
|
|
563
|
|
564 @item [C-S-mouse-3]
|
|
565 Inserts "(ses-range A1 C1)" (@code{ses-insert-ses-range-click}).
|
|
566
|
|
567 @item C-c C-s
|
|
568 Keyboard version (@code{ses-insert-ses-range}).
|
|
569 @end table
|
|
570
|
|
571 If you delete the @var{from} or @var{to} cell for a range, the nearest
|
|
572 still-existing cell is used instead. If you delete the entire range,
|
|
573 the formula relocator will delete the ses-range from the formula.
|
|
574
|
|
575 If you insert a new row just beyond the end of a one-column range, or
|
|
576 a new column just beyond a one-row range, the new cell is included in
|
|
577 the range. New cells inserted just before a range are not included.
|
|
578
|
|
579
|
|
580 @node Sorting by column, Standard formula functions, Ranges in formulas, Advanced Features
|
|
581 @section Sorting by column
|
60140
|
582 @cindex sorting
|
|
583 @findex ses-sort-column
|
|
584 @findex ses-sort-column-click
|
47667
|
585
|
|
586 @table @kbd
|
|
587 @item C-c M-C-s
|
|
588 Sort the cells of a range using one of the columns
|
|
589 (@code{ses-sort-column}). The rows (or partial rows if the range
|
|
590 doesn't include all columns) are rearranged so the chosen column will
|
|
591 be in order.
|
|
592
|
|
593 @item [header-line mouse-2]
|
|
594 The easiest way to sort is to click mouse-2 on the chosen column's header row
|
|
595 (@code{ses-sort-column-click}).
|
|
596 @end table
|
|
597
|
|
598 The sort comparison uses @code{string<}, which works well for
|
|
599 right-justified numbers and left-justified strings.
|
|
600
|
|
601 With prefix arg, sort is in descending order.
|
|
602
|
|
603 Rows are moved one at a time, with relocation of formulas. This works
|
|
604 well if formulas refer to other cells in their row, not so well for
|
|
605 formulas that refer to other rows in the range or to cells outside the
|
|
606 range.
|
|
607
|
|
608
|
|
609 @node Standard formula functions, More on cell printing, Sorting by column, Advanced Features
|
|
610 @section Standard formula functions
|
60140
|
611 @cindex standard formula functions
|
|
612 @cindex *skip*
|
|
613 @cindex *error*
|
|
614 @findex ses-delete-blanks
|
|
615 @findex ses-average
|
|
616 @findex ses+
|
47667
|
617
|
|
618 Oftentimes you want a calculation to exclude the blank cells. Here
|
|
619 are some useful functions to call from your formulas:
|
|
620
|
|
621 @table @code
|
|
622 @item (ses-delete-blanks &rest @var{args})
|
56279
|
623 Returns a list from which all blank cells (value is either @code{nil} or
|
47667
|
624 '*skip*) have been deleted.
|
|
625
|
|
626 @item (ses+ &rest @var{args})
|
|
627 Sum of non-blank arguments.
|
|
628
|
|
629 @item (ses-average @var{list})
|
|
630 Average of non-blank elements in @var{list}. Here the list is passed
|
|
631 as a single argument, since you'll probably use it with @code{ses-range}.
|
|
632 @end table
|
|
633
|
|
634 @node More on cell printing, Import and export, Standard formula functions, Advanced Features
|
|
635 @section More on cell printing
|
60140
|
636 @cindex cell printing, more
|
|
637 @findex ses-truncate-cell
|
|
638 @findex ses-recalculate-cell
|
47667
|
639
|
|
640 Special cell values:
|
|
641 @itemize
|
|
642 @item nil prints the same as "", but allows previous cell to spill over.
|
|
643 @item '*skip* replaces nil when the previous cell actually does spill over;
|
|
644 nothing is printed for it.
|
63612
|
645 @item '*error* indicates that the formula signaled an error instead of
|
47667
|
646 producing a value: the print cell is filled with hash marks (#).
|
|
647 @end itemize
|
|
648
|
|
649 If the result from the printer function is too wide for the cell and
|
56279
|
650 the following cell is @code{nil}, the result will spill over into the
|
47667
|
651 following cell. Very wide results can spill over several cells. If
|
|
652 the result is too wide for the available space (up to the end of the
|
56279
|
653 row or the next non-@code{nil} cell), the result is truncated if the cell's
|
47667
|
654 value is a string, or replaced with hash marks otherwise.
|
|
655
|
|
656 SES could get confused by printer results that contain newlines or
|
|
657 tabs, so these are replaced with question marks.
|
|
658
|
|
659 @table @kbd
|
|
660 @item C-c C-t
|
|
661 Confine a cell to its own column (@code{ses-truncate-cell}). This
|
65220
|
662 allows you to move point to a rightward cell that would otherwise be
|
47667
|
663 covered by a spill-over. If you don't change the rightward cell, the
|
|
664 confined cell will spill over again the next time it is reprinted.
|
|
665
|
|
666 @item C-c C-c
|
|
667 When applied to a single cell, this command displays in the echo area any
|
|
668 formula error or printer error that occurred during
|
|
669 recalculation/reprinting (@code{ses-recalculate-cell}).
|
|
670 @end table
|
|
671
|
|
672 When a printer function signals an error, the default printer
|
|
673 @samp{"%s"} is substituted. This is useful when your column printer
|
|
674 is numeric-only and you use a string as a cell value.
|
|
675
|
|
676
|
|
677 @node Import and export, Virus protection, More on cell printing, Advanced Features
|
|
678 @section Import and export
|
60140
|
679 @cindex import and export
|
|
680 @cindex export, and import
|
|
681 @findex ses-export-tsv
|
|
682 @findex ses-export-tsf
|
47667
|
683
|
|
684 @table @kbd
|
|
685 @item x t
|
|
686 Export a range of cells as tab-separated values (@code{ses-export-tsv}).
|
|
687 @item x T
|
|
688 Export a range of cells as tab-separated formulas (@code{ses-export-tsf}).
|
|
689 @end table
|
|
690
|
|
691 The exported text goes to the kill ring --- you can paste it into
|
|
692 another buffer. Columns are separated by tabs, rows by newlines.
|
|
693
|
|
694 To import text, use any of the yank commands where the text to paste
|
|
695 contains tabs and/or newlines. Imported formulas are not relocated.
|
|
696
|
|
697 @node Virus protection, Spreadsheets with details and summary, Import and export, Advanced Features
|
|
698 @section Virus protection
|
60140
|
699 @cindex virus protection
|
47667
|
700
|
|
701 Whenever a formula or printer is read from a file or is pasted into
|
|
702 the spreadsheet, it receives a ``needs safety check'' marking. Later,
|
|
703 when the formula or printer is evaluated for the first time, it is
|
|
704 checked for safety using the @code{unsafep} predicate; if found to be
|
|
705 ``possibly unsafe'', the questionable formula or printer is displayed
|
|
706 and you must press Y to approve it or N to use a substitute. The
|
|
707 substitute always signals an error.
|
|
708
|
|
709 Formulas or printers that you type in are checked immediately for
|
|
710 safety. If found to be possibly unsafe and you press N to disapprove,
|
65220
|
711 the action is canceled and the old formula or printer will remain.
|
47667
|
712
|
|
713 Besides viruses (which try to copy themselves to other files),
|
|
714 @code{unsafep} can also detect all other kinds of Trojan horses, such as
|
|
715 spreadsheets that delete files, send email, flood Web sites, alter
|
|
716 your Emacs settings, etc.
|
|
717
|
|
718 Generally, spreadsheet formulas and printers are simple things that
|
|
719 don't need to do any fancy computing, so all potentially-dangerous
|
|
720 parts of the Emacs Lisp environment can be excluded without cramping
|
|
721 your style as a formula-writer. See the documentation in @file{unsafep.el}
|
|
722 for more info on how Lisp forms are classified as safe or unsafe.
|
|
723
|
|
724 @node Spreadsheets with details and summary, , Virus protection, Advanced Features
|
|
725 @section Spreadsheets with details and summary
|
60140
|
726 @cindex details and summary
|
|
727 @cindex summary, and details
|
47667
|
728
|
|
729 A common organization for spreadsheets is to have a bunch of ``detail''
|
|
730 rows, each perhaps describing a transaction, and then a set of
|
|
731 ``summary'' rows that each show reduced data for some subset of the
|
|
732 details. SES supports this organization via the @code{ses-select}
|
|
733 function.
|
|
734
|
|
735 @table @code
|
|
736 @item (ses-select @var{fromrange} @var{test} @var{torange})
|
|
737 Returns a subset of @var{torange}. For each member in @var{fromrange}
|
|
738 that is equal to @var{test}, the corresponding member of @var{torange}
|
|
739 is included in the result.
|
|
740 @end table
|
|
741
|
|
742 Example of use:
|
|
743 @lisp
|
|
744 (ses-average (ses-select (ses-range A1 A5) 'Smith (ses-range B1 B5)))
|
|
745 @end lisp
|
|
746 This computes the average of the B column values for those rows whose
|
|
747 A column value is the symbol 'Smith.
|
|
748
|
|
749 Arguably one could specify only @var{fromrange} plus
|
|
750 @var{to-row-offset} and @var{to-column-offset}. The @var{torange} is
|
|
751 stated explicitly to ensure that the formula will be recalculated if
|
|
752 any cell in either range is changed.
|
|
753
|
|
754 File @file{etc/ses-example.el} in the Emacs distribution is an example of a
|
|
755 details-and-summary spreadsheet.
|
|
756
|
|
757
|
|
758 @c ===================================================================
|
|
759
|
60140
|
760 @node For Gurus, Index, Advanced Features, Top
|
47667
|
761 @chapter For Gurus
|
60140
|
762 @cindex advanced features
|
47667
|
763
|
|
764 @menu
|
|
765 * Deferred updates::
|
|
766 * Nonrelocatable references::
|
|
767 * The data area::
|
|
768 * Buffer-local variables in spreadsheets::
|
|
769 * Uses of defadvice in SES::
|
|
770 @end menu
|
|
771
|
|
772 @node Deferred updates, Nonrelocatable references, For Gurus, For Gurus
|
|
773 @section Deferred updates
|
60140
|
774 @cindex deferred updates
|
|
775 @cindex updates, deferred
|
|
776 @vindex run-with-idle-timer
|
47667
|
777
|
|
778 To save time by avoiding redundant computations, cells that need
|
|
779 recalculation due to changes in other cells are added to a set. At
|
|
780 the end of the command, each cell in the set is recalculated once.
|
|
781 This can create a new set of cells that need recalculation. The
|
|
782 process is repeated until either the set is empty or it stops changing
|
|
783 (due to circular references among the cells). In extreme cases, you
|
|
784 might see progress messages of the form ``Recalculating... (@var{nnn}
|
|
785 cells left)''. If you interrupt the calculation using @kbd{C-g}, the
|
|
786 spreadsheet will be left in an inconsistent state, so use @kbd{C-_} or
|
|
787 @kbd{C-c C-l} to fix it.
|
|
788
|
|
789 To save even more time by avoiding redundant writes, cells that have
|
|
790 changes are added to a set instead of being written immediately to the
|
|
791 data area. Each cell in the set is written once, at the end of the
|
|
792 command. If you change vast quantities of cells, you might see a
|
|
793 progress message of the form ``Writing... (@var{nnn} cells left)''.
|
|
794 These deferred cell-writes cannot be interrupted by @kbd{C-g}, so
|
|
795 you'll just have to wait.
|
|
796
|
|
797 SES uses @code{run-with-idle-timer} to move the cell underline when
|
|
798 Emacs will be scrolling the buffer after the end of a command, and
|
|
799 also to narrow and underline after @kbd{C-x C-v}. This is visible as
|
|
800 a momentary glitch after C-x C-v and certain scrolling commands. You
|
|
801 can type ahead without worrying about the glitch.
|
|
802
|
|
803
|
|
804 @node Nonrelocatable references, The data area, Deferred updates, For Gurus
|
|
805 @section Nonrelocatable references
|
60140
|
806 @cindex nonrelocatable references
|
|
807 @cindex references, nonrelocatable
|
47667
|
808
|
|
809 @kbd{C-y} relocates all cell-references in a pasted formula, while
|
|
810 @kbd{C-u C-y} relocates none of the cell-references. What about mixed
|
|
811 cases?
|
|
812
|
|
813 You can use
|
|
814 @lisp
|
|
815 (symbol-value 'B3)
|
|
816 @end lisp
|
|
817 to make an @dfn{absolute reference}. The formula relocator skips over
|
|
818 quoted things, so this will not be relocated when pasted or when
|
|
819 rows/columns are inserted/deleted. However, B3 will not be recorded
|
|
820 as a dependency of this cell, so this cell will not be updated
|
|
821 automatically when B3 is changed.
|
|
822
|
|
823 The variables @code{row} and @code{col} are dynamically bound while a
|
|
824 cell formula is being evaluated. You can use
|
|
825 @lisp
|
|
826 (ses-cell-value row 0)
|
|
827 @end lisp
|
|
828 to get the value from the leftmost column in the current row. This
|
|
829 kind of dependency is also not recorded.
|
|
830
|
|
831
|
|
832 @node The data area, Buffer-local variables in spreadsheets, Nonrelocatable references, For Gurus
|
|
833 @section The data area
|
60140
|
834 @cindex data area
|
|
835 @findex ses-reconstruct-all
|
47667
|
836
|
|
837 Begins with an 014 character, followed by sets of cell-definition
|
|
838 macros for each row, followed by column-widths, column-printers,
|
|
839 default-printer, and header-row. Then there's the global parameters
|
|
840 (file-format ID, numrows, numcols) and the local variables (specifying
|
|
841 SES mode for the buffer, etc.)
|
|
842
|
|
843 When a SES file is loaded, first the numrows and numcols values are
|
|
844 loaded, then the entire data area is @code{eval}ed, and finally the local
|
|
845 variables are processed.
|
|
846
|
|
847 You can edit the data area, but don't insert or delete any newlines
|
|
848 except in the local-variables part, since SES locates things by
|
|
849 counting newlines. Use @kbd{C-x C-e} at the end of a line to install
|
|
850 your edits into the spreadsheet data structures (this does not update
|
|
851 the print area, use e.g. @kbd{C-c C-l} for that).
|
|
852
|
|
853 The data area is maintained as an image of spreadsheet data
|
|
854 structures that area stored in buffer-local variables. If the data
|
|
855 area gets messed up, you can try reconstructing the data area from the
|
|
856 data structures:
|
|
857
|
|
858 @table @kbd
|
|
859 @item C-c M-C-l
|
|
860 (@code{ses-reconstruct-all}).
|
|
861 @end table
|
|
862
|
|
863
|
|
864 @node Buffer-local variables in spreadsheets, Uses of defadvice in SES, The data area, For Gurus
|
|
865 @section Buffer-local variables in spreadsheets
|
60140
|
866 @cindex buffer-local variables
|
|
867 @cindex variables, buffer-local
|
47667
|
868
|
|
869 You can add additional local variables to the list at the bottom of
|
|
870 the data area, such as hidden constants you want to refer to in your
|
|
871 formulas.
|
|
872
|
|
873 You can override the variable @code{symbolic-formulas} to be a list of
|
|
874 symbols (as parenthesized strings) to show as completions for the '
|
|
875 command. This initial completions list is used instead of the actual
|
|
876 set of symbols-as-formulas in the spreadsheet.
|
|
877
|
|
878 For examples of these, see file @file{etc/ses-example.ses}.
|
|
879
|
|
880 If (for some reason) you want your formulas or printers to save data
|
|
881 into variables, you must declare these variables as buffer-locals in
|
|
882 order to avoid a virus warning.
|
|
883
|
|
884 You can define functions by making them values for the fake local
|
|
885 variable @code{eval}. Such functions can then be used in your
|
|
886 formulas and printers, but usually each @code{eval} is presented to
|
|
887 the user during file loading as a potential virus --- this can get
|
|
888 annoying.
|
|
889
|
|
890 You can define functions in your @file{.emacs} file. Other people can
|
|
891 still read the print area of your spreadsheet, but they won't be able
|
|
892 to recalculate or reprint anything that depends on your functions. To
|
|
893 avoid virus warnings, each function used in a formula needs
|
|
894 @lisp
|
|
895 (put 'your-function-name 'safe-function t)
|
|
896 @end lisp
|
|
897
|
|
898 @node Uses of defadvice in SES, , Buffer-local variables in spreadsheets, For Gurus
|
|
899 @section Uses of defadvice in SES
|
60140
|
900 @cindex defadvice
|
|
901 @cindex undo-more
|
|
902 @cindex copy-region-as-kill
|
|
903 @cindex yank
|
47667
|
904
|
|
905 @table @code
|
|
906 @item undo-more
|
|
907 Defines a new undo element format (@var{fun} . @var{args}), which
|
|
908 means ``undo by applying @var{fun} to @var{args}''. For spreadsheet
|
|
909 buffers, it allows undos in the data area even though that's outside
|
|
910 the narrowing.
|
|
911
|
|
912 @item copy-region-as-kill
|
|
913 When copying from the print area of a spreadsheet, treat the region as
|
|
914 a rectangle and attach each cell's formula and printer as 'ses
|
|
915 properties.
|
|
916
|
|
917 @item yank
|
|
918 When yanking into the print area of a spreadsheet, first try to yank
|
|
919 as cells (if the yank text has 'ses properties), then as tab-separated
|
|
920 formulas, then (if all else fails) as a single formula for the current
|
|
921 cell.
|
|
922 @end table
|
|
923
|
60140
|
924 @c ===================================================================
|
|
925 @node Index, Acknowledgements, For Gurus, Top
|
65220
|
926 @unnumbered Index
|
60140
|
927
|
|
928 @printindex cp
|
|
929
|
47667
|
930 @c ===================================================================
|
|
931
|
60140
|
932 @node Acknowledgements, , Index, Top
|
47667
|
933 @chapter Acknowledgements
|
|
934
|
53945
|
935 Coding by:
|
|
936 @quotation
|
|
937 Jonathan Yavner @email{jyavner@@member.fsf.org}@*
|
|
938 Stefan Monnier @email{monnier@@gnu.org}
|
|
939 @end quotation
|
|
940
|
60140
|
941 @noindent
|
|
942 Texinfo manual by:
|
|
943 @quotation
|
|
944 Jonathan Yavner @email{jyavner@@member.fsf.org}@*
|
|
945 Brad Collins <brad@@chenla.org>
|
|
946 @end quotation
|
|
947
|
|
948 @noindent
|
53945
|
949 Ideas from:
|
47667
|
950 @quotation
|
|
951 Christoph Conrad @email{christoph.conrad@@gmx.de}@*
|
|
952 CyberBob @email{cyberbob@@redneck.gacracker.org}@*
|
|
953 Syver Enstad @email{syver-en@@online.no}@*
|
|
954 Ami Fischman @email{fischman@@zion.bpnetworks.com}@*
|
|
955 Thomas Gehrlein @email{Thomas.Gehrlein@@t-online.de}@*
|
|
956 Chris F.A. Johnson @email{c.f.a.johnson@@rogers.com}@*
|
|
957 Yusong Li @email{lyusong@@hotmail.com}@*
|
54477
|
958 Juri Linkov @email{juri@@jurta.org}@*
|
47667
|
959 Harald Maier @email{maierh@@myself.com}@*
|
|
960 Alan Nash @email{anash@@san.rr.com}@*
|
|
961 Fran�ois Pinard @email{pinard@@iro.umontreal.ca}@*
|
|
962 Pedro Pinto @email{ppinto@@cs.cmu.edu}@*
|
|
963 Stefan Reich�r @email{xsteve@@riic.at}@*
|
|
964 Oliver Scholz @email{epameinondas@@gmx.de}@*
|
|
965 Richard M. Stallman @email{rms@@gnu.org}@*
|
53945
|
966 Luc Teirlinck @email{teirllm@@dms.auburn.edu}@*
|
47667
|
967 J. Otto Tennant @email{jotto@@pobox.com}@*
|
|
968 Jean-Philippe Theberge @email{jphil@@acs.pagesjaunes.fr}
|
|
969 @end quotation
|
|
970
|
|
971 @c ===================================================================
|
|
972
|
|
973 @bye
|
52401
|
974
|
|
975 @ignore
|
|
976 arch-tag: 10a4ee1c-7ef4-4c06-8b7a-f975e39f0dec
|
|
977 @end ignore
|