comparison man/ses.texi @ 60140:3f04dc96bdc4

ses.texi: Add concept/function/variable indices

60139:cf2460efae4d

@c %**end of header

@copying
This file documents SES: the Simple Emacs Spreadsheet.

Copyright @copyright{} 2002  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.1 or
any later version published by the Free Software Foundation; with no

@menu
* Sales Pitch::                 Why use SES?
* The Basics::                  Basic spreadsheet commands
* Advanced Features::           Want to know more?
* For Gurus::                   Want to know @emph{even more}?
* Acknowledgements::            Acknowledgements
@end menu

@c ===================================================================

@node Sales Pitch, The Basics, Top, Top
@comment  node-name,  next,  previous,  up
@chapter Sales Pitch

@itemize @bullet
@item Create and edit simple spreadsheets with a minimum of fuss.
@item Full undo/redo/autosave.
@item Immune to viruses in spreadsheet files.

@c ===================================================================

@node The Basics, Advanced Features, Sales Pitch, Top
@comment  node-name,  next,  previous,  up
@chapter The Basics

A @dfn{cell identifier} is a symbol with a column letter and a row
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.

* Customizing SES::
@end menu

@node Formulas, Resizing, The Basics, The Basics
@section Cell formulas

To enter a number into the current cell, just start typing:

@table @kbd
@item 0..9

Recalculate the entire spreadsheet (@code{ses-recalculate-all}).
@end table

@node Resizing, Printer functions, Formulas, The Basics
@section Resizing the spreadsheet

Basic commands:

@table @kbd
@item C-o

@end table


@node Printer functions, Clearing cells, Resizing, The Basics
@section Printer functions

Printer functions convert binary cell values into the print forms that
Emacs will display on the screen.

A printer can be a format string, like @samp{"$%.2f"}.  The result

@end table


@node Clearing cells, Copy/cut/paste, Printer functions, The Basics
@section Clearing cells

These commands set both formula and printer to @code{nil}:

@table @kbd
@item DEL

@end table


@node Copy/cut/paste, Customizing SES, Clearing cells, The Basics
@section Copy, cut, and paste

The copy functions work on rectangular regions of cells.  You can paste the
copies into non-SES buffers to export the print text.

@table @kbd

yank.  This doesn't make any difference?
@end table

@node Customizing SES,  , Copy/cut/paste, The Basics
@section Customizing SES

By default, a newly-created spreadsheet has 1 row and 1 column.  The
column width is 7 and the default printer is @samp{"%.7g"}.  Each of these
can be customized.  Look in group ``ses''.

@c ===================================================================

@node Advanced Features, For Gurus, The Basics, Top
@chapter Advanced Features

@table @kbd
@item C-c M-C-h
(@code{ses-set-header-row}).  The header line at the top of the SES
window normally shows the column letter for each column.  You can set

* Spreadsheets with details and summary::
@end menu

@node The print area, Ranges in formulas, Advanced Features, Advanced Features
@section The print area

A 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
formatted by printer functions.  The data area records the formula and

(@code{ses-reprint-all}).
@end table

@node Ranges in formulas, Sorting by column, The print area, Advanced Features
@section Ranges in formulas

A formula like
@lisp
(+ A1 A2 A3)
@end lisp

the range.  New cells inserted just before a range are not included.


@node Sorting by column, Standard formula functions, Ranges in formulas, Advanced Features
@section Sorting by column

