   This file documents Oleo, the GNU spreadsheet.

   This file is part of GNU Oleo.

   Copyright (C) 1993-2000 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

Oleo
****

Oleo is the GNU spreadsheet program.  This documentation is of Oleo
version {No value for `version'}, as of {No value for `update-date'}.
It is by no means complete, nor necessarily accurate for that matter.

1 Basics
********

`Oleo' is the GNU spreadsheet (1).

   `Oleo' has more than one user interface.  The traditional `oleo'
environment shows a curses based (character mode) user interface.  A
bare bones user interface based on the X Window System exists as of
version 1.6 which dates back to 1994.  In 1998, development started for
a `motif' based user interface.  It should be more user friendly than
the character based UI.

   Most of this manual describes the character based user interface,
the `motif' user interface is treaded in (see Motif).

   To start Oleo, type `oleo'.  If `filename' is the name of a
spreadsheet that you have saved from a previous `oleo' session, you can
type `oleo filename' to start Oleo with the spreadsheet loaded.

   To stop Oleo, type `C-x C-c'.  This will prompt you for the name of
a file in which to save the current spreadsheet.  If you do not want to
save it, type <RET>, otherwise type the name of the filename that you
wish to save it in, and then press <RET>.

   Type `C-z' to suspend `oleo'.  This does not do anything if you are
running under X-windows.

   If you wish to abort a command, type `C-g'

   ---------- Footnotes ----------

   (1) better than the high priced spread

1.1 How to type commands
========================

We use emacs abbreviations for keystrokes.  These examples should make
the notation clear.
`C-c'
     Hold down the control key and press `c'

`C-D'
     Hold down the control key and press `D' (capital `D')

`C-x c'
     Hold down the control key and press `x', then press `c'

`C-u C-x c'
     Hold down the control key and press `ux', then press `c'

`M-c'
     Type an escape followed by a `c'.  If you can't find the escape
     key, you can always type `C-['.

`M-C-c'
     Type an escape followed by  `C-c'.

   Some commands are not bound to key strokes.  For instance, if you
wish to erase the entire spreadsheet, you have to use the command
`clear-spreadsheet'.  To execute a command, type `M-x' and then the
command name:
                    M-x clear-spreadsheet

1.2 Cell Referencing
====================

Many commands and functions operate on a given cell or group of cells,
and therefore take a cell or range reference (address) as an argument.
An individual cell is specified by its row/column coordinates, which
start with row 1, column 1 in the upper left of the spreadsheet.  A
"range" is a rectangular group of cells, specified by giving its left
and rightmost columns and top and bottom rows.

   A reference may be absolute or relative.  An "absolute" reference is
measured from the upper left of the spreadsheet, and does not change
when the cell containing it is moved or copied.  A "relative"
reference, however, is measured as an offset from the cell it is in, and
when moved points to the cell at the same offset relative to the new
location.

   There are two ways of addressing cells in Oleo, called `a0' and
`noa0'.  To switch between the modes, use the `set-option' command:

`M-x set-option a0'
     Sets `a0' mode.

`M-x set-option no a0'
     Sets `noa0' mode.

   In both modes the case of cell and range letters is ignored.

1.2.1 noa0 Mode
---------------

In `noa0' mode (the default), absolute cell addresses have the form
`RROWCCOL', where ROW and COL are the row and column (as integers).
Thus, `R1C2' is the second cell from the left on the top row.       The
cell in the leftmost uppermost corner is `R1C1', and the cell in the
rightmost lowermost corner is `R65535C65535'.

   Relative addresses have the form `R[ROWOFFSET]C[COLOFFSET]', as in
`R[-1]C[+1]' (the cell above and to the right of the current cell).  An
offset of 0 can be omitted, along with its square brackets: `RC[+2]'
(the cell two columns to the right).  The plus signs of positive
offsets can also be omitted.  Absolute and relative addresses can be
combined, as in `R4C[-1]' (the cell in row four that's one left of the
current cell).

   Ranges in `noa0' mode are specified as `RROW1:ROW2CCOL1:COL2', where
the row and column references may be either absolute or relative, and
can be mixed.  Thus, `R1:4C1:[-2]' refers to the cells of rows one
through 4, columns one through the second column to the left.  If ROW1 =
ROW2 or COL1 = COL2, the colon and second number may be omitted, as in
`R1:10C2' (rows one through ten in column two).

1.2.2 a0 Mode
-------------

In `a0' mode, relative references have the form COL_LET ROW_NUM, where
COL_LET is the letter of the column and ROW-NUM is the row number.
COL_LET can be upper or lower case.  The cell in the leftmost uppermost
corner is `A1', and the cell in the rightmost lowermost corner is
`CRXO65535'. The columns are initially single letters (A-Z) , then
double letters (AA-ZZ), then triple letters (AAA-ZZZ), and finally some
quadruple letters (AAAA-CRXO).

   `B3' refers to the cell in the second column of row 3.  Since this
is a relative reference, it will change when the containing cell is
moved, to refer to the cell at the same relative position; e.g., if the
cell is moved two columns to the right the reference will change to
`D3'.

   Absolute references have the form `$'COL_LET`$'ROW_NUM, as in `$A$1'
(top left cell).  These do not change when the containing cell is
moved.  Both types can be mixed with predictable results, e.g., `$A4'
has an absolute column but a relative row.

   Ranges are given as CELL_REF`:'CELL_REF or CELL_REF`.'CELL_REF,
where the CELL_REFs describe diagonally opposite corners of the range.
Thus, `A1:B2' refers to the topmost, leftmost four cells in the
spreadsheet.

1.2.3 Comparison
----------------

In order to get an understanding of these two addressing modes, assume
that the cell cursor is in `E7' = `R7C5'.  The left hand column is
`noa0' mode, and the right hand one is `a0' mode.

                      R1C2              $B$1
                      R[-1]C[+1]        F6
                      RC[+2]            G7
                      R4C[-1]           $D4

1.3 The Screen
==============

The screen is divided into three parts: the input line, the status
line, and the work area.

The input line
--------------

The input line is also referred to as the Minibuffer.  This is where
you enter data into cells (see Entering).  You can change the
location of the input line.  For example, to change the input line to
the bottom of the screen, type

     M-x set-option <RET> input -1

   This can be made the default.  (see .oleorc file)

The status line
---------------

The status line describes the current status.  This includes:
   *         The cell number (e.g., `A1' or `R1C1'), or the current
     range (cursor to mark) if the mark is set (1)

   *         The `C-u' repeat count of the current command (if set), in
     curly braces

   *         The value of the cell

   *         The literal contents of the cell, if a formula

   For instance, if the mark is located at cell `D4', the cell cursor
is in cell `A11', the cell contents is `@sum(A1.B10)', and the sum of
the entries in the region `A1.B10' is 89, then the status line is

     *A11:D4 89 [@sum(A1.B10)]

   The `*' indicates that the mark is set, and thus `A11:D4' is the
range from the cursor cell to the mark.  You can change the location of
the status line using `M-x set-option'.  To move the status line to the
bottom of the screen, type

     M-x set-option <RET> status -1

   ---------- Footnotes ----------

   (1) Note that the current range is given as upper-left corner to
lower-right corner, even if the mark is to the lower _left_ of the
cursor (or vice versa).  This is confusing.

The work area and its borders
-----------------------------

The work area is surrounded by a border giving the row and column
numbers.  When there are multiple windows, there will be several
borders.  A cell is a box that can hold data.  The cell cursor is the
highlighted rectangle indicating the `active cell'.  A region is a
rectangular block of cells.  Regions are described by giving
coordinates of the upper left cell and lower right cell.

   The appearance of the screen can be changed (see Appearance).

1.4 The cell cursor and the mark
================================

Every window has its own cell cursor.  The most recently used window
defines the current cell position.  There is one cell marker, called the
`mark', global to the spreadsheet.

`C-x j'
     You are asked for a cell to go to, and the cell cursor is moved
     there.  The cell can be either a cell name as in `R32C96', or a
     variable.  This command starts with a default of wherever the
     cursor was the last time this command was used.  (`goto-cell')

`M-x j'
     You are asked for a region. The cursor is placed in the top-left
     corner of the region, and the cell-mark is placed at the opposite
     corner of the region. (`goto-region')

`C-@'
     Set the cell mark to the current cell. (`mark-cell')

`C-u C-@'
     Set the cell cursor equal to the mark, and clear the mark,

`C-x C-x'
     Exchange the cell cursor and cell mark.
     (`exchange-point-and-mark')

`C-u C-x C-x'
     Clear the mark.

1.5 How updating works
======================

Oleo periodically recalculates the values of the spreadsheet that can
change.  This calculation can be done between keystrokes, and usually
stops when a key is pressed.  This behavior can be changed with the
options `background' and `nobackground'.  The time between updates
(initially 10 seconds) can be changed using the option `ticks'.   You
can also disable automatic recalculation with the option `noauto'.  In
this case, recalculation is only done when the `recalculate' command is
used.  (see Options)

`C-x !'
     Recalculate the spreadsheet until all the cells whose values may
     have changed have been evaluated.  If there are circular cell
     references, the cells in the loop will be evaluated at most 40
     times (this number subject to change!).  (`recalculate')

1.6 Moving around the spreadsheet
=================================

1.6.1 Moving to a neighboring cell
----------------------------------

The arrow keys work in the obvious fashion, moving the cell cursor one
cell in the direction of the key.  In addition, there are keyboard
commands

`C-p'
     Move up one cell (`up-cell')

`C-n'
     Move down one cell (`down-cell')

`C-f'
     Move forward (right) one cell (`right-cell')

`C-b'
     Move backward (left) one cell (`left-cell')

   There are also commands for diagonal movements, but they are not
bound to any keys.  These commands are `upleft-cell', `downleft-cell',
`upright-cell', `downright-cell'.

1.6.2 Finding the next empty cell
---------------------------------

These commands move to the next empty cell in a given direction.  (1)

`M-p'
     Move to the first empty cell above the current cell in the current
     column.  If given a repeat count, go to the N-th most empty cell.
     (`scan-up')

`M-n'
     Move to the first empty cell below the current cell in the current
     column.  If given a repeat count, go to the N-th most empty cell.
     (`scan-down')

`M-f'
     Move to the first empty cell to the right of the current cell in
     the current row.  If given a repeat count, go to the N-th most
     empty cell.  (`scan-right')

`M-b'
     Move to the first empty cell to the left of the current cell in the
     current row.  If given a repeat count, go to the N-th most empty
     cell.  (`scan-left')

   ---------- Footnotes ----------

   (1) the doc doesn't seem to agree with the behavior; what is the
intended behavior?  the repeat counts seem to be ignored.

1.6.3 Moving long distances
---------------------------

These commands move over large areas of the spreadsheet, so they first
set the mark to the current cell before moving (if it's not already
set).  You can thus jump back to where you were with `C-x C-x'
(`exchange-point-and-mark').

`M-<'
     Go to the upper left cell (1).  (`upper-left')

`M->'
     Go to lower right cell.  The lower right cell is the cell in the
     rightmost column that has a value, and the lowermost row that has
     a value.  There might not be any value in the lower right cell.
     (`lower-right')

`C-a'
     Go to the beginning of the row.  With a `C-u' prefix argument N,
     it also moves N-1 (2) rows down first. (`beginning-of-row')

`C-e'
     Go to the last cell of the current row (that has a value).  A
     `C-u' prefix is also accepted. (`end-of-row')

`M-C-a'
     Go to the beginning of the column. (`beginning-of-column')

`M-C-e'
     Go to the last cell of the current column. (`end-of-column')

   ---------- Footnotes ----------

   (1) This is always cell `A1' in the current version, but supposedly
might change in the future.

   (2) why -1?

1.6.4 Examples of movement commands
-----------------------------------

We use the spreadsheet below.  The blank squares are empty.

                   | A | B | C | D | E | F |
                 --|---|---|---|---|---|---|
                 1 |   |   |   |   |   |   |
                 --|---|---|---|---|---|---|
                 2 |   |   | x |   | x |   |
                 --|---|---|---|---|---|---|
                 3 |   |   | x | x | x |   |
                 --|---|---|---|---|---|---|
                 4 |   | x |   |   |   |   |
                 --|---|---|---|---|---|---|

   The first column is the command, the second is the cell the cell
cursor is in initially, and the third column is the location of the
cell cursor at the end of the command.

                     <M-<>       B4    =>    A1

                     <M->>       B4    =>    E4
                     <M->>       C2    =>    E4

                     <C-a>       E4    =>    E1
                     <C-a>       D4    =>    E1

                     <C-e>       A4    =>    B4
                     <C-e>       A3    =>    E3
                     <C-e>       A2    =>    E2
                     <C-e>       A1    =>    A1

                     <M-C-a>     E2    =>    E1
                     <M-C-e>     B1    =>    B4

                     <M-f>       A4    =>    C4
                     <M-f>       A2    =>    D2

1.6.5 Moving by screens
-----------------------

These commands scroll the current window one screenful in the
appropriate direction.  They try to leave the cell cursor in
approximately the same place, so that `M-v' followed by `C-v' should
leave the cell cursor in the original cell.  In addition to these
commands, there are diagonal movements that are not bound to keys:
`scroll-upright', `scroll-upleft', `scroll-downright',
`scroll-downleft'.

`M-v'
     Scroll up one screenful. (`scroll-up')

`C-v'
     Scroll down one screenful. (`scroll-down')

`C-x >'
     Scroll right one screenful. (`scroll-right')

`C-x <'
     Scroll left one screenful. (`scroll-left')

1.7 Using the mouse
===================

It is possible to use to mouse to move the cell cursor.  `down-mouse-0'
means to press the leftmost mouse button.

`down-mouse-0'
     Move to the cell pointed to by the mouse. (`mouse-goto')

`down-mouse-1'
     Set the mark to the cell pointed to by the mouse, but don't move
     the cell cursor. (`mouse-mark')

`down-mouse-2'
     Set the mark to the current cell, and move to the cell pointed to
     by the mouse. (`mouse-mark-and-goto') (1)

   ---------- Footnotes ----------

   (1) should these be changed - emacs uses 1 for 0, 2 for 1, and 3 for
2

1.8 Regions and Variables
=========================

Variables are symbolic names for regions of a spreadsheet.  Once
defined, they can be used in cell formulas as region addresses.  They
can also be used as arguments to any command that expects a region
address.  A variable name should not be the name of a cell.  Thus, `A1'
is not a good name for a variable.

`C-x :'
     Use this command to set a variable  (`set-variable'). For instance,
     to set the variable `test1' to the region `B2:C3', type
                  C-x :   test1    <RET>   B2:C3   <RET>

`C-h v'
     Shows the value of a variable.  To find the value of `test1', type
                  C-h v test1 <RET>
     If the variable has not been defined you get an error. If you
     mistype `test1' as `tset1', you get the message
                  there is no 'tset1'

`C-h C-v'
     This lists all variables and their current values.

1.9 Getting Help
================

`C-h'
     Enter into the help system.  The commands below give various bits
     of information about Oleo.

`C-h C'
     When a complex command is being invoked (i.e., when Oleo is
     prompting you for arguments), `C-x C' displays documentation for
     the command being invoked.  This can often be used to get more
     information about what is being prompted for.

`C-h c'
     Give the name of the command (if any) associated with of the next
     keystroke(s).  For instance, to find out command is executed when
     you type  `M-p', type `C-h c M-p'. (`describe-key-briefly')

`C-h k'
     Give a brief description of the command associated with the next
     keystroke(s).  For instance, to find out what `M-p' does, type
     `C-h k M-p'. (`describe-key')

`C-h f'
     Give a  description of a command (one that you execute with
     `M-x').  For instance, to find out exactly what `scan-up' does,
     type `C-h f scan-up'.  (`describe-function')

`C-h F'
     Give a  description of a formula function.  For instance, to find
     out how to use  `@sum', type `C-h F sum'.  Note that even though
     `@sum' is used in `a0' mode, you must type `C-h F sum', not `C-h F
     @sum'.  (`describe-formula-function')

`C-h w'
     Give the key(s) (if any) that a command is bound to.  For example,
     to find which keys `scan-up' is bound to, type `C-h w scan-up'.
     (`where-is')

`C-h v'
     Show the value of a variable.  (`show-variable')

`C-h C-v'
     Show the values of all the variables. (`show-all-variables')

`C-h o'
     Show all the options that have been set. (`show-options')

`C-h W'
     Display all the bindings of the keys. (`view-wallchart')

`C-h C-w'
     Write all the bindings of the keys to a file. (`write-wallchart')

1.10 Saving and Reading Spreadsheets
====================================

`Oleo' can save a spreadsheet, visit a saved one, or merge with a
previously saved one.

`C-x C-s'
     Save the spreadsheet to a file, using the current file-format.
     (`save-spreadsheet') (1)

`C-x C-v'
     Read in a file in the current file-format.  This erases the
     current contents of the spreadsheet first.  This may ask for
     confirmation.  (`visit-spreadsheet')

`C-x i'
     Read in a file and merge its contents into the current
     spreadsheet.  Note that some file-formats, (like panic-save) won't
     work with this command.  (`merge-spreadsheet')

`M-x toggle-load-hooks'
     Change whether load-hooks are run when spreadsheets are loaded.
     When active, the find-alternate-spreadsheet command looks for a
     variable called `load_hooks' and executes the macro at that
     address.  With a positive prefix argument, turns load hooks on.
     With a negative argument, turns them off.  With no argument, acts
     as a toggle.  (2)

   ---------- Footnotes ----------

   (1) where is info on file formats?

   (2) what is the default

1.11 Command Line Options
=========================

At the command line, Oleo has several options

             oleo [options] [file]

   where `file' is an optional spreadsheet to open.  The remaining
options are

`-q'
`--quiet'
     Be quiet. (1)

`-V'
`--version'
     print out the version and exit

`-h'
`--help'
     Describe these options

`-f'
`--ignore-init-file'
     do not read the file `.oleorc' on startup

`--nw'
     do not use X-windows

`-F x'
`--format x'
     set the default file type to x (oleo, list, sc, ...)

`--filter'
     stdin/stdout are used for reading and writing the spreadsheet Note
     this only works well for X Window System user interfaces, or in
     very specific circumstances.

`-s x'
`--separator x'
     set separator for 'list' file type to x

`-S'
`--space'
     set separator for 'list' file type to a space

   ---------- Footnotes ----------

   (1) But what does this really do?

1.12 The `.oleorc' file
=======================

If there is a file `.oleorc' located in the home directory, it is read
when Oleo starts up.  For example, if you always want to use the `a0'
reference system, and wish to have the status line  on the bottom line,
rather than on the second line from the top, your `.oleorc' file could
be (1)

             set-option a0
             set-option status -1

   ---------- Footnotes ----------

   (1) what else can go here? can I set the default font here?

1.13 Expressions
================

A cell entry is a value or an expression of values (see Oleo values).

1.13.1 Infix Expressions
------------------------

The following infix expressions are defined.  Values labeled N1 and N2
are numbers (floats or integers), BOOL booleans, STR strings, and VAL
any type (but both sides must be the same type).

`-N1'
     Arithmetic negation: 0-N1

`!BOOL'
     Logical negation: `#TRUE' if BOOL is `#FALSE', `#FALSE' if
     `#TRUE', and an error otherwise.

`N1 ^ N2'
     Exponentiation.  Note that a^b^c is defined to be a^(b^c).

`N1 * N2'
     Multiplication

`N1 / N2'
     Division

`N1 + N2'
     Addition

`N1 - N2'
     Subtraction

`N1 % N2'
     Modulus; the remainder of N1 / N2.

`N1 >=N2'
     `#TRUE' if N1 is greater than or equal to N2; else `#FALSE'

`N1 > N2'
     `#TRUE' if N1 is greater than  N2; else `#FALSE'

`N1 < N2'
     `#TRUE' if N1 is less than N2; else `#FALSE'

`N1 <=N2'
     `#TRUE' if N1 is less than or equal to N2; else `#FALSE'

`VAL1 = VAL2'
     Comparison: `#TRUE' if VAL1 and VAL2 can be considered equal,
     `#FALSE' if not.  VAL1 and VAL2 can be numbers, strings, or
     boolean values.

`VAL1 != VAL2'
     Equivalent to `!(VAL1 = VAL2)'.

`STR1 & STR2'
     Text concatenation of strings.

`BOOL ? VAL1 : VAL2'
     Like the C operator: if BOOL is `#TRUE', VAL1 is evaluated; if
     BOOL is `#FALSE', VAL2 is evaluated; otherwise an error is
     returned.

`(EXPR)'
     Overrides default precedence of expression EXPR.  Note that since
     Oleo stores expressions in a byte-compiled form, unneeded
     parentheses will mysteriously vanish.

1.13.2 Examples
---------------

Assume that the spreadsheet contains the figure below, where the block
of X's marks the cursor.

                      |  C  |  D  |
                      |     |     |
                   --------------------
                      |     |     |
                   2  |  3  |     |
                   --------------------
                      |     |     |
                   3  | "A" | "B" |
                   --------------------
                      | XXX |     |
                    4 | XXX |  7  |
                   --------------------

   Here are some computations in  `a0' mode.

                     C2 * D4    =>     21

                     D4 % C2    =>     1

                     C2 = D4    =>     #FALSE

                     C3 < D3    =>     #TRUE

                     C3 & D3    =>     "AB"

1.13.3 Error Values
-------------------

Error values are returned by the parser under various error conditions,
such as invalid parameters to functions, badly formatted expressions,
etc.

`#TRUE'
`#FALSE'
     The boolean true and false values.  Not really errors, but
     classified as such to distinguish them from numbers and strings.

`#ERROR'
     An unclassified error.

`#BAD_INPUT'
     Indicates an inappropriate parameter to a formula function.

`#NON_NUMBER'
     A numerical value was expected.

`#NON_STRING'
     A string value was expected.

`#NON_BOOL'
     A boolean value was expected.

`#NON_RANGE'
     A range value was expected.

`#OUT_OF_RANGE'
     An out-of-range value was given, such as a cell coordinate outside
     a given cell range.

`#NO_VALUES'
     An error value.

`#DIV_BY_ZERO'
     A division by zero was attempted.

`#BAD_NAME'
     An error value that indicates an invalid variable name.  It may be
     the symptom of an incorrectly written address, or a string literal
     given without double quotes.

`#NOT_AVAIL'
     An error value.

`#PARSE_ERROR'
     A generic error value that indicates the parser failed to parse an
     expression.

`#NEED_OPEN'
     An open parenthesis is missing.

`#NEED_CLOSE'
     A close parenthesis is missing.

`#NEED_QUOTE'
     A quote was expected; e.g., the terminating quote of a string
     literal.

`#UNK_CHAR'
     An unknown character was encountered.

`#UNK_FUNC'
     An unknown function was called.

`#INF'
`#INFINITY'
`#NINF'
`#MINUS_INFINITY'
`#NAN'
`#NOT_A_NUMBER'
     Various floating-point exceptions.  On some machines these may be
     all the same value, or indistinguishable from other values.

2 Entering Data
***************

2.1 The different values in Oleo
================================

A value can be a literal (an immediate value, like `"foo"', `16', or
`#TRUE'), a function call, or another expression.  There are 5 types of
values:

   * Integers.

   * Floats, expressed in the usual format:
     [`-']NNN[`.'NNN][`e'[`-']NNN], e.g., -103.14e-7 or .00000012 or
     103.14.

   * Strings, which are surrounded by double quotes.  To include
     unusual characters, you can either quote them with a backslash
     (e.g., `"This is \"quoted\"."') or use an octal escape code: `\NNN'
     where NNN is the octal code for the ASCII value of the character.

   * Expressions, such as `@sum(A1.B3)', or `A1 + B2'.

   * Errors, which have alphabetic names and start with a `#' sign.

   * Booleans, which are "error" values of either `#TRUE' or `#FALSE'.

2.2 Entering values in a cell
=============================

To enter values into an empty cell, simply start typing.  To replace
the contents of a cell or of all cells in a region, use

`='
     Replace the contents of the current cell. (`set-cell')

`M-='
     Replace the contents of a region. (`set-cell-region')

   For example, to put the numbers 2,3,...,11 in the  cells from `B1' to
`B10', type
             <M-=>  B1.B10   <RET>   @row()+1   <RET>

2.3 Editing in the input line
=============================

When the spreadsheet is reading text input, you can use a few
text-editing commands.  Note that there in no history mechanism and no
yank command.  If you accidentally type `C-u', the text is _erased_.
(1)

   While the input area is active, the commands that move the cell
cursor are disabled.  If you want to move the cell cursor, use the
other-window command (`C-x o') to leave and later reenter the input
area.

`M-a'
     Insert/over-write an absolute reference to the current
     cell/region. (`insert-abs-ref')

`M-r'
     Insert/over-write a relative reference to the current cell/region.
     (`insert-rel-ref')

`C-e'
     Insert/over-write the expression in the current cell into the
     input area. (`insert-cell-expression')

`M-e'
     Insert/over-write the value (not the formula) of the current cell
     into the input area. (`insert-cell-value')

`C-a'
     Move the cursor to the beginning of the text. (`cursor-begin-line')

`C-e'
     Move to the end of the text. (`cursor-end-line')

`C-b'
     Move the cursor back a character. (`cursor-back-char')

`M-b'
     Move back a word. (`cursor-back-word')

`C-f'
     Move forward a character. (`cursor-fwd-char')

`M-f'
     Move forward a word. (`cursor-fwd-word')

`C-d'
     Delete the character under the cursor. (`delete-next-char')

`M-d'
     Delete the word under the cursor.  (`delete-next-word')

`C-?'
     Delete the character to the left of the cursor.
     (`delete-prev-char')

`M-C-?'
     Delete the word to the left of the cursor. (`delete-prev-word')

`C-k'
     Delete from the cursor to the end of the text. (`delete-to-end')

`C-o'
     Move the cursor into the cell area.

   The following commands are not bound to any keys
`toggle-overwrite'
     Toggle between overwrite and insert mode.

`delete-to-start'
     Deletes from the cursor to the beginning of the line

   Almost all editing commands remember what you typed the last time
you used that command, and start you up editing a copy of that text.
If you want to type in something completely new, just type `C-x' (or
`C-u') and type in your new text.

   ---------- Footnotes ----------

   (1) This will be improved in the future.

2.4 Moving to the next input cell while editing
===============================================

When you are finished entering data in a cell, you type <RET>. If you
wish to enter data in the cell below, type either `C-i' or the
down-arrow key, and you are placed in the  cell below, waiting for
input.  If you type the up-arrow key, you are placed in the cell above,
waiting for input.  If you type `C-j', you move to the right.  The
direction of `C-i' can be changed - the commands are  given below.  For
example, if you wish to move upwards when you type `C-i', type `C-x m
^'.

`C-i'
     Enter the data, and move to next cell.  The tab key also does this.
     (`next-edit')

`C-j'
     Enter the data, and move to next cell in alternative direction
     (`next-edit-set')

`C-x m ^'
     `auto-move-up'

`C-x m v'
     `auto-move-down'

`C-x m <'
     `auto-move-left'

`C-x m >'
     `auto-move-right'

`C-x m `'
     `auto-move-up-left'

`C-x m ''
     `auto-move-up-right'

`C-x m /'
     `auto-move-down-left'

`C-x m \'
     `auto-move-down-right'

`C-x m'
     `auto-move-no-motion'

3 Making Changes
****************

3.1 Copying
===========

Both the cells, and the calculated values in the cells, can be copied
from one location to another. Note, however, that any relative cell
addresses present in formulas will refer to different cells - those at
the same offset from the new location.  In `a0' mode, this means that
the relative addresses in the new locations' formula(s) will change to
reflect the new cells they refer to.

`M-c'
     Copy a region.  Given two ranges, it copies the source range into
     the destination range.  If the destination range size is a
     multiple of the source range size, the source range is copied
     multiple times.  If the destination range is given as a cell, that
     cell is the location of the top-left corner of the destination
     range.  (`copy-region')

`M-C-c'
     Copy just the values of one region to another.
     (`copy-values-in-region')

   Consider the  spreadsheet, where `B2' contains `@sum(C2.D2)':

                  | Col B | Col C | Col D |
            ------|-------|-------|-------|
            Row 2 |   8   |   3   |   5   |
            ------|-------|-------|-------|
            Row 3 |       |   4   |   2   |
            ------|-------|-------|-------|
            Row 4 |       |   1   |   3   |
            ------|-------|-------|-------|

   If you type `M-c B2 <RET> B3.B4', then `B2' is unchanged, but `B3'
contains `@sum(C3.D3)', since it was copied from a formula with
relative addresses. Similarly, `B4' contains `@sum(C4.D4)'.  The
display shows

                  | Col B | Col C | Col D |
            ------|-------|-------|-------|
            Row 2 |   8   |   3   |   5   |
            ------|-------|-------|-------|
            Row 3 |   6   |   4   |   2   |
            ------|-------|-------|-------|
            Row 4 |   4   |   1   |   3   |
            ------|-------|-------|-------|

   If you had typed `M-C-c B2 <RET> B3.B4', then `B2' is unchanged,
`B3' contains 8, `B4' contains 8, and the display shows

                  | Col B | Col C | Col D |
            ------|-------|-------|-------|
            Row 2 |   8   |   3   |   5   |
            ------|-------|-------|-------|
            Row 3 |   8   |   4   |   2   |
            ------|-------|-------|-------|
            Row 4 |   8   |   1   |   3   |
            ------|-------|-------|-------|

3.2 Moving Cells and Regions
============================

`M-m'
     This is similar to copy-region, except that the source region is
     erased after the copy.  The two ranges must be the same size.
     Relative addresses and variables whose ranges are inside the
     source region are adjusted, as with `copy-region'. (1)
     (`move-region')

   Consider the previous spreadsheet, where `B2' contains `@sum(C2.D2)'.

                  | Col B | Col C | Col D |
            ------|-------|-------|-------|
            Row 2 |   8   |   3   |   5   |
            ------|-------|-------|-------|
            Row 3 |       |   4   |   2   |
            ------|-------|-------|-------|
            Row 4 |       |   1   |   3   |
            ------|-------|-------|-------|

   If we type `M-m  B2  <RET>  B3', then `B2' is empty, `B3' contains
`@sum(C3.D3)', and the display shows

                  | Col B | Col C | Col D |
            ------|-------|-------|-------|
            Row 2 |       |   3   |   5   |
            ------|-------|-------|-------|
            Row 3 |   6   |   4   |   2   |
            ------|-------|-------|-------|
            Row 4 |       |   1   |   3   |
            ------|-------|-------|-------|

   ---------- Footnotes ----------

   (1) This can be subtle - some good examples are needed

3.3 Deleting
============

`C-k'
     Delete the current row.  With an argument count it deletes several
     rows. (`delete-row') For instance, to delete the row containing
     the cell cursor, and the next 4 rows, type `C-u 5 C-k'.

`M-k'
     Delete the current column.  With an argument count it deletes
     several columns. (`delete-col') For instance, to delete the column
     that the cell cursor is in, and the 3 columns to the right, type
     `C-u 4 M-k'.

`M-C-?'
     Delete the contents (value, formula, format, etc) of a region.
     This DOES NOT ask for confirmation.          (`delete-region')

`M-x clear-spreadsheet'
     This is an extreme action!  Erase all the values in the cells, and
     reset all the heights and widths.

3.4 Inserting Rows and Columns
==============================

These commands insert blank rows and columns.

`C-o'
     Insert a row above the cell cursor.  With an argument count it adds
     several rows. (`insert-row') For instance, to add 5 rows above the
     cell cursor, type `C-u 5 C-o'.

`M-o'
     Insert a column to the left of the cell cursor.  With an argument
     count it adds several columns. (`insert-col') For instance, to add
     4 rows to the left of  the cell cursor, type `C-u 4 M-o'.

4 Style
*******

It is often important to change how the value of a cell is displayed.
It is possible to change the height and width of a cell, the font used
in a cell, the alignment and protection of a cell, and the formats used
to represent numbers.  Entire rows and columns can be hidden.

4.1 Alignment
=============

An entry in a cell can be aligned on the left, on the right, or
centered.   All cells in a region can have their alignment set.  The
default is left alignment.

`M-a a'
     Change the alignment of the cell under the cursor.  The options are
     `def' (the default), `l' (left), `r' (right), and `c' (center).
     (`set-cell-alignment').

`M-r a'
     Change the alignment of a region.  The options are the same as
     above.  (`set-region-alignment').

`M-d a'
     Change the default alignment.  The options are `l' (left), `r'
     (right), and `c' (center).  (`set-default-alignment').

4.2 Formats for numbers
=======================

Oleo can display numbers in a variety of formats.  In addition to
sixteen user-defined formats, you can choose from a variety of simple
formats.  You can set the format for a cell, for a region, and change
the default format.

`M-a f'
     Change the format of the cell under the cursor.  The options
     include INTEGER, FLOAT, HIDDEN, GRAPH, GENERAL.X, DOLLAR.X,
     COMMA.X, COMMA.X, PERCENT.X, FIXED.X, EXPONENT.X,  where X is an
     integer from 0 to 14, or the word FLOAT.  (`set-cell-format').

`M-r f'
     Change the format of a region.  The options are the same as above.
     (`set-region-format').

`M-d f'
     Change the default format.  The options are as above.
     (`set-default-format').

   There are some examples following a description of the simple and
general formats.

4.2.1 Simple Formats
--------------------

`integer'
     The number is rounded to an integer before being displayed.

`float'
     The number is displayed in normal, everyday notation, using
     whatever precision is needed (or fits).

`hidden'
     The number is not displayed.  It is recalculated, etc as normal,
     but the cell is displayed as if it were empty.

`graph'
     The number is displayed as a small graph.  If the number is close
     to zero, it will be displayed as '0', If it is positive, a row of
     '+'-es is displayed.  If it is negative, a row of '-'-es is
     displayed.  For instance, the number 4.234 is displayed as ++++,
     and the number -5.2 is displayed as ----.  If the number has
     absolute value greater than 70 (1), then a string of 35 #'s is
     displayed.

4.2.2 General Formats
---------------------

The following formats require a precision.  The precision may be a
number from zero to 14, in which case that number of digits will always
be displayed after the decimal point (zero-padding or rounding the
number as needed), or the precision may be 'float', in which case Oleo
will use as many digits as necessary.

`general'
     This uses either normal or scientific notation, depending on the
     magnitude of the number and the width of the column.

`dollar'
     Positive values are preceeded by '$', (so 3 is displayed as '$3').
     Negative values are parenthesized (so -3 is displayed as '($3)'),
     and all large values have a ',' every three digits (so 1000 is
     displayed as '$1,000').

`comma'
     This is like the dollar option, but without the '$'.  Positive
     numbers are presented normally, and negative ones are in
     parenthesis.

`percent'
     The value is multiplied by 100, and is displayed with a trailing
     '%'.  Thus .01 displays as '1%', while 1 displays as '100%'.

`fixed'
     The number is displayed in normal, everyday notation, using the
     precision specified.  'fixed.float' is the same as 'float'.
     'fixed.0' is the same as 'integer'.

`exponent'
     The number is displayed in scientific notation.

4.2.3 StyleExamples
-------------------

Suppose that a cell contains `1234.567'.  If we set the format of the
cell to the left hand column, the cell is displayed as in the right
hand column:

                integer          1234
                hidden
                general.float    1234.567
                general.1        1234.6
                dollar.0       $1,234
                dollar.2       $1,234.57
                comma.1         1,234.6
                percent.0      123457%
                fixed.1          1234.6
                exponent.2        123e+03

4.2.4 User Defined Formats
--------------------------

You can define up  to sixteen user-defined numeric formats.  The
current parts of a format are in the table below.  We use the
definition of the 'dollar' format for an example.  (2)

`Example:'
     What it is:

`$'
     What to print before positive numbers.

`('
     What to print before negative numbers.

`'
     What to print after positive numbers.

`)'
     What to print after negative numbers.

`$0'
     What to print if the number is zero.

`,'
     What to print between the thousands and the 	hundreds, etc.

`.'
     What to print for a decimal point.

`0-14'
`float'
     The number of digits to print after the decimal point.  'float'
     means use however many digits are needed, or however many will
     fit, whichever is less. . .

`number'
     What to multiply the value by before printing.  Most often this
     will be one, but it might be 100 if you're printing percentages,
     or .000001 if you're printing in megabucks.  (Beware of overflow!)

   Some advice: do not use digits for the headers, trailers, the comma,
or the decimal point symbol.  Using digits will confuse the internal
routines and produce incomprehensible results. . .  (3)

   ---------- Footnotes ----------

   (1) is this fixed?

   (2) this does not appear to be implemented

   (3) Should the set-user-format command check its input for validity?

4.3 Changing the height of cells
================================

The height of all the cells in a row is the same.  The default height
of a row is 1.  A row of height 0 is not displayed, but is still
updated just as if it were visible.  (1)

`M-a h'
     Change the height of the row containing the cell cursor.  The
     options are a non-negative integer, or `def'.  (`set-cell-height').

`M-r h'
     Change the height of all cells in a region.  The options are the
     same as above.  (`set-region-height').

`M-d h'
     Change the default height to a positive integer.
     (`set-default-height').

   ---------- Footnotes ----------

   (1) what is the unit of height

4.4 Changing the width of cells
===============================

The width of all the cells in a column is the same.  The default width
of a column is 11.  (1)  A column of width 0 is not displayed.

`M-a w'
     Change the width of the column containing the  cell cursor.  The
     options are a non-negative integer, or `def'.  (`set-cell-width').

`M-r w'
     Change the width of all cells in a region.  The options are the
     same as above.  (`set-region-width').

`M-d w'
     Change the default width to a positive integer.
     (`set-default-width').

   ---------- Footnotes ----------

   (1) is it?

4.5 Creating Hidden Rows and Columns
====================================

Rows and columns of the spreadsheet can be hidden, so that they do not
appear on the screen.  They continue to exist, and are updated when
necessary.  The following  hides the third column in `a0' mode

                M-x set-region-width <RET> C1 <RET> 0 <RET>

   or more simply,

                M-r w C1 <RET> 0 <RET>

   This  hides the third row in `noa0' mode

                M-r h <RET> R3C1 <RET> 0 <RET>

   If the cell cursor is located at any cell in the third column, then
we can  hide the third column column:
                M-a w  0 <RET>

   Similarly, if the cell cursor is in the fourth row, we can hide the
fourth row:
                M-a h  0 <RET>

   To make a row visible again, just set its height to some positive
value.

4.6 Protection
==============

A cell can be protected.  For example, if cell `E5' is protected, and
you attempt to enter data into it, you are  not allowed to.  Instead,
you get the message
             Cell C5 is locked.
   Moreover, all the cells in a region can be protected.  It is also
possible to make the default protection "locked", so that all cells are
automatically locked.

   The default is that all cells are unlocked.
`M-a p'
     Change the protection of a cell.  The options are `def' (the
     default), `p' (protect, or lock), and `u' (unprotect, or unlock).
     (`set-cell-protection').

`M-r p'
     Change the protection of a region.  The options are the same as
     above.  (`set-region-protection').

`M-d p'
     Change the default protection.  The options are `p' (protect, or
     lock), and `u' (unprotect, or unlock).  (`set-default-protection').

4.7 Fonts (in X11)
==================

The default cell font is 12 point times-roman.  The easiest way to
specify a font is to use one of the built-in short-hand names.  These
names are `fixed', `times', and `courier'.  Optionally, these names can
be followed by a scale.  The scale is the ratio of the default point
size to the desired point size. For example, if the default font is a
10 point font, then `times 1.2' refers to a 12 point Times-Roman type
font.

`M-a o'
     Use this command to set the font in a cell.  For instance, to set
     the current cell to `times-roman' at 24pt, type
                  M-a o times <RET> 2.0  <RET>
     Since the default size is 12pt, the 2.0 magnification factor makes
     the size 24 points. (`set-cell-font')

`M-r o'
     Use this command to set the font in a region.  For instance, to
     set the range `A1.E3' to `courier' at 12pt, type
                  M-r o courier <RET> 1.0   <RET>
     (`set-region-font')

`M-d o'
     Use this command to set the default font.  For instance, to set
     the range `A1.E3' to `fixed' at 12pt, type
                  M-r o fixed <RET> 1.0  <RET>
     All cells whose font has not been specified have the default font,
     so changing this will change the font in the entire spreadsheet.
     (`set-default-font')

`M-x set-default-point-size'
     Set the default point size.  To set the default point size to 10,
     type
                  M-x set-default-point-size <RET> 10  <RET>
     (`set-default-point-size')

`M-x define-font-name'

5 Multiple Windows
******************

Oleo can split a spreadsheet into two or more windows.   The windows
showing the spreadsheet can show different parts of it.  Only one
spreadsheet can be displayed at a time.

5.1 Concepts of Oleo Windows
============================

At any time, one of the windows is the "selected window".    The cell
cursor is located in this window.  Each other window has a location of
point as well, but since the terminal has only one cell cursor there is
no way to show where those locations are.

   Commands to move the cell cursor affect the cell cursor for the
selected Oleo window only.  They do not change the value of the cell
cursor in any other Oleo window.

   When there are multiple windows,  they can have different regions,
because they can have different values of the cell cursor.

5.2 Splitting Windows
=====================

`C-x 2'
     Split the selected window into two windows, one above the other
     (`split-window-vertically').

`C-x 5'
     Split the selected window into two windows positioned side by side
     (`split-window-horizontally').

   The command `C-x 2' (`split-window-vertically') breaks the selected
window into two windows, one above the other.  Both windows start out
displaying the cell cursor in the same position.  By default the two
windows each get half the height of the window that was split.

   `C-x 5' (`split-window-horizontally') breaks the selected window
into two side-by-side windows.

5.3 Using Other Windows
=======================

`C-x o'
     Select another window (`other-window').  That is `o', not zero.

`M-C-v'
     Scroll the next window (`scroll-other-window').

   To select a different window, use `C-x o' (`other-window').  That is
an `o', for `other', not a zero.  When there are more than two windows,
this command moves through all the windows in a cyclic order, generally
top to bottom and left to right.  After the rightmost and bottommost
window, it goes back to the one at the upper left corner.  When the
minibuffer is active, the minibuffer is the last window in the cycle;
you can switch from the minibuffer window to one of the other windows,
and later switch back and finish supplying the minibuffer argument that
is requested.

   The usual scrolling commands  apply to the selected window only, but
there is one command to scroll the next window.  `C-M-v'
(`scroll-other-window') scrolls the window that `C-x o' would select.

5.4 Deleting and Rearranging Windows
====================================

`C-x 0'
     Get rid of the selected window (`delete-window').  That is a zero.

`C-x 1'
     Get rid of all windows except the selected one
     (`delete-other-windows').

   To delete a window, type `C-x 0' (`delete-window').  (That is a
zero.)  The space occupied by the deleted window is given to an
adjacent window.  Once a window is deleted, its attributes are
forgotten.

   `C-x 1' (`delete-other-windows') is more powerful than `C-x 0'; it
deletes all the windows except the selected one (and the minibuffer);
the selected window expands to use the whole frame.

6 Options
*********

Oleo has various options.  They can be set as a default in the
`.oleorc' file, or using the command `M-x set-option'.  To see all the
current options, type `C-h o'.

6.1 Changing Oleo's appearance
==============================

`a0'
     In a0 mode, Oleo uses {letters}{digits} style cell-references,
     like some popular spreadsheets.

`noa0'
     In noa0 mode, Oleo uses R{digits}C{digits} style references, like
     some other popular spreadsheets.  (`Default')

`status'
     This option controls which line on the screen is used for
     displaying the status of the current cell.  The number may be
     positive, (counting down from the top), negative (counting up from
     the bottom, or zero (disabling the status line).  (`Default=2')

`input'
     This option controls which line on the screen is used for reading
     lines of text.  The number may be positive (counting down from the
     top), or negative (counting up from the bottom), but not zero.
     (`Default=1')

`edges'
     In edges mode Oleo displays row and column numbers at the top and
     left edges of the window. (`Default')

`noedges'
     Row and column numbers are not displayed.

`standout'
     In standout mode, the edges  are drawn in standout mode (reverse
     video, usually). (`Default')

`nostandout'
     Edges are not drawn in standout mode.

`list (ch)'
     		Use the character CH to separate the cell values.  (1)

   ---------- Footnotes ----------

   (1) example? it it `M-x set-option list ","'?

6.2 Options for the active window
=================================

The following options affect the currently active window:

`page'
     In page mode, whenever a particular cell is displayed in the
     window, it will always be in the same location on the screen.  In
     page mode, the recenter command acts just like the redraw-screen
     command.

`nopage'
     Turns off page mode.

`pageh'
     Turns on  page mode only in the horizontal direction.

`nopageh'
     Turns off  page mode only in the horizontal direction.

`pagev'
     Turns on  page mode only in the vertical direction.

`nopageh'
     Turns off  page mode only in the vertical direction.

`link'
     This option 'links' the current window with the one specified.  A
     window may only be linked to one other window at a time.  When a
     window is linked to another one, whenever the cell cursor in the
     first window is moved, the cursor in the other window moves as
     well.  (unless the cursor in other window is locked from moving in
     that direction.)

`nolink'
`unlink'
     This removes the link (if any) on the current window.

`lockh'
     Prevent the cell cursor in the current window from moving in the
     horizontal direction, but only when the cell cursor is moved in a
     window that this one is linked.

`nolockh'
     Disable horizontal locking

`lockv'
     Prevent the cell cursor in the current window from moving in the
     vertical direction, but only when the cell cursor is moved in a
     window that this one is linked.

`nolockv'
     Disable vertical locking

6.3 Other Options
=================

`auto'
     In auto mode, cells whose values may have changed are
     automatically recalculated.  (`Default')

`noauto'
     In noauto mode, cells are only recalculated when the recalculate
     command is used.

`bkgrnd'
`background'
     In background mode, automatic recalculation is done while the
     spreadsheet waits for you to type a key (and stops while the key
     is being handled).  (`Default')

`nobkgrnd'
`nobackground'
     In nobackground mode, Oleo performs all its recalculation before
     listening for keystrokes.

`backup'
     In backup mode, whenever the spreadsheet writes out a file, if the
     file already exists, a backup copy is made (like emacs).
     (`Default')

`nobackup'
     A backup copy is not made.

`bkup_copy'
     In bkup_copy mode, backup files are made by copying the original
     file, instead of renaming it.

`nobkup_copy'
     In nobackup mode bkup_copy is ignored. (`Default')

`ticks'
     This value controls how often should rnd(), cell(), my(),
     curcell(), etc cells get updated.  This value is in seconds. (1)
     The initial value is 10, meaning once every 10 seconds.

`print'
     This is the width of the page for the print command.  The initial
     value is the width of the screen.

`file'
     (2) If -DUSE_DLD was defined, format-name may be any .o file that
     contains definitions for the appropriate functions, or 'panic',
     which is the only file format that Oleo will have compiled into
     it.  If -DUSE_DLD was not defined, format-name must be one of
     sylk, sc, panic, or list, and Oleo will have to be re-compiled
     before any other formats may be used.

`load (file-name)'
     (3)This option is only avaliable if Oleo was compiled with
     -DUSE_DLD.  This option loads in a .o file of spreadsheet
     functions, keyboard commands, and/or keymaps.  Spreadsheet
     functions and keyboard commands must be loaded in before they can
     be used in expressions or bound to keys.

   ---------- Footnotes ----------

   (1) is it?

   (2) I don't understand this

   (3) nor do I understand this one

7 Printing and Plotting
***********************

7.1 Writing  ASCII and Postscript Files
=======================================

Spreadsheets, and regions of spreadsheets,  can be printed in ASCII,
LaTeX, or postscript format.  For postscript files, the font and page
size can be specified.

`M-C-p a'
     Write a region to a file in ASCII format.  If the mark is set, you
     are prompted for a file name.  The region between mark and cell
     cursor will be printed in a tabular ASCII format. If the mark is
     not set, then you are first prompted for the region, and then for
     the file name.  (`print-region') For example, if the mark is not
     set, and you want to print the region A1.C20 to the file
     `/tmp/myfile', then you type
                       M-C-p a A1.C20 <RET> /tmp/myfile <RET>

     If the mark had been set so that the region between mark and the
     current cell is A1.C20, then you only need type
                       M-C-p a  /tmp/myfile <RET>

`M-C-p l'
     Write a region to a file in LaTeX format.  By default the LaTeX
     code prints the entries in ruled boxes in portrait mode.  There are
     directions in the output file for the simple changes to print in
     landscape mode, or to have all the entries unboxed.  If your region
     contains a percent sign, then you must escape it by hand in the
     LaTeX file to make LaTeX run correctly.

     If the mark is set, you are prompted for a file name.  The region
     between mark and cell cursor will be printed in LaTeX format.  If
     the mark is not set, then you are first prompted for the region,
     and then for the file name.  (`latex-region') For example, if the
     mark is not set, and you want to print the region A1.C20 to the
     file `/tmp/myfile.tex', then you type
                       M-C-p l A1.C20 <RET> /tmp/myfile.tex <RET>

     If the mark had been set so that the region between mark and the
     current cell is A1.C20, then you only need type
                       M-C-p l  /tmp/myfile.tex <RET>

`M-C-p p p'
     Write a region to a file in PostScript format.  If the mark is
     set, you are prompted for a file name.  If the mark is not set,
     then you are first prompted for the region, and then for the file
     name.  (`psprint-region') For example, if the mark is not set, and
     you want to write the region A1.C20 in PostScript to the file
     `/tmp/myfile', then you type
                       M-C-p p p A1.C20 <RET> /tmp/myfile <RET>

     If the mark had been set so that the region between mark and the
     current cell is A1.C20, then you only need type
                       M-C-p p p  /tmp/myfile <RET>

`M-C-p p f'
     This command sets the default font used in printing a region in
     PostScript.  (`set-default-ps-font') Fonts (in X11) for
     information about the possible fonts.  To set the font to 24 point
     courier, type
                     M-C-p p f courier 2.0 <RET>(1)

`M-C-p p s'
     Set the page size for the PostScript output (`set-page-size'). You
     are prompted for a pagesize.  There are several possible ways of
     describing a page size:

                  8.5x11          -- a page size in inches.
                  22x28c          -- a page size in centimeters.
                  612x792p        -- a page size in points.
                  letter          -- 8.5 x 11 in. (the default)

     To set the correct page size for A4 paper, type

                   M-C-p p s A4 <RET>

     The following table gives the possible paper sizes.  The widths
     and heights are given in "points", of which there are 72 in an
     inch.

             Name            Width   Height    Comments
             ------------------------------------------------
             letter          612     792       8.5 x 11   in.
             landscape       792     612       11  x 8.5  in.
             tabloid         792     1224      11  x 17   in.
             ledger          1224    792       17  x 11   in.
             legal           612     1008      8.5 x 14   in.
             statement       396     612       5.5 x 8.5  in.
             executive       540     720       7.5 x 10   in.
             a3              842     1190
             a4              595     842
             latex-a4        523     770       A4 with 1in. margins
             a5              420     595
             b4              729     1032
             b5              516     729
             folio           612     936       8.5 x 13  in.
             quarto          610     780

   ---------- Footnotes ----------

   (1) actually, this does not print correctly - ghostscript gives an
error

7.2 Graphing Using GNU Plotutils
================================

Note: this chapter is only partially updated, however functionality has
changed drastically !!

   Plotting in Oleo is done using GNU Plotutils. (Versions prior to
Oleo 1.99.12 used gnuplot.) Currently these types of graphs are
supported :
   * XY

   * bar

   * pie

   There are two modes in which Oleo can produce plots on the fly :
   * in a Motif window

   * in Xterm using its Tektronix emulation

   The former is the default behaviour of you use the Motif interface
of Oleo, the latter can be initialised by this sequence :
             M-g  o  t  f - <RET>

   This sequence sets output device to Tektronix, and output file to -
which means to standard output. Sending Tektronix formatted output to
an xterm will pop up xterm's Tektronix emulation window which shows the
plot.

   The file examples/xy.oleo can be used to show a simple XY plot in
this way.

   Oleo can print up to 10 different data sets at once.  The data sets
are numbered 0,1,...,9.

   When the plot command (`p') is chosen, all the currently defined
data sets will be plotted.

7.2.1 Clearing the Plots
------------------------

The plot ranges and styles are remembered; if you decide to plot using
`M-g', you probably want to clear the ranges and styles using the `C'
and `R' keys in the main graph menu:

`C'
     Clear all the datasets (0-9) of their ranges.

`R'
     Remove all the style information from all datasets

7.2.2 Choosing a data set
-------------------------

The key `d' is used to choose a range for a data set.  If the mark is
active, then the region between the mark and the current cell is chosen
as the data set.  Otherwise, you are prompted for the range.

   When you define a data set (using the `d' key in the graph menu),
you select a number to refer to the data set.  If we are already in the
graph menu (having typed `M-g'), then the following assigns the region
G5.L6 to data set 4:
                           d  4  <RET> G5.L6  <RET>

   If the mark is set, then it is not necessary (nor possible) to enter
the range.  Thus, if the mark is set to G5 and the cursor is in L6,
then these commands set the fourth data set to G5.L6:
                           d  4  <RET>

                       | Col B | Col C | Col D | Col E | Col F |
                 ------|-------|-------|-------|-------|-------|
                 Row 2 |   11  |   33  |  55   |   77  |   99  |
                 ------|-------|-------|-------|-------|-------|
                 Row 3 |   22  |   44  |  66   |   88  |    0  |
                 ------|-------|-------| ------|-------|-------|

   and that we are in the graph menu.
   * If we type `d 4 RET B2.F3 RET', then when we print there will be
     three line segments:

               (11,33) -- (22,44) -- (55,77) -- (66,88)

   * If we type `d 4 RET B2.F3 RET', then when we print there will be
     four line segments:

               (11,22) -- (33,44) -- (55,66) -- (77,88) -- (99,0)

   * If we type `d 4 RET B2.F3 RET', then when we print there will be
     nine line segments.  Notice that all the items in the first row are
     plotted, then all the ones in the second row, and so on.

          (0,11)--(1,33)--(2,55)--(3,77)--(4,99)--(5,22)--(6,44)--(7,66)--(8,88)--(9,0)

   Finally, you are asked about labels.  (1)

   ---------- Footnotes ----------

   (1) I don't understand them

7.2.3 Changing the axes style
-----------------------------

The commands `x' and `y' allow you to control the axes style.

`['
     You are prompted for the lower limit of the range.

`]'
     You are prompted for the upper limit of the range.  For instance,
     to set the range of the x-axis to [-3,5], type the following in
     the graph menu:
                        x [ -3 <RET>
                        x ]  5 <RET>

`s'
     Use a symbolic expression for the range (1)

`l'
     Use values in the spreadsheet for the ticks on the axis.  (2)

`L'
     Restore the default tick marks for the axis.  This undoes the
     effect of the `l' command.

   ---------- Footnotes ----------

   (1) what?

   (2) example?

7.2.4 Viewing your choices
--------------------------

Typing `v' in the main graph menu gives a help screen with all of your
choices.  A typical  help screen is

         Graph type is XY plot.

         Parameter               Value

         output type             Tektronix
         output file             -
         x-axis title            "Tijd"
         y-axis title            "Appelen"
         logarithmic axes        -neither-
         x-axis range            [def..def]
         y-axis range            [def..def]

         Data Set 0
           data for this set: A1:A6
           style for this set: lines

         Data Set 1
           data for this set: C4:C9
           style for this set: lines

7.2.5 The Output Type
---------------------

The `o' key in the main graph menu selects the type of output.  A graph
can be drawn in several ways - see the table below.

   Note however that, depending on compilation parameters, not all of
the options documented below may be available (e.g. no X or x commands).

`p'
     Write a file of PostScript commands that draw that graph.

`X'
     Draw the graph in an X window, in color.

`t'
     Write Tektronix graphics terminal commands.

`r'
     Write ReGIS commands (VT340 type terminals, most VT emulators
     don't support this)

`P'
     Write PCL printer commands.

`h'
     Write HP-GL plotter command language.

`i'
     Write Adobe Illustrator format.

`m'
     Write GNU Metaplot format.

`f'
     Write FIG output

`n'
     Write PNG (Portable Network Graphics, an unencumbered replacement
     for GIF)

`g'
     Write GIF format

`x'
     Draw the graph in an X window, in black and white.

7.2.6 Picking a plot style
--------------------------

The `s' option on the main graph menu selects the graph style.  There
are 5 possibilities:(1)

`lines'
     The _lines_ style connects adjacent points with lines. (Default)

`points'
     The _points_ style displays a small symbol at each point.

`impulses'
     The _impulses_ style displays a vertical line from the x axis to
     each point.

`dots'
     The _dots_ style  plots a tiny dot at each point; this is useful
     for  scatter plots with many points.

`linespoints'
     The _linespoints_ style does both _lines_ and _points_.

   ---------- Footnotes ----------

   (1) gnuplot has 9 styles; should these be added?

7.2.7 Naming a data set
-----------------------

The `d' option on the main graph menu allows a name to be attached to a
data set.  The default name of the i-th data set is "Data set i".  When
the graphs are plotted, each graph is printed with a different line
type, and the names of the data set and their line type are printed in
the upper right corner. The name must be in quotes. (1) To add the name
"my Fermat plot" to  data set 3, type

           n  3  <RET>   "my Fermat plot"  <RET>

   ---------- Footnotes ----------

   (1) this is not a good choice

8 Macros
********

8.1 Keyboard Macros
===================

A "keyboard macro" is a command defined by the user to abbreviate a
sequence of keys.  For example, if you discover that you are about to
type `C-b' forty times, you can speed your work by defining a keyboard
macro to do `C-b' and calling it with a repeat count of forty.  (1)

`C-x ('
     Start defining a keyboard macro (`start-kbd-macro').

`C-x )'
     End the definition of a keyboard macro (`end-kbd-macro').

`C-x e'
     Execute the most recent keyboard macro (`call-last-kbd-macro').

`C-x ='
     Store the most recent keyboard macro (`store-last-kbd-macro').

   Keyboard macros differ from ordinary Oleo commands in that they are
simply records of keystrokes.  This makes it easier for the novice to
write them, and makes them more convenient as temporary hacks.
However, the Oleo command language is not powerful enough as a
programming language to be useful for writing anything intelligent or
general.  For such things, functions and programs must be used.

   You define a keyboard macro while executing the commands which are
the definition.  Put differently, as you define a keyboard macro, the
definition is being executed for the first time.  This way, you can see
what the effects of your commands are, so that you don't have to figure
them out in your head.  When you are finished, the keyboard macro is
defined and also has been, in effect, executed once.  You can then do
the whole thing over again by invoking the macro.

   ---------- Footnotes ----------

   (1) does repeat count work?

8.2 Basic Use
=============

To start defining a keyboard macro, type the `C-x (' command
(`start-kbd-macro').  From then on, your keys continue to be executed,
but also become part of the definition of the macro.  `Def' appears in
the status line to remind you of what is going on.  (1)   When you are
finished, the `C-x )' command (`end-kbd-macro') terminates the
definition (without becoming part of it!).  For example

     C-x ( M-f foo C-x )

defines a macro to move forward a word (while editing the input line)
and then insert `foo'.

   The macro thus defined can be invoked again with the `C-x e' command
(`call-last-kbd-macro'), which may be given a repeat count as a numeric
argument to execute the macro many times.

   If you wish to repeat an operation at regularly spaced places in the
spreadsheet, define a macro and include as part of the macro the
commands to move to the next place you want to use it.

   You can use function keys in a keyboard macro, just like keyboard
keys.  You can even use mouse events, but be careful about that: when
the macro replays the mouse event, it uses the original mouse position
of that event, the position that the mouse had while you were defining
the macro.  The effect of this may be hard to predict.  (Using the
current mouse position would be even less predictable.)  (2)

   ---------- Footnotes ----------

   (1) does it - it should

   (2) is this correct?

8.3 Naming and Saving Keyboard Macros
=====================================

If you wish to save a keyboard macro for longer than until you define
the next one, you must give it a cell to store it in  name using `M-x
save-last-kbd-macro'.  This reads a cell as an argument using the
minibuffer and stores the macro in the cell.  (1)

     M-x store-last-kbd-macro <RET> CELLNAME <RET>

   ---------- Footnotes ----------

   (1) isn't this C-x =?

9 Programs
**********

9.1 Writing One Line Programs
=============================

Any `M-x' command can be written into a cell.  Typing `M-x cell-number'
will execute the commands in the cell.  For example, assume the cell
cursor is located on cell `A1'.  Enter the keystrokes (including the
quotes and braces).

     "{right-cell 4}"

   If you now type `M-x A1' the cell cursor will be positioned in `E1'.
Typing `M-x A1' again, the cell cursor is positioned at `I1'.  Some
examples:

`"{set-option status -1}"'
     Set the status line to the bottom row of the screen

`"{print-region A1.F35 /tmp/out}"'
     Write the values of the cells in the region `A1.F35' to the file
     `/tmp/out'.  The contents of the cells are truncated to fit in
     their column's width.  The result is a rectangular array.  Notice
     that there are no quotes around the file name.

9.2 Multiple Commands in One Line
=================================

To execute several commands at once, concatenate them in a cell.  If
`A1' contains
     "{right-cell 1}{up-cell 1}"

   then typing `M-x A1' moves the cell cursor one right and one up.

9.3 Writing Programs
====================

If commands are entered into a region named by a variable VAR, then we
can use `M-x var' to execute the code.

   Suppose that the contents of `A1.A3' are given below , and that
region `A1.A3' is named `test1'.  Typing `M-x test1' has the same
effect as `{up-cell 1}'.

             "{right-cell 1}"
             "{up-cell    1}"
             "{left-cell  1}"

   (1)

   If `filename' contains a list of `Oleo' commands (like the `.oleorc'
file), the commands in this file can be executed:

`M-x	read-commands'
     This command opens the file you specify, reads in each line, and
     executes them as if you'd typed them in to execute-command.  If
     any command needs more arguments than are included on the line, it
     will prompt you (interactively) for the missing information.

     The syntax for a command is a command name followed by a whitespace
     separated list arguments.  For example:

          	bind-key main next-row ^n,

     Blank lines and lines that begin with `#' are ignored.  Lines may
     be continued by preceeding the final newline with an odd number of
     `\\' characters.  One backslash and the newline will, be discarded.

     The commands in the next file perform some arithmetic operations
     on an already loaded spreadsheet.  Note that the division is
     protected against division by zero.
          goto-cell r3c84
          edit-cell  ((rc82-rc3)/if(rc4=0,0.5,rc4) )^2 + \
                     ((rc82-rc5)/if(rc6=0,0.5,rc6) )^2
          goto-cell r3c85
          edit-cell rc[-1]/36.0

   ---------- Footnotes ----------

   (1) yes it's trivial - how about something complex!

9.4 Commands available in programs
==================================

The commands available in programs are listed in the command index
(see Command Index).  For more information, look at the online help
for the individual entries.

10 Keymaps and defining keys
****************************

What a key does when it is pressed depends on the context.  The listing
of actions associated with a key in a given context is called a
'keymap'.  Keymaps may have a 'default map'.  If a key is pressed which
does not have an assigned meaning in that map, the map's default map is
checked, and that map's default map, until a command is found or there
are no more default maps to scan.

   The different keymaps, and their usage are as follows:

       universal         The root of all keymaps.
       main              The default keymap.
       meta              Default <ESC> commands.
       ansi              ANSI arrow keys.
       trolx             Default <C-x> commands.
       generic-*         More generic versions of the above, work everywhere.
       mouse             Bindings for mouse buttons.
       prefix            Number keys, and -, for argument prefix.
       help              Various levels of help commands.

   The diagram below shows the relationship between the various keymaps.
The keymap to the left of a given keymap is its default.

                       | generic-main ----| main
                       |                  | read-string ---| read-<item>*
     		  |
                       | generic-meta ----| meta
                       |                  | meta-read-string --- meta-read-formula
     		  |
                       | generic-ansi ----| ansi
                       |                  | edit-ansi
     		  |
                       | generic-trolx ---| trolx
                       |                  | trolx-read-string
       universal ------| mouse
                       | generic-menu
                       | prefix
                       | meta-edit-ansi
                       | read-keyseq
                       | set-auto-motion
                       | read-most-chars ---| read-char
                       |                    | read-menu
                       | press-any
                       | view-info
                       | set-*-attr  (cell, region, default)
                       | generic-help ---| unprompted-help
                                         | help
                                         | verbose-help

`M-x bind-key'
     This asks for the name of a keymap followed by a command name and
     a key to bind it to.  If the 'command' you give is a cell or
     region in the spreadsheet, it is taken as a macro, and bound to
     the key you specify.  For example, to make <C-1> move up one cell
     in the main keymap, type

                  <M-x> bind-key <RET> main <RET> up-cell <C-1> <RET>

`M-x unbind-key'
     This asks for the name of a keymap and the key in that map to
     unbind.  For example, to remove the default mapping bound to
     `M-k', type
          	<M-k> unbind-key <RET> meta <RET> <k>

`M-x describe-key'
     Have the user press a key, and then describe what function that
     key is bound to. (bound to `C-h c')

`M-x write-keys'
     Write a list o`f commands' to a file that, when executed with
     read-commands, will return the keymaps to their current state.  To
     write a list of commands to the file `/tmp/name', type

                  M-x write-keys <RET> /tmp/name <RET>

`M-x read-commands'
     This command opens the file you specify, reads in each line, and
     executes them as if you'd typed them in to execute-command.  If
     any command needs more arguments than are included on the line, it
     will prompt you (interactively) for the missing information.

11 Functions
************

Cell functions take a comma-separated list of arguments in parentheses,
and return a value based on those values.  In addition to the standard
value types, some arguments may be cell ranges.

11.1 Boolean Functions
======================

Boolean functions return either a `#TRUE' or `#FALSE' value.  Most
arguments (those labelled BOOL) are also boolean.  If these arguments
have any other value instead, the function returns `#NON_BOOL' as an
error.

`if(BOOL, VAL1, VAL2)'
     If BOOL is `#TRUE', then VAL1 is returned.  If BOOL is `#FALSE',
     VAL2 is returned.

`and(BOOL1, BOOL2)'
     Returns `#TRUE' if and only if both arguments are `#TRUE',
     otherwise returns `#FALSE'.

`or(BOOL1, BOOL2)'
     Returns `#TRUE' if either or both arguments are `#TRUE', otherwise
     returns `#FALSE'.

`not(BOOL)'
     Returns `#TRUE' if BOOL is `#FALSE'; `#FALSE' if `#TRUE'.

`iserr(VAL)'
     returns `#TRUE' if VAL is an error, `#FALSE' otherwise.

`isnum(VAL)'
     `#TRUE' if VAL is a number, or can be automatically converted to a
     number.  Thus, `isnum("12")' is `#TRUE', while `isnum("foobar")'
     is `#FALSE'.

11.2 Elementary mathematical functions
======================================

11.2.1 General Math Functions
-----------------------------

For these these functions, the argument X can be a number (integer or
floating point), a reference to a cell containing an integer, or a
reference to a cell containing a quoted integer.  Thus, if cell (1)
`A2' contains `"-12.34"', then all of the following expressions compute
the absolute value of -12.34:
                    @abs(-12.34)
                    @abs(A2)
                    @abs(@cell(2,1,"value"))

`abs(X)'
     Returns the absolute value of X.

`negate(X)'
     Returns  -X.

`int(X)'
     `int()' converts X to an integer by truncating the fractional
     part.  For instance,
                     int(2.3)     =>   2
                     int(-2.3)    =>  -2

`ceil(X)'
     `ceil()' replaces X by the least integer greater than or equal to
     X.
                     ceil(2.3)     =>   3
                     ceil(-2.3)    =>  -2

`floor(X)'
     `floor()' replaces X by the largest integer less than or equal to
     X.
                     floor(2.3)     =>   2
                     floor(-2.3)    =>  -3

`log(X)'
     The natural log  of X.  If X is negative, the result is
     `#MINUS_INFINITY', and the cell displays is `#OUT_OF_RANGE'.

`exp(X)'
     The  exponential of X

`log10(X)'
     The log base 10 of X.  If X is negative, the result is
     `#MINUS_INFINITY', and the cell displays is `#OUT_OF_RANGE'.

`sqrt(X)'
     The square root of X.  If X is negative, the error message is
     `#OUT_OF_RANGE'.

`rnd(X)'
     Generates a random integer from 0 to X-1.  This is updated
     regularly. This can get annoying. To change the time that it is
     updated from 1 second to 10 seconds, type
                  M-x set-option  <RET> ticks 10  <RET>

`fixed(X, PLACES)'
     Rounds X to PLACES decimal places.

   ---------- Footnotes ----------

   (1) how do I make a reference to a cell?

11.2.2 Trigonometric Functions
------------------------------

`pi()'
     Constant; 15 decimals of pi, 3.141592653589793.

`sin(ANG)'
     The sine of angle ANG (in radians).

`cos(ANG)'
     The  cosine of angle ANG (in radians).

`tan(ANG)'
     The  tangent of angle ANG (in radians).

`asin(VAL)'
     The arc sine (in radians) of VAL.

`acos(VAL)'
     The arc  cosine (in radians) of VAL.

`atan(VAL)'
     The arc  tangent (in radians) of VAL.

`dtr(DEG)'
     `dtr' converts degrees to radians.

`rtd(RAD)'
     `rtd' converts radians  to degrees.

`atan2(Y, X)'
     Expanded arc tangent; returns the arc tangent (in radians) of
     Y / X.  The range of `atan2' is (-pi..pi).  The quadrant of the
     angle returned is determined by the quadrant of the point (X, Y).

`hypot(X, Y)'
     Returns the length of the hypotenuse of a triangle with sides X
     and Y; i.e., `sqrt(X*X + Y*Y)'.  (see General math functions)

11.2.3 Statistical Functions
----------------------------

These functions take a variable number of arguments, labeled VR1, VR2,
etc.  Each of these values can be a numeric type or a range.  If the
value is a range, the values of all numeric cells in that range are
used (strings, empty cells, etc. are ignored).  Values can also be
strings that are easily convertible to numbers; i.e., `"123"'.

   If none of the arguments include valid numbers, then the value of the
function is `#NO_VALUES'.  To ensure that the expression doesn't return
an error in such cases, you can provide a default value as an extra
argument (e.g., `@sum(0,r1:10c1:10)').

   The spreadsheet below is used for examples of the statistical
functions.

                  | Col B | Col C | Col D |
            ------|-------|-------|-------|
            Row 2 |   2   |   3   |   5   |
            ------|-------|-------|-------|
            Row 3 |   8   |   4   |   6   |
            ------|-------|-------|-------|
            Row 4 |   9   |   1   |   3   |
            ------|-------|-------|-------|
            Row 5 |   4   |   7   |   0   |
            ------|-------|-------|-------|

`sum(VR1, ...)'
     The sum  of the given values.  Each value can be a numeric value
     or a range.
    `18'
          @sum(B2.B5)

    `20'
          @sum(B2.B5,2)

    `25'
          @sum(B2.B5,C4.C5)

`prod(VR1, ...)'
     The product  of the given values.  Each value can be a numeric
     value or a range.
    `512'
          @prod(B2.B5)

    `1024'
          @prod(B2.B5,2)

    `0'
          @prod(B2.B5,C4.C5)

`count(VR1, ...)'
     The number of numeric values found among the arguments. In the
     example, assume that the first row and column are not numbers.
    `4'
          @count(B2.B5)

    `4'
          @count(B2.B5,A1.D1)

    `6'
          @count(B2.B5,C4.C5)

`max(VR1, ...)'
     The maximum  value of all the arguments.  Non-numeric values are
     ignored.
    `8'
          @max(B2.B5)

    `8'
          @max(B2.B5,A1.D1)

    `8'
          @max(B2.B5,C4.C5)

`min(VR1, ...)'
     The  minimum value of all the arguments.
    `2'
          @min(B2.B5)

    `2'
          @min(B2.B5,A1.D1)

    `1'
          @min(B2.B5,C4.C5)

`avg(VR1, ...)'
     The average of the given values.  The sum of the numerical values
     in the arguments is divided by the number of numeric values, not
     by the number of cells.
    `4.5'
          @avg(B2.B5)

    `4.5'
          @avg(B2.B5,A1.D1)

    `4.333'
          @avg(B2.B5,C4.C5)

`std(VR1, ...)'
     The _sample_ standard deviation.  To get the population standard
     deviation, use `@sqrt(@var(...))'.
    `2.51'
          @std(B2.B5)

    `2.51'
          @std(B2.B5,A1.D1)

    `2.73'
          @std(B2.B5,C4.C5)

`var(VR1, ...)'
     The population variance of the arguments.  To get the sample
     variance, use `@std(...)^2'.
    `4.75'
          @var(B2.B5)

    `4.75'
          @var(B2.B5,A1.D1)

    `6.22'
          @var(B2.B5,C4.C5)

11.3 String Functions
=====================

Strings indexes start with 1 for the first character.  Indices less
than 1 or greater than the length of the corresponding string will
generate an `#OUT_OF_RANGE' error return, unless otherwise noted.

   These functions are in the `string' package.  If Oleo is compiled
with `-DUSE_DLD', the string package must be loaded before these
functions can be used.  If a spreadsheet that uses these functions is
loaded before the string package is loaded, things will fail
(silently!).  This is a bug.

`len(STR)'
     Returns the number of characters in STR.

`strupr(STR)'
     Converts STR to all upper  case.

`strlwr(STR)'
     Converts STR to all  lower case.

`strcap(STR)'
     Capitalizes each word in STR.

`trim(TRIM)'
     String beautifier.  Trims extra spaces and non-ASCII characters
     from STR.

`find(STR1, STR2, POS)'
     Returns the index at or beyond POS where STR2 appears in STR1 (1).
     If STR2 does not appear at or beyond POS, 0 is returned.

`substr(POS1, POS2, STR)'
     Extracts the substring from index POS1 through POS2 of STR.
     Positive indices, starting with 1, count from the start of the
     string, and negative indices (from -1) count from the end of the
     string.  POS1 must occur at or before POS2.

`mid(STR, POS, LEN)'
     Extracts the substring of LEN characters starting at POS in STR.
     The substring is truncated if it begins or extends beyond the end
     of STR(2).

`edit(STR, POS1, POS2)'
     Deletes the substring from POS1 through POS2 of STR.  Negative
     indices can be used as with `substr'.

`repeat(STR, NUM)'
     Returns a string of NUM concatenations of STR with itself; e.g.,
     `repeat("foo", 2)' returns `"foofoo"'.

`concat(VR1, ...)'
     Returns the concatenation of all its arguments.  An argument may
     be a range, in which case the cell values in the range are
     concatenated.

   ---------- Footnotes ----------

   (1) Actually, due to a bug in version 1.5 STR1 is searched for in
STR2.

   (2) In version 1.5 this function counts indices from 0 instead of 1
as with other string functions; this is probably a bug.

11.4 Structural Functions
=========================

These functions return information about a cell or range of cells.
Some of them are in the `cells' package; if Oleo is compiled with
`-DUSE_DLD', the cells package must be loaded first.

`row()'
`col()'
     The row or column of the cell the expression is in.

`rows(RNG)'
`cols(RNG)'
     The number of rows or columns in RNG.

`my(KEY)'
     Returns information about the cell containing the expression
     according to the key string KEY.  Valid values for KEY are:

    `"row"'
          The cell's row address (an integer).

    `"column"'
          The cell's column address.

    `"width"'
          Width of the cell.

    `"lock"'
    `"protection"'
          `"locked"' or `"unlocked"'.

    `"justify"'
    `"alignment"'
          `"left"', `"right"', `"center"' or `"default"'.

    `"format"'
    `"fmt"'
          `"default"', `"user-1"', etc.

    `"type"'
          The type of the value of the cell: `"error"', `"boolean"',
          `"float"', `"integer"', `"null"', `"unknown"', etc.

    `"formula"'
          A string of the cell's current formula.

    `"value"'
          The cell's current value.

     Any other value generates `#BAD_INPUT'.

`curcell(KEY)'
     Same as `my()', but returns information about the cell where the
     cell-cursor is.

`cell(ROW, COL, KEY)'
     Same as `my()', but for the cell at (ROW, COL).  Be careful about
     the indices in `a0' mode.  The cell in row 2, column 1 is `A2',
     not `B1'.

11.5 Search Functions
=====================

These functions search for a value or string in a range of cells, and
return the index of the first cell that matches.  Cells are numbered
from 1 in column-major order; e.g., in the range `r1:2c1:3' cell `r1c1'
is index 1, cell `r2c1' is 2, cell `r1c2' is 3, etc.

`member(RNG, VAL)'
     Returns the index of the first cell in RNG that contains value
     VAL, or 0 if no cells contain it.  VAL may be an error value.

`smember(RNG, STR)'
     Search for a substring.  Returns the index of the first cell in
     RNG that is a substring of STR, or 0 if no cells are contained in
     STR.  If STR is empty, it matches empty cells as well (1).

`members(RNG, STR)'
     Like `members()', but vice-versa: matches the first cell with a
     substring of STR (i.e., STR is contained in the cell).  If STR is
     empty, empty cells are still ignored (unlike `members()').

`pmember(RNG, STR)'
`memberp(RNG, STR)'
     Same as `smember()' and `members()', respectively, but these
     search for an _initial_ string STR of the cells in RNG.

`index(RNG, INDEX)'
`index(RNG, ROWOFFSET, COLOFFSET)'
     The first form returns the contents of the cell at index INDEX in
     RNG.  The second form returns the cell in RNG that is ROWOFFSET
     rows and COLOFFSET columns from the upper left.

`oneof(CHOICE, VAL1, ...)'
     Case expression.  Returns VAL1 if CHOICE is 1, the next value if
     2, etc.  If CHOICE is not a valid integer in the appropriate
     range, `#OUT_OF_RANGE' is returned.  If no value arguments are
     supplied, `#NO_VALUES' is returned.  Note that arguments must be
     values; ranges are not allowed.

   These functions are used to index into a table of entries:

`hlookup(RNG, NUM, ROWOFFSET)'
     Scans the top row of RNG looking for a number which is greater
     than NUM, then returns the value in the cell that is ROWOFFSET
     rows down from the top of the range.

`vlookup(RNG, NUM, COLOFFSET)'
     Like `vlookup()', but vertically: scans the first column of RNG
     for a value greater than NUM, and returns the cell value COLOFFSET
     columns to the right.

`vlookup_str(RNG, STR, COLOFFSET)'
     Like `vlookup()', but looks for string STR.

   ---------- Footnotes ----------

   (1) An empty cell is a cell with no value; a cell with an empty
_string_ value (`""') would match anyway, since an empty string is a
substring of an empty string.

11.6 Business Functions
=======================

Functions for various business-related calculations.  Rates are
expressed as exactly, i.e. don't expect `10' to mean 10%, but rather use
`0.10'.  The units for TERM are payment periods.  Thus, if you want to
calculate any of the following using, for example, monthly
componunding, you will want `pmt(p, r/12, t*12)', where T is in years.

`pmt(P, R, TERM)'
     Payment per period for a loan of principal P at rate R for   TERM
     payments, assuming a fully amortizing loan which compounds   at
     the payment rate.

`pv(PMT, R, TERM)'
     Present value of an investment that pays PMT at the end of each
     of TERM periods with a discount (interest) rate of R.

`npv(RNG, R)'
     Net present value of an investment which will pay uneven payments.
     The term   is calculated from the number of cells in range RNG,
     with the first   cell corresponding to T=0 (i.e., assuming a
     beginning of year paymest   stream).  Entries in the range can be
     positive or negative, corresponding to   receipts or payments,
     respectively.

`irr(RNG, GUESS)'
     Internal rate of return.  Given a range of cells corresponding to
     uneven periodic payments, calculate the rate R such that
     `npv(rng,r)==0'.  This function can be multivalued when entries
     in the range change sign more than once, and hence returns
     `#BAD_INPUT'   if it fails to converge.  Argument GUESS helps the
     function return   more quickly, but is not critical.

`fmrr(RNG, SAFE, REINVEST, REINVMIN)'
     Financial management rate of return.  This function attempts to be
     a more   encompassing and consistent version of the internal rate
     of return, which   ignores the disposition of intermediate cash
     in- and outflows.  The   `fmrr' function pulls back negative
     values to the nearest positive ones   at the SAFE rate (e.g.
     certificate of deposit rate), and pushes   forward all outflows to
     the end of the period as specified by RNG.    These outflows
     generate income at the REINVESTment rate if they   accumulate to
     be over REINVINMIN, otherwise at the SAFE rate.

`fv(PMT, R, TERM)'
     Future value of an annuity that pays PMT at the end of each   of
     TERM periods assuming a discount rate of R.

`rate(FUT, PRES, TERM)'
     Interest rate required to turn current principal PRES into
     future principal FUT in TERM periods.

`term(PMT, R, FUT)'
     Number of periods required to collect FUT in payments of   PMT,
     with an interest rate of R.

`cterm(R, FUT, PRES)'
     Number of periods required to collect FUT from a single deposit
     of PRES, at an interest rate of R.

`sln(COST, SCRAP, LIFE)'
     Straight line depreciation of an asset that cost COST when new,
     can be sold for SCRAP, and will last for LIFE periods.

`syd(COST, SCRAP, LIFE, PER)'
     Sum-of-the-digits depreciation in period PER of an asset that cost
      COST, can be sold for SCRAP, and lasts LIFE periods.

`ddb(COST, SCRAP, LIFE, PER)'
     Double-declining-balance depreciation; similar to `syd()'.

`anrate(PMT, P, TERM)'
     Solve `pmt(pmt, r, term) == p' for R.

`anterm(PMT, PRIN, R)'
     Solve `pmt(pmt, r, term) == p' for TERM.

`balance(P, R, TERM, N)'
     After N payments (of `pmt(p, r, term)') towards a debt of   P at
     interest rate R over TERM periods, this function   gives the
     amount left due.

`paidint(P, R, TERM, N)'
     After N payments (of `pmt(p, r, term)') towards a debt of   P at
     interest rate R over TERM periods, this function   gives the sum
     of the amounts of the payments which have gone to service   the
     interest on the debt.

`kint(P, R, TERM, N)'
     At period N, this amount goes towards paying the interest on the
     amortizing loan at rate R, term TERM, and principal P.

`kprin(P, R, TERM, N)'
     At period N, this amount goes towards reducing the principal on the
      amortizing loan at rate R, term TERM, and principal P.    Note
     that `kint(p,r,term,n)+kprin(p,r,term,n)==pmt(p,r,term)'.

`compbal(P, R, TERM)'
     Compound balance.  Returns the value of principal P after earning
     interest R over TERM terms.

11.7 Date Functions
===================

Functions for manipulating date and time.  Arguments named TIME are
times in seconds, either an arbitrary count or from a specific epoch
(i.e., local time), unless otherwise noted.  Here are some examples.
Assume that the date is December 16, 1994, and the time is 7:56 am.
The left hand column is the command, and the right hand column is the
result.

               local_month(now())             11
               ctime(now())                   Fri Dec 16 7:58:34 1994
               strftime("%d-%b-%C",now())     11-12-94

`now()'
     Time of day.  Returns the current time in seconds since Jan 1 1970.

`ctime(TIME)'
     Converts TIME into a date/time string.  TIME is seconds since the
     the epoch, as returned by `now()'.

`hms_to_time(HOURS, MINUTES, SECONDS)'

`dhms_to_time(DAYS, HOURS, MINUTES, SECONDS)'
     Converts DAYS, HOURS, MINS, SECONDS to a count of seconds.

`time_to_d(TIME)'

`time_to_h(TIME)'

`time_to_m(TIME)'

`time_to_s(TIME)'
     Returns the number of days, hours (0..23), minutes (0..59), or
     seconds (0..59) in TIME seconds.

`ymd(YEAR, MONTH, DAY)'

`ymd_dst(YEAR, MONTH, DAY, DST)'
     Convert YEAR, MONTH, and DAY to the number of seconds since
     January 1, 1970 (typically).  The conversion assumes the local
     time zone.  For `ymd_dst()', if DST is positive, daylight savings
     time is assumed; if 0, standard time; and if negative, neither
     (i.e., the same as `ymd()').

`local_year(TIME)'

`local_month(TIME)'
     For a time in seconds (e.g., as returned by `now()') return its
     year or month in the local timezone.

`local_date(TIME)'
     Returns the date in the local timezone of TIME.

`local_hour(TIME)'

`local_min(TIME)'

`local_sec(TIME)'
     Returns the hour, minutes or seconds in the local timezone of TIME.

`local_isdst(TIME)'
     Returns DST in the local timezone for TIME.  The return is
     positive if daylight savings time is in effect, 0 otherwise.

`local_yday(TIME)'

`local_wday(TIME)'
     Returns the give day-of-year (0..364 or 0..365 for leap years) or
     day-of-week (0..6) in the local timezone for TIME.

`gmt_year(TIME)'

`gmt_month(TIME)'

`gmt_date(TIME)'
     Returns the year, month, or day in Greenwich of TIME.

`gmt_hour(TIME)'

`gmt_min(TIME)'

`gmt_sec(TIME)'
     Returns the hour, minutes or seconds in Greenwich of TIME.

`gmt_isdst(TIME)'
     Returns a positive value if daylight savings time is in effect in
     Greenwich TIME, 0 otherwise.

`gmt_yday(TIME)'

`gmt_wday(TIME)'
     Returns the day-of-year (0..365) or day-of-week (0..6) in
     Greenwich.

`get_date(DATE)'

`posix_date(DATE)'
     Parse a string date and return its time (seconds since epoch).  The
     syntax of DATE is the same as is understood by GNU tar or GNU date
     for `get_date()', and as per the Posix standard for `posix_date()'.

`strftime(FORMAT, TIME)'
     Returns a string according to FORMAT describing TIME (as returned
     by `now()').  This function is implemented by the C library
     function `strftime()'.  The following documentation describes the
     GNU implementation of `strftime()'.  Your version of Oleo may have
     been built with a different version, in which case, you can find
     documentation in the `strftime()' man page.  (In the future this
     anomaly will be removed).

     Performs `%' substitutions similar to those in `printf()'.  Except
     where noted, substituted fields have a fixed size; numeric fields
     are padded if necessary.  Padding is with zeros by default; for
     fields that display a single number, padding can be changed or
     inhibited by following the `%' with one of the modifiers described
     below.  Unknown field specifiers are copied as normal characters.
     All other characters are copied to the output without change.

     Supports a superset of the ANSI C field specifiers.

     Literal character fields:
    `%'
          `%'

    `n'
          newline

    `t'
          tab

     Numeric modifiers (a nonstandard extension):
    `-'
          do not pad the field

    `_'
          pad the field with spaces

     Time fields:
    `%H'
          hour (`00'..`23')

    `%I'
          hour (`01'..`12')

    `%k'
          hour (` 0'..`23')

    `%l'
          hour (` 1'..`12')

    `%M'
          minute (`00'..`59')

    `%p'
          locale's AM or PM

    `%r'
          time, 12-hour (`HH:MM:SS A/PM')

    `%R'
          time, 24-hour (`HH:MM')

    `%S'
          second (`00'..`61')

    `%T'
          time, 24-hour (`HH:MM:SS')

    `%X'
          locale's time representation (`%H:%M:%S')

    `%Z'
          time zone (EDT), or nothing if no time zone is determinable

     Date fields:
    `%a'
          locale's abbreviated weekday name (`Sun'..`Sat')

    `%A'
          locale's full weekday name, variable length
          (`Sunday'..`Saturday')

    `%b'
          locale's abbreviated month name (`Jan'..`Dec')

    `%B'
          locale's full month name, variable length
          (`January'..`December')

    `%c'
          locale's date and time (`Sat Nov 04 12:02:33 EST 1989')

    `%C'
          century (`00'..`99')

    `%d'
          day of month (`01'..`31')

    `%e'
          day of month (` 1'..`31')

    `%D'
          date (`MM/DD/YY')

    `%h'
          same as `%b'

    `%j'
          day of year (`001'..`366')

    `%m'
          month (`01'..`12')

    `%U'
          week number of year with Sunday as first day of week
          (`00'..`53')

    `%w'
          day of week (`0'..`6')

    `%W'
          week number of year with Monday as first day of week
          (`00'..`53')

    `%x'
          locale's date representation (`MM/DD/YY')

    `%y'
          last two digits of year (`00'..`99')

    `%Y'
          year (`1970'...)

11.8 GSL Functions
==================

The GNU Scientific Library (GSL) is a collection of routines for
numerical computing.  The routines are written from scratch by the GSL
team in C, and are meant to present a modern Applications Programming
Interface (API) for C programmers, while allowing wrappers to be
written for very high level languages.

   More information about GSL is available from
`http://sources.redhat.com/gsl/'

   Currently only a small subset of the GSL functions (as they are in
GSL 0.6) are made available in Oleo. They're most of the statistical
functions :
`gsl_stats_mean'

`gsl_stats_variance'

`gsl_stats_sd'

`gsl_stats_absdev'

`gsl_stats_skew'

`gsl_stats_kurtosis'

`gsl_stats_lag1_autocorrelation'

`gsl_stats_median_from_sorted_data'

`gsl_stats_quantile_from_sorted_data'

`gsl_stats_variance_m'

`gsl_stats_sd_m'

`gsl_stats_variance_with_fixed_mean'

`gsl_stats_sd_with_fixed_mean'

`gsl_stats_absdev_m'

`gsl_stats_skew_m_sd'

`gsl_stats_kurtosis_m_sd'

   The API made available in Oleo for these functions differs slightly
from the native C API of GSL. The C API provides for a `stride' and a
`number' parameter when passing a data array. In Oleo, both of these
are not explicitly passed.

   For example, the `gsl_stats_mean' function has just one parameter in
Oleo, which is a range of cells from which it calculates the mean.
`oleo_gsl_stats_kurtosis_m_sd' has three parameters : a range of cells,
and two numbers.

12 Extending the Oleo system
****************************

12.1 Adding new at Functions
============================

It is easy to add new @ functions.  Suppose that I want to add a
greatest common divisor function.  Here is a definition:
     int gcd(i,k)
         int i,k;
     {
       int c;
       if ( i < 0 )  i = -i;
       if ( k < 0 )  k = -k;
       while ( k != 0 ) {
         c = k;
         k = i % k;
         i = c;
       }
       return  i;
     }

   In Oleo, I would like to enter `@gcd(6,20)', and have the result `2'
displayed.  The following files need to be changed or created:

`my-new-functions.c'
     We will create a new class of functions called INT_FUNS.  For
     simplicity, there is only one function, `gcd', in this class, but
     there could be many more. In addition to the code given above for
     GCD, we need an interface between Oleo and GCD.
          static void
          do_gcd (p)
               struct value *p;
          {
            int arg0 = p[0].Int;
            int arg1 = p[1].Int;

            p->Int = gcd (arg0,arg1);
            p->type = TYP_INT;
          }

     Next, we need to give information about the members of this new
     class of functions.  The "II" refers to the two integer arguments.
     For more examples, see `busi.c'.
          struct function int_funs[] =
          {
            {C_FN2, X_A2, "II", do_gcd, "gcd"},
            {0, 0, "", 0, 0},
          };

     Oleo also (as of release 1.99.6) requires a function in each file
     to figure out how many new user accessible functions it contains.
     Look in busi.c for a simple example (init_busi_function_count)
     which will probably work for your new functions as well.  As you
     can see the function simply takes information from the above array
     and offers it to another Oleo module.

     Finally, we need some standard headers and defines.  These are
     probably not all necessary.

          #include "funcdef.h"
          #include "sysdef.h"
          #include "global.h"
          #include "cell.h"
          #include "eval.h"
          #include "errors.h"

          struct value
            {
              int type;
              union vals x;
            };

          #define Float	x.c_d
          #define String	x.c_s
          #define Int	x.c_l
          #define Value	x.c_i
          #define Rng	x.c_r

`forminfo.c'
     It's polite to add information about new functions.  This
     information can be added in an appropriate place in `forminfo.c':
          "gcd",
          "find gcd                       gcd(a,b)",
          ""
          "The greatest common divisor of A and B.",
          0,

`byte-compile.c'
     The byte compiler needs to be told about the new class of
     functions.  We declare the new class of functions:
          extern struct function int_funs[];
     and instruct the compiler to read them by adding the class to the
     appropriate structure.
          static struct function *__usr_funs[] =
          {
            date_funs,
            busi_funs,
            string_funs,
            cells_funs,
            int_funs,
          };

          extern int init_int_function_count(void);

          static init_function_count init_function_counts[] = {
                  &init_date_function_count,
                  &init_busi_function_count,
                  &init_string_function_count,
                  &init_cells_function_count,
                  &init_int_function_count
                  /* Add something here */
          };

`Makefile.am'
     The file `my-new-functions.c' needs to be added to the list of
     source files. Editing the file src/Makefile.am and adding to the
     list of files named oleo_SOURCES will do :

          oleo_SOURCES = parse.y byte-compile.c eval.c ref.c \
           decompile.c sort.c regions.c utils.c lists.c\
           io-term.c io-utils.c io-x11.c window.c io-edit.c\
           line.c key.c format.c funcs.c \
           hash.c ir.c io-curses.c font.c display.c init.c \
           sylk.c oleofile.c sc.c list.c busi.c string.c cells.c \
           cmd.c basic.c args.c \
           stub.c input.c info.c help.c \
           graph.c plot.c \
           forminfo.c posixtm.y date.c xrdb.c \
           $(GUI) $(XBSRC) $(MYSQL) \
           print.c postscript.c pcl.c epson.c prtext.c \
           my-new-functions.c

13 Reporting Bugs
*****************

If you have problems with Oleo or think that you have found a bug,
please report it; we cannot promise to do anything but we might well
want to fix it.

   Before reporting a bug, make sure you have actually found a real bug.
Carefully reread the documentation and see if it really says you can do
what you're trying to do.  If it's not clear whether you should be able
to do something or not, report that too; it's a bug in the
documentation!

   Before reporting a bug or trying to fix it yourself, try to isolate
it to the smallest possible Oleo program and input data file that
reproduces the problem.  Then send us the program and data file, some
idea of what kind of Unix system you're using, and the exact results
Oleo gave you.  Also say what you expected to occur; this will help us
decide whether the problem was really in the documentation.

   Once you have a precise problem, send e-mail to
`bug-oleo@prep.ai.mit.edu'.

   Non-bug suggestions are always welcome as well.  If you have
questions about things that are unclear in the documentation or are
just obscure features, send a note to `bug-oleo@prep.ai.mit.edu'.

   Also, if you wish to add to the documentation, please do so.  Send
your additions to the address above.

14 A Motif Graphical User Interface for Oleo
********************************************

14.1 Motif Introduction
=======================

Motif is a toolkit for building graphical user interfaces (GUIs) with
the X Window System.

   Such a GUI has been built for oleo.  The combination of oleo and its
Motif interface comes close to professional quality spreadsheets that
one can buy off the shelf.

14.2 LessTif
============

When this manual talks about Motif, it refers to what is commonly
referred to as OSF/Motif, a user interface toolkit for the X Window
System which was originally developped by the Open Software Foundation
(OSF).  The OSF has merged with X/Open, the new name of the
organisation is The Open Group.

   A free implementation of Motif, called LessTif, which is available
from the LessTif home page (http://www.lesstif.org), can be used
instead of Motif.

   LessTif is covered by the LGPL (Library General Public License).

14.3 Advantages
===============

Advantages to using either the Motif or the GTK interface to Oleo are
the same as for any GUI: users with little experience will find it
easier to get started with the application.  The GUI interfaces also
happen to be more aesthetically pleasing.

14.4 What you need
==================

A user of Oleo typically only needs a recent Oleo distribution, which
he installs through his operating system's standard mechanism.

   Someone who's building Oleo from sources will need several packages
that Oleo depends on :
   * Xbae widgets `http://www.lesstif.org'
     `ftp://ftp.lesstif.org/pub/hungry/lesstif/srcdist'

   * XmHTML `http://www.xs4all.nl/~ripley/XmHTML'

   * GNU plotutils
     `http://www.gnu.org/software/plotutils/plotutils.html'

   * Motif or LessTif `http://www.opengroup.org'
     `http://www.lesstif.org'

   * GNU gettext `http://www.gnu.org'

   * GNU texinfo (3.12 or later) `http://www.gnu.org'

14.5 Alternatives
=================

Another toolkit for building GUIs is GTK.  It is also freely available,
and another user interface for oleo may be built with it too.

   GTK is the FSF's official GUI toolkit.

14.6 Using the mouse
====================

The mouse is used in the same manner as in any Motif application.

   The top of the Oleo window is a horizontal bar which is called the
menu bar.  It consists of a small number of buttons (represented by
words such as File, Edit, ...).

   Using the mouse to point at such a word, you can click MB1 on such a
button to make a pulldown menu appear.  MB1 is usually the left mouse
button.

   The words in these pulldown menus are action buttons which should
perform actions that the user can understand.

   You can select a cell in the spreadsheet by clicking MB1 in it.
Once a cell is selected, its position and current value are displayed
in a status area in the upper left of the Oleo window (just below the
menu bar).  The area to the right of that is the formula editor: it
displays the formula on this cell, if any.

   Formulas should be edited in the formula editor.

14.7 Using the keyboard shortcuts
=================================

Using the method described above you can pull down a menu which reveals
a number of action buttons. These buttons typically contain a text such
as `Open   Ctrl-O'.

   Additionally, the O is underlined.

   The Ctrl-O means that you can press down the Control key on your
keyboard, and while doing that, depress the O key. This should activate
the button.

   The underlining means that once you've pulled down this menu, you
should be able to activate this button by just the O key.

   The pulldown menu, which was indicated by the word File (with
underlined F), can in itself be triggered by pressing the Alt key and
depressing the F key.

14.8 Using Help
===============

14.9 Fallback
=============

If you have a version of oleo that has been built with Motif support,
but you don't currently have an X Window System display (for instance
you're using a dialup connection), then it is still possible to use the
curses based character user interface.

   The command `oleo -t' should start Oleo with a curses based user
interface, even if you're running in an X environment.

14.10 Motif Buttons in a Spreadsheet Cell
=========================================

You can put a button in a cell in the Motif version.  The formula of
the cell that you want to have a button should be ` button("text",
"cell-specification")'

   The first argument is the text that the button will show, the second
argument is the cell whose content will be executed. That cell will
typically contain a command like `psprint-region r3:45c8:13 invoice.ps'

   Note that this is currently an experimental feature.

15 Accessing Databases
**********************

15.1 Database Access Introduction
=================================

Oleo can interface to database management systems (DBMSs) in more than
one way.

   This is work in progress though, we expect the implementation to
evolve quite a bit from the current status.

   Currently there are three ways of accessing databases from Oleo :
   * reading a DBF (xbase) file

   * reading rows of content from an MySQL database, prompted by the
     user

   * reading the single result of an SQL query (to MySQL) into a cell

15.2 MySQL
==========

You can get a value from a database into a cell by putting a statement
like

     @mysql_query("select max(salary) from salaries")

   in the cell.

15.3 Xbase
==========