-\input texinfo @c -*-texinfo-*-
+\input texinfo @c -*- mode: texinfo; coding: utf-8; -*-
@c %**start of header
-@setfilename ../../info/ses
+@setfilename ../../info/ses.info
@settitle @acronym{SES}: Simple Emacs Spreadsheet
@setchapternewpage off
@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky cp
+@documentencoding UTF-8
@c %**end of header
@copying
This file documents @acronym{SES}: the Simple Emacs Spreadsheet.
-Copyright @copyright{} 2002-2012 Free Software Foundation, Inc.
+Copyright @copyright{} 2002--2014 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
-Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
+Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below. A copy of the license
is included in the section entitled ``GNU Free Documentation License.''
(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
-modify this GNU manual. Buying copies from the FSF supports it in
-developing GNU and promoting software freedom.''
+modify this GNU manual.''
@end quotation
@end copying
@c ===================================================================
@ifnottex
-@node Top, Sales Pitch, (dir), (dir)
+@node Top
@comment node-name, next, previous, up
@top @acronym{SES}: Simple Emacs Spreadsheet
@end display
@end ifnottex
-To report bugs, send email to @email{jyavner@@member.fsf.org}.
+To report bugs, use @kbd{M-x report-emacs-bug}.
@insertcopying
@menu
* Sales Pitch:: Why use @acronym{SES}?
+* Quick Tutorial:: A quick introduction
* 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 Quick Tutorial
+@chapter Quick Tutorial
+@cindex introduction
+@cindex tutorial
+
+If you want to get started quickly and think that you know what to
+expect from a simple spreadsheet, this chapter may be all that you
+need.
+
+First, visit a new file with the @file{.ses} extension.
+Emacs presents you with an empty spreadsheet containing a single cell.
+
+Begin by inserting a headline: @kbd{"Income"@key{RET}}. The double
+quotes indicate that this is a text cell. (Notice that Emacs
+automatically inserts the closing quotation mark.)
+
+To insert your first income value, you must first resize the
+spreadsheet. Press @key{TAB} to add a new cell and navigate back up
+to it. Enter a number, such as @samp{2.23}. Then proceed to add a
+few more income entries, e.g.:
+
+@example
+@group
+A
+ Income
+ 2.23
+ 0.02
+ 15.76
+ -4.00
+@end group
+@end example
+
+To add up the values, enter a Lisp expression:
+
+@example
+(+ A2 A3 A4 A5)
+@end example
+
+Perhaps you want to add a cell to the right of cell A4 to explain
+why you have a negative entry. Pressing @kbd{TAB} in that cell
+adds an entire new column @samp{B}, where you can add such a note.
+
+The column is fairly narrow by default, but pressing @kbd{w} allows
+you to resize it as needed. Make it 20 characters wide. You can
+now add descriptive legends for all the entries, e.g.:
+
+@example
+@group
+A B
+ Income
+ 2.23 Consulting fee
+ 0.02 Informed opinion
+ 15.76 Lemonade stand
+ -4 Loan to Joe
+ 14.01 Total
+@end group
+@end example
+
+By default, the labels in column B are right-justified. To change
+that, you can enter a printer function for the whole column, using
+e.g., @kbd{M-p ("%s")}. You can override a column's printer function
+in any individual cell using @kbd{p}.
+
+If Joe pays back his loan, you might blank that entry; e.g., by
+positioning the cursor in cell A5 and pressing @kbd{C-d} twice.
+If you do that, the total cell will display @samp{######}. That is
+because the regular @code{+} operator does not handle a range that
+contains some empty cells. Instead of emptying the cell, you could
+enter a literal @samp{0}, or delete the entire row using @kbd{C-k}.
+An alternative is to use the special function @code{ses+} instead of
+the regular @code{+}:
+
+@example
+(ses+ A2 A3 A4 A5)
+@end example
+
+To make a formula robust against changes in the spreadsheet geometry,
+you can use the @code{ses-range} macro to refer to a range of cells by
+the end-points, e.g.:
+
+@example
+(apply 'ses+ (ses-range A2 A5))
+@end example
+
+(The @code{apply} is necessary because @code{ses-range} produces a
+@emph{list} of values. This allows for more complex possibilities.)
+
+@c ===================================================================
+
+@node The Basics
@comment node-name, next, previous, up
@chapter The Basics
@cindex basic commands
number. Cell B7 is the 2nd column of the 7th row. For very wide
spreadsheets, there are two column letters: cell AB7 is the 28th
column of the 7th row. Super wide spreadsheets get AAA1, etc.
+You move around with the regular Emacs movement commands.
@table @kbd
@item j
ranges.
@table @kbd
-@item C-SPC
+@item C-@key{SPC}
@itemx C-@@
Set mark at point (@code{set-mark-command}).
* Customizing @acronym{SES}::
@end menu
-@node Formulas, Resizing, The Basics, The Basics
+@node Formulas
@section Cell formulas
@cindex formulas
@cindex formulas, entering
+@cindex values
+@cindex cell values
+@cindex editing cells
@findex ses-read-cell
@findex ses-read-symbol
@findex ses-edit-cell
@findex ses-recalculate-cell
@findex ses-recalculate-all
-To enter a number into the current cell, just start typing:
+To insert a value into a cell, simply type a numeric expression,
+@samp{"double-quoted text"}, or a Lisp expression.
@table @kbd
@item 0..9
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
+@cindex dimensions
+@cindex row, adding or removing
+@cindex column, adding or removing
+@cindex adding rows or columns
+@cindex inserting rows or columns
+@cindex removing rows or columns
+@cindex deleting rows or columns
@findex ses-insert-row
@findex ses-insert-column
@findex ses-delete-row
@end table
-@node Printer functions, Clearing cells, Resizing, The Basics
+@node Printer functions
@section Printer functions
@cindex printer functions
+@cindex cell formatting
+@cindex formatting cells
@findex ses-read-cell-printer
@findex ses-read-column-printer
@findex ses-read-default-printer
Centering with tildes (~) and spill-over.
@end table
+You can define printer function local to a sheet with command
+@code{ses-define-local-printer}. For instance define printer
+@samp{foo} to @code{"%.2f"} and then use symbol @samp{foo} as a
+printer function. Then, if you call again
+@code{ses-define-local-printer} on @samp{foo} to redefine it as
+@code{"%.3f"} all the cells using printer @samp{foo} will be reprinted
+accordingly.
-@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 @acronym{SES}, Clearing cells, The Basics
+@node Copy/cut/paste
@section Copy, cut, and paste
@cindex copy
@cindex cut
yank. This doesn't make any difference?
@end table
-@node Customizing @acronym{SES}, , Copy/cut/paste, The Basics
+@node Customizing @acronym{SES}
@section Customizing @acronym{SES}
@cindex customizing
@vindex enable-local-eval
@c ===================================================================
-@node Advanced Features, For Gurus, The Basics, Top
+@node Advanced Features
@chapter Advanced Features
@cindex advanced features
@findex ses-read-header-row
* 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
(@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
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
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
Export a range of cells as tab-separated formulas (@code{ses-export-tsf}).
@end table
-The exported text goes to the kill ring --- you can paste it into
+The exported text goes to the kill ring; you can paste it into
another buffer. Columns are separated by tabs, rows by newlines.
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
@c ===================================================================
-@node For Gurus, Index, Advanced Features, Top
+@node For Gurus
@chapter For Gurus
@cindex advanced features
* 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
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
-@acronym{SES} mode for the buffer, etc.)
+@acronym{SES} mode for the buffer, etc.).
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
@end table
-@node Buffer-local variables in spreadsheets, Uses of defadvice in @acronym{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
You can define functions by making them values for the fake local
variable @code{eval}. Such functions can then be used in your
formulas and printers, but usually each @code{eval} is presented to
-the user during file loading as a potential virus --- this can get
+the user during file loading as a potential virus. This can get
annoying.
You can define functions in your @file{.emacs} file. Other people can
(put 'your-function-name 'safe-function t)
@end lisp
-@node Uses of defadvice in @acronym{SES}, , Buffer-local variables in spreadsheets, For Gurus
+@node Uses of defadvice in @acronym{SES}
@section Uses of defadvice in @acronym{SES}
@cindex defadvice
@cindex undo-more
@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
-Jonathan Yavner @email{jyavner@@member.fsf.org}@*
-Stefan Monnier @email{monnier@@gnu.org}@*
-Shigeru Fukaya @email{shigeru.fukaya@@gmail.com}
+@c jyavner@@member.fsf.org
+Jonathan Yavner,
+@c monnier@@gnu.org
+Stefan Monnier,
+@c shigeru.fukaya@@gmail.com
+Shigeru Fukaya
@end quotation
@noindent
Texinfo manual by:
@quotation
-Jonathan Yavner @email{jyavner@@member.fsf.org}@*
-Brad Collins <brad@@chenla.org>
+@c jyavner@@member.fsf.org
+Jonathan Yavner,
+@c brad@@chenla.org
+Brad Collins
@end quotation
@noindent
Ideas from:
@quotation
-Christoph Conrad @email{christoph.conrad@@gmx.de}@*
-CyberBob @email{cyberbob@@redneck.gacracker.org}@*
-Syver Enstad @email{syver-en@@online.no}@*
-Ami Fischman @email{fischman@@zion.bpnetworks.com}@*
-Thomas Gehrlein @email{Thomas.Gehrlein@@t-online.de}@*
-Chris F.A. Johnson @email{c.f.a.johnson@@rogers.com}@*
-Yusong Li @email{lyusong@@hotmail.com}@*
-Juri Linkov @email{juri@@jurta.org}@*
-Harald Maier @email{maierh@@myself.com}@*
-Alan Nash @email{anash@@san.rr.com}@*
-François Pinard @email{pinard@@iro.umontreal.ca}@*
-Pedro Pinto @email{ppinto@@cs.cmu.edu}@*
-Stefan Reichör @email{xsteve@@riic.at}@*
-Oliver Scholz @email{epameinondas@@gmx.de}@*
-Richard M. Stallman @email{rms@@gnu.org}@*
-Luc Teirlinck @email{teirllm@@dms.auburn.edu}@*
-J. Otto Tennant @email{jotto@@pobox.com}@*
-Jean-Philippe Theberge @email{jphil@@acs.pagesjaunes.fr}
+@c christoph.conrad@@gmx.de
+Christoph Conrad,
+@c cyberbob@@redneck.gacracker.org
+CyberBob,
+@c syver-en@@online.no
+Syver Enstad,
+@c fischman@@zion.bpnetworks.com
+Ami Fischman,
+@c Thomas.Gehrlein@@t-online.de
+Thomas Gehrlein,
+@c c.f.a.johnson@@rogers.com
+Chris F.A. Johnson,
+@c lyusong@@hotmail.com
+Yusong Li,
+@c juri@@jurta.org
+Juri Linkov,
+@c maierh@@myself.com
+Harald Maier,
+@c anash@@san.rr.com
+Alan Nash,
+@c pinard@@iro.umontreal.ca
+François Pinard,
+@c ppinto@@cs.cmu.edu
+Pedro Pinto,
+@c xsteve@@riic.at
+Stefan Reichör,
+@c epameinondas@@gmx.de
+Oliver Scholz,
+@c rms@@gnu.org
+Richard M. Stallman,
+@c teirllm@@dms.auburn.edu
+Luc Teirlinck,
+@c jotto@@pobox.com
+J. Otto Tennant,
+@c jphil@@acs.pagesjaunes.fr
+Jean-Philippe Theberge
@end quotation
@c ===================================================================
-@node GNU Free Documentation License, , Acknowledgments, Top
+@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi
HCoop / bpt / emacs.git / blobdiff