sc.doc

.\" Warning:  The string "pname" is converted to the true program name
.\" by the makefile, throughout this document.
.\"
.\" Warning:  The order of presentation of commands largely matches the
.\" help screen built into the program.
.\"
.\" Conventions:
.\" - pname italicized and never uppercased (it's a proper name).
.\" - Refer to lists of commands in the same order as introduced.
.\" - Command and function names bold when introduced, italicized in all
.\"   other places if possible, or in `` '' if not.
.\" - Cell names italicized except when used in expressions; row numbers
.\"   and column names not italicized.
.\" - Use `` '' rather than " " except referring to literal input or output.
.\" - TPs use default indent except for function names, then 18.
.\" - Smallify uppercase strings.
.\" - Avoid passive voice and third person.
.\" $Revision: 7.16 $
.\"
.TH PNAME 1 "19 September 2002" "PNAME #REVISION#"
.SH NAME
pname \- spreadsheet calculator
.SH SYNOPSIS
.B pname
.RB [ -a ]
.RB [ -c ]
.RB [ -e ]
.RB [ -m ]
.RB [ -n ]
.RB [ -o ]
.RB [ -q ]
.RB [ -r ]
.RB [ -v ]
.RB [ -x ]
.RB [ -C ]
.RB [ -R ]
.RB [ -P
.IR range [ /address ]
|
.IR /address ]
.RB [ -W
.IR range ]
.RI [ file... ]
.\" ==========
.SH DESCRIPTION
The spreadsheet calculator
.I pname
is based on rectangular tables much like a financial spreadsheet.
When invoked, it first looks for a file in the user's home
directory called .scrc and if found, reads that file into memory.
If that file contains the command
.RI `` set\ scrc '',
.I pname
looks for a file called .scrc in the current directory,
and if found, reads that file into memory, too.
Next, it reads the options from the command line, and
finally, it reads in the file or files specified on
the command line and presents the data in a table
organized as rows and columns of cells.
If invoked without a
.I file
argument, the table is initially empty, unless it is
running in a pipeline, in which case it will read
its data from the standard input.
If more than one file is specified,
all files except the first one will be merged.
The default filename for saving a file with the
.I Put
command will be the same as the first file specified,
and the other files will be treated as macros.
If you want to use advanced macros from the command
line, the ``|'' must be quoted to prevent it from being
expanded by the shell.
.LP
Options begin with -.
However, an argument of a single - will be
interpreted to mean that spreadsheet data
will be taken from the standard input.
This is useful for including
.I pname
in a pipeline if the system supports pipes.
However, if standard input is not a terminal,
the - is only necessary if there are multiple
files and standard input is not the last to be
read, since standard input is automatically
read in after all other files in such cases
if it is not specified explicitly, or if there
are no other filenames on the command line.
If
.I pname
is included in a pipeline, and a filename of ``-''
is not specified, the standard input will be merged
in after all of the other named files have been
processed.
.LP
The first argument not beginning with a -,
or a single - by itself, and any subsequent
arguments will all be interpreted as
filenames (a filename of - meaning
standard input as noted above).
In addition, an argument of -- may
be used to signify that all subsequent
arguments should be treated as filenames
even if they begin with a -, but unlike -,
-- won't be treated as a filename itself.
.LP
Each cell may have associated with it
a numeric value,
a label string,
and/or an expression (formula)
which evaluates to a numeric value or label string,
often based on other cell values.
.LP
For an online tutorial, type the command:
.IP
pname #LIBDIR#/tutorial.pname
.LP
To print a quick reference card, type the command:
.IP
pnameqref | [your_printer_commmand]
.\" ----------
.SH OPTIONS
.\" ----------
.TP
.B \-a
Do not run the autorun macro, if one is specified in the file.
.\" ----------
.TP
.B \-c
Start the program with the recalculation being done in column order.
.\" ----------
.TP
.B \-e
Start the program with round-to-even (banker's rounding) enabled.
.\" ----------
.TP
.B \-m
Start the program with automatic recalculation disabled.
The spreadsheet will be recalculated only when the ``@'' command is used.
.\" ----------
.TP
.B \-n
Start the program in quick numeric entry mode (see below).
.\" ----------
.TP
.B \-o
Start the program with automatic optimization of expressions enabled.
.\" ----------
.TP
.B \-q
Quit after loading all files, but before becoming interactive.
This is useful in shell scripts for getting information from
a file, for example, or using
.I pname
as a non-interactive calculator using the
.I eval
command.
.\" ----------
.TP
.B \-r
Start the program with the recalculation being done in row
order (default option).
.\" ----------
.TP
.B \-v
When piping data out using the
.I -P
option (below), change all expressions to values.
The
.I -v
option must precede the
.I -P
option to have an effect.
If the
.I -P
option is used more than once, there must be a separate
.I -v
option for each instance of the
.I -P
option.
.\" ----------
.TP
.B \-x
Cause the
.I Get
and
.I Put
commands (see below) to encrypt and decrypt data files.
.\" ----------
.TP
.B \-C
Start the program with automatic newline action set to increment the column
(see below).
.\" ----------
.TP
.BI \-P " range[/address]"
.PD 0
.TP
.BI \-P " /address"
.PD
Pipe a range to standard output.
The output is similar to that of the
.I Put
command (below), except that only cell data and
formatting information for cells in the range are
output, without all of the colors, range definitions,
column formatting, etc.
The optional
.I /address
is used to adjust all addresses
in the range to a new starting point.
This is useful for copying data from one file to
another, especially when used in conjunction with the 
.I -v
option (above), using something like
.I "merge ""|sc -v -Prange/address filename"""
(note the pipe symbol).
This option may be used more than once to specify multiple ranges.
Note, however, that the
.I -v
option must precede the
.I -P
option on the command line,
and there must be a separate
.I -v
option for each instance of the
.I -P
option.
Any instance of
.I -P
not preceded by its own
.I -v
option will output unevaluated expressions.

A range of
.RI `` % ''
may be used to refer to the entire spreadsheet.
If the range is left out, as shown in the
second form above,
.I pname
will be started interactively in navigate mode,
allowing you to navigate the spreadsheet and
highlight the range you want to output.
Pressing ESC, ^G, or q will terminate without
outputting any data.
.\" ----------
.TP
.B \-R
Start the program with automatic newline action set to increment the row
(see below).
.\" ----------
.TP
.B \-W
Pipe a range to standard output.
The output is identical to that of the
.I Write
command (below).
This option may be used more than once to specify multiple ranges.
A range of
.RI `` % ''
may be used to refer to the entire spreadsheet.
.\" ----------
.PP
All of these options can be changed with the
.I ^T
and 
.I S
commands (see below) while
.I pname
is running.  Options specified when
.I pname 
is invoked
override options saved in the data file.
.\" ==========
.SS "Personal Initialization File"
.\" ----------
When
.I pname
first starts, it looks for a file in the user's home
directory called .scrc and if found, loads it into memory.
The format of this file is the same as any other
.I pname
file, but should be reserved for setting certain defaults.
Any options set which have equivalent command line options may
be overridden by the command line.
If that file contains the command
.RI `` set\ scrc '',
.I pname
will then look for a file called .scrc in the current directory,
and if found, load that file into memory, too (this is analogous
to the ``set exrc'' command used by vi/ex).
These ``dotfiles'' may be created by any text editor.
Several commands exist specifically for setting default file
name extensions in the .scrc file, although they may also
be used from macros, ordinary spreadsheet files, or from within
.I pname
at the command line.
They will not, however, be saved along with the file.
The extensions should be quoted, and should not include
the preceding `.' (e.g., 
.I scext\ "sc"
will add the extension 
.I .sc
).
These commands are:
.\" ----------
.TP
.B scext
This is the default extension for normal
.I pname
files (those created with the
.I Put
command).
If this command is not used, all
.I pname
files will be saved without an extension,
and any existing extension will not be removed.
Setting this option causes all
.I pname
files to be saved with the specified extension added,
unless it is already present.
If the file name already has an extension of
.I .sc,
it will first be removed.
Any other extension will not be removed.
.\" ----------
.TP
.B ascext
This is the default extension for plain text files
created with the
.I Write
command.
The file name will first be checked to see if it
already has an extension of either
.I .sc
or the extension specified with
.I scext
above, and if either one exists, it will first
be removed before adding the new extension.
If this option is not set,
a default of
.I .asc
will be used.
.\" ----------
.TP
.B tbl0ext
This is the default extension for files
created with the
.I Tbl
command if tblstyle is set to 0 (default).
The file name will first be checked to see if it
already has an extension of either
.I .sc
or the extension specified with
.I scext
above, and if either one exists, it will first
be removed before adding the new extension.
If this option is not set,
a default of
.I .cln
will be used.
.\" ----------
.TP
.B tblext
This is the default extension for files
created with the
.I Tbl
command if tblstyle is set to tbl.
The file name will first be checked to see if it
already has an extension of either
.I .sc
or the extension specified with
.I scext
above, and if either one exists, it will first
be removed before adding the new extension.
If this option is not set,
a default of
.I .tbl
will be used.
.\" ----------
.TP
.B latexext
This is the default extension for files
created with the
.I Tbl
command if tblstyle is set to latex.
The file name will first be checked to see if it
already has an extension of either
.I .sc
or the extension specified with
.I scext
above, and if either one exists, it will first
be removed before adding the new extension.
If this option is not set,
a default of
.I .lat
will be used.
.\" ----------
.TP
.B slatexext
This is the default extension for files
created with the
.I Tbl
command if tblstyle is set to slatex.
The file name will first be checked to see if it
already has an extension of either
.I .sc
or the extension specified with
.I scext
above, and if either one exists, it will first
be removed before adding the new extension.
If this option is not set,
a default of
.I .stx
will be used.
.\" ----------
.TP
.B texext
This is the default extension for files
created with the
.I Tbl
command if tblstyle is set to tex.
The file name will first be checked to see if it
already has an extension of either
.I .sc
or the extension specified with
.I scext
above, and if either one exists, it will first
be removed before adding the new extension.
If this option is not set,
a default of
.I .tex
will be used.
.\" ==========
.SS "General Information"
.\" ----------
The screen is divided into four regions.
The top line is for entering commands and displaying cell values.
The second line is for messages from
.IR pname .
The third line and the first four columns show the column and row numbers,
from which are derived cell addresses, e.g.
.I A0
for the cell in column A, row 0.
Note that column names are case-insensitive: you can enter
.I A0
or
.IR a0 .
.\" ----------
.PP
The rest of the screen forms a window looking at a portion of the table.
The total number of display rows and columns available,
hence the number of table rows and columns displayed,
is set by
.IR curses (3)
and may be overridden by setting the
.SM LINES
and
.SM COLUMNS
environment variables, respectively.
.\" ----------
.PP
The screen has two cursors:
a cell cursor, indicated by either a highlighted cell
or a ``<'' on the screen, and a character cursor,
indicated by the terminal's hardware cursor.
.\" ----------
.PP
If a cell's numeric value is wider than the column width (see the
.I f
command), the cell is filled with asterisks.
If a cell's label string is wider than the column width,
it is truncated at the start of the next non-blank cell in the row, if any.
.\" ----------
.PP
Cursor control commands and row and column commands
can be prefixed by a numeric argument
which indicates how many times the command is to be executed.
You can type
.I ^U
before a repeat count if quick numeric entry mode is enabled.
.\" ==========
.SS "Changing Options"
.\" ----------
\0 \" exactly one blank line (hard to get)
.PD 0
.TP
.BI ^T o
Toggle options.
This command allows you to switch the state of one option selected by
.IR o .
A small menu lists the choices for
.I o
when you type
.IR ^T .
Unless otherwise noted, the options selected are saved
when the data and formulas are saved so that you will
have the same setup next time you enter the spreadsheet. 
.PD
.RS
.\" ----------
.TP
.B a
Automatic Recalculation.
When set, each change in the spreadsheet
causes the entire spreadsheet be recalculated.
Normally this is not noticeable, but for very large
spreadsheets, it may be faster to clear
automatic recalculation mode and update the
spreadsheet via explicit ``@'' commands.
Default is automatic recalculation on.
.\" ----------
.TP
.B b
Braille enhancement mode.
See the braille section under the
.I Set
command below for a complete description of
how to use this mode.
This option is not saved when saving a file,
to allow blind and sighted users to easily
share files.  It is intended for use in a user's
.I .scrc
file.
.\" ----------
.TP
.B c
Current cell highlighting.
If enabled, the current cell is highlighted
(using the terminal's standout mode, if available)
and the cell pointer ``<'' is turned off.
This is enabled by default.
.\" ----------
.TP
.B e
External function execution.
When disabled, external functions (see
.IR @ext ()
below) are not called.
This saves a lot of time at each screen update.
External functions are disabled by default.
If disabled, and external functions are used anywhere,
a warning is printed each time the screen is updated,
and the result of
.IR @ext ()
is the value from the previous call, if any, or a null string.
.\" ----------
.TP
.B i
Automatic insertion of rows/columns.
If this is enabled and craction is set to move the
cell cursor either down or to the right after entering
data into a cell, and the last cell in a row/column
in the scrolling portion of a framed range was just
filled, causing the cell cursor to move outside of this
range, a new column/row will be inserted, thus enlarging
the range and allowing you to continue entering data
into the row/column without overwriting the frame (which
may contain expressions of some sort, such as totals).
If autowrap is also enabled, it will take precedence,
and a new row/column will only be inserted after
entering data in the very last cell (bottom right corner)
of the scrolling range.
The default is no automatic insertion.
.\" ----------
.TP
.B w
Automatic wrap to next row/column.
If this is enabled and craction is set to move the
cell cursor either down or to the right after entering
data into a cell, and the last cell in a row/column
in the scrolling portion of a framed range was just
filled, causing the cell cursor to move outside of this
range, the cell cursor will move to the first cell in
the next row/column in this range.
If this would also take the cursor out of the scrolling
portion of the range, the cursor will remain in last
edited cell instead, unless autoinsert is also enabled,
in which case a new row/column will be added so that
the cursor can wrap.
The default is no autowrap.
.\" ----------
.TP
.B l
Autolabeling.
If enabled, using the define command (rd) causes
a label to be automatically generated in the cell
to the left of the defined cell.
This is only done if the cell to the left is empty.
Default is enabled.
.\" ----------
.TP
.B n
Quick numeric entry.
If enabled,
a typed digit is assumed to be
the start of a numeric value for the current cell,
not a repeat count, unless preceded by
.IR ^U .
Also, the `+' and `-' keys will enter insert mode
and append a `+' or `-' to the existing contents
of the cell, allowing the user to easily add to or
subtract from the current numeric contents of the cell.
The cursor controls
.RI ( ^P ,
.IR ^N ,
or any of the arrow keys)
in this mode will end a numeric entry if the entry
was started by pressing `+', `-', or a digit.
Switching from insert mode to edit mode will cause the
cursor controls to revert to their normal functions.
.\" ----------
.TP
.B o
Automatic optimization of expressions.
If this is enabled, expressions which evaluate to
a constant are automatically optimized upon entry.
For example, if you enter @pow(2,32) into a cell,
the value 4294967296 will be stored in that cell,
whereas if optimization is turned off, the calculated
value will be displayed, but the actual expression will
be stored in the cell instead.
This allows you to edit the expression instead of
re-entering it from scratch when you just want to
make a minor change.
Default is automatic optimization off.
.\" ----------
.TP
.B t
Top line display.
If enabled,
the name and value of the current cell is
displayed on the top line.
If there is an associated label string,
the first character of the string value
is ``|'' for a centered string, ``<'' for a
leftstring or ``>'' for a rightstring (see below),
followed by "\fIstring\fP" for a constant string or
.RI { expr }
for a string expression.
A constant string may be preceeded with a backslash (`\\').
In this case the constant string will be used as a ``wheel''
to fill a column, e.g. "\\-" for a line in a column,
and "\\Yeh\ " for "Yeh\ Yeh\ Ye".
If the cell has a numeric value,
it follows as
.RI [ value ],
which may be a constant or expression.
.\" ----------
.TP
.B $
Dollar prescale.
If enabled, all numeric
.B constants
(not expressions) which you enter are multipled by 0.01
so you don't have to keep typing the decimal point
if you enter lots of dollar figures.
.\" ----------
.TP
.B r
Newline action.
This is a 3-way toggle which determines which direction to
move after pressing the
.SM RETURN
key to enter data into a cell.
It has the same effect as using the
.I set
(S) command to set the value of craction.
After selecting this option, you will be prompted for
the direction you want to move.
Valid directions are down (craction=1) and to the right (craction=2).
Pressing j, ^N, or the cursor-down key will cause
the cursor to move down a cell each time you press
the
.SM RETURN
key and pressing l, the cursor-right key, or the
space bar will cause the cursor to move one cell to the right.
Pressing the
.SM RETURN
key at the prompt selects no action
(craction=0, which means that the cursor will remain in
the current cell).
No action is the default unless
.I pname
is started with either the -R or -C option.
This option is ignored if the cell into which data is
being entered is not the current cell.
.\" ----------
.TP
.B s
Enable/disable color slop.
If a cell's label string is wider than the column width,
it will slop over into the next cell to the right if that
cell is empty.
However, if that cell is in a different color range than
the first, this slopover will be disabled, regardless of
whether the colors assigned to the two ranges are different
or not.
If cslop is enabled, strings may slop over even if the
next cell is in a different color range, carrying their
color with them, which may cause a ragged boundary between
the ranges, but may allow the strings to be seen in their
entirety.
Cslop is disabled by default.
.\" ----------
.TP
.B x
Encryption.
See the
.B \-x
option.
.\" ----------
.TP
.B z
Set newline action limits.
This option sets limits to the newline action option above.
When this option is invoked, the row and column of the
current cell are remembered.
If a later newline action would take the current cell to the right of
the remembered column, then the current cell is instead moved to the
first column of the next row.
If a newline action would take the current cell below the remembered row,
then the current cell is instead moved to the top row of the next column.
.\" ----------
.TP
.B C
Color.
This option enables color, and must be set before any
other color options, such as colorneg (color negative
numbers) or colorerr (color cells with errors), will
have an effect.
On a slow connection, turning off color can noticeably
speed up screen updates.
.\" ----------
.TP
.B E
Color cells with errors.
Setting this option will cause all cells with expressions
which evaluate to ERROR or INVALID to be set to color 3.
Color must be enabled for this option to take effect.
.\" ----------
.TP
.B N
Color negative numbers.
When this option is set, all cells containing negative
numbers will have their color number incremented by one.
Cells with color 8 will cycle back to color 1.
Color must be enabled for this option to take effect.
.PP
The quick numeric entry, newline action and set
newline action limits options can be combined to
allow very quick entry of large amounts of data.
If all the data to be entered is in a single row
or column then setting the quick numeric entry and
the appropriate newline action will allow the
numbers to be entered without any explicit commands
to position the current cell or enter a number.
.PP
If the data entry involves several entries in each row for many rows, then
setting the quick numeric entry option, setting the newline action to move
right after each entry and setting the newline action limits on the last
column on which data should be entered will allow the data to entered
quickly.
An alternative to setting newline action limits is to
enclose the range for entry in a frame (see "Framed Ranges"
below), and setting the autowrap option.
Setting autoinsert will insert new rows as needed if the
frame includes data at the bottom.
If necessary, columns which do not need data to be
entered can be hidden with the
.B z
command.
Similar arrangements can be made for entering several rows of data
in each column.
.RE
.\" ----------
\0 \" exactly one blank line (hard to get)
.PD 0
.TP
.B S
Set options.  This command allows you to set various options.
A small menu lists the options that cannot be changed through
.I ^T
above.
.PD
.RS
.\" ----------
.TP
.BR byrows /  bycols
Specify the order cell evaluation when updating.
These options also affect the order in which
cells are filled (see 
.IR rf )
and whether a row or column is cleared by an 
.I x
command.
.\" ----------
.TP
.BI iterations =n
Set the maximum number of recalculations before
the screen is displayed again. 
.I Iterations
is set to 10 by default.
.\" ----------
.TP
.BI tblstyle =s
Control the output of the 
.I T
command.
.I s
can be:
.B 0
(default) to give colon delimited fields, with no 
.I tbl
control lines;
.B tbl
to give colon delimited fields, with
.IR tbl (1)
control lines;
.B latex
to give a
.I LaTeX
tabular environment; 
.B slatex
to give a
.I SLaTeX (Scandinavian LaTeX)
tabular environment;
.B tex
to give a
.I TeX
simple tabbed alignment with ampersands as delimiters; and
.B frame
to give a tblstyle output for FrameMaker.
.\" ----------
.TP
.BI pagesize =n
Set the page size for the PageUp, PageDown, J, and K commands.
If set to 0, the default is to move up or down
half the number of rows displayed on the screen,
or if the current cell is in a framed range,
half the number of displayed rows in the scrolling
region of that range.
.\" ----------
.PP
Other
.I Set
options are normally used only in 
.I pname
data files since they are available through 
.IR ^T .
You can also use them interactively.
.\" ----------
.TP
.BR autocalc / !autocalc
Set/clear auto recalculation mode.
.\" ----------
.TP
.BR autoinsert / !autoinsert
Set/clear automatic insertion mode.
.\" ----------
.TP
.BR autowrap / !autowrap
Set/clear autowrap mode.
.\" ----------
.TP
.BR optimize / !optimize
Set/clear auto optimize mode.
.\" ----------
.TP
.BR numeric / !numeric
Set/clear numeric mode.
.\" ----------
.TP
.BR prescale / !prescale
Set/clear numeric prescale mode.
.\" ----------
.TP
.BR extfun / !extfun
Enable/disable external functions.
.\" ----------
.TP
.BR toprow /  !toprow
Set/clear top row display mode.
.\" ----------
.TP
.BR rndtoeven /  !rndtoeven
Default: *.5 will be rounded up to the next integer;
doing a 'set rndtoeven' will cause it to be rounded to
the closest even number instead (aka banker's rounding).
Round-to-even has advantages over the default rounding
for some applications.
For example, if X+Y is an integer,
then X+Y = rnd(X)+rnd(Y) with round-to-even,
but not always with the defaulting rounding method.
This could be an advantage, for example, when trying to
split an odd amount of money evenly between two people (it
would determine who gets the extra penny).
Note: rndtoeven only effects the @rnd and @round functions.
It has no effect on how a number is rounded to fit the
display format of a cell.
.\" ----------
.TP
.BI craction =n
Set the newline action.
.I n
can be:
.B 0
(default) to give no action;
.B 1
to move down after each entry; or
.B 2
to move right after each entry.
.TP
.BI rowlimit =n
Set the remembered limit for the maximum row below which
the current cell will be moved to the top of the next column
if the newline action is set to move the current cell down.
.I n
can be
.B -1
(default) to disable this facility.
.\" ----------
.TP
.BI collimit =n
Set the remembered limit for the maximum column to the right of which
the current cell will be moved to the left of the next row
if the newline action is set to move the current cell right.
.I n
can be
.B -1
(default) to disable this facility.
.\" ----------
.TP
.BR color / !color
Enable color.
This option must be set for any other color options,
such as colorneg or colorerr, to take effect.
On a slow connection, turning off color can noticeably
speed up screen updates.
.\" ----------
.TP
.BR colorneg / !colorneg
Color negative numbers.
When this option is set, all cells containing negative
numbers will have their color number increased by one.
Cells with color 8 will cycle back to color 1.
Color must be enabled for this option to take effect.
.\" ----------
.TP
.BR colorerr / !colorerr
Color cells with errors.
Setting this option will cause all cells with expressions
which evaluate to ERROR or INVALID to be set to color 3.
Color must be enabled for this option to take effect.
.\" ----------
.TP
.BR cslop / !cslop
Enable color slop.
If a cell's label string is wider than the column width,
it will slop over into the next cell to the right if that
cell is empty.
However, if that cell is in a different color range than
the first, this slop over will be disabled, regardless of
whether the colors assigned to the two ranges are different
or not.
If cslop is enabled, strings may slop over even if the
next cell is in a different color range, carrying their
color with them, which may cause a ragged boundary between
the ranges, but may allow the strings to be seen in their
entirety.
Cslop is disabled by default.
.PP
The following
.I Set
options are considered personal preferences,
or are terminal dependent, and are therefore not
saved when saving a file, but are instead intended
for use in a user's .scrc file.
.\" ----------
.TP
.BR braille / !braille
Set/clear braille enhancement mode.
When braille enhancement mode is set, the cursor
behaves in a manner that makes the use of
.I pname
much easier when using a braille display.
In spite of its name, this mode also works well with
screen readers such as SpeakUp, and can even be used
by sighted users to make cutting and pasting using the
.I screen
program much easier.

There are actually two different braille modes.
When the braille option is set, the
.I C
command, which is normally used to set colors,
will instead change from one braille mode to the other.
If it is desired to set/change colors so you can
share files with others not using a braille display,
braille mode will have to be switched off temporarily,
and then switched back on after the color operation
is done.

When the braille option is set, the default braille mode
will cause the cursor to be positioned at the left edge of
the current cell, while the alternate braille mode will
cause the cursor to be placed at the beginning of the top
line, which will contain information such as the current
cell address, contents of the cell, and column formatting
information.
The column names will also be moved to the left edge of
their respective columns in order to remain aligned with
the cursor as it moves up and down the column.

In either mode, the cursor will be placed in the
top line when editing a line, except when switching
to navigate mode, in which case the cursor will be
placed in either the current cell (default braille mode)
or the second line, where the cell address or default
range will be displayed (alternate braille mode).

Whenever a message is displayed on the second line,
such as an error message or prompt for further
information, both modes will cause the cursor to
be placed at the beginning of that message.
After this message goes away, the cursor will
revert to its former behavior.
The easiest way to make this message go away
without effecting anything, except in the cases
where it is asking the user for more information,
is to press
.IR CC ,
which effectively changes modes twice, with a net
effect of leaving
.I pname
in the original mode.
.\" ----------
.TP
.BR locale / !locale
If locale support is compiled into
.IR pname ,
this option will cause certain locale-dependent
behaviors, such as the display of numbers and the
determination of word boundaries for some operations
in edit mode.
Note that if this option is set and the environment
variable LC_ALL is unrecognized, unset, or set to
either ``POSIX'' or ``C'', commas in format commands
will be ignored.
.\" ----------
.TP
.BR cellcur / !cellcur
Set/clear current cell highlighting mode.
This option is included here because it is likely to
be terminal dependent and/or a user preference,
and therefore is not saved when saving a file.
.\" ----------
.TP
.BI scrc
It tells
.I pname
to also read the file .scrc in the current directory when starting.
Settings in this file will override those in $HOME/.scrc
but may themselves be overridden by command line options.
Setting this could be a potential security risk, since starting
.I pname
with an unknown .scrc could potentially execute arbitrary commands.
This risk is probably very slight, since a spreadsheet program
is not likely to be run in just any directory, and should
.B never
be run as root.
.RE
.\" ==========
.SS "Cursor Control Commands"
.\" ----------
\0 \" exactly one blank line (hard to get)
.PD 0
.TP
.B ^A
Go to cell
.I A0
(same as HOME).
.PD
.\" ----------
.TP
.B ^P
Move the cell cursor up to the previous row.
.\" ----------
.TP
.B ^N
Move the cell cursor down to the next row.
.\" ----------
.TP
.B ^H
Move the cell cursor backward one column.
.\" ----------
.TP
.B SPACE
Move the cell cursor forward one column.
When in navigate mode, if a range is highlighted,
insert the highlighted range into the command line,
followed by a space, while remaining in navigate mode.
This is useful when entering copy, move, or frame commands,
for example, which accept more than one range argument.
.\" ----------
.TP
.B "h, j, k, l"
These are alternate,
.IR vi -compatible
cell cursor controls (left, down, up, right).
Space is just like l (right).
.TP
.B "H, J, K, L"
These move the cursor
by half pages (left, down, up, right).
If
.I pagesize
is nonzero, up/down paging will be by
.I pagesize
rows, instead.
.\" ----------
.TP
.B "^F, ^B"
Same as J and K above.
.\" ----------
.TP
.B PAGE-DOWN PAGE-UP
Same as J and K above.
.\" ----------
.TP
.B TAB
If the character cursor is on the top line,
.SM TAB
tries to complete a range name if the character
immediately preceding it is alphanumeric or ``_'',
and starts a range if not (see below).
Otherwise, move the cell cursor forward one column.
.\" ----------
.TP
.B HOME
Go to cell
.IR A0 .
.\" ----------
.TP
.B END
Same as ^E (see below).
.\" ----------
.TP
.B "Arrow Keys"
The terminal's arrow keys provide another alternate
set of cell cursor controls if they exist and are
supported in the appropriate
.I termcap
entry.
Some terminals have arrow keys which conflict with other control key codes.
For example, a terminal might send
.I ^H
when the back arrow key is pressed.
In these cases, the conflicting arrow key performs the same function
as the key combination it mimics.
.\" ----------
.TP
.B ^
Move the cell cursor up to row 0 of the current column.
.\" ----------
.TP
.B #
Move the cell cursor down to the last valid row of the current column.
.\" ----------
.TP
.B 0
Move the cell cursor backward to column A of the current row.
This command must be prefixed with
.I ^U
if quick numeric entry mode is enabled.
.\" ----------
.TP
.B $
Move the cell cursor forward to the last valid column of the current row.
.\" ----------
.TP
.B b
Scan the cursor backward (left and up) to the previous valid cell.
.\" ----------
.TP
.B w
Scan the cursor forward (right and down) to the next valid cell.
.\" ----------
.TP
.B g
Go to a cell.
.I pname
prompts for a cell's name, a regular expression surrounded by
quotes, or a number.
If a cell's name such as
.I ae122 
or the name of a defined range is given, the cell cursor goes
directly to that cell.
If a quoted regular expression such as "
.I Tax Table 
" or "
.I ^Jan [0-9]*$
" is given,
.I pname
searches for a cell containing a string matching the regular
expression.
See 
.I regex(3)
or
.I ed(1)
for more details on the form of regular
expressions.
.IP
You can also search formatted numbers or expressions
using regular expressions by preceding the opening quotes
of the regular expression with a ``#'' (for formatted
numbers) or a ``%'' (for expressions).
These are handy for searching for dates within a specified
range or cells which reference a given cell, for example,
although they are somewhat slower than searching through
ordinary strings, since all numbers must be formatted or
expressions decompiled on the fly during the search.
.IP
If a number is given, 
.I pname
will search for a cell containing that number.
Searches for either strings or numbers proceed forward from the
current cell, wrapping back to a0 at the end of the table, and
terminate at the current cell if the string or number is not found.
You may also go to a cell with an ERROR (divide by zero, etc. in this cell)
or INVALID (references a cell containing an ERROR).
.IR g\ error
will take you to the next ERROR, while
.IR g\ invalid
take you to the next INVALID.
The last
.I g
command is saved, and can be re-issued by entering 
.IR g<return> .
You can also repeat the last search by pressing
.IR n .
.IP
An optional second argument is available whose meaning
depends on whether you're doing a search or jumping to a
specific cell.  When doing a search, the second argument
specifies a range to search.  When jumping to a specific
cell, the second argument specifies which cell should be
in the upper lefthand corner of the screen, if possible,
which allows you to position the destination cell where
you want it on the screen.
.\" ----------
.TP
.BI ^E d
Go to end of range.
Follow
.I ^E
by a direction indicator such as
.I ^P
or
.IR j .
If the cell cursor starts on a non-blank cell,
it goes in the indicated direction until the
last non-blank adjacent cell.
If the cell cursor starts on a blank cell,
it goes in the indicated direction until
the first non-blank cell.
This command is useful when specifying ranges
of adjacent cells (see below), especially when
the range is bigger than the visible window.
.IP
If
.I ^E
is pressed twice in succession,
or if it is pressed after another
.I ^E
or a
.IR ^Y ,
it will cause the screen to scroll up without
moving the cell cursor, unless the cell cursor
is already at the top of the screen, in which
case, it will remain at the top of the visible
screen.
.\" ----------
.TP
.B ^Y
Causes the screen to scroll down without moving
the cell cursor, unless the cell cursor is
already at the bottom of the screen, in which case,
it will remain at the bottom of the visible screen.
.\" ----------
.TP
.BI m x
Mark the current cell.
.I pname
will prompt for a lowercase letter to be
used as a mark specifier.
Marked cells may be used as the source for the
.I c
(copy a marked cell) command, or as the target of a
.I `
or
.I '
(go to marked cell) command.
In addition to cells marked with lowercase letters,
.I pname
also automatically marks the last nine cells that
have been edited with the numbers 1-9, and the
current cell being edited with the number 0.
When not editing a cell, marks 0 and 1 usually
refer to the same cell, unless the last edit was
begun in one cell, but the cell address was changed
before pressing the
.SM RETURN
key, or the last edit was aborted prematurely.
.\" ----------
.TP
.BI ` x
Jump to a previously marked cell.
If the target cell is currently on the screen,
.I pname
will simply jump to the target cell, making it current.
Otherwise,
.I pname
will attempt to center the cell on the screen, if possible.
As a special case, following the ` with another ` will
return you to the cell you were in before the last g, ', `,
*, or ^E (or END key) was used to jump to another cell.
.\" ----------
.TP
.BI ' x
Jump to a previously marked cell.
.I '
works just like
.I `
, except that
.I '
will attempt to restore the marked cell to the same
position on the screen as when it was marked.
It does this by remembering which cell was in the upper
left hand corner of the screen at the time the mark was
set, and restoring that cell to its original position.
As a special case, following the ' with another ' will
return you to the cell you were in before the last g, ', `,
*, or ^E (or END key) was used to jump to another cell,
and will also try to position that cell on the screen in
the same position as when you left it.
.\" ----------
.TP
.BI z<RETURN>
Move the current row to the top of the screen.
If the current row is in a framed range, move the current
row to the top of the scrolling region.
.\" ----------
.TP
.BI z.
Move the current row to the center of the screen.
.\" ----------
.TP
.BI z|
Move the current column to the center of the screen.
.\" ----------
.TP
.BI zc
Center the current cell both horizontally and vertically.
.\" ==========
.SS "Cell Entry and Editing Commands"
.\" ----------
Cells can contain both a numeric value and a string value.
Either value can be the result of an expression,
but not both at once,
i.e. each cell can have only one expression associated with it.
Entering a valid numeric expression
alters the cell's previous numeric value, if any,
and replaces the cell's previous string expression, if any,
leaving only the previously computed constant label string.
Likewise, entering a valid string expression
alters the cell's the previous label string, if any,
and replaces the cell's previous numeric expression, if any,
leaving only the previously computed constant numeric value.
.TP
.B =
Enter a numeric constant or expression into the current cell.
.I pname
prompts for the expression on the top line.
The usual way to enter a number into a cell is to type ``='',
then enter the number in response to the prompt on the top line.
The quick numeric entry option, enabled through the
.B \-n
option or
.I ^T
command, shows the prompt when you enter the first digit of a number
(you can skip typing ``='').
If you want to begin entering an expression in the current cell,
but you want to start out in navigate mode (e.g. to enter cell
addresses, or sums of ranges using ``@sum''), use the ``+''
command instead (see below).
.\" ----------
.TP
.B <
Enter a label string into the current cell
to be flushed left against the left edge of the cell.
.\" ----------
.IP \fB\\\\\fP
Enter a label string into the current cell
to be centered in the column.
.\" ----------
.TP
.B >
Enter a label string into the current cell
to be flushed right against the right edge of the cell.
.\" ----------
.TP
.B {
Left justify the string in the current cell.
.\" ----------
.TP
.B |
Center the string in the current cell.
.\" ----------
.TP
.B }
Right justify the string in the current cell.
.\" ----------
.TP
.B F
Enter a format string into the current cell.
This format string overrides the precision
specified with the
.I f
command unless
.I &
is present in the fractional part of the format
string (see below).
The format only applies to numeric values.
There are two types of format strings allowed:
standard numeric and date.
(Note: these format strings may also be used with the 
.I f
command to create user-defined format types.)
The following characters can be used to build
a standard numeric format string:
.RS
.TP
.BR #
Digit placeholder.
If the number has fewer digits on either
side of the decimal point than there are
`#' characters in the format, the extra `#'
characters are ignored.
The number is rounded to the number of digit
placeholders as there are to the right
of the decimal point.
If there are more digits in the number than
there are digit placeholders on the left side
of the decimal point, then those digits
are displayed.
.TP
.BR 0
Digit placeholder.
Same as for `#' except that the number
is padded with zeroes on either side of the decimal point.
The number of zeroes used in padding is determined by the
number of digit placeholders after the `0' for digits on
the left side of the decimal point and by the number of
digit placeholders before the `0' for digits on the right
side of the decimal point.
.TP
.BR .
Decimal point.
Determines how many digits are placed on
the right and left sides of the decimal point in the number.
If
.I locale
is set, the decimal point for the user's current locale
will be used when formatting a number.
Note that numbers smaller than 1 will begin with a decimal
point if the left side of the decimal point contains only
a `#' digit placeholder.
Use a `0' placeholder to get a leading zero in decimal formats.
.TP
.BR %
Percentage.
For each `%' character in the format, the actual
number gets multiplied by 100 (only for purposes of formatting
-- the original number is left unmodified) and the `%' character
is placed in the same position as it is in the format.
.TP
.BR ,
Thousands separator.
The presence of a `,' in the format
(multiple commas are treated as one) will cause the number
to be formatted with a `,' separating each set of three digits
in the integer part of the number with numbering beginning
from the right end of the integer.
If
.I locale
is set, the thousands separator for the user's current
locale will be used in place of the comma.
If the environment variable LC_ALL is unset, unrecognized,
or is set to ``POSIX'' or ``C'',  any commas in the format
string will be ignored.
.TP
.BR &
Precision.
When this character is present in the fractional
part of the number, it is equivalent to a number of 0's equal
to the precision specified in the column format command.
For example, if the precision is 3, `&' is equivalent to `000'.
.TP
.BR \e
Quote.
This character causes the next character to be
inserted into the formatted string directly with no
special interpretation.
.TP
.BR E-\ E+\ e-\ e+
Scientific format.
Causes the number to be formatted in scientific notation.
The case of the `E' or `e' given is preserved.
If the format uses a `+', then the sign is
always given for the exponent value.
If the format uses a `-', then the sign is
only given when the exponent value is negative.
Note that if there is no digit placeholder
following the `+' or `-', then that part of the
formatted number is left out.
In general, there should be one or more digit
placeholders after the `+' or `-'.
.TP
.BR ;
Format selector.
Use this character to separate the format
into two distinct formats.
The format to the left of the `;' character
will be used if the number given is zero or positive.
The format to the right of the `;' character is
used if the number given is negative.
.RE
.IP
Some example formats are integer (``0'' or ``#''),
fixed (``0.00''), percentage (``0%'' or ``0.00%''),
scientific (``0.00E+00''),
and currency (``$#,0.00;($#,0.00)'').
.IP
Date format strings are identified by the
presence of a ^D in the first postition.
If this is present, the remainder of the
string is passed to the strftime() function,
and therefore uses the same conversion
specifiers as strftime().
For more information on conversion specifiers
for date format strings, see the man page
for strftime(3).
.\" ----------
.PP
Strings you enter must start with ".
You can leave off the trailing " and
.I pname
will add it for you.
You can also enter a string expression
by backspacing over the opening " in the prompt.
.\" ----------
.TP
.B e
Edit the value associated with the current cell.
This is identical to ``=''
except that the command line starts out containing
the old numeric value or expression associated with the cell.
The editing in this mode is vi-like.
.RS
.TP
.BR ^H 
Move back a character
.TP
.BR "^V, v"
Enter navigate mode.
This mode allows you to navigate the spreadsheet
while editing a command.
When in navigate mode,
.I v
will insert the
numeric value of the current cell, if any,
into the command line, instead, while
.I ^V
will return to the previous mode (like 
the ESCAPE key).
.TP
.BR ^W
Insert the expression attached to the current
cell into the command line.
If there is none, the result is ``?''.
This only works while in navigate mode.
.TP
.BR ^A
In navigate mode, go to cell
.IR A0 .
When not in navigate mode, jump to the
beginning of the line instead.
.TP
.BR ^E
Jump to the end of the line.
Unlike ``$'' (below), this can also be used from insert mode.
.TP
.BR TAB
If the character immediately preceding the
cursor is alphanumeric or ``_'',
.SM TAB
tries to find a match in the list of range names,
and if one is found, the name will be completed
on the command line.
If there are multiple matches, pressing
.SM TAB
repeatedly without any other intervening keys
will cycle through all of the valid matches.
If the character immediately preceding the cursor
is not alphanumeric or ``_'',
.SM TAB
defines a range of cells via the cursor control commands or the arrow keys.
Pressing
.SM TAB
automatically switches
.I pname
to navigate mode if you haven't already done so using the
.I ^V
command, and the range is highlighted,
starting at the cell where you typed
.SM TAB,
and continuing through the current cell.
Pressing
.SM TAB
again causes the highlighted range to be inserted into
the command line, the highlighting to be turned off,
and the previous mode to be restored.
This is most useful for defining ranges to functions such as
.IR @sum ().
Pressing ``)'' acts just like typing the
.SM TAB
key the second time and adds the closing ``)''.
Note that when you give a range command,
if the first argument to the command is a range,
you don't need to press the first
.SM TAB
to begin defining a range starting with the current cell.
.TP
.BR :
Synonym for
.SM TAB,
when in navigate mode.
.TP
.BR "` '"
In navigate mode, go to marked cell.
.TP
.BR *
In navigate mode, go to note linked to current cell.
.TP
.BR +
Forward through history (same as j)
.TP
.BR - 
Backward through history (same as k)
.TP
.BR ESC
Done editing
.TP
.BR CR
Save.
When in navigate mode, insert the name of the current
cell (the one at the cell cursor) into the command line.
This is useful when entering expressions
which refer to other cells in the table.
.TP
.BR $
Goto last column
.TP
.BR %
Goto matching parenthesis
.TP
.BR .
Insert current dot buffer.
When in navigate mode, this is a synonym for : or
.SM TAB.
.TP
.BR ;
Repeat the last f, F, t, or T command.
.TP
.BR ,
Repeat the last f, F, t, or T command,
but in the reverse direction.
.TP
.BR ~
Change the case of the character under the cursor.
.TP
.BR /
Search backwards for a string in the history
.RS
\fBESC\fP	edit the string you typed
.br
\fBCR\fP	search
.br
\fB^H\fP	backspace
.RE
.TP
.BR ?
Search forward for a string in the history (see ``/'' above)
.TP
.BR 0
Goto column 0
.TP
.BR B
Move back a word.
Like
.IR b ,
except words are space delimited only.
.TP
.BR C
Change to end of line (delete first, then enter insert mode)
.TP
.BR D
Delete to end of line
.TP
.BR F
Find the next char typed, moving backwards in the line
.TP
.BR G
Go to the end of history, i.e., to the line being currently entered
.TP
.BR I
Insert at column 0; ESC revert back to edit mode
.TP
.BR N
Repeat the last search in the opposite direction
.TP
.BR P
Insert the most recently deleted text before the cursor
.TP
.BR R
Replace mode; ESC revert back to edit mode
.TP
.BR T
Goto a char, moving backwards in the line
.TP
.BR W
Forward a word.
Like
.IR w ,
except words are space delimited only.
.TP
.BR X
Delete the char to the left
.TP
.BR a
Append after cursor; ESC revert back to edit mode
.TP
.BR b
Move back a word
.TP
.BR c
Change mode; ESC revert back to edit mode.
In navigate mode, insert color range which includes
the current cell.
.TP
.BR d
Delete ...
.RS
\fB0\fP	delete to beginning of line\br
.br
\fB$\fP	delete to end of line\br
.br
\fBb\fP	back word\br
.br
\fBe\fP	delete to end of word\br
.br
\fBf\fP	forward (right)\br
.br
\fBh\fP	back char\br
.br
\fBl\fP	forward\br
.br
\fBt\fP	delete forward up to a given char (next char typed)\br
.br
\fBw\fP	delete next word forward\br
.RE
.TP
.BR e
Forward to next end-of-word
.TP
.BR f
Find the next char typed.
In navigate mode, insert the outer frame range which
includes the current cell.
.TP
.BR g
In navigate mode, allows you to `goto' a cell or range,
just like the regular
.I goto
command.
Ignored in edit, insert or replace modes.
.TP
.BR h
Move left a char
.TP
.BR i
Insert before cursor; ESC revert back to edit mode
.TP
.BR j
Forward through history (same as +)
.TP
.BR k
Backward through history (same as -)
.TP
.BR l
Move right a char
.TP
.BR n
Repeat the last search (find the next match)
.TP
.BR o
When highlighting a range in navigate mode, move
to the opposite corner of the highlighted range.
.TP
.BR p
Insert the most recently deleted text after the cursor
.TP
.BR q
Stop editing
.TP
.BR r
Replace char.
In navigate mode, insert the inner frame range which
includes the current cell.
.TP
.BR s
Delete current char and enter insert mode (stands for substitute)
.TP
.BR t
Goto a char
.TP
.BR u
Undo
.TP
.BR w
Forward a word
.TP
.BR x
Delete the current char (moving to the right)
.TP
.BR y
Copies to the delete buffer without deleting.
Use like d (above).
.RE
.\" ----------
.TP
.B E
Edit the string associated with the current cell.
This is identical to ``<'', ``\\'', or ``>''
except that the command line starts out containing
the old string value or expression associated with the cell.
SEE
.I e
ABOVE.
.\" ----------
.PP
To enter and edit a cell's number part, use the ``='', ``+'', and
.I e
commands.
To enter and edit a cell's string part, use the ``<'', ``\\'', ``>'', and
.I E
commands.
See the sections below on numeric and string
expressions for more information.

Note that the descriptions of the ``+'' and ``-'' commands below
may seem very confusing at first, but once they're understood,
they can facilitate the rapid entry of expressions which add and
subtract large numbers of cells and sums of ranges of cells, so read
them over carefully several times until you understand them.
.\" ----------
.IP \fB"\fP
Specify a named buffer for the next
yank/delete/pull command.
Buffers are named with a single character.
Buffers
.RI `` a ''
through
.RI `` z ''
are general purpose buffers,
buffers
.RI `` 1 ''
through
.RI `` 9 ''
hold the last nine deletions,
with buffer
.RI `` 1 ''
being the most recent,
and buffer
.RI `` 0 ''
holds the last cell or range yanked.
Buffer
.RI `` """" ''
is the default buffer, which holds the last
cell or range that was deleted or yanked.
.\" ----------
.TP
.B x
Clear the current cell.
Deletes the numeric value, label string, and/or
numeric or string expression.
You can prefix this command with a count of the
number of cells on the current row to clear.
The current column is used if column
recalculation order is set.
Cells cleared with this command may be recalled
with any of the
.I pull
commands (see below).
.\" ----------
.TP
.BI m x
Mark the current cell.
.I pname
will prompt for a lowercase letter to
be used as a mark specifier.
Marked cells may be used as the source for the
.I copy
command, or as the target of a
.I `
or
.I '
(go to marked cell) command.
.\" ----------
.TP
.BI c x
Copy a marked cell to the current cell, adjusting row and
column references in its numeric or string expression, if any.
.I pname
will prompt for the name of the cell to be copied, which may
be a lowercase letter specified previously with the
.I m
command, a digit 1-9 to reference one of the last nine edited
cells (0 will reference the last cell in which an edit was
begun, regardless of whether the edit was completed or not), or
.RI `` . ''
to reference the current cell, which, as a special case, is to
be used as a source rather than a destination, and is to be
copied into a range which includes the current cell.
When
.RI `` . ''
is specified, the current cell is set as the default source
range for the range copy
.RI ( rc )
command, and then the
.I copy
command is entered into the command line and
.I pname
switches to navigate mode.
Moving the cell cursor will then highlight the destination
range.
After the desired range is highlighted, press
.SM RETURN
to execute the copy.
.\" ----------
.TP
.B +
If not in numeric mode, add the current numeric argument
(default 1) to the value of the current cell.
The current value of the cell must not be an expression.
In numeric mode,
.I +
switches to insert mode and appends a ``+'' to the current
expression or value, if any, which makes it easy to add to
existing data.

In navigate mode,
.I +
inserts the current cell address into the line, followed
by another
.IR + ,
and
.I pname
remains in navigate mode, unless a range is highlighted.
If a range is highlighted and the character immediately
preceding the cursor is a ``+'' or ``-'',
or the cursor is at the beginning of an empty ``let''
expression, the string ``@sum('' will be
inserted, followed by the highlighted range, followed
by ``)+''.
If a range is highlighted and the character immediately
preceding the cursor is not a ``+'' or ``-'', and the
cursor is not at the beginning of an empty ``let''
expression, the highlighted range will be inserted,
followed by  ``)+''.
.\" ----------
.TP
.B -
If not in numeric mode, subtract the current numeric
argument (default 1) from the value of the current cell.
The current value of the cell must not be an expression.
In numeric mode,
.I -
switches to insert mode and appends a ``-'' to the current
expression or value, if any, which makes it easy to subtract
from existing data.

In navigate mode,
.I -
inserts the current cell address into the line, followed
by another
.IR - ,
and
.I pname
remains in navigate mode, unless a range is highlighted.
If a range if highlighted and the character immediately
preceding the cursor is a ``+'' or ``-'',
or the cursor is at the beginning of an empty ``let''
expression, the string ``@sum('' will be
inserted, followed by the highlighted range, followed
by ``)-''.
If a range is highlighted and the character immediately
preceding the cursor is not a ``+'' or ``-'', and the
cursor is not at the beginning of an empty ``let''
expression, the highlighted range will be inserted,
followed by  ``)-''.
.\" ----------
.TP
.B RETURN
If you are not editing a cell (top line is empty),
pressing
.SM RETURN
will make
.I pname
enter insert mode.
At this point you may type any valid command or press
.B ESC
once to edit.
.\" ==========
.SS "File Commands"
.\" ----------
\0 \" exactly one blank line (hard to get)
.PD 0
.TP
.B G
Get a new database from a file.
If encryption is enabled,
the file is decrypted before it is loaded into the spreadsheet.
.PD
.\" ----------
.TP
.B P
Put the current database into a file.
If encryption is enabled,
the file is encrypted before it is saved.
.\" ----------
.TP
.B ZZ
Save the current database into a file if
it has been modified, and then quit.
This is like the
.I P
command followed by the
.I q
command, except that the default filename will
be used instead of prompting you for one, and
the file will only be saved if it was modified.
If there is no default filename, an error message
will be displayed, and no action taken.
.\" ----------
.TP
.B W
Write a listing of the current database into a file
in a form that matches its appearance on the screen.
This differs from the
.I Put
command in that its files are intended to be reloaded with
.IR Get ,
while
.I Write
produces a file for people to look at.
Hidden rows or columns are not shown when the data is printed.
.\" ----------
.TP
.B T
Write a listing of the current database to a file,
but include delimiters suitable for processing by the
.IR tbl ,
.IR LaTeX ,
or
.I TeX
table processors.
The delimiters are controlled by the
.I tblstyle
option.  See
.I Set
above.
The delimiters are a colon\ (:) for style
.IR 0
or
.IR tbl
and an ampersand\ (&) for style
.IR latex
or
.IR tex .
.\" ----------
.PP
With the
.IR Put ,
.IR Write ,
and
.I Table
commands, the optional range argument writes a subset
of the spreadsheet to the output file.
.\" ----------
.PP
With the
.I Write
and
.I Table
commands, if you try to write to the last file used with the
.I Get
or
.I Put
commands, or the file specified on the command line when
.I pname
was invoked, you are asked to confirm that the
(potentially) dangerous operation is really what you want.
.\" ----------
.PP
The three output commands,
.IR Put ,
.IR Write ,
and
.IR Table ,
can pipe their (unencrypted only) output to a program.
To use this feature,
enter ``| program'' to the prompt asking for a filename.
For example, to redirect the output of the
.I Write
command to the printer,
you might enter ``| lpr -p''.
.\" ----------
.TP
.B M
Merge the database from the named file into the current database.
Values and expressions defined in the named file
are read into the current spreadsheet overwriting
the existing entries at matching cell locations.
.\" ----------
.TP
.B R
Run macros.
There are two different kinds of macros that can be used with
.IR pname :
simple macros, which are stored in plain text files,
and advanced macros, which are executable files, and
which can be written in the language of your choice.
Advanced macros are only available on systems that support pipes.

