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