Oleo is the GNU spreadsheet program. This documentation is of Oleo version 1.99.13, as of July 29 2000. It is by no means complete, nor necessarily accurate for that matter.

1. Basics
2. Entering Data
3. Making Changes
4. Style
5. Multiple Windows
6. Options
7. Printing and Plotting
8. Macros
9. Programs
10. Keymaps and defining keys
11. Functions
12. Extending the Oleo system
13. Reporting Bugs
14. A Motif Graphical User Interface for Oleo
15. Accessing Databases
16. Key Index
17. Command Index
18. Function Index
19. Options Index
20. Concept Index

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 section 14. A Motif Graphical User Interface for Oleo).

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

Typing	How to type commands
Cell referencing	Two ways of naming cells
The Screen	The parts of the screen
Cursor and Mark	The cell cursor and the mark
Recalculation	How updating works
Movement	Moving around the spreadsheet
Mouse	Using the mouse
Regions and Variables	How to use regions and variables
Getting Help	Getting help
Saving and reading	Saving and reading Spreadsheets
Command Line Options	Command Line Options
.oleorc file	The initialization file
Expressions	Types of expressions

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.

noa0 mode	Using noa0 Mode
a0 mode	Using a0 Mode
Comparison	Comparing a0 and noa0 modes

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

Minibuffer	The input line
Status Line	The status line
Work Area	The work area and its borders

1.3.1 The input line