@table @kbd
@item C-c M-C-s
Sort the cells of a range using one of the columns
(@code{ses-sort-column}).  The rows (or partial rows if the range

range.


@node Standard formula functions, More on cell printing, Sorting by column, Advanced Features
@section Standard formula functions

Oftentimes you want a calculation to exclude the blank cells.  Here
are some useful functions to call from your formulas:

@table @code

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
@section More on cell printing

Special cell values:
@itemize
@item nil prints the same as "", but allows previous cell to spill over.
@item '*skip* replaces nil when the previous cell actually does spill over;

is numeric-only and you use a string as a cell value.


@node Import and export, Virus protection, More on cell printing, Advanced Features
@section Import and export

@table @kbd
@item x t
Export a range of cells as tab-separated values (@code{ses-export-tsv}).
@item x T

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
@section Virus protection

Whenever a formula or printer is read from a file or is pasted into
the spreadsheet, it receives a ``needs safety check'' marking.  Later,
when the formula or printer is evaluated for the first time, it is
checked for safety using the @code{unsafep} predicate; if found to be

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
@section Spreadsheets with details and summary

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-and-summary spreadsheet.


@c ===================================================================

@node For Gurus, Acknowledgements, Advanced Features, Top
@chapter For Gurus

@menu
* Deferred updates::
* Nonrelocatable references::
* The data area::

* Uses of defadvice in SES::
@end menu

@node Deferred updates, Nonrelocatable references, For Gurus, For Gurus
@section Deferred updates

To save time by avoiding redundant computations, cells that need
recalculation due to changes in other cells are added to a set.  At
the end of the command, each cell in the set is recalculated once.
This can create a new set of cells that need recalculation.  The

can type ahead without worrying about the glitch.


@node Nonrelocatable references, The data area, Deferred updates, For Gurus
@section Nonrelocatable references

@kbd{C-y} relocates all cell-references in a pasted formula, while
@kbd{C-u C-y} relocates none of the cell-references.  What about mixed
cases?

kind of dependency is also not recorded.


@node The data area, Buffer-local variables in spreadsheets, Nonrelocatable references, For Gurus
@section The data area

Begins with an 014 character, followed by sets of cell-definition
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

@end table


@node Buffer-local variables in spreadsheets, Uses of defadvice in SES, The data area, For Gurus
@section Buffer-local variables in spreadsheets

You can add additional local variables to the list at the bottom of
the data area, such as hidden constants you want to refer to in your
formulas.

(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

@table @code
@item undo-more
Defines a new undo element format (@var{fun} . @var{args}), which
means ``undo by applying @var{fun} to @var{args}''.  For spreadsheet

as cells (if the yank text has 'ses properties), then as tab-separated
formulas, then (if all else fails) as a single formula for the current
cell.
@end table


@c ===================================================================

@node Acknowledgements,  , For Gurus, Top
@chapter Acknowledgements

Coding by:
@quotation
Jonathan Yavner @email{jyavner@@member.fsf.org}@*
Stefan Monnier @email{monnier@@gnu.org}
@end quotation

Ideas from:
@quotation
Christoph Conrad @email{christoph.conrad@@gmx.de}@*
CyberBob @email{cyberbob@@redneck.gacracker.org}@*
Syver Enstad @email{syver-en@@online.no}@*

60140:3f04dc96bdc4

@c %**end of header

@copying
This file documents SES: the Simple Emacs Spreadsheet.

Copyright @copyright{} 2002, 2005  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.1 or
any later version published by the Free Software Foundation; with no

@menu
* Sales Pitch::                 Why use SES?
* The Basics::                  Basic spreadsheet commands
* Advanced Features::           Want to know more?
* For Gurus::                   Want to know @emph{even more}?
* Index::                       Concept, Function and Variable Index
* Acknowledgements::            Acknowledgements
@end menu

@c ===================================================================

@node Sales Pitch, The Basics, Top, Top
@comment  node-name,  next,  previous,  up
@chapter Sales Pitch
@cindex features

@itemize @bullet
@item Create and edit simple spreadsheets with a minimum of fuss.
@item Full undo/redo/autosave.
@item Immune to viruses in spreadsheet files.

@c ===================================================================

@node The Basics, Advanced Features, Sales Pitch, Top
@comment  node-name,  next,  previous,  up
@chapter The Basics
@cindex basic commands
@findex ses-jump
@findex ses-mark-row
@findex ses-mark-column
@findex ses-mark-whole-buffer
@findex set-mark-command
@findex keyboard-quit

A @dfn{cell identifier} is a symbol with a column letter and a row
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.

* Customizing SES::
@end menu

@node Formulas, Resizing, The Basics, The Basics
@section Cell formulas
@cindex formulas
@cindex formulas, entering
@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:

@table @kbd
@item 0..9

Recalculate the entire spreadsheet (@code{ses-recalculate-all}).
@end table

@node Resizing, Printer functions, Formulas, The Basics
@section Resizing the spreadsheet
@cindex resizing spreadsheets
@findex ses-insert-row
@findex ses-insert-column
@findex ses-delete-row
@findex ses-delete-column
@findex ses-set-column-width
@findex ses-forward-or-insert
@findex ses-append-row-jump-first-column


Basic commands:

@table @kbd
@item C-o

@end table


@node Printer functions, Clearing cells, Resizing, The Basics
@section Printer functions
@cindex printer functions
@findex ses-read-cell-printer
@findex ses-read-column-printer
@findex ses-read-default-printer
@findex ses-center
@findex ses-center-span
@findex ses-dashfill
@findex ses-dashfill-span
@findex ses-tildefill-span


Printer functions convert binary cell values into the print forms that
Emacs will display on the screen.

A printer can be a format string, like @samp{"$%.2f"}.  The result

@end table


@node Clearing cells, Copy/cut/paste, Printer functions, The Basics
@section Clearing cells
@cindex clearing commands
@findex ses-clear-cell-backward
@findex ses-clear-cell-forward

These commands set both formula and printer to @code{nil}:

@table @kbd
@item DEL

@end table


@node Copy/cut/paste, Customizing SES, Clearing cells, The Basics
@section Copy, cut, and paste
@cindex copy
@cindex cut
@cindex paste
@findex kill-ring-save
@findex mouse-set-region
@findex mouse-set-secondary
@findex ses-kill-override
@findex yank
@findex clipboard-yank
@findex mouse-yank-at-click
@findex mouse-yank-at-secondary
@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.

@table @kbd

yank.  This doesn't make any difference?
@end table

@node Customizing SES,  , Copy/cut/paste, The Basics
@section Customizing SES
@cindex customizing
@vindex enable-local-eval
@vindex ses-mode-hook
@vindex safe-functions
@vindex enable-local-eval


By default, a newly-created spreadsheet has 1 row and 1 column.  The
column width is 7 and the default printer is @samp{"%.7g"}.  Each of these
can be customized.  Look in group ``ses''.

@c ===================================================================

@node Advanced Features, For Gurus, The Basics, Top
@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
window normally shows the column letter for each column.  You can set

* Spreadsheets with details and summary::
@end menu

@node The print area, Ranges in formulas, Advanced Features, Advanced Features
@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
buffer is narrowed to show only the print area.  The print area is
read-only except for special SES commands; it contains cell values
formatted by printer functions.  The data area records the formula and

(@code{ses-reprint-all}).
@end table

@node Ranges in formulas, Sorting by column, The print area, Advanced Features
@section Ranges in formulas
@cindex ranges
@findex ses-insert-range-click
@findex ses-insert-range
@findex ses-insert-ses-range-click
@findex ses-insert-ses-range
@vindex from
@vindex to

A formula like
@lisp
(+ A1 A2 A3)
@end lisp

the range.  New cells inserted just before a range are not included.


@node Sorting by column, Standard formula functions, Ranges in formulas, Advanced Features
@section Sorting by column
@cindex sorting
@findex ses-sort-column
@findex ses-sort-column-click

@table @kbd
@item C-c M-C-s
Sort the cells of a range using one of the columns
(@code{ses-sort-column}).  The rows (or partial rows if the range

range.


@node Standard formula functions, More on cell printing, Sorting by column, Advanced Features
@section Standard formula functions
@cindex standard formula functions
@cindex *skip*
@cindex *error*
@findex ses-delete-blanks
@findex ses-average
@findex ses+

Oftentimes you want a calculation to exclude the blank cells.  Here
are some useful functions to call from your formulas:

@table @code

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
@section More on cell printing
@cindex cell printing, more
@findex ses-truncate-cell
@findex ses-recalculate-cell

Special cell values:
@itemize
@item nil prints the same as "", but allows previous cell to spill over.
@item '*skip* replaces nil when the previous cell actually does spill over;

is numeric-only and you use a string as a cell value.


@node Import and export, Virus protection, More on cell printing, Advanced Features
@section Import and export
@cindex import and export
@cindex export, and import
@findex ses-export-tsv
@findex ses-export-tsf

@table @kbd
@item x t
Export a range of cells as tab-separated values (@code{ses-export-tsv}).
@item x T

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
@section Virus protection
@cindex virus protection

Whenever a formula or printer is read from a file or is pasted into
the spreadsheet, it receives a ``needs safety check'' marking.  Later,
when the formula or printer is evaluated for the first time, it is
checked for safety using the @code{unsafep} predicate; if found to be

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
@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-and-summary spreadsheet.


@c ===================================================================

@node For Gurus, Index, Advanced Features, Top
@chapter For Gurus
@cindex advanced features

@menu
* Deferred updates::
* Nonrelocatable references::
* The data area::

* Uses of defadvice in SES::
@end menu

@node Deferred updates, Nonrelocatable references, For Gurus, For Gurus
@section Deferred updates
@cindex deferred updates
@cindex updates, deferred
@vindex run-with-idle-timer

To save time by avoiding redundant computations, cells that need
recalculation due to changes in other cells are added to a set.  At
the end of the command, each cell in the set is recalculated once.
This can create a new set of cells that need recalculation.  The

can type ahead without worrying about the glitch.


@node Nonrelocatable references, The data area, Deferred updates, For Gurus
@section Nonrelocatable references
@cindex nonrelocatable references
@cindex references, nonrelocatable

@kbd{C-y} relocates all cell-references in a pasted formula, while
@kbd{C-u C-y} relocates none of the cell-references.  What about mixed
cases?

kind of dependency is also not recorded.


@node The data area, Buffer-local variables in spreadsheets, Nonrelocatable references, For Gurus
@section The data area
@cindex data area
@findex ses-reconstruct-all

Begins with an 014 character, followed by sets of cell-definition
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

@end table


@node Buffer-local variables in spreadsheets, Uses of defadvice in SES, The data area, For Gurus
@section Buffer-local variables in spreadsheets
@cindex buffer-local variables
@cindex variables, buffer-local

You can add additional local variables to the list at the bottom of
the data area, such as hidden constants you want to refer to in your
formulas.

(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
@cindex defadvice
@cindex undo-more
@cindex copy-region-as-kill
@cindex yank

@table @code
@item undo-more
Defines a new undo element format (@var{fun} . @var{args}), which
means ``undo by applying @var{fun} to @var{args}''.  For spreadsheet

as cells (if the yank text has 'ses properties), then as tab-separated
formulas, then (if all else fails) as a single formula for the current
cell.
@end table

@c ===================================================================
@node Index, Acknowledgements, For Gurus, Top
@unnumbered Concept Index

@printindex cp

@heading Function Index

@printindex fn

@heading Variable Index

@printindex vr


@c ===================================================================

@node Acknowledgements, , Index, Top
@chapter Acknowledgements

Coding by:
@quotation
Jonathan Yavner @email{jyavner@@member.fsf.org}@*
Stefan Monnier @email{monnier@@gnu.org}
@end quotation

@noindent
Texinfo manual by:
@quotation
Jonathan Yavner @email{jyavner@@member.fsf.org}@*
Brad Collins <brad@@chenla.org>
@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}@*