\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename ../../info/ses
-@settitle SES: Simple Emacs Spreadsheet
+@settitle @acronym{SES}: Simple Emacs Spreadsheet
@setchapternewpage off
@syncodeindex fn cp
@syncodeindex vr cp
@c %**end of header
@copying
-This file documents SES: the Simple Emacs Spreadsheet.
+This file documents @acronym{SES}: the Simple Emacs Spreadsheet.
Copyright @copyright{} 2002--2013 Free Software Foundation, Inc.
@dircategory Emacs misc features
@direntry
-* SES: (ses). Simple Emacs Spreadsheet.
+* @acronym{SES}: (ses). Simple Emacs Spreadsheet.
@end direntry
@finalout
@titlepage
-@title SES
+@title @acronym{SES}
@subtitle Simple Emacs Spreadsheet
@author Jonathan A. Yavner
@author @email{jyavner@@member.fsf.org}
@c ===================================================================
@ifnottex
-@node Top, Sales Pitch, (dir), (dir)
+@node Top
@comment node-name, next, previous, up
-@top SES: Simple Emacs Spreadsheet
+@top @acronym{SES}: Simple Emacs Spreadsheet
@display
-SES is a major mode for GNU Emacs to edit spreadsheet files, which
+@acronym{SES} is a major mode for GNU Emacs to edit spreadsheet files, which
contain a rectangular grid of cells. The cells' values are specified
by formulas that can refer to the values of other cells.
@end display
@insertcopying
@menu
-* Sales Pitch:: Why use SES?
+* Sales Pitch:: Why use @acronym{SES}?
* The Basics:: Basic spreadsheet commands
* Advanced Features:: Want to know more?
* For Gurus:: Want to know @emph{even more}?
@c ===================================================================
-@node Sales Pitch, The Basics, Top, Top
+@node Sales Pitch
@comment node-name, next, previous, up
@chapter Sales Pitch
@cindex features
@c ===================================================================
-@node The Basics, Advanced Features, Sales Pitch, Top
+@node The Basics
@comment node-name, next, previous, up
@chapter The Basics
@cindex basic commands
Point is always at the left edge of a cell, or at the empty endline.
When mark is inactive, the current cell is underlined. When mark is
-active, the range is the highlighted rectangle of cells (SES always
+active, the range is the highlighted rectangle of cells (@acronym{SES} always
uses transient mark mode). Drag the mouse from A1 to A3 to create the
-range A1-A2. Many SES commands operate only on single cells, not
+range A1-A2. Many @acronym{SES} commands operate only on single cells, not
ranges.
@table @kbd
* Printer functions::
* Clearing cells::
* Copy/cut/paste::
-* Customizing SES::
+* Customizing @acronym{SES}::
@end menu
-@node Formulas, Resizing, The Basics, The Basics
+@node Formulas
@section Cell formulas
@cindex formulas
@cindex formulas, entering
expression, you can use @kbd{M-@key{TAB}} to complete symbol names.
@item ' @r{(apostrophe)}
-Enter a symbol (ses-read-symbol). SES remembers all symbols that have
+Enter a symbol (ses-read-symbol). @acronym{SES} remembers all symbols that have
been used as formulas, so you can type just the beginning of a symbol
and use @kbd{@key{SPC}}, @kbd{@key{TAB}}, and @kbd{?} to complete it.
@end table
Recalculate the entire spreadsheet (@code{ses-recalculate-all}).
@end table
-@node Resizing, Printer functions, Formulas, The Basics
+@node Resizing
@section Resizing the spreadsheet
@cindex resizing spreadsheets
@findex ses-insert-row
@end table
-@node Printer functions, Clearing cells, Resizing, The Basics
+@node Printer functions
@section Printer functions
@cindex printer functions
@findex ses-read-cell-printer
@end table
-@node Clearing cells, Copy/cut/paste, Printer functions, The Basics
+@node Clearing cells
@section Clearing cells
@cindex clearing commands
@findex ses-clear-cell-backward
@end table
-@node Copy/cut/paste, Customizing SES, Clearing cells, The Basics
+@node Copy/cut/paste
@section Copy, cut, and paste
@cindex copy
@cindex cut
@findex ses-yank-pop
The copy functions work on rectangular regions of cells. You can paste the
-copies into non-SES buffers to export the print text.
+copies into non-@acronym{SES} buffers to export the print text.
@table @kbd
@item M-w
differently depending on the format of the text being inserted:
@itemize @bullet
@item
-When pasting cells that were cut from a SES buffer, the print text is
+When pasting cells that were cut from a @acronym{SES} buffer, the print text is
ignored and only the attached formula and printer are inserted; cell
references in the formula are relocated unless you use @kbd{C-u}.
@item
is the current cell. If part of the rectangle is beyond the edges of
the spreadsheet, you must confirm the increase in spreadsheet size.
@item
-Non-SES text is usually inserted as a replacement formula for the
+Non-@acronym{SES} text is usually inserted as a replacement formula for the
current cell. If the formula would be a symbol, it's treated as a
string unless you use @kbd{C-u}. Pasted formulas with syntax errors
are always treated as strings.
@item M-y
Immediately after a paste, you can replace the text with a preceding
element from the kill ring (@code{ses-yank-pop}). Unlike the standard
-Emacs yank-pop, the SES version uses @code{undo} to delete the old
+Emacs yank-pop, the @acronym{SES} version uses @code{undo} to delete the old
yank. This doesn't make any difference?
@end table
-@node Customizing SES, , Copy/cut/paste, The Basics
-@section Customizing SES
+@node Customizing @acronym{SES}
+@section Customizing @acronym{SES}
@cindex customizing
@vindex enable-local-eval
@vindex ses-mode-hook
list.
@code{ses-mode-hook} is a normal mode hook (list of functions to
-execute when starting SES mode for a buffer).
+execute when starting @acronym{SES} mode for a buffer).
The variable @code{safe-functions} is a list of possibly-unsafe
functions to be treated as safe when analyzing formulas and printers.
@c ===================================================================
-@node Advanced Features, For Gurus, The Basics, Top
+@node Advanced Features
@chapter Advanced Features
@cindex advanced features
@findex ses-read-header-row
@table @kbd
@item C-c M-C-h
-(@code{ses-set-header-row}). The header line at the top of the SES
+(@code{ses-set-header-row}).
+@findex ses-set-header-row
+@kindex C-c M-C-h
+The header line at the top of the @acronym{SES}
window normally shows the column letter for each column. You can set
it to show a copy of some row, such as a row of column titles, so that
row will always be visible. Default is to set the current row as the
@item [header-line mouse-3]
Pops up a menu to set the current row as the header, or revert to
column letters.
+@item M-x ses-rename-cell
+@findex ses-rename-cell
+Rename a cell from a standard A1-like name to any
+string.
+@item M-x ses-repair-cell-reference-all
+@findex ses-repair-cell-reference-all
+When you interrupt a cell formula update by clicking @kbd{C-g}, then
+the cell reference link may be broken, which will jeopardize automatic
+cell update when any other cell on which it depends is changed. To
+repair that use function @code{ses-repair-cell-reference-all}
@end table
@menu
* Spreadsheets with details and summary::
@end menu
-@node The print area, Ranges in formulas, Advanced Features, Advanced Features
+@node The print area
@section The print area
@cindex print area
@findex widen
@findex ses-renarrow-buffer
@findex ses-reprint-all
-A SES file consists of a print area and a data area. Normally the
+A @acronym{SES} file consists of a print area and a data area. Normally the
buffer is narrowed to show only the print area. The print area is
-read-only except for special SES commands; it contains cell values
+read-only except for special @acronym{SES} commands; it contains cell values
formatted by printer functions. The data area records the formula and
printer functions, etc.
(@code{ses-reprint-all}).
@end table
-@node Ranges in formulas, Sorting by column, The print area, Advanced Features
+@node Ranges in formulas
@section Ranges in formulas
@cindex ranges
@findex ses-insert-range-click
a new column just beyond a one-row range, the new cell is included in
the range. New cells inserted just before a range are not included.
+Flags can be added to @code{ses-range} immediately after the @var{to}
+cell.
+@table @code
+@item !
+Empty cells in range can be removed by adding the @code{!} flag. An
+empty cell is a cell the value of which is one of symbols @code{nil}
+or @code{*skip*}. For instance @code{(ses-range A1 A4 !)} will do the
+same as @code{(list A1 A3)} when cells @code{A2} and @code{A4} are
+empty.
+@item _
+Empty cell values are replaced by the argument following flag
+@code{_}, or @code{0} when flag @code{_} is last in argument list. For
+instance @code{(ses-range A1 A4 _ "empty")} will do the same as
+@code{(list A1 "empty" A3 "empty")} when cells @code{A2} and @code{A4}
+are empty. Similarly, @code{(ses-range A1 A4 _ )} will do the same as
+@code{(list A1 0 A3 0)}.
+@item >v
+When order matters, list cells by reading cells row-wise from top left
+to bottom right. This flag is provided for completeness only as it is
+the default reading order.
+@item <v
+List cells by reading cells row-wise from top right to bottom left.
+@item v>
+List cells by reading cells column-wise from top left to bottom right.
+@item v<
+List cells by reading cells column-wise from top right to bottom left.
+@item v
+A short hand for @code{v>}.
+@item ^
+A short hand for @code{^>}.
+@item >
+A short hand for @code{>v}.
+@item <
+A short hand for @code{>^}.
+@item *
+Instead of listing cells, it makes a Calc vector or matrix of it
+(@pxref{Top,,,calc,GNU Emacs Calc Manual}). If the range contains only
+one row or one column a vector is made, otherwise a matrix is made.
+@item *2
+Same as @code{*} except that a matrix is always made even when there
+is only one row or column in the range.
+@item *1
+Same as @code{*} except that a vector is always made even when there
+is only one row or column in the range, that is to say the
+corresponding matrix is flattened.
+@end table
-@node Sorting by column, Standard formula functions, Ranges in formulas, Advanced Features
+@node Sorting by column
@section Sorting by column
@cindex sorting
@findex ses-sort-column
range.
-@node Standard formula functions, More on cell printing, Sorting by column, Advanced Features
+@node Standard formula functions
@section Standard formula functions
@cindex standard formula functions
@cindex *skip*
as a single argument, since you'll probably use it with @code{ses-range}.
@end table
-@node More on cell printing, Import and export, Standard formula functions, Advanced Features
+@node More on cell printing
@section More on cell printing
@cindex cell printing, more
@findex ses-truncate-cell
row or the next non-@code{nil} cell), the result is truncated if the cell's
value is a string, or replaced with hash marks otherwise.
-SES could get confused by printer results that contain newlines or
+@acronym{SES} could get confused by printer results that contain newlines or
tabs, so these are replaced with question marks.
@table @kbd
argument type''.
-@node Import and export, Virus protection, More on cell printing, Advanced Features
+@node Import and export
@section Import and export
@cindex import and export
@cindex export, and import
To import text, use any of the yank commands where the text to paste
contains tabs and/or newlines. Imported formulas are not relocated.
-@node Virus protection, Spreadsheets with details and summary, Import and export, Advanced Features
+@node Virus protection
@section Virus protection
@cindex virus protection
your style as a formula-writer. See the documentation in @file{unsafep.el}
for more info on how Lisp forms are classified as safe or unsafe.
-@node Spreadsheets with details and summary, , Virus protection, Advanced Features
+@node Spreadsheets with details and summary
@section Spreadsheets with details and summary
@cindex details and summary
@cindex summary, and details
A common organization for spreadsheets is to have a bunch of ``detail''
rows, each perhaps describing a transaction, and then a set of
``summary'' rows that each show reduced data for some subset of the
-details. SES supports this organization via the @code{ses-select}
+details. @acronym{SES} supports this organization via the @code{ses-select}
function.
@table @code
@c ===================================================================
-@node For Gurus, Index, Advanced Features, Top
+@node For Gurus
@chapter For Gurus
@cindex advanced features
* Nonrelocatable references::
* The data area::
* Buffer-local variables in spreadsheets::
-* Uses of defadvice in SES::
+* Uses of defadvice in @acronym{SES}::
@end menu
-@node Deferred updates, Nonrelocatable references, For Gurus, For Gurus
+@node Deferred updates
@section Deferred updates
@cindex deferred updates
@cindex updates, deferred
These deferred cell-writes cannot be interrupted by @kbd{C-g}, so
you'll just have to wait.
-SES uses @code{run-with-idle-timer} to move the cell underline when
+@acronym{SES} uses @code{run-with-idle-timer} to move the cell underline when
Emacs will be scrolling the buffer after the end of a command, and
also to narrow and underline after @kbd{C-x C-v}. This is visible as
a momentary glitch after C-x C-v and certain scrolling commands. You
can type ahead without worrying about the glitch.
-@node Nonrelocatable references, The data area, Deferred updates, For Gurus
+@node Nonrelocatable references
@section Nonrelocatable references
@cindex nonrelocatable references
@cindex references, nonrelocatable
kind of dependency is also not recorded.
-@node The data area, Buffer-local variables in spreadsheets, Nonrelocatable references, For Gurus
+@node The data area
@section The data area
@cindex data area
@findex ses-reconstruct-all
macros for each row, followed by column-widths, column-printers,
default-printer, and header-row. Then there's the global parameters
(file-format ID, numrows, numcols) and the local variables (specifying
-SES mode for the buffer, etc.).
+@acronym{SES} mode for the buffer, etc.).
-When a SES file is loaded, first the numrows and numcols values are
+When a @acronym{SES} file is loaded, first the numrows and numcols values are
loaded, then the entire data area is @code{eval}ed, and finally the local
variables are processed.
You can edit the data area, but don't insert or delete any newlines
-except in the local-variables part, since SES locates things by
+except in the local-variables part, since @acronym{SES} locates things by
counting newlines. Use @kbd{C-x C-e} at the end of a line to install
your edits into the spreadsheet data structures (this does not update
the print area, use, e.g., @kbd{C-c C-l} for that).
@end table
-@node Buffer-local variables in spreadsheets, Uses of defadvice in SES, The data area, For Gurus
+@node Buffer-local variables in spreadsheets
@section Buffer-local variables in spreadsheets
@cindex buffer-local variables
@cindex variables, buffer-local
(put 'your-function-name 'safe-function t)
@end lisp
-@node Uses of defadvice in SES, , Buffer-local variables in spreadsheets, For Gurus
-@section Uses of defadvice in SES
+@node Uses of defadvice in @acronym{SES}
+@section Uses of defadvice in @acronym{SES}
@cindex defadvice
@cindex undo-more
@cindex copy-region-as-kill
@end table
@c ===================================================================
-@node Index, Acknowledgments, For Gurus, Top
+@node Index
@unnumbered Index
@printindex cp
@c ===================================================================
-@node Acknowledgments, GNU Free Documentation License, Index, Top
-@chapter Acknowledgments
+@node Acknowledgments
+@unnumbered Acknowledgments
Coding by:
@quotation
@c ===================================================================
-@node GNU Free Documentation License, , Acknowledgments, Top
+@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi