[Emacs-diffs] /srv/bzr/emacs/trunk r110872: * ses.texi: Doc for ses-rename-cell, ses-repair-cell-reference-all & ses-range.

[Vincent Belaïche]

------------------------------------------------------------
revno: 110872
committer: Vincent Belaïche  <address@hidden>
branch nick: trunk
timestamp: Mon 2012-11-12 06:53:53 +0100
message:
  * ses.texi: Doc for ses-rename-cell, ses-repair-cell-reference-all & 
ses-range.
  In all file place SES into @acronym{...}.
  (Advanced Features): Add key index and function index for
  ses-set-header-row. Add description for function
  ses-rename-cell. Add description for function
  ses-repair-cell-reference-all.
  (Ranges in formulas): Add description for ses-range flags.
modified:
  doc/misc/ChangeLog
  doc/misc/ses.texi

=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog        2012-11-12 03:10:51 +0000
+++ b/doc/misc/ChangeLog        2012-11-12 05:53:53 +0000
@@ -1,3 +1,13 @@
+2012-11-12  Vincent Belaïche  <address@hidden>
+
+       * ses.texi: Doc for ses-rename-cell, ses-repair-cell-reference-all & 
ses-range.
+       In all file place SES into @acronym{...}.
+       (Advanced Features): Add key index and function index for
+       ses-set-header-row. Add description for function
+       ses-rename-cell. Add description for function
+       ses-repair-cell-reference-all.
+       (Ranges in formulas): Add description for ses-range flags.
+
 2012-11-12  Paul Eggert  <address@hidden>
 
        * texinfo.tex: Merge from gnulib.

=== modified file 'doc/misc/ses.texi'
--- a/doc/misc/ses.texi 2012-07-25 05:48:19 +0000
+++ b/doc/misc/ses.texi 2012-11-12 05:53:53 +0000
@@ -1,7 +1,7 @@
 \input texinfo   @c -*-texinfo-*-
 @c %**start of header
 @setfilename ../../info/ses
address@hidden SES: Simple Emacs Spreadsheet
address@hidden @acronym{SES}: Simple Emacs Spreadsheet
 @setchapternewpage off
 @syncodeindex fn cp
 @syncodeindex vr cp
@@ -9,7 +9,7 @@
 @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-2012 Free Software Foundation, Inc.
 
@@ -29,13 +29,13 @@
 
 @dircategory Emacs misc features
 @direntry
-* SES: (ses).                   Simple Emacs Spreadsheet.
+* @acronym{SES}: (ses).                   Simple Emacs Spreadsheet.
 @end direntry
 
 @finalout
 
 @titlepage
address@hidden SES
address@hidden @acronym{SES}
 @subtitle Simple Emacs Spreadsheet
 @author Jonathan A. Yavner
 @author @email{jyavner@@member.fsf.org}
@@ -52,10 +52,10 @@
 @ifnottex
 @node Top, Sales Pitch, (dir), (dir)
 @comment  node-name,  next,  previous,  up
address@hidden SES: Simple Emacs Spreadsheet
address@hidden @acronym{SES}: Simple Emacs Spreadsheet
 
 @display
-SES is a major mode for GNU Emacs to edit spreadsheet files, which
address@hidden 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
@@ -66,7 +66,7 @@
 @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}?
@@ -126,9 +126,9 @@
 
 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
@@ -155,7 +155,7 @@
 * Printer functions::
 * Clearing cells::
 * Copy/cut/paste::
-* Customizing SES::
+* Customizing @acronym{SES}::
 @end menu
 
 @node Formulas, Resizing, The Basics, The Basics
@@ -192,7 +192,7 @@
 expression, you can use @address@hidden 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 @address@hidden, @address@hidden, and @kbd{?} to complete it.
 @end table
@@ -349,7 +349,7 @@
 @end table
 
 
address@hidden Copy/cut/paste, Customizing SES, Clearing cells, The Basics
address@hidden Copy/cut/paste, Customizing @acronym{SES}, Clearing cells, The 
Basics
 @section Copy, cut, and paste
 @cindex copy
 @cindex cut
@@ -365,7 +365,7 @@
 @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 address@hidden buffers to export the print text.
 
 @table @kbd
 @item M-w
@@ -394,7 +394,7 @@
 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
@@ -402,7 +402,7 @@
 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
address@hidden 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.
@@ -420,12 +420,12 @@
 @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
 
address@hidden Customizing SES,  , Copy/cut/paste, The Basics
address@hidden Customizing SES
address@hidden Customizing @acronym{SES},  , Copy/cut/paste, The Basics
address@hidden Customizing @acronym{SES}
 @cindex customizing
 @vindex enable-local-eval
 @vindex ses-mode-hook
@@ -443,7 +443,7 @@
 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.
@@ -469,7 +469,10 @@
 
 @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}).
address@hidden ses-set-header-row
address@hidden 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
@@ -478,6 +481,16 @@
 @item [header-line mouse-3]
 Pops up a menu to set the current row as the header, or revert to
 column letters.
address@hidden M-x ses-rename-cell
address@hidden ses-rename-cell 
+Rename a cell from a standard A1-like name to any 
+string. 
address@hidden M-x ses-repair-cell-reference-all
address@hidden 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
@@ -498,9 +511,9 @@
 @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.
 
@@ -576,6 +589,52 @@
 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.
address@hidden @code
address@hidden !
+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.
address@hidden _
+Empty cell values are replaced by the argument following flag
address@hidden, or @code{0} when flag @code{_} is last in argument list. For
+instance @code{(ses-range A1 A4 _ "empty")} will do the same as
address@hidden(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
address@hidden(list A1 0 A3 0)}.
address@hidden >v
+When order matters, list cells by reading cells rowwise from top left
+to bottom right. This flag is provided for completeness only as it is
+the default reading order.
address@hidden <v
+List cells by reading cells rowwise from top right to bottom left.
address@hidden v>
+List cells by reading cells columnwise from top left to bottom right.
address@hidden v<
+List cells by reading cells columnwise from top right to bottom left.
address@hidden v
+A short hand for @code{v>}.
address@hidden ^
+A short hand for @code{^>}.
address@hidden >
+A short hand for @code{>v}.
address@hidden <
+A short hand for @code{>^}.
address@hidden *
+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.
address@hidden *2
+Same as @code{*} except that a matrix is always made even when there
+is only one row or column in the range.
address@hidden *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.
address@hidden table
 
 @node Sorting by column, Standard formula functions, Ranges in formulas, 
Advanced Features
 @section Sorting by column
@@ -653,7 +712,7 @@
 row or the next address@hidden 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
address@hidden could get confused by printer results that contain newlines or
 tabs, so these are replaced with question marks.
 
 @table @kbd
@@ -734,7 +793,7 @@
 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
@@ -771,7 +830,7 @@
 * 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
@@ -799,7 +858,7 @@
 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
address@hidden 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
@@ -843,14 +902,14 @@
 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.)
address@hidden 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).
@@ -866,7 +925,7 @@
 @end table
 
 
address@hidden Buffer-local variables in spreadsheets, Uses of defadvice in 
SES, The data area, For Gurus
address@hidden Buffer-local variables in spreadsheets, Uses of defadvice in 
@acronym{SES}, The data area, For Gurus
 @section Buffer-local variables in spreadsheets
 @cindex buffer-local variables
 @cindex variables, buffer-local
@@ -900,8 +959,8 @@
 (put 'your-function-name 'safe-function t)
 @end lisp
 
address@hidden Uses of defadvice in SES,  , Buffer-local variables in 
spreadsheets, For Gurus
address@hidden Uses of defadvice in SES
address@hidden Uses of defadvice in @acronym{SES},  , Buffer-local variables in 
spreadsheets, For Gurus
address@hidden Uses of defadvice in @acronym{SES}
 @cindex defadvice
 @cindex undo-more
 @cindex copy-region-as-kill