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