Simple macros are interpreted by
.IR pname 's
internal parser, and use the same commands
used to enter data and perform other operations
(the single key commands are shortcuts which switch
to input mode after first entering the beginning of
the full command for you).
These are also the same commands found in
.I pname
files created with the Put command.
Since
.I pname
files are saved as ASCII files,
it is possible to use them as primitive macro definition files.
The
.I Run
command makes this easier.
It's like the
.I Merge
command,
but prints a saved path name as the start of the filename to merge in.
The string to use is set with the
.I Define
command.
To write macros, you must be familiar with the file format written by the
.I Put
command.

Advanced macros use executable files that are started by
.I pname
as a child process with stdin and stdout redirected back to
.I pname
for bidirectional communication.
Special commands are available for requesting information
such as cell contents, formatting information, or the
current location of the cell cursor.
Commands are written to stdout, and responses are read from
stdin.
To use advanced macros, the filename must be preceded by
a | (the pipe symbol), and the file must be executable.
If the pathname set with the
.I Define
command begins with a |, all files in that path will
be executed as advanced macros.
It is also possible to include a filename as
part of the path when using advanced macros,
which allows you to put multiple macros in a single
file, and use the
.I Run
command to add command line arguments or options
to determine which macro should be run.
Advanced macros are relatively new, and
documentation is still incomplete.
This feature will probably be enhanced in future releases.
.\" ----------
.TP
.B A
Specify a macro to be automatically run whenever
the current sheet is reloaded from a file.
.\" ----------
.TP
.B D
Define a path for the
.I Run
command to use (see above).
.\" ----------
.PP
All file operations take a filename as the first argument
to the prompt on the top line.
The prompt supplies a " to aid in typing in the filename.
The filename can also be obtained from a cell's label string
or string expression.
In this case, delete the leading " with the backspace key
and enter a cell name such as
.I a22
instead.
If the resulting string starts with ``|'',
the rest of the string is interpreted as a
.SM UNIX
command, as above.
.\" ==========
.SS "Row and Column Commands"
.\" ----------
These are two-letter commands which can be used on
either rows or columns.  The exceptions are the
.I f
command, which only works on columns, and therefore
doesn't require a second letter, and the
.I p
command which, in addition to operating on rows or columns,
has several other options for merging the data in directly,
without opening up a new row or column.
There are also a few special cases where pressing the same
letter twice will affect only the current cell instead of
a row or column (except for
.IR ZZ ,
which is a special case all its own).
.PP
In all of the remaining cases, the second letter of the
command will be either
.I r
or
.IR c ,
depending on whether the operation should be performed on
rows or columns, respectively (additional options for the
.I p
command and the double letter cases are listed below).
A small menu lists the choices for the second letter
when you type the first letter of one of these commands.
.PP
Alternatively, you may define a range of rows or columns
by moving the cell cursor, either a cell at a time, or
by pages (roughly 1/2 screen, unless the
.I pagesize
option has been set), but this only works for the
.IR d ,
.IR y ,
and
.I Z
commands.
Vertical cursor movement will begin highlighting rows,
and horizontal movement will highlight columns.
Pressing the
.SM RETURN
key will then perform the chosen operation
on the specified rows/columns.
.PP
Commands which copy cells also modify the row and
column references in affected cell expressions.
The references may be frozen by using the
.I @fixed
operator or using the
.I $
character in the reference to the cell (see below).
Commands which create new rows or columns will include
all newly created cells in the same ranges (named, framed,
color, or those used in expressions) as their counterparts
in the current row or column.
This can sometimes be a significant factor when deciding
whether to use
.IR ir / ic " or " or / oc .
.\" ----------
.TP
.B "ir, ic"
Insert a new row (column) by moving the row (column)
containing the cell cursor, and all following
rows (columns), down (right) one row (column).
The new row (column) is empty.
Inserting rows while the cell cursor is in a framed
range will only effect rows in that range, leaving
all rows to the left and right untouched.
.\" ----------
.TP
.B "or, oc"
Open a new row (column).
These commands work like the
.I ir
and
.I ic
commands, except that the new row (column) will be
inserted
.I after
the current row (column) instead of before it.
.\" ----------
.TP
.B "ar, ac"
Append a new row (column) immediately following
the current row (column).
It is initialized as a copy of the current one.
Appending rows while the cell cursor is in a framed
range will only effect rows in that range, leaving
all rows to the left and right untouched.
.\" ----------
.TP
.B "dr, dc, dd"
Delete the current row (column).
.I dd
deletes the current cell (i.e., it is a synonym for
.IR x ).
Deleting rows while the cell cursor is in a framed
range will only effect rows in that range, leaving
all rows to the left and right untouched.
.\" ----------
.TP
.B "yr, yc, yy"
Yank a copy of the current row (column) into the
delete buffer without actually deleting it.
.I yy
yanks the current cell (similar to
.IR x ,
but without actually deleting the contents of the cell).
Yanking rows while the cell cursor is in a framed
range will only copy the portion of each row contained
in that range, while ignoring everything outside the
range.
.\" ----------
.TP
.B "pr, pc, pp, pm, px, pt, pC, p."
Pull deleted rows/columns/cells back into the spreadsheet.
The last set of cells that was deleted or yanked is put
back into the spreadsheet at the current location.
.I pr
inserts enough rows to hold the data.
.I pc
inserts enough columns to hold the data.
.I pp
(paste) does not insert rows or columns;
it overwrites the cells beginning at the
current cell cursor location.
.I pm
(merge) merges the cells in at the current cell
cursor location, but does not erase the destination
range first like
.IR pp .
The difference between
.I pp
and
.I pm
is similar to the difference between the
.I Get
and
.I Merge
commands.
.I pf
(format) works like
.I pm
except that only cell formatting information is merged in,
leaving the actual data untouched.
This makes it easy to copy cell formats from one part of the
spreadsheet to another, such as when expanding an existing
spreadsheet file.
.I px
(exchange) copies the contents of the delete buffer into
the range beginning at the current cell cursor location,
while simultaneously copying the contents of this range
back into the delete buffer, replacing its current contents.
.I pt
(transpose) overwrites the cells beginning at the current
cell cursor location like
.I pp,
but transposes rows for columns and vice versa.
.I pC
(copy) works like
.I pp,
except that all cell references are adjusted in
the same way that they are for the
.I copy
command.
.I p.
is the same as
.I pC,
except that it switches to navigate mode and allows
you to define the destination range to be used.
This works like the
.I copy
command in that if the source range (the contents of
the delete buffer) is a single row, column, or cell,
multiple copies may be made.
.\" ----------
.TP
.B "vr, vc, vv"
Remove expressions from the affected rows (columns),
leaving only the values which were in the cells
before the command was executed.
When used in a framed range,
.I vr
only affects the portion of the the row inside the range,
leaving the rest of the row unchanged.
.I vv
only affects the contents of the current cell.
.\" ----------
.TP
.B "Zr, Zc, ZZ"
Hide (``zap'') the current row (column).
This keeps a row (column) from being displayed
but keeps it in the data base.
The status of the rows and columns is saved with
the data base so hidden rows and columns will
still be hidden when you reload the spreadsheet.
Hidden rows or columns are not printed by the
.I W
command.
The
.IR ZZ
command is a special case.
It does not hide anything.
Instead, the file will be saved, if modified, and
.I pname
will exit.
See
.I ZZ
above, under
.I "File Commands."
.\" ----------
.TP
.B "sr, sc"
Show hidden rows (columns).
Enter a range of rows (columns) to be revealed.
The default is the first range of rows (columns) currently hidden.
This command ignores the repeat count, if any.
.\" ----------
.TP
.B f
Set the output format to be used for printing the
numeric values in each cell in the current column.
This command has only a column version (no second letter).
You may change the column width by pressing the
.IR h ,
.IR < ,
or cursor left key to reduce it, or the
.IR l ,
.IR > ,
or cursor right key to increase it.
Likewise, you may change the precision (the
number of digits to follow decimal points)
by pressing the
.IR j ,
.IR - ,
or cursor down key to reduce it, or the
.IR k ,
.IR + ,
or cursor up key to increase it.
You may also change the format type for the
column by pressing any digit.
If the
.I f
command is preceded by a numeric argument,
that argument will determine how many columns should
be changed, beginning with the current column, and
in the case of incrementing or decrementing the width
or precision of the columns, each column will be
incremented or decremented separately, regardless of
its initial values.
Several formatting operations may be performed in sequence.
To leave the formatting command, simply press
.BR ESC ,
.IR ^G ,
.IR q ,
or
.SM RETURN .
.IP
Alternatively, you may press
.BR SPACE
to get the
.I format
command in the top line and enter all three values directly.
In order, these are:
the total width in characters of the column,
the precision, and the format type.
Format types are 0 for fixed point, 1 for scientific
notation, 2 for engineering notation, 3 for dates with
a two digit year, and 4 for dates with a four digit year.
Values are rounded off to the least significant digit displayed.
The total column width affects displays of strings as well as numbers.
A preceding count can be used to affect more than one column.
.IP
You can also create your own format types by pressing
.I =
after the
.I f
command, followed by any digit (see the 
.I F
command above under
.I "Cell Entry and Editing Commands"
for a description of how to build a format string).
Format numbers 0 through 4 will supersede the
built-in format types, while numbers 5 through 9
will supplement them.
User defined format types may be used in
the same way as the built-in types.
For example, the command
.RS
.IP
.I "format 5 = ""#,0.& ;(#,0.&)"""
.RE
.IP
will define a currency format which may then be
assigned to column C, for example, with the command
.RS
.IP
.I format C 10 2 5
.RE
.\" ----------
.TP
.B "@myrow, @mycol"
Are functions that return the row or column
of the current cell respectively.
ex: The cell directly above a cell in the D
column could then be accessed by @nval("d",@myrow-1).
NOTE: @myrow and @mycol can't be used in specifying ranges.
.\" ----------
.TP
.B "@lastrow, @lastcol"
These return the last row and column of the spreadsheet, respectively.
They are useful for macros designed to default to the
whole spreadsheet.
.\" ==========
.SS "Range Commands"
.\" ----------
Range operations affect a rectangular region on the screen
defined by the upper left and lower right cells in the region.
All of the commands in this class begin with ``r'';
the second letter of the command indicates which command.
A small menu lists the choices for the second letter when you type ``r''.
.I pname
prompts for needed parameters for each command.
Phrases surrounded by square brackets in the prompt are
informational only and may be erased with the backspace key.
.\" ----------
.PP
Prompts requesting variable names may be satisfied
with either an explicit variable name, such as
.IR A10 ,
or with a variable name previously defined in a
.I rd
command (see below).
Range name prompts require either an explicit range such as
.IR A10:B20 ,
or a range name previously defined with a
.I rd
command.
A default range shown in the second line
is used if you omit the range from the command or press the
.SM TAB
key (see below).
The default range can be changed by moving the cell cursor
via the control commands
.RI ( ^P " or " ^N )
or the arrow keys.
The cells in the default range are highlighted
(using the terminal's standout mode, if available).
.\" ----------
.TP
.B rx
Clear a range.
Cells cleared with this command will be saved in the
delete buffer, and may be recalled with any of the
.I pull
commands.
.\" ----------
.TP
.B ry
Yank a range.
Like
.IR rx ,
cells yanked with this command will be saved in the
delete buffer, and may be recalled with any of the
.I pull
commands.
This command differs from
.IR rx ,
however, in that the original cells will not be cleared.
Although this command may be used to copy a range of
cells, it treats all references as fixed.
Use
.I rc
if you want references to be relative to the
cell which contains them unless specified otherwise,
either with the
.I @fixed
operator or using the
.I $
character in the reference to the cell.
.\" ----------
.TP
.B rc
Copy a source range to a destination range.
The source and destination may be different sizes.
The result is always one or more full copies of the source.
Copying a row to a row yields a row.
Copying a column to a column yields a column.
Copying a range to anything yields a range.
Copying a row to a column or a column to a
row yields a range with as many copies of the
source as there are cells in the destination.
This command can be used to duplicate a
cell through an arbitrary range by making
the source a single cell range such as
.IR b20:b20 .

If the source range is omitted (second argument),
the source range from the last
.I copy
command will be used, unless a range is currently
highlighted, in which case the highlighted range
will be copied instead.
If both the source range and destination range
are omitted, the current cell will be used as
the destination, unless a range is currently
highlighted, in which case the highlighted range
will serve as the destination, and the source
range from the last
.I copy
command will be copied into that destination.
.\" ----------
.TP
.B rm
Move a source range to a destination range.
This differs from deleting a range with
.I rx
and pulling it back in with
.I pm
in that any expressions that reference a cell
in the range to be moved will reference the cell
at its new address after the move.
Unlike the
.I rc
command, the destination of a move is a single cell,
which will be the upper lefthand corner of the
source range after the move.
.\" ----------
.TP
.B rv
Values only.
This command removes the expressions from a range of cells,
leaving just the values of the expressions.
.\" ----------
.TP
.B rs
Sort a range.
The rows in the specified range will be sorted according
to criteria given in the form of a string of characters.
This string, enclosed in double quotes, may comprise a
single criterion or multiple criteria in decreasing order
of precedence.
Each criterion has three parts, all of which are mandatory.
The first part is a single character, which must be either
.I +
or
.IR - ,
which specifies whether the sort should be done in ascending
or descending order, respectively.
The second part, which is also a single character, must be either
.I #
or
.IR $ ,
and is used to specify whether the sort should be based
on the numeric portion or the string portion, respectively,
of the cells being used for the comparison.
The third part may be either one or two characters, and
must be alphabetic (case insensitive), and specifies
the column to be used when making the comparisons.
This column must be in the range being sorted.
Any number of criteria may be concatenated, and will
be used in the order specified.
If no criteria are specified, the default behavior is to sort
in ascending order, first by string and then by number,
using the leftmost column of the range being sorted.
This is equivalent to specifying the sort criteria to be
.RI """ +$a+#a """,
where both
.IR a 's
are replaced by the name of the leftmost
column of the range being sorted.
.\" ----------
.TP
.B rf
Fill a range with constant values
starting with a given value and increasing by a given increment.
Each row is filled before moving on to the
next row if row order recalculation is set.
Column order fills each column in the range
before moving on to the next column.
The start and increment numbers may be positive or negative.
To fill all cells with the same value, give an increment of zero.
.\" ----------
.TP
.B r{
Left justify all strings in the specified range.
.\" ----------
.TP
.B r}
Right justify all strings in the specified range.
.\" ----------
.TP
.B r|
Center all strings in the specified range.
.\" ----------
.TP
.B rd
Use this command to assign a symbolic name to a single
cell or a rectangular range of cells on the screen.
The parameters are the name, surrounded by "",
and either a single cell name such as
.I A10
or a range such as
.IR a1:b20 .
Names defined in this fashion are used by the program in future prompts,
may be entered in response to prompts requesting a cell or range name,
and are saved when the spreadsheet is saved with the
.I Put
command.
Names defined may be any combination of alphanumeric
characters and
.RI ` _ '
as long as the name isn't a valid cell address.
Thus,
.IR x ,
.IR H2SO4 ,
and
.I 3rdDay
are all valid names, but
.I H2
is not.
.\" ----------
.TP
.B rl
Use this command to lock the current cell or
a range of cells, i.e. make them immune
to any type of editing.
A locked cell can't be changed in
any way until it is unlocked.
.\" ----------
.TP
.B rU
This command is the opposite of the
.I rl
command and thus unlocks a locked cell and makes it editable.
.\" ----------
.TP
.B rS
This command shows lists of the currently defined
range names, framed ranges, and color definitions
and ranges, one after the other.
The output of this command will be piped to
.IR less .
If the environment variable PAGER is set,
its value is used in place of
.IR less .
.\" ----------
.TP
.B ru
Use this command to undefine a previously defined range name.
.\" ----------
.TP
.B rF
Use this command to assign a value format string (see
the ``F'' cell entry command) to a range of cells.
.\" ----------
.TP
.B rr
This command is used for creating, modifying,
and deleting framed ranges.
A framed range, is one which has a number of rows
or columns specified at the top, bottom, left,
and/or right (the frame) which must remain onscreen
whenever the cell cursor is within that range.
In other words, a frame consists of an outer range
and an inner range, where the inner range is allowed
to scroll within the outer range.
Once a frame is defined, the inner range may be
resized, but the outer range remains fixed unless
rows or columns are added or deleted within the range.

When this command is invoked, you will be prompted for
the type of frame-related action you would like to perform.
You may select an option from the list by typing its
first letter.

The options are
.IR top ,
.IR bottom ,
.IR left ,
.IR right ,
.IR all ,
and
.I unframe.
If you choose
.IR top ,
.IR bottom ,
.IR left ,
or
.I right,
you will be prompted for a range and number of rows/columns.
The range may be omitted if the cell cursor is
in a previously defined framed range, in which case
that range's outer range will be used instead.
The number of rows/columns will set or adjust the
width of the corresponding side of the frame.
If all of these widths are set to zero, the frame
will be undefined (same as the unframe command).

If you choose
.IR all ,
you will be prompted for an outer range and an inner range,
in which case the inner range will scroll within the outer
range, and any rows or columns outside of the inner range,
but inside the outer range will be part of the ``frame''
that is to remain onscreen.
The outer range may be omitted if the cell cursor is
in a previously defined framed range, in which case
the previously defined outer range will be used.
However, if a single range is specified on the command line,
while another range wholly contained within this range is
highlighted, the specified range will be used as the
outer range, and the highlighted range will be used as
the inner range.
If no range is specified on the command line, but a range
is highlighted, and the highlighted range is wholly contained
within a previously defined framed range, the highlighted
range will be used as the inner range, and the previously
defined outer range will be used as the outer range.

If you choose
.IR unframe,
you will be prompted for a range, and if the
range is found in the list of frames, the frame
will be deleted, and the framing will no longer
be active (the specified range must be the outer
range of the previously defined frame to be deleted).
The range may be omitted if the cell cursor is
in a previously defined framed range, in which case
that range will be used by default.

Framed ranges may not be nested or overlapping.
If you try to define a range that contains any cells
in common with a previously defined framed range,
an error message will be issued, and the frame
will not be created.
.\" ----------
.TP
.B rC
This command defines a color range, and specifies a
foreground/background pair to be used for that range.
See "Color Commands" below for more information.
.\" ==========
.SS "Note Commands"
.\" ----------
A note is a cell or range of cells that can
be jumped to quickly from another cell by
creating a special link in that cell.
The note may contain text explaining the
contents of the cell containing the link,
similar to a footnote, or it may simply be
another part of the spreadsheet that is
related to the cell in some way.
When you press the `n' key, you will get a
short prompt asking you whether you want
to add or delete a note, or to ``show''
(by highlighting) which cells on the
screen have attached notes.
.PP
If a cell with an attached note contains
numeric data, it will be preceded with an ``*''.
If color is available and turned on, the ``*''
will be displayed with color 4.
Also, the note address will be displayed
in curly braces on the top line, preceded by an ``*'',
when the cell is current (e.g.
.I {*AC30:AE43}
or
.I {*note1}
for a named range).
You may also use the
.I *s
(Note/Show) command to highlight all cells
on the current screen with attached notes.
.TP
.B *a
Add a note.
This will bring up the addnote command
in the top line, followed by the target address
of the cell where you want the note added.  You
must then enter the cell or range where the note
resides to add the note.
If you omit the note address or range, the currently
highlighted range, if any, will be used.
Otherwise, the current cell will be used (you
would, of course, want to move away from the
cell in which the addnote command was invoked
in the latter case).
.\" ----------
.TP
.B *d
Delete a note.
If there is a note attached to the current
cell, the link will be removed (deleted).
The note itself will not be removed from
the spreadsheet.
If it is no longer needed, it must be deleted
in a separate step.
.\" ----------
.TP
.B *s
Show all notes on the current screen.
If there are any cells on the visible portion
of the spreadsheet which contain attached
notes, they will be highlighted until the
next screen change, no matter how minor.
Simply moving to a new cell will be enough
to turn off the highlighting.
.\" ----------
.TP
.B **
Jump to a note.
If there is a note attached to the current cell,
you will be immediately transported to that cell.
You may return from the note to where you were
by pressing ` twice.
.\" ==========
.SS "Color Commands"
.\" ----------
Color may be enabled by setting the color option
(``set color''), or by toggling it with ^TC
(control-T followed by an uppercase C).
If color is enabled, you may define up to eight
color pairs, each consisting of a foreground
color and a background color.
Each of these colors may be defined by an expression
which is evaluated at the same time the rest of the
spreadsheet is evaluated.
Color expressions may be simple, specifying only
a foreground color and a background color, or
they may be arbitrarily complex, causing the colors
to change based upon other data in the spreadsheet,
for example.
Color ranges may then be defined using the
.I rC
command, with a color number (1-8) assigned to
the range (see below).
.PP
Some of the color numbers may have special meaning
under certain circumstances, but may also be used
explicitly at the same time.
For example, color 1 is the default color pair if
color is enabled but no color has been defined for
a given cell.
It is also the color used for the column and row
labels and the top two lines of the display, which
are used for prompts, input, error messages, etc.
Color 2, while not explicitly used for all negative
numbers, will be used for negative numbers in cells
which have no other color defined when colorneg is
turned on (``set colorneg'' or ^TN).
This is because colorneg causes all cells with
negative numbers to have their color number incremented
by one (cycling back to color 1 if the cell is defined
as using color 8).
Color 3 is used for all cells with errors (ERROR or
INVALID), if colorerr is set (``set colorerr'' or ^TE),
regardless of which color they have been defined to use,
or whether they have been defined to use any color at all.
Color 4 is used to highlight the ``*'' which signifies
that a cell has a note attached.
.PP
If two color ranges are nested or overlapping, any
cell that is common to both will be displayed using
the color of the most recently defined color range.
You can list all color definitions and color ranges
with the rS (show) command (see below).
.TP
.B C
This command first prompts you for the color
number you would like to define (or redefine).
After selecting a number (1-8), you may enter
an expression which defines the foreground and
background colors.
If the chosen color has previously been defined,
the old definition will be presented for editing.
The syntax of the color command is:
.RS
.IP
.B color
.I number
=
.I expression
.RE
.IP
where
.I number
is the number of the color pair you want to define, and
.I expression
is the definition.
If the expression is missing, the specified
color number will be unset (it will revert
to its default start-up colors).
Unlike setting it explicitly to its original
value, this will not cause the expression
to be written to the file when saved.
See below for an explanation of the format
of a color expression.
.\" ----------
.TP
.B rC
This command defines a color range, and specifies a
foreground/background pair to be used for that range.
Although this command also uses the
.I color
command, the syntax is different from that used for
defining a color pair.
This syntax is:
.RS
.IP
.B color
.I range number
.RE
.\" ----------
.TP
.B rS
This command shows lists of the currently defined
range names, framed ranges, and color definitions
and ranges, one after the other.
The output of this command will be piped to
.IR less .
If the environment variable PAGER is set,
its value is used in place of
.IR less .
.PP
Color expressions are exactly like any other numeric expression,
and may contain any function or operator that is valid in 
any other numeric expression.
There are, however special functions designed specifically for
defining colors.
These functions are:
.IP
 @black
 @red
 @green
 @yellow
 @blue
 @magenta
 @cyan
 @white
.PP
Although these function names are intended to reflect the
color they produce, and use the same names as the curses
colors, @yellow may appear as brown on many displays,
especially those based on the VGA standard.
.PP
In addition to special functions for specifying colors,
there is also a special operator for combining two such
colors into a single number which specifies both a
foreground and a background color.
This operator is the semicolon (;).
For example, the command
.IP
.I color 1 = @white;@green
.PP
will set the foreground color to white and the
background color to green for any cell or range
of cells defined to use color 1, or which have no color
defined.
If the semicolon operator is not used, and only one
color is specified, that color will be used for the
foreground, and the background will default to black.
.PP
Although the above example is the easiest way to specify
foreground and background colors, and will probably meet
most people's needs,
.I pname
allows much more power and flexibility, should the
need arise, due to the fact that any color can be
specified by an expression.
For example,
.IP
.I color 5 = B23<E75?(@black;@cyan):(@white;@magenta)
.PP
will cause all cells defined with color 5 to be displayed
as black text on a cyan background if the numeric value
in cell B23 is less than the numeric value in cell E75;
otherwise, they will be displayed as white text on a
magenta background.  If you prefer to have the foreground
and background colors dependent on different criteria,
you could do something like this:
.IP
.I color 5 = (B23<E75?@white:@cyan);(D5%2?@red:@blue)
.PP
This will cause the text color for color 5 to be either white
or cyan, depending on the numeric values in cells B23 and E75,
as in the previous example, and the background color to be
either red or blue, depending on whether the numeric value in
cell D5 is odd or even.
.PP
Note that although a color expression may contain any
function which is valid in any other numeric expression, 
the @myrow and @mycol functions will always evaluate to 0.
This is because a color expression is not tied to any
particular cell, but is instead evaluated once, and the
result used for all cells defined to use that color.
.PP
Also note that if a color expression results in an error,
the color will default to black text on a black background.
If color 1 results in an error, color will be disabled so
that you can see the input line to correct the error,
after which color will need to be reenabled manually.
.PP
Default colors are in effect for all colors until defined
otherwise.
These default colors are as follows:
.IP
 color 1 = @white;@blue
 color 2 = @red;@blue
 color 3 = @white;@red
 color 4 = @black;@yellow
 color 5 = @black;@cyan
 color 6 = @red;@cyan
 color 7 = @white;@black
 color 8 = @red;@black
.\" ==========
.SS "Miscellaneous Commands"
.\" ----------
\0 \" exactly one blank line (hard to get)
.PD 0
.TP
.B Q
.TP
.B q
.TP
.B ^C
Exit from
.IR pname .
If you made any changes since the last
.I Get
or
.IR Put ,
.I pname
asks about saving your data before exiting.
.PD
.\" ----------
.TP
.B ^G
.PD 0
.TP
.B ESC
Abort entry of the current command.
.PD
.\" ----------
.TP
.B ?
Enter an interactive help facility.
Lets you look up brief summaries of
the main features of the program.
The help facility is structured like this
manual page so it is easy to find more
information on a particular topic,
although it may not be completely
up-to-date.
.\" ----------
.TP
.B !
Shell escape.
.I pname
prompts for a shell command to run.
End the command line with the
.SM RETURN
key.
If the environment variable
.SM SHELL
is defined, that shell is run.
If not, /bin/sh is used.
Giving a null command line starts the shell in interactive mode.
A second ``!'' repeats the previous command.
.\" ----------
.TP
.B ~
Abbreviations.
You may set abbreviations to speed up the entry of repetitive data.
Abbreviations work much like abbreviations in vi, except that
when defining an abbreviation, both the abbreviation and the
expanded text must be contained within quotes, separated by a
single space.
If more than one space separates the abbreviation from the
expanded text, it will be included as part of the expanded
text.

There are three types of abbreviations available in sc.
In the first type, all characters must be either alphanumeric
or ``_''.
In the second type, the last character must be alphanumeric
or ``_'', but all other characters must not be alphanumeric
or ``_''.
Neither type may contain spaces.
The third type of abbreviation is a single character, and
must be alphanumeric or ``_''.

When using abbreviations, the first type must be at the beginning
of the line, or must be preceded by any character which is not
alphanumeric or ``_''.
The second type must be at the beginning of the line, or must
be preceded either by an alphanumeric character, ``_'', or a
space.
Single character abbreviations must be at the beginning of the
line or preceded by a space.

Abbreviations will be automatically expanded as soon as the
space bar or return key is pressed, or when pressing the
ESC key at the end of the abbreviation to switch to edit mode.
You can also force an abbreviation to be expanded by following
it with a
.IR ^] ,
which won't be inserted into the line.
If you don't want an abbreviation to be expanded, you must
either press
.I ^V
twice or switch to edit mode and back again
somewhere within the abbreviation (pressing
.I ^V
twice also has the effect of switching to navigate mode
and back again).

If the string in the abbreviation command contains no spaces,
the entire string will be looked up in the list of abbreviations,
and if found, the definition will be displayed in the form of
the original
.I abbreviation
command used to define it.
When looking up an abbreviation in this manner, be sure to
disable abbreviation expansion, as described above, or the
results may not be what you expect.

If the string is empty, a list of all abbreviations and their
corresponding expanded text will be output to your pager.
Note that abbreviations are not saved with the file.
This allows each user to create his own file of abbreviations
and either merge them in or include them in his own .scrc file,
rather than force all users who access a file to use the same
list of abbreviations.
.\" ----------
.TP
.B ^L
Redraw the screen.
.\" ----------
.TP
.B ^R
Redraw the screen with special highlighting of cells to be filled in.
This is useful for finding values you need to provide
or update in a form with which you aren't familiar
or of which you have forgotten the details.

It's also useful for checking a form you are creating.
All cells which contain constant numeric values
(not the result of a numeric expression)
are highlighted temporarily,
until the next screen change, however minor.
To avoid ambiguity,
the current range (if any) and current cell are not highlighted.
.\" ----------
.TP
.B ^X
This command is similar to
.IR ^R ,
but highlights cells which have expressions.
It also displays the expressions in the highlighted cells
as left-flushed strings,
instead of the numeric values and/or label strings of those cells.
This command makes it easier to check expressions,
at least when they fit in their cells or the following
cell(s) are blank so the expressions can slop over
(like label strings).
In the latter case, the slop over is not cleared
on the next screen update, so you may want to type
.I ^L
after the
.I ^X
in order to clean up the screen.
.\" ----------
.TP
.B @
Recalculates the spreadsheet.
.\" ==========
.SS "Variable Names"
.\" ----------
Normally, a variable name is just the name of a cell, such as
.IR K20 .
The value is the numeric or string value of the cell,
according to context.
.\" ----------
.PP
When a cell's expression (formula) is copied to another location via
.I copy
or
.IR range-copy ,
variable references are by default offset by the amount the formula moved.
This allows the new formula to work on new data.
If cell references are not to change,
you can either use the
.I @fixed
operator (see below),
or one of the following variations on the cell name.
.\" ----------
.TP
.I K20
References cell
.IR K20 ;
the reference changes when the formula is copied.
.\" ----------
.TP
.BI $ K $ 20
Always refers to cell
.IR K20 ;
the reference stays fixed when the formula is copied.
.\" ----------
.TP
.BI $ K20
Keeps the column fixed at column K;
the row is free to vary.
.\" ----------
.TP
.IB K $ 20
Similarly, this fixes the row and allows the column to vary.
.\" ----------
.PP
These conventions also hold on defined ranges.
Range references vary when formulas containing them are copied.
If the range is defined with fixed variable references,
the references do not change.
.\" ----------
.TP
.B @fixed
To make a variable not change automatically when a cell moves,
put the word
.I @fixed
in front of the reference, for example:
B1 \(** @fixed C3.
.\" ==========
.SS "Numeric Expressions"
.\" ----------
Numeric expressions used with the ``=''
and
.I e
commands have a fairly conventional syntax.
Terms may be
constants,
variable names,
parenthesized expressions,
and negated terms.
Ranges may be operated upon with range functions such as sum
.RI ( @sum ())
and average
.RI ( @avg ()).
Terms may be combined using binary operators.
.\" ----------
.TP
.BI \- e
Negation.
.\" ----------
.TP
.IB e + e
Addition.
.\" ----------
.TP
.IB e \- e
Subtraction.
.\" ----------
.TP
.IB e \(** e
Multiplication.
.\" ----------
.TP
.IB e / e
Division.
.\" ----------
.TP
.IB e1 % e2
e1 mod e2.
.\" ----------
.TP
.IB e ^ e
Exponentiation.
.\" ----------
.TP
.IB e < e
.PD 0
.TP
.IB e <= e
.TP
.IB e = e
.TP
.IB e != e
.TP
.IB e >= e
.TP
.IB e > e
Relationals:
true (1) if and only if the indicated relation holds,
else false (0).
Note that ``<='', ``!='', and ``>=''
are converted to their ``!()'' equivalents.
.PD
.\" ----------
.TP
.BI ~ e
Boolean operator
.SM NOT.
.\" ----------
.TP
.IB e & e
Boolean operator
.SM AND.
.\" ----------
.TP
.IB e | e
Boolean operator
.SM OR.
.\" ----------
.TP
.BI @if( e , e , e )
.PD 0
.TP
.IB e ? e : e
.PD
Conditional:
If the first expression is true then the value of the second is returned,
otherwise the value of the third.
.\" ----------
.PP
Operator precedence from highest to lowest is:
.PP
.nf
.RS
\-, ~, !
^
\(**, /
+, \-
<, <=, =, !=, >=, >
&
|
?:
.RE
.fi
.\" ==========
.SS "Built-in Range Functions"
.\" ----------
These functions return numeric values.
The @sum, @prod, @avg, @count, @max, @min, and @stddev functions
may take an optional second argument which is an expression that
is to be evaluated for each cell in the specified range to determine
which cells to include in the function.
Only those cells for which the expression evaluates to true (non-zero)
will be used in calculating the value of the function.
Before evaluation for each cell, the expression is first converted
as if it was being copied from the cell in the upper left-hand corner
of the range into the cell under consideration, with all cell
references adjusted accordingly.
Because the parts of the expression that should remain fixed during
the evaluation of the function may not necessarily be the same as
those which should remain fixed during an actual copy operation,
the rules for adjusting cell references during a copy operation are
slightly different than normal.
In particular, these rules differ in two different ways.

The first difference is that the
.I @fixed
operator is ignored during a copy operation unless it is enclosed
in parentheses.
This is so that selected cells whose addresses should remain fixed
during any given evaluation of a range function can be adjusted
relative to the cell containing the range function when copied (the
.I $
prefix is still honored for these cells when copying).
Enclosing the
.I @fixed
operator in parentheses will have the opposite effect.
That is, it will cause cell references to be fixed while copying,
while allowing them to be adjusted when the function is being evaluated,
subject to any
.I $
prefixes present.
Note that only the
.I @fixed
operator itself should be enclosed in parentheses for this to work properly.

The second difference is that any references in the expression
that refer to cells in the range in the first argument of the
range function will have any
.I $
prefixes ignored, and the references will be treated instead
as if they had the same
.I $
prefixes as the left side of the range argument.
For example, if the left side of the range argument (the cell
address on the left side of the colon) has a fixed row, but does not
have a fixed column, any cell references that refer to cells in
that range will also have a fixed row, but will not have a fixed
column.
This is so that if the range reference moves when copying,
references to any cells in that range will also move accordingly.

Note that the test expression will be evaluated once for every cell in
the range, which means that excessive use of these functions with the
optional test expression, or the use of overly complex test expressions
or with very large ranges can greatly slow down the recalculation of a
spreadsheet, and may require turning off autocalc for speed, and then manually
recalculating with the
.I @
command.
.\" ----------
.TP 18
.BI @sum( r )
.PD 0
.TP 18
.BI @sum( r , e )
.PD
Sum all valid (nonblank) entries in the region
whose two corners are defined by the two variable names (e.g.
.IR c5:e14 )
or the range name specified.
The optional second argument is an expression which can be
used to determine which cells in the range to sum (see above).
.\" ----------
.TP 18
.BI @prod( r )
.PD 0
.TP 18
.BI @prod( r , e )
.PD
Multiply together all valid (nonblank) entries in the specified region.
The optional second argument is an expression which can be
used to determine which cells in the range to multiply (see above).
.\" ----------
.TP 18
.BI @avg( r )
.PD 0
.TP 18
.BI @avg( r , e )
.PD
Average all valid (nonblank) entries in the specified region.
The optional second argument is an expression which can be
used to determine which cells in the range to average (see above).
.\" ----------
.TP 18
.BI @count( r )
.PD 0
.TP 18
.BI @count( r , e )
.PD
Count all valid (nonblank) entries in the specified region.
The optional second argument is an expression which can be
used to determine which cells in the range to count (see above).
.\" ----------
.TP 18
.BI @max( r )
.PD 0
.TP 18
.BI @max( r , e )
.PD
Return the maximum value in the specified region.
The optional second argument is an expression which can be
used to exclude specific cells in the range when determining
this maximum value (see above).
See also the multi argument version of
.I @max
below.
.\" ----------
.TP 18
.BI @min( r )
.PD 0
.TP 18
.BI @min( r , e )
.PD
Return the minimum value in the specified region.
The optional second argument is an expression which can be
used to exclude specific cells in the range when determining
this minimum value (see above).
See also the multi argument version of
.I @min
below.
.\" ----------
.TP 18
.BI @stddev( r )
.PD 0
.TP 18
.BI @stddev( r , e )
.PD
Return the sample standard deviation of the cells in the specified region.
The optional second argument is an expression which can be
used to exclude specific cells in the range when calculating
the standard deviation (see above).
.\" ----------
.TP 18
.BI @rows( r )
Return the number of rows in the specified range.
.\" ----------
.TP 18
.BI @cols( r )
Return the number of columns in the specified range.
.\" ----------
.TP 18
.BI @lookup( e , r )
.PD 0
.TP 18
.BI @lookup( r , e )
.PD 0
.TP 18
.BI @lookup( se , r )
.PD 0
.TP 18
.BI @lookup( r , se )
.PD
Evaluates the expression then searches through the range
.I r
for a matching value.
The range should be either a single row or a single column.
The expression can be either a string expression
or a numeric expression.
If it is a numeric expression, the range is searched
for the the last value less than or equal to 
.IR e .
If the expression is a string expression, the string portions
of the cells in the range are searched for an exact string match.
The value returned is the numeric value from the next row and the same
column as the match, if the range was a single row, or the value from
the next column and the same row as the match if the range was a single
column.
.\" ----------
.TP 18
.BI @hlookup( e , r , n )
.PD 0
.TP 18
.BI @hlookup( r , e , n )
.PD 0
.TP 18
.BI @hlookup( se , r , n )
.PD 0
.TP 18
.BI @hlookup( r , se , n )
.PD
Evaluates the expression then searches through the first row in the range
.I r
for a matching value.
The expression can be either a string expression
or a numeric expression.
If it is a numeric expression,
the row is searched for the the last value less than or equal to 
.IR e .
If the expression is a string expression, the string portions
of the cells in the row are searched for an exact string match.
The value returned is the numeric value from the same column
.I n
rows below the match.
.\" ----------
.TP 18
.BI @vlookup( e , r , n )
.PD 0
.TP 18
.BI @vlookup( r , e , n )
.PD 0
.TP 18
.BI @vlookup( se , r , n )
.PD 0
.TP 18
.BI @vlookup( r , se , n )
.PD
Evaluates the expression then searches through
the first column in the range
.I r
for a matching value.
The expression can be either a string
expression or a numeric expression.
If it is a numeric expression, the column is searched
for the the last value less than or equal to 
.IR e .
If the expression is a string expression, the string portions
of the cells in the column are searched for an exact string match.
The value returned is the numeric value from the same row
.I n
columns to the right of the match.
.\" ----------
.TP 18
.BI @index( e1 , r )
.PD 0
.TP 18
.BI @index( r , e1 )
.PD 0
.TP 18
.BI @index( r , e1 , e2 )
.PD
Use the values of expressions 
.I e1
and (optionally)
.I e2
to index into
the range
.IR r .
The numeric value at that position is returned. 
With two arguments, the range should be either a
single row or a single column.
An expression with the value 1 selects the first
item in the range, 2 selects the second item, etc.
With three arguments, the range must come first,
and the second and third arguments will then be
interpreted as row and column, respectively,
for indexing into a two-dimensional table.
.\" ----------
.TP 18
.BI @stindex( e1 , r )
.PD 0
.TP 18
.BI @stindex( r , e1 )
.PD 0
.TP 18
.BI @stindex( r , e1 , e2 )
.PD
Use the values of expressions
.I e1
and (optionally)
.I e2
to index into
the range
.IR r .
The string value at that position is returned. 
With two arguments, the range should be either a
single row or a single column.
An expression with the value 1 selects the first
item in the range, 2 selects the second item, etc.
With three arguments, the range must come first,
and the second and third arguments will then be
interpreted as row and column, respectively,
for indexing into a two-dimensional table.
.\" ==========
.SS "Built-in Numeric Functions"
.\" ----------
All of these functions operate on floating point numbers (doubles)
and return numeric values.
Most of them are standard system functions more fully described in
.IR math (3).
The trig functions operate with angles in radians.
.\" ----------
.TP 18
.BI @sqrt( e )
Return the square root of
.IR e .
.\" ----------
.TP 18
.BI @exp( e )
Return the exponential function of
.IR e .
.\" ----------
.TP 18
.BI @ln( e )
Return the natural logarithm of
.IR e .
.\" ----------
.TP 18
.BI @log( e )
Return the base 10 logarithm of
.IR e .
.\" ----------
.TP 18
.BI @floor( e )
Return the largest integer not greater than
.IR e .
.\" ----------
.TP 18
.BI @ceil( e )
Return the smallest integer not less than
.IR e .
.\" ----------
.TP 18
.BI @rnd( e )
Round
.I e
to the nearest integer.
default: *.5 will be rounded up to the next integer;
doing a 'set rndtoeven' will cause it to be rounded to
the closest even number instead (aka banker's round).
Round-to-even has advantages over the default rounding
for some applications.
For example, if X+Y is an integer,
then X+Y = rnd(X)+rnd(Y) with round-to-even,
but not always with the defaulting rounding method.
This could be an advantage, for example, when trying to
split an odd amount of money evenly between two people (it
would determine who gets the extra penny).
.TP 18
.BI @round( e , n )
Round
.I e
to
.I n
decimal places.
.I n
may be positive to round off the right side of the decimal
or negative to round off the left side.
See @rnd(e) above for rounding types.
.\" ----------
.TP 18
.BI @abs( e )
.PD 0
.TP 18
.BI @fabs( e )
Return the absolute value of
.IR e .
.PD
.\" ----------
.TP 18
.BI @pow( e1 , e2 )
Return
.I e1
raised to the power of
.IR e2 .
.\" ----------
.TP 18
.BI @hypot( e1 , e2 )
Return sqrt(e1\(**e1+e2\(**e2), taking precautions
against unwarranted overflows.
.\" ----------
.TP 18
.B @pi
A constant quite close to pi.
.\" ----------
.TP 18
.BI @dtr( e )
Convert
.I e
in degrees to radians.
.\" ----------
.TP 18
.BI @rtd( e )
Convert
.I e
in radians to degrees.
.\" ----------
.TP 18
.BI @sin( e )
.PD 0
.TP 18
.BI @cos( e )
.TP 18
.BI @tan( e )
Return trigonometric functions of radian arguments.
The magnitude of the arguments are not checked
to assure meaningful results.
.PD
.\" ----------
.TP 18
.BI @asin( e )
Return the arc sine of
.I e
in the range -pi/2 to pi/2.
.\" ----------
.TP 18
.BI @acos( e )
Return the arc cosine of
.I e
in the range 0 to pi.
.\" ----------
.TP 18
.BI @atan( e )
Return the arc tangent of
.I e
in the range -pi/2 to pi/2.
.\" ----------
.TP 18
.BI @atan2( e1 , e2 )
Returns the arc tangent of
.IR e1 / e2
in the range -pi to pi.
.\" ----------
.TP 18
.BI @max( e1 , e2 , ... )
Return the maximum of the values of the expressions.
Two or more expressions may be specified.
See also the range version of 
.I @max
above.
.\" ----------
.TP 18
.BI @min( e1 , e2 , ... )
Return the minimum of the values of the expressions.
Two or more expressions may be specified.
See also the range version of 
.I @min
above.
.\" ----------
.TP 18
.BI @ston( se )
Convert string expression
.I se
to a numeric value.
.\" ----------
.TP 18
.BI @eqs( se1 , se2 )
Return 1 if string expression
.I se1
has the same value as string expression
.IR se2 ,
0 otherwise.
.\" ----------
.TP 18
.BI @nval( se , e )
Return the numeric value of a cell selected by name.
String expression
.I se
must evaluate to a column name (``A''-``AE'') and
.I e
must evaluate to a row number (0-199). 
If
.I se
or
.I e
is out of bounds, or the cell has no numeric value, the result is 0.
You can use this for simple table lookups.
Be sure the table doesn't move unexpectedly!
See also
.IR @sval ()
below.
.\" ----------
.TP 18
.B @err
Force an error.
This will force the expression which contains it
to result in an error.
.\" ==========
.SS "String Expressions"
.\" ----------
String expressions are made up of constant strings
(characters surrounded by double quotation marks),
variables
(cell names, which refer to the cells's label strings or expressions),
and string functions.
Note that string expressions are only allowed
when entering a cell's label string, not its numeric part.
Also note that string expression results may
be left or right flushed or centered,
according to the type of the cell's string label.
.\" ----------
.TP
.B #
Concatenate strings.
For example, the string expression
.IP ""
	A0 # "zy dog"
.IP ""
displays the string ``the lazy dog'' in the cell if the value of
.IR A0 's
string is ``the la''.
.\" ==========
.SS "Built-in String Functions"
.\" ----------
\0 \" exactly one blank line (hard to get)
.PD 0
.TP 18
.BI @filename( e )
Return the current default filename, as specified
when the file was first loaded or created,
or during the last save, with the
.I Put
command.
If
.I e
is 0, only the actual filename will be returned,
with any path removed.
If non-zero, the full path specified on the command line
or in the last
.I Get
or
.I Put
command will be returned.
If the path begins with ``~'', it will be expanded to
the appropriate users home directory.
.PD
.\" ----------
.TP 18
.BI @substr( se , e1 , e2 )
Extract and return from string expression
.I se
the substring indexed by character number
.I e1
through character number
.I e2
(defaults to the size of
.I se
if beyond the end of it).
If
.I e1
is less than 1 or greater than
.IR e2 ,
the result is the null string.
For example,
.IP ""
	@substr ("Nice jacket", 4, 8)
.IP ""
returns the string ``e jac''.
.\" ----------
.TP 18
.BI @fmt( se , e )
Convert a number to a string.
The argument
.I se
must be a valid
.IR printf (3)
format string.
.I e
is converted according to the standard rules.
For example, the expression
.IP ""
	@fmt ("\(**\(**%6.3f\(**\(**", 10.5)
.IP ""
yields the string ``\(**\(**10.500\(**\(**''.
.I e
is a double, so applicable formats are e, E, f, g, and G.
Try ``%g'' as a starting point.
.\" ----------
.TP 18
.BI @sval( se , e )
Return the string value of a cell selected by name.
String expression
.I se
must evaluate to a column name (``A''-``AE'') and
.I e
must evaluate to a row number (0-199). 
If
.I se
or
.I e
is out of bounds, or the cell has no string value,
the result is the null string.
You can use this for simple table lookups.
Be sure the table doesn't move unexpectedly!
.\" ----------
.TP 18
.BI @upper( se )
.PD 0
.TP 18
.BI @lower( se )
will case the string expression to upper or lower.
.PD
.\" ----------
.TP 18
.BI @capital( se )
will convert the first letter of words in a string
into upper case and other letters to lower case
(the latter if all letters of the string are upper case).
.\" ----------
.TP 18
.BI @ext( se , e )
Call an external function (program or script).
The purpose is to allow arbitrary functions on values,
e.g. table lookups and interpolations.
String expression
.I se
is a command or command line to call with
.IR popen (3).
The value of
.I e
is converted to a string and appended to the
command line as an argument.
The result of
.IR @ext ()
is a string:
the first line printed to standard output by the command.
The command should emit exactly one output line.
Additional output, or output to standard error, messes up the screen.
.IR @ext ()
returns a null string and prints an appropriate warning
if external functions are disabled,
.I se
is null, or the attempt to run the command fails.
.IP ""
External functions can be slow to run,
and if enabled are called at each screen update,
so they are disabled by default.
You can enable them with
.I ^T
when you really want them called.
.IP ""
A simple example:
.IP ""
	@ext ("echo", a1)
.IP ""
You can use
.IR @ston ()
to convert the
.IR @ext ()
result back to a number.
For example:
.IP ""
	@ston (@ext ("form.sc.ext", a9 + b9))
.IP ""
Note that you can build a command line (including more argument values)
from a string expression with concatenation.
You can also "hide" the second argument by ending the command line
(first argument) with `` #'' (shell comment).
.\" ----------
.TP 18
.BI @coltoa( e )
Returns a string name for a column from the numeric argument.
For example:
.IP ""
	@coltoa(@mycol-1)
	@nval(coltoa(@mycol-1), @myrow+1)
.IP ""
.\" ==========
.SS "Built-in Financial Functions"
.\" ----------
Financial functions compute the mortgage (or loan)
payment, future value, and the present value functions.
Each accepts three arguments, an amount, a rate of interest
(per period), and the number of periods.
These functions are the same as those commonly found
in other spreadsheets and financial calculators
.\" ----------
.TP 18
.BI @pmt( e1 , e2 , e3 )
.IR @pmt (60000,.01,360)
computes the monthly payments for a $60000 mortgage at
12% annual interest (.01 per month) for 30 years (360 months).
.\" ----------
.TP 18
.BI @fv( e1 , e2 , e3 )
.IR @fv (100,.005,36)
computes the future value for 36 monthly payments
of $100 at 6% interest (.005 per month).
It answers the question:
"How much will I have in 36 months if I deposit $100
per month in a savings account paying 6% interest
compounded monthly?"
.\" ----------
.TP 18
.BI @pv( e1 , e2 , e3 )
.IR @pv (1000,.015,36)
computes the present value of an ordinary annuity of
36 monthly payments of $1000 at 18% annual interest.
It answers the question:
"How much can I borrow at 18% for 3 years if I
pay $1000 per month?"
.\" ==========
.SS "Built-in Date and Time Functions"
.\" ----------
Time for
.I pname
follows the system standard:
the number of seconds since the beginning of 1970.
All date and time functions except
.IR @date ()
return numbers, not strings.
.\" ----------
.TP 18
.B @now
Return the current time encoded
as the number of seconds since the beginning of the
epoch (December 31, 1969, midnight, GMT).
.\" ----------
.TP 18
.BI @dts( e1 , e2 , e3 )
Convert a date to the number of seconds from the epoch
to the first second of the specified date, local time.
Dates may be specified in either (m,d,y) or (y,m,d) format,
although the latter is preferred, since it's more universally
recognized (m,d,y is only used in America).
If e2 > 12 or e3 > 31, then (m,d,y) is assumed.
Otherwise, (y,m,d) is assumed.
For example,
.IR @date(@dts(1976,12,14))
yields
.IP ""
.I "	Tue Dec 14 00:00:00 1976"
.IP ""
The month should range from  1 to 12;
the day should range from 1 to the number
of days in the specified month;
and the year should include the century
(e.g. 1999 instead of 99).
Any date capable of being handled by the system
is valid, typically 14 Dec 1901 to 18 Jan 2038
on a system that uses a 32 bit time_t.
Invalid dates or dates outside of this range will return ERROR.
For rapid entry of dates using only the numeric keypad,
.I pname
provides the alternate syntax
.IR y.m.d
or
.IR m.d.y,
which is automatically converted to the @dts(...) format above.
The year, month, and day must be entered numerically
in the alternate syntax; formulas are not allowed.
.\" ----------
.TP 18
.BI @tts( e1 , e2 , e3 )
.IR @tts (8,20,45)
converts the time 8:40:45 to the number of seconds since
midnight, the night before.
The hour should range from 0 to 23;
the minutes and seconds should range from 0 to 59.
.\" ----------
.PP
The following functions take the time in seconds
(e.g. from
.IR @now )
as an argument and return the specified value.
The functions all convert from GMT to local time.
.\" ----------
.TP 18
.BI @date( e )
.PD 0
.TP 18
.BI @date( e , se )
.PD
Convert the time in seconds to a date string.
With a single numeric argument, the date will
be 24 characters long in the following form:
.IP ""
.I "	Sun Sep 16 01:03:52 1973"
.IP ""
Note that you can extract parts of this fixed-format string with
.IR @substr ().
A format string compatible with the strftime()
function may optionally be given as a second
argument to override the default format.
See the strftime(3) man page for details.
.\" ----------
.TP 18
.BI @year( e )
Return the year.
Valid years begin with 1970, although many
systems will return years prior to 1970 if
.I e
is negative.
The last legal year is system dependent.
.\" ----------
.TP 18
.BI @month( e )
Return the month, encoded as 1 (January) to 12 (December).
.\" ----------
.TP 18
.BI @day( e )
Return the day of the month, encoded as 1 to 31.
.\" ----------
.TP 18
.BI @hour( e )
Return the number of hours since midnight, encoded as 0 to 23.
.\" ----------
.TP 18
.BI @minute( e )
Return the number of minutes since the last full hour,
encoded as 0 to 59.
.\" ----------
.TP 18
.BI @second( e )
Return the number of seconds since the last full minute,
encoded as 0 to 59.
.\" ==========
.SS "Spreadsheet Update"
.\" ----------
Re-evaluation of spreadsheet expressions is done by row
or by column depending on the selected calculation order.
Evaluation is repeated up to 
.I iterations
times for each update if necessary,
so forward references usually work as expected.
See
.I set
above.
If stability is not reached after ten iterations,
a warning is printed.
This is usually due to a long series of forward references,
or to unstable cyclic references (for example, set
.IR A0 's
expression to ``A0+1'').
.TP 18
.B @numiter 
Returns the number of iterations performed so far.
.\" ==========
.SS "Programmable Function Keys"
.\" ----------
Function keys can be used in
.I pname
if your terminal supports them, and they are programmable.
To program the function keys, you use the
.I fkey
command.
This command may be used in a
.I .scrc
file or a macro file, or it may be entered directly into
.IR pname 's
command line.
Defined function keys will be saved with the file.
There is no shortcut, as there is with most commands,
so the full command must be typed in.
Pressing enter when not editing a line will start
you off with a blank line for this purpose.
The format of the
.I fkey
command is:
.IP
.B fkey
.I n
=
.I """command""
.LP
where
.I n
is the function key number (n = 1 for F1, n = 2 for F2, etc.), and
.I command
is the command to be run.
For example,
.IP
.I "fkey 2 = ""merge \\\\""|~/scmacros/macro1\\\\""""
.LP
will run the macro called
.I macro1
located in a subdirectory of your home directory called
.IR scmacros
when the F2 key is pressed.
Note that embedded quotes must be escaped by a backslash.
If you want to include the cell address of the
current cell in the command line,
you may do so by entering ``$$'' in its place
in the command.
For example,
.IP
.I "fkey 5 = ""fmt $$ \\\\""^D%A\\\\""""
.LP
will cause the F5 key to format the current cell to display the
full weekday name of the numeric date value stored there.
The ^D is a CTRL-D character, which denotes a date format.
.LP
Although it may be overridden by the
.I fkey
command, the F1 key is predefined by default to execute
.I man sc.
Unlike the user-defined function keys, this definition will also
work in edit, insert, replace, and navigate modes.
.LP
To undefine a function key, merely define it as
the empty string ("").
Undefining the F1 key will restore the default behavior.
.\" ==========
.SS "Plugins"
.\" ----------
There are three ways in which external
programs can be used as plugins with
.IR pname .
First, they can be used as external commands.
When used as an external command, any command 
not recognized by
.I pname
will be searched for first in $HOME/.sc/plugins,
and then in #LIBDIR#/plugins.
If found, it will be run with its standard input
and standard output redirected back to
.IR pname .
These are used to send commands to, and receive
responses back from
.I pname
in the same way that advanced macros do.
.LP
The second and third ways that programs can be used
as plugins with
.I pname
are to automatically convert files to and from
.I sc
format based on their extensions.
In order to use them in this way, you must first
associate a given extension to a corresponding
plugin (for reading) or plugout (for writing) using
the
.I plugin
and
.I plugout
commands.
These commands should be placed in your
.I .scrc
file, and have the following syntax:
.IP
.B plugin
.I """ext""
=
.I """programname""
.LP
or
.IP
.B plugout
.I """ext""
=
.I """programname""
.LP
where
.I ext
is the extension and
.I programname
is the name of the plugin program to be used
for filenames with that extension.
For input, the plugin merely reads the specified file,
performs whatever conversion is necessary, and writes
the resulting data to standard output.
For output, the plugin writes
.I pname
commands to standard output and reads the replies
from standard input in the same way that an advanced
macro would, and then converts the data to the
appropriate format and writes it to a file with
the specified filename.
.\" ==========
.SH FILES
.TP 3in
#LIBDIR#/tutorial.pname
Tutorial spreadsheet.
.TP 3in
$HOME/.scrc
Initialization commands.
.IP "./.scrc"
More initialization commands.
.SH SEE ALSO
bc(1), dc(1), crypt(1), ppname(1)
.\" ==========
.SH BUGS
Top-to-bottom, left-to-right evaluation of expressions is silly.
A proper following of the dependency graph
with (perhaps) recourse to relaxation should be implemented.
.\" ----------
.PP
On some systems,
if the cell cursor is in column 0 with topline enabled
(so the current cell is highlighted),
or if any cell in column 0 is highlighted,
the corresponding row number gets displayed and then blanked
during a screen refresh.
This looks like a bug in
.IR curses .
.\" ----------
.PP
Many commands give no indication (a message or beep)
if they have null effect.
Some should give confirmation of their action, but they don't.
.SH AUTHORS
This is a much modified version of a public domain spread sheet
originally authored by James Gosling,
and subsequently modified and posted to USENET by
Mark Weiser under the name
.IR vc .
The program was subsequently renamed
.IR sc ,
and further modified by numerous contributors,
Jeff Buhrt
of Proslink, Inc.
and Robert Bond of Sequent,
prominent among them.
The current maintainer is Chuck Martin (nrocinu@myrealbox.com).
.PP
Other contributors include:
Tom Anderson,
Glenn T. Barry,
Gregory Bond,
Stephen (Steve) M. Brooks,
Peter Brower,
John Campbell,
Lawrence Cipriani,
Jim Clausing,
Dave Close,
Chris Cole,
Jonathan Crompron,
David I. Dalva,
Glen Ditchfield,
Sam Drake,
James P. Dugal,
Paul Eggert,
Andy Fyfe,
Jack Goral,
Piercarlo "Peter" Grandi,
Henk Hesselink,
Jeffrey C Honig,
Kurt Horton,
Jonathan I. Kamens,
Peter King,
Tom Kloos,
Michael Lapsley,
Casey Leedom,
Jay Lepreau,
Dave Lewis,
Rick Linck,
Soren Lundsgaard,
Tad Mannes,
Rob McMahon,
Chris Metcalf,
Mark Nagel,
Ulf Noren,
Marius Olafsson,
Gene H. Olson,
Henk P. Penning,
Rick Perry,
Larry Philps,
Eric Putz,
Jim Richardson,
Michael Richardson,
R. P. C. Rodgers,
Kim Sanders,
Mike Schwartz,
Alan Silverstein,
Lowell Skoog,
Herr Soeryantono,
Tim Theisen,
Tom Tkacik,
Andy Valencia,
Adri Verhoef,
Rick Walker,
Petri Wessman,
and
Tim Wilson.
.\" end of man page