Basics
******

Oleo is the GNU spreadsheet  (better than the high priced spread).

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

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

     [file cell-refs.texi not included]

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 (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 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

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).

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.

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)

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

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.

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

These commands move to the next empty cell in a given direction. (the doc doesn't seem to agree with the behavior; what is the intended behavior?  the repeat counts seem to be ignored.)

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)

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  (This is always cell A1 in the current version, but supposedly might change in the future.). (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  (why -1?) 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)

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

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)

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) (should these be changed - emacs uses 1 for 0, 2 for 1, and 3 for 2)

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.

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)

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) (where is info on file formats?)

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. (what is the default)

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.  (But what does this really do?)

-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

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  (what else can go here? can I set the default font here?)

             set-option a0
             set-option status -1

     [file expressions.texi not included]