The input line is also referred to as the Minibuffer. This is where you enter data into cells (see section 2.2 Entering values in a cell). 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 section 1.12 The `.oleorc' file)

1.3.2 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 (2)
• 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

1.3.3 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 section 6.1 Changing Oleo's appearance).

1.4 The cell cursor and the mark

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 section 6. 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

Single Cell Movement	Moving to a neighboring cell
Scanning	Finding the next empty cell
Large Scale Movement	Moving long distances
Movement examples	Examples of movement commands
Screen Moving	Moving by screens

1.6.1 Moving to a neighboring cell

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

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)

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 (4). (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 (5) 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)

1.6.4 Examples of movement commands

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

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

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

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

-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

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

        set-option a0
        set-option status -1

1.13 Expressions

A cell entry is a value or an expression of values (see section 2.1 The different values in Oleo).

Infix expressions	Infix Expressions
Examples	Examples of infix expressions
Error values	A List of Error 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
1.13.3 Error Values

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
Entering	Entering values in a cell
Input Editing	Editing in the input line
Cell Motion	Moving to the next input cell while editing

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

=

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

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.

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

Copying	Copying cells and regions
Moving	Moving Cells and regions
Deleting	Deleting cells and regions
Insertion	Inserting a new row or column

3.1 Copying

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

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

Alignment	Aligning cell entries
Formats for numbers	Formats for numbers
Cell Height	Changing the height of cells
Width of Cells	Changing the width of cells
Hidden Rows and Columns	Creating hidden rows and columns
Protection	Protecting cells
Fonts (in X11)	Working with X11 Fonts

4.1 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

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 (13), 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. (14)

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

4.3 Changing the height of cells

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

4.4 Changing the width of cells

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

4.5 Creating Hidden Rows and Columns

           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

        Cell C5 is 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.

Windows	Introduction to Oleo windows.
Split Window	New windows are made by splitting existing windows.
Other Window	Moving to another window or doing something to it.
Change Window	Deleting windows and changing their sizes.

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.

Appearance	Changing Oleo's appearance
Window Options	Options for the active window
Other Options	Other Options

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

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

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

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

7. Printing and Plotting

Writing Files	Writing ASCII and Postscript Files
Graphing	Graphing Using GNU Plotutils

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) See section 4.7 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(22)

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

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.

Clearing Plots	Clearing the plots
Data sets	Choosing a data set
The axes	Changing the axes style
Viewing Choices	Viewing your choices
Output Type	Choosing the output type
Style Options	Picking a plot style
Name Options	Naming a data set

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)

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

Use a symbolic expression for the range (25)

l

Use values in the spreadsheet for the ticks on the axis. (26)

L

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

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

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.

7.2.7 Naming a data set

      n  3  RET   "my Fermat plot"  RET

8. Macros

8.1 Keyboard Macros
8.2 Basic Use
8.3 Naming and Saving Keyboard 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. (29)

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.

Basic Kbd Macro	Defining and running keyboard macros.
Save Kbd Macro	Saving keyboard macros

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. (30) 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.) (31)

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

M-x store-last-kbd-macro RET cellname RET

9. Programs

One Line Programs	Writing One Line Programs
Long One Liners	Multiple Commands in One Line
Writing programs	Writing Programs
Commands in Programs	Commands available in programs

9.1 Writing One Line Programs

"{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}"

(33)

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

9.4 Commands available in programs

The commands available in programs are listed in the command index (see section 17. 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.
  help                          Help commands.
  mouse                         Bindings for mouse buttons.
  navigate                      Commands that move the cursor.
  trolx-navigate                Navigate commands prefixed by C-x
  meta-navigate                 Navigate commands prefixed by ESC.
  main                          The default keymap.
  trolx                         Default C-x commands.
  meta                          Default ESC commands.
  digit                         The numeric prefix keymap.
  edit                          The keymap for editing in the input area.
  meta-edit                     Edit commands prefixed by ESC.
  trolx-edit                    Edit commands prefixed by C-x.
  ansi                          ANSI arrows keys.

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

                  | help 
                  | mouse
                  | navigate ---------- main ------- digit 
                  | trolx-navigate ---- trolx  
  universal ------| meta-navigate ----- meta 
                  | edit 
                  | meta-edit
                  | trolx-edit
                  | ansi 

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

Boolean functions	and, or, not, etc.
Math functions	Elementary mathematical functions
String functions	String manipulation functions.
Structural functions	Info about the structure of the spreadsheet.
Search functions	Search for cells by value, string, etc.
Business functions	Business stuff.
Date functions	Time and date manipulation.
Gsl functions	GSL (GNU Scientific Library) functions.

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

General math functions	log, sqrt, etc.
Trigonometric functions	Trigonometric functions
Statistical functions	Statistical 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 (34) 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.

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 section 11.2.1 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 (35). 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(36).

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.

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

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.

11.6 Business Functions

pmt(p, r, t)

Payment per period for a loan of principle p at rate r for t payments.

pv(pmt, r, term)

Present value of an investment that pays $pmt at the end of each of term periods with a discount rate (interest) 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.

irr(rng, guess)

Internal rate of return. This function is untested and should not be trusted. Returns #BAD_INPUT if it does not converge for the given input.

fv(pmt, r, term)

Future value of an annuity.

rate(fut, pres, term)

Interest rate required to turn $pres into $fut in term periods.

term(pmt, r, put)

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 of an asset that cost $cost, can be sold for $scrap and lasts life, in period per.

ddb(cost, scrap, life, per)

Double-declining-balance depreciation; similar to syd().

anrate(pmt, pres, term)

Undocumented.

anterm(pmt, prin, r)

Undocumented.

balance(prin, r, term, per)

Undocumented.

paidint(prin, r, term, per)

Undocumented.

kint(prin, r, term, per)

Undocumented.

kprin(prin, r, term, per)

Undocumented.

compbal(prin, r, term)

Undocumented.

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

New at functions	Adding new at Functions

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 `[email protected]'.

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 `[email protected]'.

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
14.2 LessTif
14.3 Advantages
14.4 What you need
14.5 Alternatives
14.6 Using the mouse
14.7 Using the keyboard shortcuts
14.8 Using Help
14.9 Fallback
14.10 Motif Buttons in a Spreadsheet Cell

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, 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
15.2 MySQL
15.3 Xbase

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

16. Key Index

Jump to: