Edition 2.4.16 (or later if we didn't update this page)

Introduction

SM is still evolving slowly, and this documentation may not be
true, helpful, or complete. In order of increasing plausibility,
information may be obtained from the HELP command, this document, the
authors, and the source code. RHL is prepared to guarantee that the
executable code has not been patched.

If you find bugs, (reasonable) features that you want, wrong documentation,
or anything else that inspires you please let us know. At least under
Unix the macro gripe should be a convenient way to send us mail.
Please also send us any clever macros that you would like to share.

Next a disclaimer: SM is copyright (C)1987, 1989, 1990, 1991,
1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000
Robert Lupton and Patricia Monger.
This programme is not public domain, except where specifically stated
to the contrary, either in the code, or in the manual. If you have a
legally acquired copy you may use it on any computer "on the same site",
but you may not give it away or sell it. If you have a legal copy we
will provide some support and allow you with as many upgrades
as you provide tapes for (or wish to retrieve with ftp).

SM is provided `as is' with no warranty, and we are not responsible for any
losses resulting from its use.

In addition to this manual there is a tutorial introduction which you
might find less intimidating.
See section `The SM Tutorial' in The SM Tutorial.

This should be unimportant, but in case it isn't you can submit SM
bug reports (or requests for new features) using the URL
http://www.astro.princeton.edu/cgi-bin/gnatsweb.pl;
you want to query on category sm (and maybe smdoc) from

advanced query; note that you can save this query, set a bookmark,
and so forth.

Description of SM

SM is an interactive plotting programme with a flexible
command language. The plot data may be defined to SM in a number of ways.
There is also a powerful mechanism for defining and editing plot `macros'
(sets of SM plot commands that are defined and
invoked as plot "subprogrammes").

The
features of SM are described fully in the next few sections, but
let us start with a description of how to produce your first SM
plot. Before you start, notice that SM is case sensitive.
Keywords may be typed in lower or uppercase (as we do in this manual),
but we would recommend using lowercase. It is in fact possible to change
the meanings of lowercase keywords, but this can be confusing. If you are
interested, see the section on "overloading".
See `uppercase' in the index
if you really want to use your shift key.

A simple plot

Let us assume that you have a file called mydata, which looks
like this:

This is an example file

1 1 1
2 4 8
3 9 27
4 16 64
5 25 125
6 36 216
7 49 343
8 64 512

SM has a history mechanism, so
first type DELETE 0 10000 to tell SM to forget any
commands that it has remembered. Then choose a device to plot on. You
do this with a command like dev tek4010. If you don't know what
to call your terminal, use the LIST DEVICE command, ask some local
expert, look at the description
of DEVICE, or (if desperate) read the manual (see section The Stdgraph Graphics Kernel).
You'll know that
you have succeeded if typing BOX draws a box.

You should now have successfully chosen a graphics terminal. To actually
plot something, use the following set of commands. The text after the
# is a comment, you don't have to type this (or the #).

DATA mydata             # Specify desired datafile
LINES 3 100             # Choose which lines to use
READ i 1                # Read column 1 into `i'
READ { ii 2 iii 3 }     # Read column 2 into `ii' and 3 into `iii'
LIMITS i ii             # Choose limits, based on i and ii
BOX                     # Draw the axes
PTYPE 4 0               # Choose square point markers
POINTS i ii             # Plot i against ii
CONNECT i ii            # and connect the points
XLABEL This is i        # Label the X-axis
YLABEL This is ii       # And the Y

You should now have a graph. If you had wanted to plot the third
column instead of the second
you could have typed LIMITS i iii POINTS i iii instead.
And of course you could plot ii against iii as a third
alternative. You
were not limited to only use squares as markers or solid lines to
connect them - see PTYPE and LTYPE for details.

If you want a logarithmic plot, SM makes that easy for you.
You can take logs of a vector using the LG (or LN) commands
on vectors; try it - SET x=1,10 SET y=x**3 set ly=LG(y) LIMITS x ly
CON x ly box. You might have wanted the axes to reflect the fact that you
had logged the y axis. The TICKSIZE command allows you to do this, and
this is in fact the commonest use of it. Try TICKSIZE 0 0 -1 0, and
then repeating the x-y plot.

What if you want hard copy of your hard-earned graph? There is a
command (actually a macro) called playback which will repeat all
the commands that you have typed. Type ERASE to clear the screen, then
HISTORY to see the commands that you have issued. You probably
don't want the ERASE command to be repeated, so type DELETE

to delete it(1).

If there are any other mistakes use DELETE m n to delete
the lines m to n containing them.
Now type playback and your plot should reappear. But we wanted a
hardcopy, so type dev laser lqueue (or whatever your friendly Guru
recommends as a hardcopy device), then playback. This time, those
plotting commands will appear on the laser printer not your terminal. To
make them actually appear, type hardcopy or issue another

dev command.
Be sure to say dev tek4010 (or whatever device you chose)
before you read any more of this
document. It is possible to edit the playback buffer, rather than
simply deleting lines from within it. The section on `examples'
describes how to do this.

In fact, the same plot could have been produced from a data file which
just contained the first column. After saying READ i 1, you could
have said SET ii = i*i SET iii = i**3 and proceeded from there, or
even skipped the file altogether by saying set i = 1,8 instead of

READing it at all. Such possibilities, and a good deal more, are
described in greater detail in the rest of this manual.

What we just did was to define a simple `macro', in this case the
special one called all which playback manipulates. A more
explicit use of a macro would be to define a macro to square a vector,
that is to square each element of a vector.
To do this say(2)

MACRO square 2 { SET $1 = $2*$2 } 

So to calculate the vector ii we could now say

square ii i

which is the same as saying

SET ii = i*i 

So now that you have met macros, how do you save them? The simplest
and least reliable way is to use SM's history, and hope that
the next time that you use SM it remembers the MACRO
command that you used to define square, so you can re-issue it.
(Try exiting SM, then starting it up again and typing
HISTORY, then ^nnn where nnn is the number
which is next to the desired command in the resulting list.)

A brute force way is to say SAVE filename which will save almost
all of your SM environment, to be recovered using the
RESTORE filename command at some later time, or later SM
session.
Specifically, SAVE will save all your macros, variables, and
vectors, along with your history buffer. This is a very convenient
way in practice but it does mean that you tend to carry around
lots of long-forgotten
macros, variables, and vectors.

Another way is to write the macros to a disk file, using the
MACRO WRITE command (see `Macros'). Then you can retrieve
your macros with MACRO READ. You should note that your macro

all will simply be a macro - to put it onto the history list
say DELETE 0 10000 WRITE HISTORY all. (Of course, you could
write a macro to do this for you).
Maybe saving your
playback buffer is something better done with SAVE, which will
restore your playback buffer, while
preparing files of useful macros is a use for MACRO READ.
Once the idea of macros gets into your blood, you can of course use
an editor to create your own files of macros, to be read with
MACRO READ.

Facilities within the Command Interpreter

This is a guide to the use of SM variables, the macro processor,
the help command, and the history facilities.
The vector arithmetic and plotting facilities are described below. Various
examples are scattered throughout the text, to give some guidance on the
use of SM's capabilities.

Perhaps the most important thing to know is how to escape from
SM. If you have a prompt, simply type QUIT(3).
If you are running some command, try control-C to get a prompt.
Most commands will eventually return control to the keyboard following a
control-C. In addition, the parser is reset, and the input buffer cleared.
Sometimes control-C leaves a } on the buffer if it thinks that it'll
help get back to the prompt, which can generate an irrelevant syntax error.
Occasionally it can still be confused -- try typing a few characters
and maybe a }.

When you have interrupted SM with a control-C, a
macro called error_handler is executed, if it is defined. The one
that we provide does things like setting the expansion back to 1, and
resetting any window commands that you might have issued, and then
prints a message handler... to tell you that it's done its work.
If you don't like this,
see `private initialisation' in the index for how to get your own
handler loaded automatically.

If you make a mistake, and SM notices a syntax error, it'll
print a message indicating where you were and which macro you were
running. It is possible for the wrong macro to be reported (if
SM has finished reading the macro before detecting the error),
in which case you'll be told that the error occurred in a macro that
called the offender. Setting VERBOSE (see section Verbose)
to 3 or 4 provides a
more direct way of finding the true location of the error.

If you define the variable traceback to be 1 (maybe with the line
traceback 1 in your `.sm' file)

you'll get a traceback of what macros were active when the error occurred;
the same caveats about the wrong macro being reported apply.
In addition, the usual interrupt capabilities of your operating system will
work under SM, with a couple of quirks.

Under Unix, in case of emergency, type control-\, and SM
will ask you if you want to return to the prompt, and if you
don't it'll offer a core dump, and then exit. As
usual, typing control-Z (from the C-shell) will interrupt the process, which may
be restarted later.
Under VMS, control-Z will interrupt SM, and return you to the command
interpreter (DCL). Typing CONTINUE will then allow you to restart
SM(4).

If SM is running in a SPAWNed sub-process, then control-Z will
reATTACH you to its parent. To continue SM, use the DCL ATTACH
command.
We strongly suggest that you learn how to do this, it makes life much
easier -- all you have to do is SPAWN a process from DCL and start SM
from there. Do check with your VMS system manager to ensure that you have the
right quotas for SPAWNing (Process limit must be at least 3, because SM
will use one for itself and one for hardcopies). An especially simple
way to do all this is is to use the command file `kept_SM.com' in the
main SM directory. It'll handle the spawning and attaching for you.

Another fact to bear in mind is that the characters ^, $, and

# are special, as ^ is used by the history system,






$ introduces a
variable, and # starts a comment. The special meanings of all of
these characters
except ^ can be turned off by preceding them with a \. To type a ^,
use the quote_next character
(initially control-Q or ESC-q) to quote the ^; i.e. type

ESC-q.(5)
A \n is interpreted as a carriage return, and a \ as the
last character on a line escapes the newline, so that the line and the one
following it are treated as one long line.
A \ preceding any other character
(except a "; see next paragraph) is simply a \. This character
is used to set font types in the LABEL commands, so it has no
special meaning to the command interpreter, which simplifies the entering of
strings for LABEL commands.

A further problem is that symbols such as +, -, *,
and / are used
to separate words, which is what you want for mathematics, but maybe not what
you had in mind for filenames.

Enclosing a word
in double quotes turns off all special meanings except ^; an embedded
" may be escaped with a \.
Single quotes are used quite differently; enclosing a word in 'single quotes'
makes it into a string so '12' is a two-character string and not
an integer at all. There are times when this is important; for example
if(y == 'yes') tests if the vector y is equal to the
string `yes', whereas if('yes' == 'yes') asks whether two
identical strings are equal (they are). When you remember that I can
legally say set yes='no' you'll appreciate the distinction.

The characters {} also perform quoting, turning off the special
meanings of all characters (including single and double quotes, but not
^). The difference between double quotes and braces is that
the latter have grammatical value; they are part of the syntax that
SM understands. In most cases you can use angle brackets instead of
curly ones if the grammar needs the brackets but you don't want to
turn off expansions (see section String Variables).

SM is case-sensitive. It will
accept keywords in either upper or lower case, but this is a special
dispensation on its part. If you insist on typing in uppercase say
load uppercase when you first start SM, or put the line
uppercase 1 in your `.sm' file.

Furthermore keywords may not be abbreviated.
This is not a great hardship as it is easy to define macros which
make the minimum abbreviation a synonym for the full command. Many such
macros are predefined for you when you first use SM; see section The System Macro Libraries
for details. In particular, certain common
abbreviations of commands have been predefined by the
SM startup file.

Every time that SM is started, it looks for an environment file
called `.sm' which consists of names of variables and their
values. From # to the end of a line is taken to be a comment. A list
of directories to be searched in order for `.sm' files
is compiled into SM, it usually
consists of the current directory, then your home directory, and then
some system directory. The system default can be over-ridden by
defining the environment variable SMPATH which is
a list of directories separated by single spaces. Each directory on the
search path is tried in turn until a file is found containing the desired
variable, which allows your choices to take preference over those of the
system administrator. In the list of directories
. is taken to be the current directory, and ~ is
your home directory unless you specified a command line -u name

option, in which case it is taken to be name's home directory instead. This
means that sm -u name will usually run SM as if you were name.
If name is null, then SM won't look for a `.sm' file in
anyones home directory.

The default path is equivalent to an SMPATH of

export SMPATH=". ~ /u/sm/lib/"

(or an equivalent incantation). Note
that the directory /u/sm/lib/ ends in a / so that a filename
can be directly appended (on a VMS system it would probably end in a :

or ]).

An example file would be (the filenames are written in Unix)

# I'm a comment line
fonts       /users/sm/fonts.bin
graphcap    /users/sm/graphcap
help        /users/sm/help/
macro       /users/sm/macros/

name        Robert         # Or alternatively `Dr._Lupton'

The fonts file contains the SM fonts (in a binary form),

the graphcap entry is used to
define the file used to describe graphics terminals (see section The Stdgraph Graphics Kernel),


help is the directory used by the help command,


macro is the default directory where macros reside,

and name is what SM will call you (you can put spaces
into your name by using underscores, e.g. My_Lord will be
referred to as My Lord).
You can access
entries in the environment file yourself, as described
in the section on variables. See the section section The System Macro Libraries
to see how entries in the `.sm' file are used to influence the
behaviour of SM, or consult your local expert. You might want
to borrow someones `.sm' file when you first use
SM, although you should do fine without one. For more detail, and
further special entries, see section Environment Variables.

The name of the `.sm' file can be specified on the command line as
"-f name" or you can ask to use name's .sm file with
-u name.
VMS users should ensure that SM has been installed
as a foreign command to take advantage of these capabilities.

SM then tries to read in any macros
in the file `default' in the directory `macro'
and attempts to execute the macro startup if it exists.


If -m filename appears on the command line, this is taken to be the
name of another file of macros and these are read, and the eponymous macro
is executed (after any pre- or suf- fix has been removed. For instance if
you start
SM with the command sm -m /home/tst.m, it will first read
the file /home/tst.m, and then attempt to execute the
macro tst).(6)

Anything left on the command line is treated as if it had been typed
at the prompt, for example sm restore vital.save will start
by RESTORing from the file vital.save (see RESTORE
if you want to know what this means). The -m option is not
really a good way to personalise SM. The startup macro
discussed under `useful macros', which is run every time that you start
SM, looks for a directory macro2 in your `.sm'

file, and if it is there reads a file `default' from it, and
executes the macro startup2 which it expects to find there.
On case-insensitive operating systems, such as VMS, you may need to
quote the command line to prevent it being translated to upper case.
SM then

attempts to read a set of history commands from a file in
the current working directory, passes control to the input routine
and issues a prompt.
The file is given by the entry hist_file in your `.sm'
file, and if it isn't present then no history will be remembered.

You are then able to type commands, as many as
will fit on one line(7),
and use the features described below.

You can use a combination of these features to run SM in `batch' mode.
If you had a history file that you just wanted to run, then you could
start SM, say playback, and quit. You could have a macro
called batch in batch.m that did just that, and say
sm -m batch.m to execute it. In fact, you don't even need your own
macro as one is pre-defined for you so sm batch is sufficient.
You could write your own macros along this lines to do more complex tasks.

A more convenient alternative (under unix) would be sm -S < history_file
where the -S is explained in the next paragraph.

For completeness, we should mention the other command line flags,
-h, -l logfile, -n, -q,

-s, -S, -v#, and -V.






The -h prints a summary of command line options,
if you specify a logfile with -l everything that you type at the
keyboard is copied into the logfile (except editing commands). When you
start SM it usually runs a macro startup; -n prevents this.
The -s (for `stupid', or `silent' or `suppress') flag disables the
command line editor (although the history list is still saved, so commands
like playback will work),

-q suppresses the initial `Hello' message,
and -S is like -s but it also suppresses the prompt
and stops SM from intercepting control-c. You can get the same effect
as -s from inside SM with the command TERMTYPE none.
If you are reading from a file or pipe SM behaves as if you had
invoked it with the -S flag.

This is useful if SM is
being run from inside another programme, via a pipe (VMS: mailbox), or
on a very stupid terminal.

If you want to set a particular value of verbose, use -v for example
-v-3 is equivalent to the VERBOSE -3 command given interactively.
If you want to know SM's version string without starting SM, you can use
the -V flag.

String Variables

Some SM users seem to be confused by variables and vectors; if you are one
of these, the section on quoting (see section What Quotes What When) might help.

SM maintains a set of variables which are defined with one of the statements

DEFINE name value

or

DEFINE name { value_list }

or

DEFINE name ( expression )

where name must consist of digits, letters and `_' (but must not start
with a digit), and may be a keyword.

Value may be a word or a number. Value_list has no such
restrictions
and may contain many words. Note that due to the presence of the {},
variables are not expanded (i.e. replaced by their value) in value_list,
whereas they are in value. In fact, the list can be delimited by

<> rather than {}; see DEFINE for details.

The expression in DEFINE variable ( expr ) should be
a scalar; if it is not, the first element of the vector will be used and
you will be warned, if VERBOSE
(see section Verbose) is one or greater.

Sometimes you just want to evaluate an expression and treat the answer
as a string; in this case use the special vector form $(expr)
which is replaced by the value of the expression -- for example
echo e is $(exp(1)).
Expressions are further discussed under `Vectors and Arithmetic'.

There are a number of special variables whose value is always the current
value of some internal SM variable such as the current position or the
point type. The variable "date" is also special and expands to give
the current time and date, -- try typing echo $date. You can freeze
these variables at their current value by saying define name |
(see below).

Each time SM reads $name it replaces it by its
value, considered as a character string. For example,

DEFINE hi hello
WRITE STANDARD $hi

will print hello. This expansion is done before even the lowest level
of lex analysis, so if a command is attempting to read a value
it is possible to give it the name of a SM variable. An example
would be the XLABEL command, which writes a string as the x-axis label
of a graph,

DEFINE name Aelfred

XLABEL My name is $name

will invoke the XLABEL command, and write My name is Aelfred below
the x-axis. (Incidentally, DEFINE Aelfred Aethelstan YLABEL $$name

will write Aethelstan as the y-axis label, which can be handy in macros.
The use of the double $$ indicates to SM to do a double
translation, as it first expands to $Aelfred which then expands to
Aethelstan).

A variable can be deleted by DEFINE name DELETE so for example the macro

MACRO undef 1 { DEFINE $1 DELETE }

invoked as

undef name

will undefine the variable name (see the section on macros if you are
confused).

There are also three special values, :, |, and
?. The command define name : means `get the
value of name from the environment file'. If this fails, and if the
variable is all uppercase, SM will then try to use the value of an
environment (VMS: logical) variable of the same name.
Using define name ? means
`read the value of name from the keyboard'. You can specify a prompt to be
used, see DEFINE for details.
The form with | has changed a little with version 2.1.1. The variables
that you can use with | have not changed, but their usage has
slightly. They are all defined for you when SM starts and each is always
correct, tracking the current value of the corresponding internal variable.
For example, try echo $angle angle 45 echo $angle. If you now
say define angle |, $angle will cease to track the internal
value and will remain fixed (the same effect can be achieved with

define angle 45). When you say define angle delete it will
once more track the internal value. Your old code will continue to work,
but in many cases it is possible to remove the explicit definition
with |. This special sort of variable will not be SAVEd,
and will not show up if you list the currently defined variables.
A list of the | variables is given in the section on DEFINE.

So using the example `.sm' environment file listed in the previous
section of the manual, DEFINE name : will define

name to be Robert, DEFINE angle | will give the last
value set by the ANGLE command, and DEFINE datafile ? will ask you
for the value of `datafile', which can be useful in macros. For example,

DEFINE noise ? { Ring bell? } IF('$noise' != 'n') { bell }

will execute the macro bell if you type anything but n in reply
to the question `Ring bell?'.

When writing macros, it is also sometimes useful to know if a variable
has been defined. The variable $?name has the value 1 if name
is defined, otherwise it is 0. For instance, there is a line

define term : if($?term) { termtype $term } 

in the startup file, to set a termtype if present in the environment
file.

There are also commands to read the values of variables from data
files defined with the DATA command.

LIST DEFINE [ begin end ]

FOREACH x ( U B V R I J K ) { SET $x_red = $x IF(B-V >1)}

DEFINE a 12

SET x=10

SET y=$a + x*12

DEFINE y $a+x*12

DEFINE y <$a+x*12>

DEFINE y ( $a+x*12 )

readem          # read multiple lines columns with names in row 1
                READ ROW names 1.s
                DEFINE rc <$(names[(0)]) 1>

                DO i=2,DIMEN(names) {
                        DEFINE rc <$rc $(names[($i - 1)]) $i>
                }
                LINES 2 0
                READ < $rc >

Command History

It is often very useful to be able to repeat a command, or perhaps correct
a mistake in what you have just typed. Ways of doing this are usually
referred to as `history', and SM has two distinct mechanisms.
One is very similar to that of the Unix C-Shell,
and the other allows you to edit commands using a syntax similar to the popular
editor `emacs', or a generalisation of the DCL history under VMS.
If you are not familiar with Unix, emacs, or VMS don't despair; a
description of the commands and how to invoke them follows in this
document.
Both of these mechanisms are implemented by the routine which reads input
lines. As each line is sent to the parser, it is copied onto a
history list. This list may be printed with HISTORY, and
the commands may be


re-used by referring to them by number, as ^nn, or by a unique
abbreviation, as ^abbrev. In addition, the last command may be
repeated by using ^^ and the last word of the last command by

^$.(8)
These symbols are expanded as soon as they are recognised (see examples,
or experiment), and are then available for modification by the editor.
Sometimes a ^string will retrieve a command beginning
string, but not the one that you want. Version 2.1.1 no longer
supports the use of ^TAB
to search for the next-most-recent command beginning string,
but you can use the search commands (control-R and control-S) instead.
Some people really don't want ^ to be their
history character, either because they're used to something else (such
as !), or because they want to type lots of real ^s (e.g. you are using
TeX-style strings); if this describes you, rebind them -- see the next
section.
If you are considering the history list as a sort of programme to be
repeated you may think that HISTORY lists the commands in the
wrong order; if so use HISTORY -.

For example, if I type:

PROMPT @
echo I like SM
HISTORY

SM will set the prompt to be @, replace the macro echo by
its value WRITE STANDARD and print

I like SM

and then

3   HISTORY
2   echo I like SM
1   PROMPT @

(The actual numbers will be different, depending on what other commands
you have executed, and also because SM may have read a history
file. In that case
there'll be many more commands on the list, but no matter.) If I then type

^2 <CR>

(that is ^2 not control-2)
the screen will look like

@ echo I like SM
I like SM

as if I had just typed it in (@ is the prompt) . Typing

^^ (Yes, ^$ ) <CR>

will now result in SM printing (truthfully)

I like SM (Yes, SM )

It is possible to delete commands from the history buffer with the
DELETE command. If the command is given with zero, one, or two
arguments, then
the specified range is deleted (but their numbers are not re-used). If
no arguments are given, the last command on the buffer is deleted, and
its number is released to be re-used. In other words, the command
DELETE will delete first itself, and then the
previous command from the history list. The command DELETE HISTORY

only removes itself from the history list, and
several of the common commands are defined as macros which use it,
for instance dev is defined as
DELETE HISTORY DEVICE. This means that the command will not
appear on the history list, to confuse you when you do a playback. But
if you now innocently use dev in a macro, that macro won't appear
on the list either. Still worse, if you use dev twice in one
macro, the previous command will be deleted as well which could be quite
confusing.


You can also delete lines of history using ESC-control-D as
described shortly.

The numbering is consecutive, starting at zero. Each command retains its
number until you use a HISTORY command to list the remembered
commands, in which case they are all renumbered, and it is these new numbers
that are listed.

By default only 80 lines are remembered,
and as you continue typing earlier
ones fall off the list.

Because the history buffer is also used to compose complex commands, this
limit can be aggravating. You may be able to defeat this by
putting many commands on
each line (you may have to use \n to terminate label
commands explicitly)
or by writing macros. Alternatively you can define a longer history buffer
when you start SM by including an entry history in your
environment file

which gives the number of commands to be remembered. If you set
history to be 0 the history list is made infinitely long.
Incidently, it is
the total
number of commands that matters, not the range of history
numbers present.

This limit on the number of history lines isn't enforced while writing a
macro onto the history list (using WRITE HISTORY). You can
use this fact to write a sneaky macro that extends your history; type
HELP extend_history if you are interested.

Some people seem to like their history editors to remember where they were,
so that after they retrieve and execute a command the next control-P
or
will retrieve the command one further back on the
history list (that is, if you have just retrieved command number 123
and executed it as command number 234, then control-P will get you
command number 124; you can execute it as command number 235). If
this describes you, define the variable remember_history_line,
which you can either do directly, or by putting a line
remember_history_line 1 in your `.sm' file.

The editor allows you to modify commands, either as you type them or
as you retrieve them from the history list. The various editing
commands may be bound to keys of your choosing, but the default
bindings are given in this list of possible commands:

Go forward one character. (Equivalent to
).

control-S. The `string' can actually be any regular expression (see the
manual entry for APROPOS). If you specify a zero-length string
(i.e. simply hit carriage return) the previous search string will be reused.

Go forward 5 lines.

Equivalent to control-H.

Some ESC-letter combinations are available which operate
upon complete words. A word is defined as a whitespace delimited
string, so 2.998e8 is a perfectly good word. In addition, it is possible
to undelete words that have been deleted with an ESC-d or ESC-h.

Any printing character is inserted before the cursor (unless overwrite
has been set with control-T ). Illegal characters ring the terminal bell.
If you insert a non-printing character on a line, the cursor may get confused.

If ever you are stuck at the command interpreter, and you want to send
a signal to the operating system (e.g. a control-Y to DCL), but
SM is catching the key and using it for its own purposes, the
easiest thing to do is to define a macro such as
MACRO aa {aa} , and then run it. While it is running (i.e.
until you type control-C) keys should have their usual functions.

Changing Key-Bindings

As mentioned above, it is possible to redefine the meanings of keys to
the history (and macro) editor.
The command EDIT keyword key-sequence will make typing that
sequence of keys correspond to the command keyword. For example,
to make control-R redraw the current line, you could say EDIT
refresh control-R.

The keyword can be any in
the list below, or any single character. Each character in the
key-sequence can be a single character, control-c, or \nnn where
nnn is an octal number.
Alternatively, READ EDIT filename will
read a file specifying the new bindings which has two lines of header,
followed by pairs of keyword key-sequence. Lines starting with a
# are comments. An example is the
file for VMS users given below.

A problem can come up with multiple-key sequences. Imagine that you have
bound some function to control-Xcontrol-A, for example

        EDIT end_of_line ^X^A

then what happens when you try it? SM sees the control-X and uses its
default binding, exit_editor, and then sees a control-A and
goes to the start of the line, which wasn't the desired effect. The solution
is to tell SM that control-X is not a legal key, in which case it will
either ring the terminal bell (if there are no key-sequences starting with
an control-X), or wait for the next key. In short,

        EDIT illegal ^X
        EDIT end_of_line ^X^A

should work.

On a somewhat similar topic, the KEY (see section Key) command may be
used to define a key to generate a string. See the end of the section on
macros for how this works.

All the current key definitions may be listed using LIST EDIT,
including the KEY definitions.

The names of operators, and their
default bindings, are given in the following table:

start_of_line

scroll_forward

attach_to_shell

A simple example of a bindings file for a hardened VMS user might be

# This is a set of DCL-ish key maps for SM
# name   key
toggle_overwrite        ^A
start_of_line           ^H
delete_previous_word    ^J
yank_buffer             ^R
search_reverse          ^[r
attach_to_shell         ^Y

Note that that's the two characters
^ and A not control-A. It could just as well have been
written \001.
We need a new character for yank_buffer now that control-Y is
otherwise engaged, and I have chosen control-R (which means that I
can't use control-R to search backwards, so I chose ESC-r for

that).
You should be warned that some
terminal protocols map control-M to control-J, so this use of control-J could
render you unable to issue commands. As mentioned above, in an emergency
control-@ can be used instead of control-M.

When SM is started, or whenever the TERMTYPE command is
used to change terminals, the arrow keys are bound to the commands
previous_line, ext_line, previous_char, and
ext_char. For terminals such as a Televideo-912, which uses
characters such as control-K for arrow motion, these can supersede the
previous meanings (in this case kill_to_end);
The only fix is to use the EDIT or

READ EDIT command to get what you want, probably within a macro.

If you want to use ' as your history character instead of ^
you need to say edit history_char ` edit ^ ^. If you try
to use a character special to SM such as ! this won't work
(you'll get a syntax error) and you'll have to use the next alternative,
namely put the commands into a file and say read edit filename,
for example:

# Change the history character
# name   key
history_char   !
^              ^

Because this particular change is so common, it's possible to specify
that ` be your history character simply by including a line
history_char ` in your `.sm' file (or you can choose your
own character. Choosing 0 has the effect of using the default, ^).

SM needs to know something about the terminal that you are
using, so as to run the history/macro editor. This is entirely
separate from the problem of describing the terminal's graphics. It
will try to discover what sort of terminal you're on by using the value
of term from your `.sm' file,

or failing that the value
of the environment variable TERM (Unix) or the logical variable
TERM (VMS). A term entry of selanar -21 is
equivalent to a TERMTYPE selanar -21 command.
You can also use the TERMTYPE command directly.
SM then uses the terminal
type specified to look up its properties in the termcap database
(see section Termcap -- A Terminal Database). You can also use

TERMTYPE to specify the size of the screen, or to turn off
SM's idea of where the cursor is. On some terminals, you can
only send a cursor to an absolute position and this is chosen to be
the bottom of the screen. This is not what you want for, e.g., a VT240
as it will lead to your graph scrolling off the screen. The use of a
negative screen size to TERMTYPE will disable this cursor
motion, but will also make editing lines slower. If a line of your
graph is being deleted when the SM prompt appears, you may
need to use TERMTYPE dumb or TERMTYPE none.

Talking to the Operating System

Any line from ! to the newline is passed to your shell (DCL under VMS,
the Bourne shell under unix. If you set the variable SHELL in
either your `.sm' file or the environment it will be used instead;
the former takes priority).(9)

For example, !ls or !directory will list the current directory.
The return code from the command is available in the variable

$exit_status, on unix systems it will be 0 for success, for weirder
systems you should look in the system manual for the return value of the
C function system. $exit_status is one of the variables
that can be set with DEFINE exit_status |.

It is also possible to change the directory that SM uses to look
for data or macro files with the CHDIR command - for instance

CHDIR "../more_data"(10).
If a directory name starts with `~', CHDIR replaces the `~'
with your home directory. This is the only place that `~' is treated
specially, for instance it is not interpreted by the DATA command.
Because directory names often contain mathematical
characters such as [ or /, it is wise to quote the directory, or
use the macro cd which quotes it for you.

Macros

In SM, it is possible to define sets of plot commands as
"subprogrammes", which can be used just like a plot command, to generate
a standard plot. These plot macros allow variables (e.g.
name of the data file, plot label or limits, etc) to be supplied at
execution time.

You can also bind commands to keys to save typing; for example I
usually bind `cursor' to the PF1 key of my terminal. Such keyboard
macros are discussed under KEY and at the bottom of this section.

The macro facility consists of commands to define macros,
delete them, write them to disk files, read them from disk files,
delete all those macros defined in a specified disk file and




list all currently defined macros. In addition, the help command
applied to a macro prints out its definition.

It is possible to pass up
to 9 arguments to a macro, referred to as $1, ... , $9,
and in addition $0 gives the name of the macro.
While macro arguments are
being read they are treated as if they are in sets of {}, except
that variables are expanded. If you want to include a space in
an argument, enclose it in quotes. If the number of declared arguments is
10 or more, the macro is treated as having a variable number of arguments.
If it is 100 or more the last argument extends to the end of the line.
For further discussion see the discussion of how macros are used.

A macro is defined by the statement

MACRO name nargs { body-of-macro }

or

MACRO name nargs < body-of-macro >

where name may be up to 80 characters, and must not be a
keyword(11),
and body-of-macro is the statements within the macro, and may
be up to 2000 characters long. Macros defined using an editor on a file
may be up to 10000 characters. If nargs, the number of
arguments, is 0 it may
be omitted. Macros may also be created using the MACRO EDIT command,
which is discussed below, and which is probably easier. To define the macro
in a disk file, the file format must be: the name of the macro starts in the
first column, followed by a tab or spaces, followed by the number of
arguments, if greater than 0, followed by commands, followed by
comments if any. The next line and
any necessary subsequent lines
contain the macro definition (starting in a column other than the first
one). Any number of macros may appear in the same file, as long as the macro
name is given in the first column and the definition starts in some other
column. The first two blanks or tabs are deleted in continuation
lines, but any further indentation will survive into the macro definition.
Tabs will be replaced by spaces as the macro is read. By default a tab
is taken to be 8 characters wide, but this may be changed by specifying

tabsize in your `.sm' file.

When a macro is invoked, by typing its name wherever a command is
valid, for example at a prompt, it first reads its arguments from the
terminal (if they are not in the lookahead buffer, it will prompt you
for them), and defines them as the variables $1, ..., $9,
before executing the commands contained within the macro. The
number of arguments must be declared correctly.

As an alternative it is possible to declare that a macro has a
variable number of arguments by declaring 10 or more(12).
The macro will
then expect between 0 and the number declared modulo 10 arguments, all
on the same line as the macro itself. (i.e. the argument list is
terminated by a newline, which may either be a `real' one, or an \n).
If the number of arguments is 100 or more it is still reduced modulo 10,
but the last argument is taken to be the rest of the line (which may
consist of many words).

The macro may find out if a particular argument is provided by using
$? to see if the variable is defined. For example the macro check,
in the format in which it would appear in a file,

check  11   if($?1 == 1) { echo Arg 1 is $1 }\n

will echo its argument, if it has one, and

split  102  if($?2 == 0) { DEFINE 2 "(none)" }

echo $1:$2:

if invoked as split word many arguments will print word:many arguments:.
If you add an explicit newline, split word many\n arguments,
you'll get word:many: and then a complaint that arguments

is not a macro.

If you try to execute a non-existent macro, if it is defined SM will
call a special macro called macro_error_handler.
It has two arguments; the first is the string
NOT_FOUND, and the second is the name of your non-existent macro.


When you start SM, the error handler is:

macro_error_handler 2 ## handle errors associated with macros
		if($?missing_macro_continue) {
		   echo $2 is not a macro
		   RETURN
		}
		if('$1' == 'NOT_FOUND') {
		   del1
		   define 3 "$2 is not a macro; aborting"
		} else {
		   define 3 "Unknown macro error for $2: $1"
		}
		USER ABORT $3

which causes an immediate syntax error (the USER ABORT),
and remove the errant command from the history list (the del1). You
can turn this off by defining the variable $missing_macro_continue,
which you can do in your `.sm' file; this was the default in SM versions
2.1.0 and earlier, and is what you get if the macro

macro_error_handler isn't defined.

Unfortunately we can get into
trouble with IF's at the end of macros, for much the same reason
that RETURN can get into trouble (see section The Command Interpreter).
The symptoms are that a macro either gets the arguments that were passed to the
macro that called it, or complains that it can't handle numbered
variables at all because it isn't in a macro at all.
To avoid this, there is an explicit \n at the end of the macro check.

It is possible to redefine the values of arguments (it won't affect
the values you originally specified, arguments are passed by value),
or to DEFINE values for arguments that you didn't declare. The
latter case allows you to have temporary variables, local in scope to
the macro.

An example is the rel macro, which is defined as

rel  2  DEFINE 1 ($1) DEFINE 2 ($2) RELOCATE $1 $2

which allows you to specify expressions to the relocate command.
For more examples see the `useful macros' section.

Newlines are allowed within macros, and as usual
any text from a # to the
next newline is taken to be a comment. If a # is needed within a
macro, escape the # with a \ or enclose it in double quotes.
If a macro starts with a comment the comment will not affect the
macro's speed of execution. Macros starting with ## are
treated specially by SAVE (they are not saved) and MACRO LIST

(they are not listed if VERBOSE is 0).

If the macro command is given as

MACRO name { DELETE }

or

MACRO name DELETE

the macro will be deleted (you can also delete a macro from the macro
editor by specifying a negative number of arguments).
If the name is already
defined, it will be silently redefined. Macros may be nested freely, and even
called recursively.
For example, the definition

MACRO aa {aa}

is perfectly legal, but SM will go away and think about it
for ever if you ever type aa (or at least until you type control-C.)
The definition

MACRO zz { zz zz    # comment: not recommended }

is also legal, but in this case if you execute it SM
will fill its call and macro stacks
and complain when it grabs more space. As
before, it will think about it forever. More useful examples of
recursive macros are compatible (see section Tips for Mongo Users), which starts

IF($?1 == 0) { compatible 1 RETURN } ...

providing a default value for its argument, and repeat which is
discussed under DO.

To find how a particular macro is defined, type HELP macroname.



For
a listing of the first line of all currently defined macros, type

LIST MACRO

or

LIST MACRO x y

The optional x and y are the alphabetical (actually asciial ) range of
macro names to list. As mentioned above, if VERBOSE is 0, macros
starting with ## are not listed by this command. There is a
macro ls defined as DELETE HISTORY LIST MACRO which will
list macros without appearing on the history list. (Or you could
overload list; see under overload in the index).

A related command is APROPOS pattern which lists all macros and
help files(13)
whose names or initial comments contain the pattern, for example

APROPOS histogram

would list bar_hist and get_hist as well as the
abbreviations hi and hist. If you wanted to find all
macros starting with a single comment character which mentioned

histogram you could say

APROPOS "^#[^#] .*histogram"

where the double quotes prevent the #'s being interpreted as
comment characters.

APROPOS ^[a-z]

will list all macros beginning with lowercase letters -- this is
similar to MACRO LIST a z, but pays no attention to the value of

VERBOSE.

It is also
possible to read macros in from disk, and in fact when SM is started,
it tries to read the file `default' in the directory specified by
macro in the environment file `.sm'. The command to read a
file of macros is

MACRO READ filename

Any line with a # in the first column is treated as a comment, and is
echoed to the terminal if VERBOSE is greater than zero.



All the currently defined macros may be written to a file with
the command

MACRO WRITE filename

If the file exists, it will be overwritten (under VMS, a new version of
the file will be written).
Macros are written out
in alphabetical order.

The command

MACRO WRITE macroname filename

writes the macro macroname to the file filename.
This command remembers which file it last wrote a macro
to, and if the current filename is the same then it appends the macro
to the end of the file, otherwise it overwrites it (or creates a new
version under VMS)
unless the filename is preceded by a +,
in which case the macros will always be appended.
This allows a set
of related macros to be written to a file.

MACRO DELETE filename

undefined all macros which are defined in filename.
This allows a file of macros to be read in, used and forgotten again.
The difference between this command and MACRO macroname DELETE
should be noted.
The SAVE command is probably a better way of saving all current macros.
The format of macros on disk is name nargs text, where

nargs may be omitted if it is 0. Continuation lines start with a
space or tab. See the files in the directory specified by macro in your `.sm' file for examples.

It is possible to define macros from the history list. The command

MACRO name i j

defines a macro name to be lines i to j inclusive of the history list,
as seen using HISTORY.


The opposite of this command, which places a macro upon the
history list, is WRITE HISTORY name. Examples of these commands are the
macros playback and edit_hist given in the section `A
Simple Plot'. This way of defining macros can
be convenient if you have created a useful set of commands on the
history buffer, and now want to save it in a macro and go on to other things.
Editing the playback buffer, and then changing its name to something
else (see next paragraph) is a convenient way of saving it that
implicitly uses this command.

Macros may be edited, using essentially the same keys as described
above for the history editor.
The command MACRO EDIT name starts up the
editor, which works on one line at a time.(14)
The zeroth line has the format

0> Macro name : Number of arguments: n

where name is the name of the macro, and n is the number of arguments to the
macro. If this line is
changed, except to change name or n, any changes made to the
macro will be ignored (note that the space after name is
required). This can be useful if you decide that you
didn't want to make those changes after all. Changing name or

n has the obvious effect, except that if n is negative the
macro is deleted when you exit the editor. An empty macro is also deleted
when you leave the editor (i.e. one with no characters in it, not even
a space).
The first line that you are presented with is the first line in the macro
rather than this special one.
Use control-N (or
) to get the next line,
control-P (or
) to get the previous line. Carriage return
(control-M) inserts a new line before the cursor, breaking the
line in the process, while control-O inserts a new line before
the current line.
To save the
changes and return to the command interpreter use control-X.
All other
keys have the same meaning as for the history editor (e.g. control-A to
go to the beginning of a line).
Note that control-K and control-Y can be used to copy lines, and
that the bindings can be changed with EDIT or READ EDIT.

It wouldn't be hard to write a macro that wrote out a macro to a file,
invoked your favourite text editor, then read the new definition back
in; see the macro emacs_all for ideas.

It is sometimes convenient to define a key to be equivalent to typing
some string, such as playback or cursor. This can be done
with the KEY command, whose syntax is KEY key string.
If you just type KEY <CR> you'll be prompted for the key and
string. In this case you are not using the history editor to read the key,
and you can simply hit the desired key followed by a space and the
desired string, terminated by a carriage return. If you put KEY,

key and string on one line you'll probably have to quote
the key with control-Q or ESC-q, or write the escape sequences
out in the way used by EDIT. If this sounds confusing, here is
an example. Type KEY<CR>, then hit the PF1 key on your terminal,
type a space, and type "echo Hello World\N". Now just hit the
PF1 key and see what happens. (The closing \N meant `and put a newline
at the end'). These keyboard macros are not generally terminal
independent, but they can be convenient. Definitions for the `PF' keys
on your keyboard can be made in a terminal-independent way by
specifying the key as pfn or PFn where n is 1, 2, 3,
or 4.
If you always use the same
terminal you might want to put some KEY definitions in your private
startup file (see the discussion of startup2 in the section on
useful macros). The current KEY definitions are listed with the

LIST EDIT command, along with the other key bindings.

DO and FOREACH loops, WHILE loops, and IF statements

Related to the macro facility are the DO, FOREACH,
and WHILE commands.

IF is included here as a flow-of-control keyword.

The syntax for a DO loop is

DO variable = expr1 , expr2 [ , expr3 ] { command_list }

where the third expression is optional, defaulting to 1. The value of variable
($variable) is in turn set to expr1, expr1+exp3, ...,

expr2, and the
commands in command_list executed. Changing the value of $variable
within the command list
has no effect upon the loop. Do loops may be nested, but the name of
the variable in each such loop must be distinct. A trivial example
would be

DO val = 123, 123+10, 2 { WRITE STANDARD $val }

while a more interesting example would be
the macro square discussed in the section on examples.

For loops within macros, it's often a good idea to make the loop variable
local: DEFINE val LOCAL DO val ... (see section Define).

Because the body of the loop must be scanned (and parsed) repeatedly, loops
with many circuits are rather slow. If at all possible you should try
to use vector operations rather than DO loops.

For example the loop

DO i=0,DIMEN(x)-1 {
     IF(x[$i] >= 0) {
        SET x[$i]=SQRT(x[$i])
     } ELSE {
        SET x[$i]=0
     }
}

is better written as

SET x=(x >= 0) ? SQRT(x) : 0

where the ternary operator ?: is discussed in the section on vectors
(see section Vectors and Arithmetic). If you only wanted the elements with x >= 0,
you'd have said

     SET x=SQRT(x) if(x >= 0)
}

As an alternative to DO loops, SM also has a general looping command, a
while loop, for example

set i=0
while {i < 10} {
        commands
        set i=i+1
}

is equivalent to a DO loop. In addition to being more flexible,


WHILE loops may also be interrupted with the BREAK command, so the
previous example could have been written (using variables instead of
vectors)

define i 0
while{1} {
        echo Hi $i
        define i ($i+1)
        if($i == 10) { break }
}

Foreach loops are similar to do loops, with syntax

FOREACH variable ( list ) { command_list }

,

FOREACH variable { list } { command_list }

, or

FOREACH variable vector { command_list }

where the list may consist of a number of words or numbers.
a vector.
Each element in the list (or of the vector) is in turn defined to be the
value of
$variable, and then the commands in command_list are executed,
so that for example the commands:

FOREACH i ( one 2 three ) { WRITE STANDARD $i }
SET str = {one 2 three}
FOREACH i str { WRITE STANDARD $i }

will print out:

one
2
three

twice.
Foreach loops may be nested, but again the variables must be distinct.
You can delimit the list with {} so that it can include
keywords (and other things that you want treated as strings such as 0.1

or $date), but even then you can't have the word delete in the
list of a foreach. Sorry.

It's often helpful to make the foreach variable LOCAL (see section Set)
inside macros, e.g.

DEFINE var LOCAL  FOREACH var ...

If statements look similar, with syntax

IF ( expr ) { list } ELSE { list2 }

where the ELSE clause is optional, but if it is omitted the closing
} must be followed by a newline (or explicit \n)
(see section The Command Interpreter).

If the (scalar) expression is true (i.e. non-zero), then the commands

list are executed, otherwise list2 is, if present. It is also
possible to use IF statements directly in plotting commands, for
example POINTS x y IF(z > 1/x).

You can use logical operators within the expr (see section If).
Note that && and || do not`short-circuit'; that is,
in the expression expr1 && expr2 both expr1 and expr2

are evaluated. In a scalar context (e.g. in an IF statement), the operators
AND and OR are available instead, and they do only evaluate
the right hand side if it's value is required.

It is possible to write general loops in SM by using of tail-recursive macros.
(15)
The simplest example would be

macro aa {echo hello, world\n aa}

which prints hello, world and then calls itself, so it prints
hello, world and then calls itself, and so on until you hit control-C.
The absence of
a space before the closing brace is very important, as it allows SM to
discard the macro before calling it again, which means that it won't fill
up its call stack and start complaining. A more interesting example is
the macro repeat which repeats a given macro while the given
condition is true. For example, if you say

macro aa { set i=i+1 calc i }
set i=0 repeat aa while i < 10

it will print the integers from 0 to 9. With a few checks, bells, and whistles
the macro looks like:

repeat 103      # Repeat a macro `name' while the condition is true
                # syntax: repeat name while condition
                # Example: set i=0 repeat body while i < 10
                if('$2' != 'while') {
                   echo Syntax: $0 macro while condition
                   return
                }
                if(int((whatis($1)-4*int(whatis($1)/4))/2) == 0) {
                   echo $1 is not a macro
                   return
                }
                macro _$1 {
                   if(($!!3) == 0) { return }
                   $!!1
                   _$!!1}
                _$1
                macro _$1 delete

and is one of SM's default macros (type "help repeat" if you don't
believe me).

The Help Command

There is an online help command. Typing HELP <CR>
or HELP HELP
gives a list of the help menu, or HELP keyword gives help with that keyword.
The help menu consists
of any files in the directory specified by the entry help

in the environment file, so for example HELP data types
the file data in that directory. For all cases except HELP help, the
file is filtered through a version of the Unix utility `more' which pages
the file. When `more' offers you a `...' prompt, type ? to see your
options.

The same filter is used by e.g. LIST MACRO .
If the command is HELP word, after HELP tries to print the file
word, it looks to see if word is a macro, and if so prints
its definition. If word is a variable, its value is then
printed, and if word is also a vector HELP

prints the dimension, followed by the help
string associated with the vector
vector_name (see section on vectors).

The APROPOS command is also useful when you need help.
APROPOS string scans all the help files (if your operating
system allows SM to do such things) and macro headers looking for the
string. The string may actually be a pattern (see the description
of APROPOS for details). If VERBOSE

(see section Verbose) is zero only
the lines from the help files matching the pattern are printed; if
it is larger you are given a couple of lines of context on each side.

It is worth remembering that the index to this manual has an entry
under weird, wherein are listed all sorts of strange happenings,
with explanations and suggestions for workarounds.

Saving and Restoring a Session

If for some reason you want to stop a SM session for later
resumption, and simply suspending the process, `control-Z', is not
sufficient, (for instance the machine is going down), then the SAVE command will write a file containing all your currently defined
macros, variables, and vectors, along with your current history buffer
as the macro all. You will be prompted before each class of
objects is saved, or you can put the answers on the command line.
The file is ascii, and can be edited if you so
desire. The filename defaults to `sm.dmp' if not specified, or to
the value of save_file from your `.sm' file.

If some bug has crawled unbeknownst to us into SM, and results
in some sort of panic (such as a segmentation violation), a save file
called `panic.dmp' is written to your temporary directory, no
questions asked.

To restart, RESTORE filename will read them all back, using the
same default file as for SAVE if no filename is specified, and
replace the current history buffer with the value of all

from the savefile. Of course, you could write a macro to preserve the
current buffer (see the definition of edit_all for hints).
If the file wasn't written by SAVE it is assumed to be a
SM history file, one of those written when you quit SM, and
each line is assumed to be a command and written to the end of the
history buffer. This is generally useful when you started SM
in the wrong directory. It wouldn't be hard to write a macro to use
RESTORE to read a history file into a macro.

One problem with SAVE is that it saves lots of macros,
including some of the system ones. Specifically, all macros are saved
except those beginning with "##".
This can be avoided with
the MACRO DELETE filename command, e.g. MACRO DELETE utils
SAVE 1 1 1 MACRO READ utils.
The macro sav discussed under `useful macros' will do this for
you, and indeed not SAVE any macros that have been read with the

load macro. This is probably the best way to use the SAVE
command. In addition, sav also decides to save variables and
macros, only prompting you about saving vectors. sav is a good
candidate for overloading (as save), and indeed is one of the
macros redefined by the set_overload command.

Vectors and Arithmetic

The basic unit of data in SM is the `vector', a named set of one or
more numbers or strings. There is no limit to the number of vectors
that may be defined. SM allows the user to read vectors from files or
define them from the keyboard, to plot them and to perform arithmetic
operations upon them. SM's string-valued vectors are less generally useful,
but can be used
for such purposes as labelling points on a graph.

To read a vector vec from a column of numbers in a file, where the
filename has been specified
using DATA and, possibly, the range of lines in the file to be used
has been specified using the

LINES command, use READ vec nn where nn is the column number,
or READ { vec1 n1 vec2 n2 ... } to read many vectors.
It is also possible to read a row, using READ ROW vec nn, where nn is
the row number in the file. See READ for how to read a
string-valued vector.

Instead of using simple column-oriented input
it is possible to specify a format like those used by C's scanf
functions (Fortran formats are not supported); if you provide your own
format string you can only read numbers.
For example, if your data file has lines like

	1:12:30  -45:30:11

you could read it with
read '%d:%d:%d %f:%f:%f' { hr min sec deg dmin dsec }.

A vector may also be defined as SET vec = x1,x2,dx to take on
the values x1,x1+dx,...,x2, where dx defaults to 1
if omitted. If a scalar is
encountered where a vector is expected, it is promoted to be a vector
of the appropriate dimension; all other dimension mismatches are
errors. Example:

SET value = 5
SET x = 0, 50, 2
SET y = x
SET y = x*0 + value
SET y[0] = 2*pi
SET y = value
SET x=0,1,.1 SET y=IMAGE(x,1.5)
SET s=str
SET s='str'
SET s[0]=1.23
SET x=1.23
SET s=x
SET s=STRING(x)

will define a scalar, value, with a value of 5, then define a vector,
x, with 26 elements, valued 0, 2, 4, 6,..., 50, then define another
vector, y with size 26 and the same values as x,
set all 26 elements of y to have the value 5,
set the first element of y to be 2 pi,
set y

to be a vector with one element with value 5, and finally
set y to be a vector with the values taken from a horizontal
cross-section from 0 to 1 through the current image. Unless a vector
str is defined SET s=str is an error; to make s a
string-valued vector use SET s='str'.

SET s[0]=1.23 makes s[0] have the value "1.23" (a string),
as s is now a pre-existing string vector.
An arithmetic vector x is then
defined, and s is redefined as an arithmetic vector too -- you must
be careful when dealing with string vectors! Finally, we explicitly
convert an arithmetic vector to a string-valued one with the STRING

operator.
This is a somewhat
contrived example, designed mainly to illustrate the convenience of the
SET command. The ability to set particular elements is mostly
used in macros such as smirnov2 which calculates the
Kolmogorov-Smirnov statistic from a pair of vectors.

If you don't have many data points, rather than type them into a file, and use
READ vec nn to define a vector, you can use the command

SET vec = { list } 

For example

SET r = 0,10 

is equivalent to

SET r = { 0 1 2 3 4 5 6 8 9 10 } 

In fact, { list } is an expression, so

SET vec = 2*{1 3 1} is also legal.
If the first element of a list is a word, the vector is taken to be
string-valued: SET s={ William William Henry Steven } defines a
4-element string vector, or you can use a string in quotes:
SET s=<'1' 2 3 4> (if you used SET s={'1' 2 3 4} the first
element would be '1' rather than 1).
Once a vector is defined, you can write it to a file for later study using the

PRINT command.

A scalar may be an integer, a floating point number, a scalar
expression, DIMEN(vector), or WORD[expr]. The last two are the
dimension of a vector, and an element of the vector with expr a
scalar subscript. Note that subscripts start at 0 and that [ ]
`not' () are used to subscript variables.
The expression WORD[expr] is in fact allowed even if expr

is not a scalar, in which case the result is a vector with the same
dimension as expr, and with the values taken from WORD in
the obvious way.

Once vectors are defined, they may be combined into expressions using

the operators +, -, *, /, **,

CONCAT and the
functions COS(), SIN(), TAN(), ACOS(),
ASIN(), ATAN(), ATAN2(), ABS(), DIMEN(), INT(), LG(), EXP(), LN(),
SQRT(), STRING(), STRLEN(), and
SUM().
The meaning of most of these is obvious, ATAN2 is like ATAN
but takes two arguments, x and y and returns an angle in the
proper sector.

DIMEN returns the number of
elements in a vector, SUM gives the sum of all the elements,
CONCAT concatenates two vectors,

INT gives the integral part of a vector, STRING
converts a number to a string, and STRLEN gives the length of a string
(in plotting units, not just the number of characters). STRING uses
the same code as the axis-labelling routines, so FORMAT can be used
to modify its behaviour; whether the x- or y-axis formats is used depends
on whether the label is more nearly horizontal or vertical.
An example would be

set x=3.08e16 define s (string(x)) relocate 0.5 0.5 putlabel 5 $s

The precedence and binding are
as for C (or Fortran), and may be altered by using parentheses
(CONCAT has a binding just below + and -).
All of these operators work element by element, so

y = 2 + sin(x)

is interpreted as

If there is a size mismatch the operation will only be carried out up
to the length of the shorter vector and a message is printed; if
VERBOSE is 1 or more, the line where the error occurred will
be printed too.
The constant PI is predefined.

You can also use WORD([ expr [ , ... ]]) as part of
an expression, where WORD is a macro taking zero or more arguments.

Suppose we define a macro pow with two arguments as

SET $0 = $1**$2 

then the command

SET y = 10 + 2*pow(1 + x,3)

is equivalent to SET y = 10 + 2*(1 + x)**3.

In addition to these arithmetic operations, there are also logical
operators == (equals), != (not equals),

>, >=, <, <=, &&
(logical and), and || (logical or). The meanings of the symbols are the
same as in C, and as in C the value 0 is false while all other values are true.
Note that && and || do not`short-circuit'; that is,
in the expression expr1 && expr2 both expr1 and expr2

are evaluated. In a scalar context (e.g. in an IF statement), the operators
AND and OR are available instead, and they do only evaluate
the right hand side if it's value is required (see section If).

String vectors may only be concatenated, added, or tested for (in)equality.
Adding two string-valued vectors concatenates their elements, so

{ a b c } + { x y z }

results in the vector ax by cz.

Testing equality for string vectors seems to cause some confusion. Consider

set str=<'a' b c d>
if('a' == 'str') {     # test if the strings `a' and `str' are equal
if('a' == str) {       # test if the string `a' equals the vector `str'
if(a == str) {         # test if the vector `a' equals the vector `str'

The second of these tests will succeed, but if you then try

if('b' == str) {       # try to see if `b' is an element of str

the test will fail as 'b' == str is the 4-element vector
{ 0 1 0 1 } and only its first element is used by the if test;
what you want is

if(sum('b' == str)) {  # is `b' an element of str?

There are also a number of less mathematical operations. If you have an
IMAGE (see section Image) defined, you can extract a set of values
using the expression IMAGE(expr,expr), where the two exprs
give the coordinates where the values are desired. Note that this may be
used as a way of reading large data files that are stored unformatted.
The expression HISTOGRAM(expr : expr) can be used to convert a
vector into a histogram. The second expression is taken to be the
centres of the desired bins: bin boundaries are taken at the mean points
(and points in the first expression lying on a boundary are taken to
fall into the lower bin. Note the use of `:' not `,').

Vectors may be assigned to, using the syntax

SET vec = expr

or

SET vec[ expr ]  = expr

or

SET vec = WORD(expr)

or

SET DIMEN(vec) = number

or

SET vec = expr1 IF(expr2)

or

SET  vec = expr1 ? expr2 : expr3

The first form sets vec to have the value expr, element by
element, vec is the name of the new vector. The form
vec[expr] may be used to assign to an element of a vector, as usual
the index starts at 0. Before you can use SET to assign values to the
elements of a vector, you must create it using one of the other forms
of the SET command.

If you want to define a vector to which you will subsequently assign values
using SET vec[ expr ] = expr, you may use SET DIMEN(vec) = number
which declares vec to be a vector of size number, and
initialises it to zero. You can optionally supply a qualifier to the
number, either a .f (the default), or a .s to
specify that the vector is string valued.

If the IF clause is present, only those
elements of expr1 for which the corresponding element of expr2 is
true
(non-zero) are copied into vec; in general vec will have a
smaller dimension than expr1. The last SET statement (with ?:)
again borrows
from C. If expr1_i is true, then vec_i is set
to expr2_i, otherwise it is
set to expr3_i. In this form of conditional assignment, the dimension
of vec is the same as that of the right hand side. It may look
strange, but it can be just what you want.

Each vector also has a help field, which may be used to provide a string
describing the vector. The field is set by

SET HELP vec str

and
viewed by

HELP vec

or via the string-valued expression HELP(name).

If VERBOSE is one or more, if a vector is arithmetic or string
will also be noted. Vectors may be printed using the

PRINT [ file ] [format] { vec1, ..., vecn }

command, where if the optional
file is missing, the values are typed to the keyboard; if the
optional format is omitted, a suitable one will be chosen for you.
Any combination of string- and arithmetic-vectors may be printed.
If a value
exceeds 1e36, it is printed as a *. This is consistent with the
convention used in reading data that a `missing' number is represented
as 1.001e36; see READ for details.
Vectors may be deleted with the command

DELETE vec

and listed with the command

LIST SET

Vectors are listed in ascii order along with their
dimension, and any help string specified using the SET HELP command

Once you start writing (or using) complicated macros you'll get bitten by
the fact that a macro called by a macro called by a friend's macro uses
a scratch vector called x or i, and that this vector quietly
overwrites your vector called x or i. To avoid this,
conscientious macro writers make their vectors LOCAL.
(16).
After the command SET x LOCAL in a macro, any redefinitions of x

within that macro, or any macros called by it, will be discarded when the
macro exits. The vector isn't strictly speaking local to the macro as it's
visible from macros that are more deeply nested, but the effect is similar.
A word on caution: a macro can exit sooner than you expect; the classic
example is

cube     11      # print a vector's cube for people we like
                 define name local  define name :
                 if('$name' != 'Thatcher') {
                        set x local  set x = $1
                        set x = x*x*x
                        print The answer is $(x)
                 }

Because the if might be followed by an else, the macro is
read and popped from the input stack before it's executed, causing
confusion.

An IF clause has been
added to the plotting commands, to allow only those elements of a
vector which satisfy some condition to be plotted, for example

POINTS x y IF(z > 3*x)

Of course, you could have used the IF command and the regular
POINTS command if you had preferred. In fact,

CONNECT x y IF(z > 3*x)

isn't quite the same as

SET log = z > 3*x SET x = x IF(log)  SET y = y IF(log) 
CONNECT x y

as the former will only connect contiguous points.

Drawing Labels and SM's TeX Emulation

There are two separate ways to specify special characters to
SM, by using a syntax
very similar to TeX (the type-setting system created by Donald Knuth
that we used for this manual), or the traditional Mongo way. You might
ask what are the advantages
of TeX? One is that sub- and super- scripts are handled much more naturally,
making it much harder to type
when you meant
Another is that you no longer have to remember that
is hidden
in the Greek font as `q', you can simply type \theta. A
third would be that you may well know TeX already.

If you want to make SM understand TeX strings
you should define the variable
TeX_strings (if you put a line

TeX_strings 1 in your `.sm' file this will be done automatically).

You can, of course, undefine it at any time to revert to the old-fashioned
strings described below.

Using TeX-style
strings is strongly recommended by the authors; all future and most
recent improvements to SM's labels are only supported in TeX mode.

If you want to change the default font used for labels, define the variable
default_font; if you wanted to use the \oe (Old English)
font you could either say (DEFINE default_font oe) interactively,
or put a line in your `.sm file': default_font oe.
This affects axis as well as regular labels and
only works if you use TeX_strings (of course).

For some devices with hardware fonts (for example, postscript printers
or a Tektronix 4010 terminal), if expand is exactly 1, and
angle is exactly 0, the hard fonts will be used for speed.
Various strategies to defeat this are discussed below.

• TeX Intro: An Introduction to TeX
  
• TeX Fonts: Available Fonts

An Introduction to TeX

(TeXsperts should skip this section.)
If you don't know TeX
let's start with an example:

label \pi^{\-21/2} = {\3\int}e^{-x^2}\,dx

will print a well-known result (You'll have to RELOCATE somewhere
where the label will be visible first, of course).
(If
you want to try it now, you should be careful typing those ^'s, as
they are special to the history editor, dealing with this is
discussed below.) In
this example the characters \, {, }, and ^

are special (and so is _ which wasn't used). Postponing \
for the moment, ^ means `make the next group a superscript',
_ means `make the next group a subscript', where a group is
either a single character, a single control sequence (wait a moment!), or a
string enclosed in braces. So A_a^{SM}B would appear as
A \ can serve one of two functions, either
turning off the special meaning of the next character (so \_

is simply a _ with no special significance), or to introduce a
named `control sequence'. These fall into three groups, those that
change fonts, those that serve as abbreviations for single
characters (e.g. \pi in the example), and those that are macros.
The font changes persist
until the end of the string, or the current group, whichever comes
first.

Available Fonts

The available fonts are
`greek', `old english', `private', `roman', `script', and `tiny'. They
may be referred to either by a
two-character control sequences (\gr, \oe, \pr,

\rm, \sc, or \ti) or simply by the first character
(e.g. \r for the roman font).
In addition \i or \it
can be used to make the current font italic (remember to use italics
within {} so that their effect is limited!).
The `bold' font \b or \bf is makes the current font bold,
and can be toggled off with a second

\bf if you didn't simply group it. I'd strongly recommend
treating \bf like any other font change, and
group them rather than relying on this toggling action.

The slant of \it letters can be controlled by the command sequence
\slant, which takes an argument which is the tangent of the desired
slope (i.e. it is the degree of shear). You can also compress all letters
along the direction that they are being written using \condense; for
example {\slant0.4\condense0.5 Hello World}.

You can alter the size of the letters
by using an escape such as \6 which scales the current group
(any font change is local to a group).
\6 corresponds to multiplying the size by
or
about 3, \-4 scales by
or 0.48. This is similar to
the `magstep' used in scaling fonts in TeX.
These scale factors
are in addition to the expansion produced by going
up or down (^ or _), or setting EXPAND.

SM's TeX Control Sequences

Other control sequences either consist of one non-alphabetic
character, or else a name consisting only of letters, so \, or
\palmtree is valid but \one2three is not. If a
alphabetic name is followed by a space, the space is treated as simply
delimiting the name and is discarded. For example,

AB^{\alpha_\beta CD} will appear as
(note that the space after beta disappeared). How do you make
just a few characters italic (script, old english, etc.)? Try
ABC{\it DEF}GHI. You can't read a subscript, and want it in
`tiny' font? Try \Lambda_{\ti ab}. All of the Greek letters are
defined, as \alpha-\omega,\Alpha-\Omega,
there are various mathematical symbols (e.g. \int, \infty,
or \sqrt), some astronomical (e.g. \AA for
and some
miscellaneous characters (e.g. \snow to draw a snowflake).
You can generate
a complete list of definitions by saying load fonts TeX_defs.

Some of these definitions are more complex than just special characters,
if you know TeX most of them should be familiar.

would have if you had drawn it.

You can also define your own TeX definitions by using the special
command \def\name{value} inside a label. It produces no output,
but defines name to expand to value. For example, I could define
\TeX to produce TeX by saying

LABEL \def\TeX{T\raise-200\kern-20E\raise200X}.

Once a
definition has been made it is remembered forever (well, until you
leave SM actually) whatever devices you plot on. You must make sure that
all curly brackets are properly paired inside your definition. You
can have arguments just like real TeX, referred to as #1,
#2, #3 and so forth, for example

\def\sub#1{_{#1}}

Your SM guru can compile TeX-definitions into the binary fonts
file, instructions are given in the fonts appendix.

SM's Extensions to TeX

We have made a number of extensions to TeX that are useful in
a plotting package, but wouldn't be especially valuable in a printed document.
We have also distorted the meanings of some of TeX's control words; sorry.

\point n s

\apoint angle n s

Insert a points (such as would be drawn with DOT) into a label. The
string \point43 (or \point 4 3) will draw a point at the
current position in the string, of ptype `4 3'. This sequence,
from the \ to the 3, is treated as a single character as regards
things like subscripts. If you want to specify an angle, use something like

\apoint 45 4 0.

\hrule width

Draw a horizontal line at the level of the current baseline, of length
width in screen units. It will be multiplied by the current
expansion.

\kern dx

\kern # moves the current plot position by #

horizontally, where the distance
# is specified in screen units (the whole screen is 32768
across). It is multiplied by the expansion currently in effect, and may be
positive or negative. See also \raise.

\line type length

\line inserts a line into a label, at about the level of the
middle of a lower-case character.
e.g. \line 1 1000 will draw a line of length 1000 (in screen
units, so the screen is 32768 across), of ltype 1.
See also \hrule.

\move dx dy

Move a group by (dx,dy), but don't disturb SM's current idea of where
it is. This means that we can draw a line over a character with a string
such as \move 0 300{\line 0 400}A. It is possible to use the
commands such as \width to take the guesswork out of such commands,
for example the definition of \bar is

\def\bar#1{\move0\advance\height{#1}by100{\rule\width{#1}}#1}

\raise dy

\raise # moves the current plot position by #
vertically, where the distance
# is specified in screen units (the whole screen is 32768
across). It is multiplied by the expansion currently in effect, and may be
positive or negative. See also \kern.

\vrule depth height

Draw a vertical line at the current position of depth d and
height h (and width 0) in screen units. Dimensions are multiplied by
the current expansion.

There are also a number of control sequences that can be used whenever
a number is expected (by \kern, \line, \move,
or \raise);
for an example of their use see \move in the preceding table.

If you want to know the dimensions of the string that you have just drawn
(or just not drawn, q.v. PUTLABEL 0) you can look at the internal variables
$sdepth, $sheight, and $slength.

Caveats and Cautions when using TeX

Now for a few caveats: Firstly, because \n is a newline, you must type
\\nu or "\nu" to get a
Secondly, the superscript
character
^ is special to the history editor, so to type it interactively
you must quote
it with the quote_next key (usually control-Q or ESC-q, i.e.
type control-Q^). Alternatively, you could change your history
character to some under-used character such as % or ' (which is the
solution that I use: you can choose a new character such as ' by
simply putting a line

history_char ' in your `.sm' file).

Thirdly, TeX (and our pseudoTeX) are
rather verbose and labels may not fit on one line. The solution is to
continue the line by ending it with a \. This is probably best done
within a macro, as the continuation line won't appear on your history
list if typed at the prompt. You can currently have about 25
continuation lines (2000 characters).

A final point will only worry
TeXies, namely that the emulation isn't perfect: for example
\sum_i won't put the i beneath the summation symbol.
Some of the other discrepancies were listed in the previous section.

How to Stop the Device using its Fonts

If EXPAND is set to exactly 1, and ANGLE is exactly 0, then SM
will use hardware fonts, when available, in writing labels. This is faster,
but can lead to two styles of labels in one plot which is ugly.

There are various ways to trick SM into always using its own fonts:
you can say say "ANGLE 360",
or use a \0 to select a font with (explicitly) no expansion. To
affect the axis tick labels too, using the AXIS or BOX commands,
you'll have to say "EXPAND 1.0001" or somesuch.

Rather than always expanding your plots, you could ask your SM
Guru to edit the `graphcap' file to prevent a given device
(usually a printer) from ever using hardware fonts. Tell her to
see section The Stdgraph Graphics Kernel. If she won't oblige, you can define your own device in
your own graphcap file, and put yours first in the `.sm' file.
For example, my `.sm' file includes the line

+graphcap    /d/rhl/graphcap

and the file `/d/rhl/graphcap' looks like:

# Private overrides for RHL:
#
postscript|postscript + no hardware fonts:\
        :TB@:TE@:TC=postscript:

Then I set $printer to postscript (also in `.sm')
and all is well.

An alternative is to specify the device as

        DEVICE postscript :TB@:TE@:tc=postscript:

which is perhaps simpler (you'd just define your value of printer
properly).

Old-style Labels

If you insist on using old-style labels (which are still the default),
here's a quick summary.
Type \a or \\a
to change to font
a for one character (first form) or permanently (second
form). The possible fonts are g, o, p, r, s, and t for
`greek', `old english', `private', `roman', `script', and `tiny'
respectively. In addition, the pseudo-fonts u

and d move text `up' and `down' respectively, and i produces
`italic' (actually just slanted) characters.
Size changes are just like any other font change, so
\6 and \-4 will affect one character and the rest of
the string respectively.
This is really somewhat simpler than it sounds - try

label \gp\u\-21/2\2\d = \3\g:e\u-x\u2\d\s dx

Note that `tiny' is a misnomer, it is (nowadays) just a font that
look better if you need small letters (
\t\-6 will produce a shrunken `tiny' font, just like the
old days).
Spaces are treated differently in different fonts, as a greek space is
a negative space (i.e. a backspace), and a script space is only half as
wide as a normal space.

Getting Hardcopies of Plots

There isn't really any need for this section because SM doesn't
distinguish between hardcopy devices such as laser printers and
other devices such as graphics terminals, except that it saves up
plotting commands for hardcopy devices and sends them all when you are
finished. There are, however, hard and
easy ways to do anything and this section is intended to make your life a
little simpler.

When a device that can produce hardcopy is closed the plot is sent off
to the printer (using the command given as SY in the device's
graphcap entry). The only way to close a device is to open another, any
other, so it is just as good to say dev x11 as it is to say

hardcopy dev x11 as the macro hardcopy does no more than
open the null device. So one way to produce a plot is to say

                device postscript
                plotting commands
                device x11

There are many different printers available, and even if you are using
a postscript printer you might want portrait (postport) or
landscape (postland) plots, so it is traditional to put the
name of the desired printer into a variable printer. It is so
traditional, indeed, that it can be done with a line such as

printer     postport

in your `.sm' file.

The two commonest incantations are probably

                device $printer
                playback
                device x11

or

                device $printer
                my_macro
                device x11

which can be simplified to hcopy and hmacro my_macro respectively.
The former
can be given a single history number (e.g. hcopy 12) to only make
a hardcopy
of the one command, or a range of numbers (hcopy 1 12) to plot
those lines (inclusive).
The latter, if you omit the name of the macro, will prompt you to create
a temporary macro that is then printed. If you want to make a hardcopy of
the last line you have a choice, either hcopy -1 or hmacro,
and then use the history editor to retrieve the desired line.

Some sites have many hardcopy devices of the same type, in which case
they usually set up the SY command to expect an argument
which is the name of the desired printer. You can deal with this by including
it in your printer variable: define printer "postscript latypus"
but this can be a nuisance, especially as unix already has a special
(environment) variable PRINTER that specifies your default printer.
The resolution is that both hcopy and hmacro are quite
careful; if you have an SM variable PRINTER it is taken to be your
default printer; if you don't have one they look for one in your

`.sm' file, if they don't find one there they look for an
environment (VMS: logical) variable. If all of these fail they take the
first argument (hcopy) or last argument (hmacro) to be the name
of the printer.

So if you have a PRINTER variable anywhere, hcopy and

hmacro macro_name will work as before, if you don't then you'll have
to say hcopy printer_name or hmacro macro_name printer_name.

Overloading Keywords

Sometimes you might wish that SM's authors had decided to make
a command behave a bit differently, for instance that ERASE or
QUIT didn't appear on the history list, or that SAVE deleted
all the system macros before saving your environment. Of course, you can
(usually) write macros to get around these annoyances, but you can't easily give them the same names as the original commands (for these
examples the macros are called era, q, and sav).

It is possible to change the meaning of keywords (to `overload' them),
but it can be confusing, primarily because your
new commands may not behave the same way that this manual claims.
For example, if you were perverse, you could define points
to mean QUIT. Another danger is that you could end up with a
recursive call -- for instance if you wrote your own version of box that did all sorts of cunning things, then drew a box. If you
said box in your macro, then overloaded the keyword, you'd have
a macro that called itself. If you tried to use it, nothing would
happen for a while, and then you'd start getting messages about "extending
i/o stack" until you hit control-C. Or if you redefined help to mean

DELETE HISTORY HELP (in upper case to avoid recursive calls, and
in case delete has been overloaded), then set help vec Help string
won't work (you'd have to use set HELP vec ...).

Despite these warnings, overloading the meaning of
SM's keywords can be very convenient. There are two sets of
system macros that do just this, the compatibility ones (see section Tips for Mongo Users),
and one called set_overload that is described below.

In addition to the semi-trivial use of overloading to allow you to type
erase not era, it is possible to add extra functionality
to simple commands. For example, set_overload defines window
to save the window parameters in variables, and box then uses these
values to label appropriate axes in touching boxes. Another example is that
(when overloaded) lines saves the line numbers used, so that you
can write a macro to print the top 10 lines of a file (it's called head).

So how do you do it? The command OVERLOAD keyword # will remove
the special meaning of lowercase keyword if # is
non-zero, or reinstate it otherwise. You can still use the uppercase form
-- you can't overload that. So now that e.g. box has no
special meaning you can define it to be a macro. What the set_overload macro does is to define new meanings for a number
of keywords, the new definitions are in the macro file `overload'.
If you intend using them (and I do all the time) you should look at
this file.
You can get them loaded by default by having a line overload 1 in your

`.sm' file.

If you don't like some, e.g. box, you can simply say OVERLOAD
box 0 in your private startup file (see `private initialisation')
which is run after the system startup.

Most of the changes are benign, but not all. For example, the
new definition of relocate allows expressions, but it'll break
if you try to say relocate ( 100 1000 ) to move to absolute
screen coordinates. You can still say RELOCATE ( 100 1000) of
course, and that's why most of the system macros are actually written
in uppercase. The definition of box (actually bo,
which box calls) may seem very complex, but
it has to deal with box \n as well as box 1 2, and it
must know if you have used the WINDOW command.
This brings up another point -- if you overload keywords,
you could slow SM down. It isn't that overloading is
inefficient, it's just that the macros that replace the old keywords
may do a good deal of work, box is a case in point. Even when
the macro is short and to the point, it's still extra work to parse
the original word and find its value as a macro.

Examples of Useful Macros

When you start SM the directory specified as macro in your
`.sm' file is searched for a file `default', and then the
macro startup from that file is executed. At the time of writing of
this manual, startup was defined as:

startup      ## macro invoked upon startup
             FOREACH 1 { default_font device edit file_type history_char \
                    macro macro2 overload printer prompt prompt2 SHELL } {
                DEFINE $1 :
             }
             FOREACH 1 { TeX_strings case_fold_search fan_compress \
                 line_up_exponents noclobber overload \
                 remember_history_line traceback uppercase } {
                DEFINE $1 :
                IF($?$1) {
                   IF('$$1' == '0') {
                      DEFINE $1 DELETE
                   }
                }
             }
             IF($?prompt) { PROMPT $prompt\n DEFINE prompt DELETE
             } ELSE { PROMPT : }
             IF($?device) { DEVICE $device
             } ELSE { DEFINE device nodevice }
             IF($?default_font && $?TeX_strings == 0) {
                echo You can only define a default font if you use TeX
             }
             IF($?history_char) {   # use $history_char as history character
                IF('$history_char' != '0' && '$history_char' != '1') {
                   EDIT history_char $history_char
                }
                EDIT ^ ^
                DEFINE history_char DELETE
             }
             # load the default macros
             DEFINE mfiles < stats utils > # $mfiles is used by `sav'
             FOREACH f ( mongo $mfiles ) { MACRO READ "$!macro"$f }
             FOREACH var ( x_col y_col data_file ) { DEFINE $var . }
             # load uppercase if defined in .sm file
             IF($?uppercase) {
                MACRO READ "$!macro"uppercase
             }
             # and overload keywords such as erase, if so desired
             set_overload $?overload
             # and some keymaps
             IF($?edit) { READ EDIT "$!edit" }
             # and an optional macro file, with macro startup2
             IF($?macro2) {
                MACRO READ "$!macro2"default
                IF(is_set(startup2,1)) { startup2 }  # startup2 is defined
             }
             # provide a \n after the IF

As this macro is executed every time that you run SM, let us consider
it in some detail. After setting the prompt, it looks for entries for
a number of variables in your `.sm' file. Some (such as printer)
are simply DEFINEd, while some (such as TeX_strings)
are only DEFINEd if they
have a non-zero value. Because some of the values might not be numeric,
the comparison is forced to be done on strings by enclosing the quantities
in single quotes.
An entry prompt is interpreted as a primary prompt, mostly for
compatibility with the use of $prompt2 to set the secondary prompt.
If device is defined it is used to set the default plotting
device, and both it and printer are used by a couple
of macros (hcopy and hmacro) that produce hardcopy.
The variables

TeX_strings and default_fonts are used in producing
labels (see section SM's Fonts).
Because TeX uses ^ for superscripts, we
allow you to put a history_char line in `.sm' to specify a
character to use rather than ^ for history (I use `).
If you use 0, or omit the value (so it is set to 1), no
history character is defined to replace ^.
The variable file_type is used by the IMAGE command to
determine the file format that you use (e.g. C, or unformatted fortran).

Startup doesn't have to check that macro was successfully
defined as it must have been found for startup to have been read
in the first place. Macro specifies where to look for macro libraries,
and startup next sets the variable mfiles containing the
names of some of

the system macros to be loaded, and reads them.
The macro load defined below also maintains the mfiles
list, as does unload. It is used by the
sav macro, which is discussed below the main listing of macros that
follows.
We also set some variables used by the id macro.

As part of our effort to be nice
to users, if you have uppercase 1 in your `.sm' file,
we also load the uppercase macros.
Next startup overloads some keywords if overload is
in your `.sm' file, reads a file of keybindings (if edit

is given in `.sm'), and
finally tries to read a second optional macro directory
macro2, and executes a macro startup2 if it's defined
(that's what the macro is_set is checking).
This is quite important, as it provides a way to customise SM
to your personal taste without convincing the local SM guru
that your taste should be foisted on everyone. If you want a prompt that
is different, or a definition of q that just quits without asking
questions, you can get them by using macro2.

You can see that it is possible
to tailor SM pretty much as you wish without changing a line of
code, just by playing with the startup macro.

SM provides various compatibility
macros, and some to package often-used functions.
The macro files `stats' and `utils', which are read when SM
is started, provide various useful
macros, a few of which are presented here. To see a current list, either
look at the files directly, set VERBOSE to zero and list all the
macros, look at the listing in this manual (see section The System Macro Libraries),
or use lsm to list macro files
(this only works if you are running Unix; try lsm demos).
We give here a number of macros taken from the files `default',

`mongo', `stats', and `utils'.
Among those not listed are those like lin defined to be lines
that are pure
abbreviations, those like xlogarithm defined as
SET x=lg(x) which provide functionality in a perhaps familiar form,
and many more like those that are given here which provide
enhancements (e.g. the macro barhist).
A discussion of a few of the more interesting or obscure follows.
Keywords are written in uppercase, because you might have been playing
tricks with overloading the lowercase equivalents.
Many of these macros, in fact all from `default' and `mongo',
start with ## so as not to show up in listings made when VERBOSE is 0, and so as not to be SAVEd. In the interest of
brevity we have omitted most of these initial comments.

cumulate 2   # Find the cumulative distribution of $1 in $2
             DEFINE sum 0 SET $2=0*$1 SET HELP $2 Cumulation of $1
             DO i=0,DIMEN($1)-1 {
                DEFINE sum ( $sum + $1[$i] )
                SET $2[$i] = $sum
             }
             define sum delete
da   1       DATA "$1"
del1 1       DELETE HISTORY \n
dev  1       del1 DEFINE device $1 DEVICE $1
dra 2        # Draw, accepting expressions
             define 1 ($1) define 2 ($2) draw $1 $2
edit_hist    # Edit the history list
             del1 MACRO all 0 100000       # define "all" from buffer
             WRITE STANDARD Editing History Buffer\n
             MACRO EDIT all                # do the editing
             DELETE 0 100000       # empty history buffer
             WRITE HISTORY all             # replace history by "all"
era          del1 ERASE
gauss 1      # Evaluate a Gaussian : N($mean,$sig)
             SET $0 = 1/(SQRT(2*PI)*$sig)*EXP(-(($1-$mean)/$sig)**2/2)
get 2        # Syntax: get i j.  Read a column from a file.
             # Name of vector is jth word of line i.
             DEFINE nn READ $1 $2 echo reading $nn\n
             READ $nn $2
             SET HELP $nn Column $2 from $data_file
             DEFINE nn DELETE
hardcopy     DEVICE nodevice   # close old device
hcopy 13     ## hcopy [printer] [l1] [l2] Make hardcopy of playback buffer
             # optionally specify printer ($1) and desired lines ($2-$3)
             # if the printer ($1) is omitted (i.e. $1 is missing or a
             # number), it will be taken from the value of the environment
             # variable PRINTER, if defined.
             IF($?printer == 0) {
                DEFINE printer ? { what kind of printer? }
             }
             IF($?1) {
                IF(WHATIS($1) == 0) { # a number
                   if($?2) { DEFINE 3 $2 }
                   DEFINE 2 $1
                   DEFINE 1 DELETE
                }
             }
             IF($?1) {
                DEVICE $printer $1
             } ELSE {
                IF($?PRINTER == 0) { DEFINE PRINTER : } # which one?
                IF($?PRINTER) {
                   DEVICE $printer $PRINTER
                } ELSE {
                   DEVICE $printer
                }
             }
             IF($?2 == 0) {
                DEFINE 2 0 DEFINE 3 10000
             } ELSE {
                IF($?3 == 0) { DEFINE 3 $2 }
             }
             playback $2 $3 \n DEVICE $device
             bell
hmacro  12   ## hmacro [macro] [printer] Make hardcopy of a macro
             # If only 1 argument is present, it is taken to be the printer
             # unless an environment PRINTER variable is defined, when
             # that's used as a printer, and the argument is taken to be
             # a macro. If no macro is specified, make a temp one
             IF($?printer == 0) {
                DEFINE printer ? { what kind of printer? }
             }
             del1
             IF($?2 == 0) {          # only one arg
                IF($?PRINTER == 0) { DEFINE PRINTER : }
                IF($?PRINTER) {
                   DEFINE 2 $PRINTER
                }
             }
             IF($?1) {
                if($?2) {            # 2 args
                   DEFINE _mac $1
                   DEFINE _temp 0    # no temp macro
                } ELSE {             # 1 arg, take as printer
                   DEFINE 2 $1       # printer
                   DEFINE _temp 1    # need temp macro
                }
             } ELSE {                # no $1
                IF($?2 == 0) { DEFINE 2 " " }
                DEFINE _temp 1       # need temp macro
             }
             IF($_temp) {
                DEFINE _mac _mac
                echo "Create temporary macro, exit with ^X"
                MACRO EDIT $_mac
                IF(is_set($_mac,1) == 0) {
                   DEFINE _mac DELETE DEFINE _temp DELETE 
                   DEFINE _test DELETE
                   RETURN
                }
             }
             DEVICE $printer $2
             $_mac \n DEVICE $device
             IF($_temp) { MACRO $_mac DELETE }
             DEFINE _mac DELETE DEFINE _temp DELETE bell
load         # load macros in default directory
             DEFINE macro :                   # get default directory
             MACRO READ "$!macro"$1  # read macro file
             IF($?mfiles == 0) {
                DEFINE mfiles $1
             } ELSE {
                DEFINE 3 0
                FOREACH 2 ( $mfiles ) {
                  IF('$2' == '$1') { DEFINE 3 1 }
                }
                IF($3 == 0) { DEFINE mfiles < $mfiles $1 > }
             }
load2 1      # load macros in (second) default directory
             DEFINE macro2 : # get directory
             IF($?macro2) {
                MACRO READ "$!macro2"$1  # read macro file
             } ELSE {
                echo Directory macro2 is not defined
             }
logerr 3     # logerr x y error, where y is logged, and error isn't
             SET _y = 10**$2
             SET d_y = LG(_y + $3) - $2 ERRORBAR $1 $2 d_y 2
             SET d_y = $2 - LG(_y - $3) ERRORBAR $1 $2 d_y 4
             DELETE _y DELETE d_y
lsq  15      # do a least squares fit to a set of vectors
             # syntax: lsq x y [ x2 y2 [rms]] Fit line y2=$a*x2+$b to x y
             # optionally, calculate rms residual as $rms
             # see rxy to find product moment correlation coeff,
             # and spear for Spearman's corr. coeff., and significance
             SET _n = DIMEN($1)              # number of points
             SET _sx = SUM($1)               # sigma x
             SET _sy = SUM($2)               # sigma y
             SET _sxy = SUM($1*$2)           # sigma xy
             SET _sxx = SUM($1*$1)           # sigma xx
             DEFINE a ( (_n*_sxy - _sx*_sy)/(_n*_sxx - _sx*_sx) )
             DEFINE b ( (_sy - $a*_sx)/_n )
             IF($?3 && $?4) {
                SET $4=$a*$3+$b
                IF($?5) {
                   DEFINE $5 ( sqrt(sum(($a*$1 + $b - $2)**2)/dimen($2)) ) 
                }
             }
             FOREACH v ( _n _sx _sy _sxy _sxx ) { DELETE $v }
playback     ## define "all" from buffer, and run it
             # with args, only playback those lines
             IF($?1 == 0) {
                DEFINE 1 0 DEFINE 2 10000
             } ELSE {
                IF($?2 == 0) { DEFINE 2 $1 }
             }
             del1 MACRO all $1 $2 all
read_old 1   del1 # read a Mongo file onto the history buffer
             READ OLD temp $1
             WRITE HISTORY temp MACRO temp { DELETE }
rel 2        # Relocate, accepting expressions
             define 1 ($1) define 2 ($2) relocate $1 $2
reverse 1    # reverse the order of a vector
             SET _i = DIMEN($1),1,-1 SORT < _i $1 > DELETE _i
sav 1        # Save to a file $1, don't save from files `$mfiles'
             _save $1
_save 1      # Save to a file $1, don't save from files `$mfiles'
             del1
             FOREACH 2 ( $mfiles ) { MACRO DELETE "$!macro"$2 }
             DEFINE 2 0 define 2 ? { save vectors? }
             SAVE "$!1" 1 $2 1
             FOREACH 2 ( $mfiles ) { MACRO READ "$!macro"$2 }

Cumulate is given as a way not to write macros if you can
help it (in this case, I couldn't). A better example is reverse
which reverses the order of
the elements in a vector without resorting to a DO loop.

The macro da could have been defined to be DATA, but there
are various special characters that appear in filenames;
try data /usr/spool/junk or

data disk$data:[ETHELRED]junk.dat. The macro da
provides a set of double quotes to escape these unwanted interpretations.
Incidently, da "/usr/spool/junk" won't work.

DELETE HISTORY deletes the last command on the history buffer, so
del1 alone on a line will delete itself, which can be used to
prevent a command from appearing on the history
list, for example changing devices with dev; dev also defines
a variable device which is used by the hcopy and hmacro

macros to make hardcopies, while returning you to your initial device. The
startup macro listed above also sets device, if it is specified
in your `.sm' file. You should be careful not to include more
than one del1 macro in any macro that you write yourself, as
each del1

will remove a command from history and you could find commands mysteriously
disappearing.

Gauss evaluates a Gaussian, e.g. SET x=-3,3,0.05 SET g=gauss(x)
lim x g box con x g, an example of using a macro like a function definition.
(For this example to work, you have to define variables mean and
sig first).

There is an example of reading variables from files and using
them in macro get. This reads a word from a line in a file with
the DEFINE nn READ i j command, which sets $nn to be the
jth word on
line i of the current data file. This variable is then used to
READ a
vector, which is given the appropriate name. So if a file looks like:

This is an example file
alpha   beta    gamma   delta
1       10      0.1     1e1
2       20      0.2     1e2
3       30      0.3     1e3
4       40      0.4     1e4
5       50      0.5     1e5

then the commands

GET 2 1   GET 2 2   GET 2 3   GET 2 4

will read `1 2 3 4 5' into vector alpha, `10 20 30 40 50' into beta and so
forth. Note that

DEFINE READ file_id 1 LABEL $file_id

will write out `This is an example file' to the current position of the
plot pointer (see, e.g. RELOCATE). Incidently, READ ROW omega 5
would set the vector omega to have values `3 30 0.3 1e3'.

The macros hcopy and hmacro make hardcopies of, respectively,
the playback buffer and a macro. Both assume that the variables

device and printer are set. device is set from
your `.sm' file and by the dev macro; printer is assumed
set in `.sm'. (See `startup' file above). If all is well, the macros
switch to device printer (with an argument to specify which
sub-printer is desired. We have so many laser printers here...), execute
the desired commands, and return to the initial device. When the

printer device is closed, hardcopy will result. Note the use of
\n to ensure that no nasty things happen;
if there were no \n and the buffer ended with LABEL Hi, the
plot could appear with a label Hi device tek4010.
The versions of hcopy and hmacro given here
accept a variable number of arguments (`13' means up to 3 arguments).
The first (if present) is
taken to be the desired laser printer(17),
the next argument is the number
of the first line that you want played back, and the third is the last
line number. (If you omit both line numbers you'll get the whole
buffer; if you omit the second you'll just get the one line).
The macro sees what it has been given by using $? to see which
variables are defined, and acts accordingly. hmacro is somewhat
similar, except that if you omit an argument it is taken to be the
macro name, and a temporary one is created for you.
The playback macro deals
with its arguments in a similar way, and is discussed further in the examples
at the end of this section.

load enables you to read a set of macros from a directory
specified as macro in your environment file.
Load2 is similar, but it looks in directory macro2. The macro
unload (not listed here) will undefine the loaded macros.
Note that a list of all the loaded macros is kept in $mlist, which is used by the sav macro to avoid SAVEing
lots of system macros. sav is written in terms of a macro

_save so that it won't itself be forgotten (by MACRO
DELETE) while in the middle of saving macros.

If you want to put errorbars on logarithmic plots, logerr is the macro
you've been looking for. It calculates the correct length for the errorbars,
and plots them de-logging and re-logging as appropriate.

The macros rel and dra illustrate a method of using expressions,
rather than numbers, in the commands RELOCATE and DRAW. There
are Good Reasons why DRAW won't accept an expression
directly (see section The Command Interpreter).
These macros exploit the fact that the arguments to a macro are whitespace
delimited, so a string such as 1+2/$x comprises one argument.
Redefining the arguments means that the macros don't have to define,
and then delete, a couple of variables to hold the expressions.

Now that you have had your appetite whetted, we strongly recommend
that you take the time to look through the other macros that are
available (see section The System Macro Libraries).
Otherwise how would you know that there are macros to draw arrows on
plots, do KS and Wilcoxon tests on vectors, and a host of other good
things?

More Examples of Macros

In all these examples, we'll use the del1 macro discussed
above to keep commands off the history list.
Let's start with a Fourier series, to demonstrate SM's ability
to manipulate vectors. All keywords are capitalised for clarity.
Start SM, choose a plotting device (with
the dev macro), and erase all the commands on the history (or
playback) buffer with DELETE 0 10000. Then type the following
commands:

SET px=-PI/10,2*PI,PI/200
SET y=SIN(px) + SIN(3*px)/3 + SIN(5*px)/5 + SIN(7*px)/7
SET y=(y>0)?y:0
LIMITS -1 7 y
BOX
CONNECT px y

The vector px could just as well have been read from a file. You
should now have a part of a square-wave, truncated at 0.

Now consider a simpler way of doing the same thing. For the present, clear
the history buffer again (DELETE 0 10000), and type:

SET px=-PI/10,2*PI,PI/200
SET y=SIN(px)
DO i=1,3 {
   SET val = 2*$i + 1
   SET y = y + SIN(val*px)/val
}
DELETE val
LIMITS -1 7 y
BOX
CONNECT px y

Here we use a vector val to save a value, an equivalent (but
slower) loop using SM variables would be

DO i=1,3 {
   DEFINE val (2*$i + 1)
   DEFINE y = y + SIN($val*px)/$val
}
DEFINE val DELETE

That is all very well if you only ever wanted to sum the first four terms of the
series. Fortunately there is a way to change this, using the macro editor. First
define a macro consisting of all the commands on the history list:

del1 MACRO all 0 10000

will define the macro all to be history lines 0-10000.
(You need the del1 to avoid having the MACRO all 0 10000 in
your macro).
Then you can edit it using

del1 MACRO EDIT all

when you have made the desired changes (e.g. changing DO i=1,3
to DO i=1,20) use control-X to leave the editor and return to the
command editor. Now you could type all to run your new macro,
or put it back onto the history list. To do the latter, delete the
commands now on the history list (the now-familiar DELETE 0 10000),
then del1 WRITE HISTORY all to put the macro all onto the
list. Now the

playback command will run all those commands, and produce a better
squarewave. (As discussed in a moment, playback is a macro so type it
in lowercase, unless you have defined your own PLAYBACK macro.)

This ability to edit the history buffer is convenient, and there is a macro
provided called edit_hist which goes through exactly the steps that we
took you through. The trick of including a del1 in macros is
pretty common, for example h is defined as

del1 HELP so that it won't appear on the history list.
The macro playback is rather similar to edit_hist, but instead
of editing and then writing all, it executes it. We discussed
the possibility of just playing back a limited number of lines while
talking about hcopy, just say playback n1 n2.

Now that you have a set of commands which produce a Fourier plot, it
would be nice to define a macro to make plots, taking the number of
terms as an argument, and then free the history buffer for other things.
After a playback, the macro all is defined, so let's change its
name to square. There is a macro ed defined more-or-less as

del1 MACRO EDIT, so type ed all to enter the macro editor.
Use
or control-P to get to line 0 and
change the number of arguments from 0 to 1, and the name of the macro
from all to square (the space between the name and the : is
required.) Then go to the DO i=1,20 line, and change 20 to

$1. Exit with control-X, clear the screen with era and
type square 10. Now how do you
save your nice macro? WRITE MACRO square filename will write it
to file `filename', and next time you run SM
MACRO READ filename
will define it. In fact there is a command SAVE to save everything
which can be a mindless way of proceeding.
A macro similar to this Fourier macro called square

is in the file demos in the default macro directory (and was used to
produce the top left box of the cover to this manual). To try it yourself, type
something like load demos square 20. (20 is the number of
terms to sum.)

If your wondering why ed is only `more-or-less' defined as del1 MACRO EDIT, it's because the real ed checks to see if you
have provided a macro name, and if you haven't it edits the same macro
as last time.

But enough of macros which fiddle with the history buffer. Here are four
sets of macros which do useful things, and may give some idea of the power
available.
First a macro to use the values of a third vector to mark points, then one
to do least-squares fits to data points, then a macro to join
pairs of points, and finally some macros to handle histograms and Gaussians.
These macros are given in the format that SM would
write them to disk (ready for a MACRO READ), with the name, then the
number of arguments if greater than 0, then the body of the macro.

First the points.

alpha_poi 3   # alpha_poi x y z. Like poi x y, with z as labels for points
              DO i=0,DIMEN($1)-1 {
                 DEFINE _x ($1[$i]) DEFINE _y ($2[$i])
                 RELOCATE $_x $_y
                 DEFINE _z ($3[$i])
                 PUTLABEL 5 $_z
              }
              FOREACH v (_x _y _z) { DEFINE $v DELETE }

Here we use the temporary variables _x _y _z to get around
restrictions on expressions in RELOCATE commands.
Note the DO loop running from 0 to DIMEN($1)-1, produced
by array indices starting at 0 not 1.
If you wanted to use character strings as labels, this could be done by
using the DEFINE READ command, but this would be a good deal slower as
SM would have to rescan the file for each data-point. The top right
box of this manual's cover was made using this macro.
The use of alpha_poi (and also the macro file called ascii)
has been superseded by the introduction of string-valued vectors into
SM. Nowadays you'd simple read the column that you want to
label the point with as a string (e.g. READ lab 3.s), set the
point type to that string (e.g. PTYPE lab), and plot the points as usual
(e.g. POINTS x y).

The least-squares macro makes heavy use of the SUM operator.
It could be used to find the dimension of a
vector too, but only clumsily, and DIMEN is provided anyway. The macro
is:

lsq 4         # Do a least squares fit to a set of vectors
              # Syntax: lsq x y x2 y2   Fit line y2=$a*x2+$b to x y
              DEFINE _n (DIMEN($1))           # number of points
              DEFINE _sx (SUM($1))            # Sigma x
              DEFINE _sy (SUM($2))            # Sigma y
              DEFINE _sxy (SUM($1*$2))        # Sigma xy
              DEFINE _sxx (SUM($1*$1))        # Sigma xx
              DEFINE a (($_n*$_sxy - $_sx*$_sy)/($_n*$_sxx - $_sx*$_sx))
              DEFINE b (($_sy - $a*$_sx)/$_n)
              SET $4=$a*$3+$b
              FOREACH v ( _n _sx _sy _sxy _sxx ) {DEFINE $v DELETE }

This does a linear fit, leaving the coefficients in $a and $b. It could
be easily generalised to deal with weights, fits constrained to pass
through the origin, quadratics...

Our third example connects pairs of points. This was written to deal with
a set of data points before and after a certain correction had been applied.

pairs 4       # pairs x1 y1 x2 y2. Connect (x1,y1) to (x2,y2)
              DO i=0,DIMEN($1)-1 {
                 DEFINE _x ($1[$i]) DEFINE _y ($2[$i])
                 RELOCATE $_x $_y
                 DEFINE _x ($3[$i]) DEFINE _y ($4[$i])
                 DRAW $_x $_y
              }
              FOREACH v ( _x _y ) { DEFINE $v DELETE }

After the introduction of vectors for ANGLE and EXPAND
(in version 2.1) this macro can be rewritten to be much faster:

pairs    4    # pairs x1 y1 x2 y2. connect (x1,y1) to (x2,y2)
              DEFINE 6 { ptype angle expand aspect }
              FOREACH 5 { $!!6 } { DEFINE $5 | }
              FOREACH 5 {fx1 fx2 fy1 fy2 gx1 gx2 gy1 gy2} {
                 DEFINE $5 DELETE
              }
              ASPECT 1
              SET _dx$0=($3 - $1)*($gx2 - $gx1)/($fx2 - $fx1)
              SET _dy$0=($4 - $2)*($gy2 - $gy1)/($fy2 - $fy1)
              PTYPE 2 0
              SET _a$0=(_dx$0 == 0 ? (_dy$0 > 0 ? PI/2 : -PI/2) : \
                  (_dy$0 > 0 ? ATAN(_dy$0/_dx$0) : ATAN(_dy$0/_dx$0) + PI))
              ANGLE 180/pi*_a$0
              EXPAND SQRT(1e-5 + _dx$0**2 + _dy$0**2)/(2*128)
              POINTS (($1 + $3)/2) (($2 + $4)/2)
              FOREACH 5 { $!!6 } { $5 $$5 DEFINE $5 DELETE }
              FOREACH 5 ( _a _dx _dy ) { DELETE $5$0 }

Note how DEFINE name | is used to save things like the angle
and expansion, while DEFINE name DELETE is used to ensure that the
up-to-date versions of things like fx1 are used (i.e. that they
haven't been DEFINEd with a !).
The name of the macro ($0) is used to
make unique vector names, or at least names like _dxpairs that
are very unlikely to be in use.

SM allows you to plot a pair of vectors as
a histogram, but what if you have only got the raw data points, not yet
binned together? Fortunately, SM can do this
binning for you. Consider the following macro:

get_hist 6    # get_hist input output-x output-y base top width
              # given $1, get a histogram in $3, with the centres of the
              # bins in $2. Bins go from $4 to $5, with width $6.
              SET $2 = $4+$6/2,$5+$6/2,$6
              SET HELP $2 X-vector for $3
              SET $3=0*$2 SET HELP $3 Histogram from $1, base $4 width $5
              DO i=0,DIMEN($1)-1 {
                 DEFINE j ( ($1[$i] - $4)/$6 )
                 SET $3[$j] = $3[$j] + 1
              }
              DEFINE j DELETE

Since this was written, a new feature was added to SM, the

expression HISTOGRAM(x:y), to make histograms. The macro we discussed
above can now be written much more efficiently as:

get_hist 6    # get_hist input output-x output-y base top width
              # given $1, get a histogram in $3, with the centres of the
              # bins in $2. Bins go from $4 to $5, with width $6.
              SET $2 = $4+$6/2,$5+$6/2,$6
              SET HELP $2 X-vector for $3
              SET $3=HISTOGRAM($1:$3)
              SET HELP $3 Histogram from $1, base $4 width $5

Suppose that your data is in vector x, for want of a better name, and
it has values between 0 and 20. Then the command

get_hist x xx yy 0 20 1

will produce a histogram in yy, bin centres in xx, running
from 0 to 20 with bins 1 unit wide. So you could plot it with
lim xx yy box hi xx yy , and maybe it looks like a Gaussian. So what
is the mean and standard deviation? The command

stats x mean sig kurt echo $mean $sig $kurt

will answer that, and find the kurtosis too. (Macro stats
consists of lines
such as define $2 ( sum($1)/dimen($1) ) ). Then we could use
the macro gauss to plot the corresponding Gaussian,

set z=0,20,.1 set gg=gauss(z) set gg=gg*dimen(x) con z gg

The bottom left box of the cover was made this way. What if you don't
like the way that the histogram looks? Try the macro barhist.
Now, if you wanted to plot a lognormal, you'd have to write your own
macro, and you could use SORT to find medians and add another macro
to utils, followed by one to find Wilcoxon statistics...
(Since this was written a wilcoxon macro was donated to stats).

What Quotes What When

This chapter is not really needed as all of its contents can be found
elsewhere in this manual, but as people manage to become confused anyway,
here's a summary. There are three ways in which characters can
alter SM's behaviour:
they can affect the way that characters and keywords are interpreted,
they can be special to the grammar, and they can perform both functions.
If you are confused, you might find a verbosity of four or five helpful.

"..."

Turn off the expansion of variables, the significance of mathematical
operators such as / or :, and the recognition of keywords.
For example, after DEFINE rhl
Patricia, /data/$rhl

would be interpreted as four tokens (/, data, /, and
Patricia), while "/data/$rhl" is only one (/data/$rhl).
Note that in the former case, the data will be taken to be part of
a DATA command, and may well lead to a syntax error.
If you need to force a variable to be expanded within double quotes, use
an exclamation mark: "$!rhl". Double quotes have no syntactical
significance.

Incidently, "12" is a number as the closing " is
read before the characters 12 are parsed. You need to say

"12 " to make 12 a word; in a different package you
might call that a bug.

'...'

Single quotes surround strings which may contain white space (spaces or tabs),
characters such as + or /, or keywords.
They don't affect variable expansion, so you have
to enclose them in double quotes if you want to protect them. Of course, you
must make sure that you are not quoting the single quotes -- use
'"$abcd"' rather than "'$abcd'" .
Strings are significant to the grammar so only use single quotes where they are
needed. For example DATA 'my_file' is a syntax error, and

SET s='abc' and SET s=abc mean quite different things.

{...}

Turn off all interpretation of special characters and keywords,
just like double quotes.
In fact, braces even turn off the expansion of $!var, to expand
a variable within braces you need to say $!!var but you only very
seldom need this. Braces have syntactical significance, delimiting lists.
Wherever you can use braces you can use angle brackets.

<...>

Almost identical to {...}, but don't turn off variable expansions.
In fact, <> don't always turn off keyword interpretation --
specifically they only do so in str_list's (if you want to
know what this means you'll have to read SM's grammar in file
`control.y'). In practice you'll probably only meet this if you
try saying Foreach f < quit when ahead > { echo $f }.

(...)

Parentheses don't turn off any sort of expansion, but can have
syntactical significance.
You are most likely to see this in DEFINE var ( 1 + 2 ) where the
parentheses tell SM to evaluate the expression before defining the variable
var as 3. Note that DEFINE var < 1 + 2 > defines
var as 1 + 2 .

$name

Expand name as a variable. Expansion is turned off within single and
double quotes and within braces. Because the expansion happens before
the parser sees the input, variables cannot have any syntactical significance
as the parser never knows about them. This means that variables could
be used to make SM look like something quite different;
for example after DEFINE begin "{ " DEFINE end "} ", you can say

MACRO hi $begin echo Hello World $!!end

(This is a little tricky. The spaces in DEFINE begin "{ " are
needed so that SM is still in quote mode when it processes the {. You
can probably figure out why I need to say $!!end -- the !! should
be a Helpful Hint.)

$(expr)

Evaluate the expression expr and substitute the resulting value. This
is identical to DEFINE temp ( expr ) $temp, but much more convenient.

As a reasonably complex example, try to guess the output from:

DEFINE hi {<"$!('Hello')" World>} DEFINE hello $hi echo :$hi:$hello:

If you are not sure, try it
(you might find VERBOSE 5 helpful)(18).

Generating SM interfaces from e.g. python

SWIG (the Simplified Wrapper and Interface Generator; see http://www.swig.org/)
is a utility that allows you to use a pre-existing library as an extension to a
scripting language such as python or perl5. SM now supports python; with a modicum
of effort it could be used with perl (or ruby or ...). To use this feature,
simply select a language when you run set_opts. You'll need to have swig

installed (yes; set_opts checks), and maybe also some additional packages.

To try this out, say (with the python port) python, and then

import sm
sm.demo('x11')

• Python: Python

Python

To use SM with python, you must have the numpy package installed. After
installing SM, you'll have to add your destination library (e.g. /usr/local/lib)
to your PYTHONPATH.

Reserved Keywords

Keywords are reserved, so don't try to use them as macro names or
whatever. You can use the lowercase forms if you explicitly ask to be
allowed to overload them.
The control words are :

WORD STRING FLOAT INTEGER ( ) { } \n ! APROPOS BREAK CHDIR DEFINE DELETE DO
EDIT ELSE FOREACH HELP HISTORY IF KEY LIST LOCAL MACRO OLD OVERLOAD PRINT
PROMPT QUIT READ RESTORE RETURN ROW SAVE SET STANDARD TABLE TERMTYPE USER
VERBOSE WHILE WRITE

Arithmetic words are :

ABS ACOS ASIN ATAN ATAN2 CONCAT COS DIMEN EXP FFT INT LG LN PI RANDOM
SIN SQRT STRLEN SUM TAN WHATIS POWER_SYMBOL [ ] = + - * ** / < > | & ? :

SM plotting keywords are:

ANGLE ASPECT AXIS BOX CONNECT CONTOUR CTYPE CURSOR DATA DEVICE DOT DRAW
ERASE ERRORBAR EXPAND FORMAT GRID HISTOGRAM IMAGE LABEL LEVELS LIMITS
LINES LOCATION LTYPE LWEIGHT MINMAX NOTATION POINTS PTYPE PUTLABEL RANGE
RELOCATE SHADE SORT SPLINE TICKSIZE WHATIS WINDOW XLABEL YLABEL

With the exception of POWER_SYMBOL (which is equivalent to **)
these are described below, with the convention that arguments between
square brackets are optional. This has nothing to do with their use in
subscripting arrays!

Glossary of Terms used in this Manual

.sm

See Environment File.

Environment File

When you start SM it looks in a file
(by default called `.sm') to discover where to find files that it
needs (such as the default macros, the help files, and the font files).
You can access variables stored in the environment file yourself,
although this is probably seldom done by non-gurus. For more details,
see section Environment Variables.

Expression

An SM expression is something that can appear on the right hand side of
a SET command. More specifically, it is something that can appear
as part of the right hand side of a SET command (this
excludes implied do loops: SET x=1,10,2). Expressions may also
appear in other contexts, such as in the ANGLE command, or in

DEFINE name ( expression ). A formal definition of an
expression is given by the YACC grammar in `control.y' as the
non-terminal symbol expr.

Filecap

Binary files produced by different programmes (and
languages, and even compilers) are not identical, Fortran
`unformatted' files being a glaring example. A filecap file is a
database used to describe the byte-by-byte format of binary files, to
allow SM to read them (using the IMAGE command).

Graphcap

There are a very large range of graphics terminals
(and laser printers and so forth) in this world, and each seems to
have its own set of commands. A graphcap
file is a database that is able to describe (almost) all of these
dialects, allowing SM to plot on a wide range of devices

History

SM remembers commands as you type them, so that you
can repeat them or modify them (which includes correcting mistakes).
The set of remembered commands is referred to as the history buffer.

List

The word list is used in a few places in the manual
in the specific sense defined by the YACC grammar in `control.y'. A
list is simply a list of words or numbers, and its meaning depends on
the context. For example, SET x=3*{1 2 3} will set the vector

x to be 2 4 6, while MACRO hi { echo Hello} will
define the macro hi.

Macro

A macro is an abbreviation for a set of commands, so
instead of typing a complicated sequence of commands you can simply
type the macro's name. You can either think of macros as a new commands in
their own right or as subroutines.

Mongo

Mongo is a plotting package written by John Tonry, and
widely used in astronomy
departments. SM's command language was based on Mongo's, and we have
provided some support for an easy transition from Mongo to SM.

p_expr

A parenthesised expression. Many commands expect to be passed the name of
a vector, but will accept an expression in parentheses; for example
in the command POINTS x (y + 2/z), (y + 2/z) is a p_expr.

s_expr

A scalar expression. This is a term used in some of the command descriptions;
examples would be 210157, x[12], or x. In the latter
case, the first element of the vector x would be used, so it is
equivalent to x[0].

Stdgraph

SM uses the stdgraph device driver for most devices, using the information
in the graphcap file (see section The Stdgraph Graphics Kernel).

String

A string to SM is a sequence of characters enclosed in single quotes:
'This is a string'. Strings are primarily used in vector expressions,
but are also used in a few other places (e.g. to specify a format for a
PRINT or READ command). Note that characters in double quotes
are not strings to SM, merely characters protected from variable
expansion.

Termcap

Terminals come in many, many, flavours and types.
Their peculiarities are described by a termcap file, allowing
SM's command editor to run on (almost) any terminal.

TeX

TeX is a typesetting language developed by
Donald Knuth. We provide an emulation of certain parts of TeX's
mathematics mode in SM's label commands.

Overload

A keyword (such as DEFINE or SET) is said
to be overloaded if its meaning has been changed. Usually this
will be by adding functionality, rather than by actually changing what
it does.

Variable

A variable is an abbreviation for a sequence of characters, and may
appear anywhere that the characters in question could appear. Even if the
variable contains a number (e.g. 6.62559e-34) it is still just
a characters, although SM may choose to treat them as a number in
some contexts (e.g. the right-hand side of a SET command).

Vector

A set of one (actually, zero) or more elements. The
elements can be either numerical (floating point) or strings. Vectors
are SM's primary data type. Do not confuse a 1-element vector (a scalar)
with a variable (see section String Variables).

YACC

The SM command language is written in a language called
YACC (which is supported on Unix systems). We have provided an
implementation of YACC called Bison in the SM distribution.

Command Reference

This is the reference manual to SM's commands

• Abort: Abort the current plot without producing a hardcopy
  
• And: Logical AND with short-circuiting

Abort

Syntax: ABORT

ABORT closes the current device without producing any hardcopy. If you
are writing an output file it will be removed. You are left talking to
the null device, so you probably want to follow ABORT with a DEVICE
command.

And

Syntax: AND

In a scalar context, you can use AND instead of &&. The difference
is that AND doesn't evaluate the right-hand-side of the expression if
the left-hand-side is false; See section If, for examples.

Angle

Syntax: ANGLE expr

For most purposes only the first element of the expr is used, let's
call it D as it's an angle in degrees.

ANGLE will cause text from LABEL to come out D degrees
anti-clockwise from horizontal. It also causes points to be rotated
counter-clockwise by D degrees.

If D is non-zero it will force axis and other labels to be
written with SM's internal fonts, and will overrule the
tendency to put x-axis labels horizontal, and y-axis labels vertical.

For plotting points the full vector of values is used, with the
point rotated by the value of expr. If more points are specified than
the dimension of expr, the first element will be used for the excess.

The current value of ANGLE is (almost) always available as the variable
$angle (it is one of the special variables that are affected by the

DEFINE variable | command).

Apropos

Syntax: APROPOS pattern

Apropos lists all macros whose name or introductory comments match
the given pattern. Probably the most common use for the command is
simply to look for a word -- e.g. APROPOS histogram.

If your system supports it, APROPOS will also search the help files
for the given pattern (in this case matches may not extend over more
than one line). If VERBOSE is zero only the line containing the
match is printed; if VERBOSE is one or more then a couple of
lines on each side of the match are printed too. If the pattern
matches more than once each match will be printed, merged together if
appropriate and separated by line of dashes otherwise. If you use `q'
to stop looking at the help files APROPOS will immediately proceed to
search the macros.

The pattern is a slightly restricted version of a
normal Unix regular expression, specifically:

If the first character is a ^ it means use anything except
the range specified (in any other position ^ isn't special)

A range may be specified with a - (e.g. [0-9]), and if a ]
is to be part of the range, it must appear first (or after
the leading ^, if specified). A - may appear as
the special range ---.

Any number of the preceding character (or range)

By default searches are case insensitive, but you can make searching
sensitive to case by deleting the variable case_fold_search (you can do this
by putting a line case_fold_search 0 in your `.sm' file if you
so desire).

The name and the comments are searched separately, so you could list
all macros beginning with a, b, c, d, e, or z by saying

APROPOS ^[a-ez]

(which works because all comments start with a #),
or

APROPOS "^#[^#]"

to list all macros that start with a single # (the quotes are
needed to stop the #'s from being treated as comment characters).

Aspect

Syntax: ASPECT A

Set the aspect ratio (Y/X) to be A; This is used in drawing
characters and points and is reset when a new DEVICE command is issued.

The current values of the x- and y- dimensions of the current device are
(almost) always available as the variables
$nx and $ny, and the current aspect ratio is $aspect
(they are some of the special variables that are
affected by the DEFINE variable | command).

If A is exactly 0, the current aspect ratio is printed -- this is equivalent
to echo $aspect and is retained as a curiosity.

Usually the aspect ratio is calculated by SM to make
characters look right (and to make square points square), but it is
sometimes useful to override this, especially when positioning labels
on graphs that will be plotted on printers of different aspect ratios.

It might be worth going through an example. Suppose that you want to make
a plot that really is square when printed; how should you proceed?

The available plotting area runs from 0--32767 on each axis. So a plot
set up as

location 5000 20000 5000 20000

will have the same aspect ratio as the plotting device, in general rectangular.
We can write this as

define len 15000                # axis length, SCREEN units
location 5000 $(5000 + $len) 5000 $(5000 + $len)

if we feel sophisticated.

The variable $aspect tells you the Y/X ratio of the current device;
so the location

location 5000 $(5000+$len) 5000 $(5000+int($len/$aspect)) box

will be a square box. Of course, you'd probably really want to say

if($aspect > 1) {
   location 5000 $(5000+int($aspect*$len)) 5000 $(5000+$len) box
} else {
   location 5000 $(5000+$len) 5000 $(5000+int($len/$aspect)) box
}

There is a problem with this; the sizes of points and labels are varied to
look right with the current aspect ratio. This means that a

putlabel 5 Hello World

command that looks fine on the screen of your workstation will look awful
on the printer. That's where the ASPECT command comes into play: on your
workstation lie to SM and tell it that the aspect ratio is that of the
printer. How do you do that? Well, the slick way is to say

macro aspect_as_device 1 {
   DEVICE $1
   define 1 $aspect
   ABORT
   DEVICE $device
   ASPECT $1
}

which assumes that you use a version of the device command that saves the
current device as $device; the macro dev does this, and you can
overload device to mean dev. Then you can say

aspect_as_device postport

to force the same aspect ratio as the postport device.; your plots
will look ugly on the screen but beautiful when printed.

Arithmetic

Arithmetic

Arithmetic is allowed on vectors and scalars in SM, using the following
operators, where expr is a expression, s_expr is a scalar expression (e.g.
a number), and vector the name of a vector.

Nonary (?):

PI              Pi

Unary:

-expr           Change sign             ABS(expr)       Absolute value
ACOS(expr)      Arccosine               ASIN(expr)      Arcsine
ATAN(expr)      Arctangent              COS(expr)       Cosine
CTYPE()         Return CTYPEs           DIMEN(vector)   Dimension of a vector
EXP(expr)       Exponential             FLOAT(expr)     Convert to float
GAMMA(expr,expr) Incomplete gamma fn    INT(expr)       Integral part
LG(expr)        Log_10                  LN(expr)        Log_e
RANDOM(s_expr)  Random numbers          SIN(expr)       Sine
SORT(expr)      Sort                    SQRT(expr)      Square root
STRING(expr)    Convert to a string     SUM(expr)       Sum_i expr_i
TAN(expr)       Tangent                 VECTOR[expr]    Elements of an array
{ list }	Set vector to list      < list >	Set vector to list
( expr )        Raise precedence

Binary:

expr + expr          Add                expr - expr     Subtract
expr CONCAT expr     Concatenate        expr * expr     Multiply
expr / expr          Divide             expr ** expr    Exponentiate
expr & expr          Bitwise AND        expr | expr     Bitwise OR
expr << expr         Bitshift left      expr >> expr    Bitshift right
expr % expr          Modulus            ATAN2(expr_y,expr_x) Atan2

(note that a bitwise XOR may be achieved as | - &).

There are also some special operators:

HISTOGRAM(expr:expr)            Construct histogram
IMAGE(expr,expr)                Extract cross section (x, y coordinates)
IMAGE[expr,expr]                Extract cross section (x, y indices)
expr1 ? expr2 : expr3           expr2 if expr1 is true, else expr3
DO(s_expr, s_expr)              Implicit DO loop
DO(s_expr, s_expr, s_expr)      Implicit DO loop with increment

GAMMA returns an incomplete Gamma function, so GAMMA(a,infty) = 1.

RANDOM generates a vector of s_expr random numbers in the
range [0,1]. If you don't specify a seed (using SET RANDOM) one
will be chosen for you based on the current time.

ATAN2 is the same as C's function of the same name, and is
equivalent to ATAN(y/x). It gives a result in the range

-pi -- pi dealing correctly with divisions by zero.

CTYPE returns a vector of red + 256*green + 256^2*blue, giving the
currently defined colours; CTYPE(STRING) returns their names
(see section Strings).

DO generates a range of values, e.g. set x=do(1,5) sets
x to have the values 1 2 3 4 5; this is the same as

set x=1,5; but set y=100 + sin(pi*do(0,10)/10) is more
interesting. You can specify an increment, so do(5,1,-1) is
5 4 3 2 1.

The expression
VECTOR[expr] results in a vector of the same dimension as
the expr, with elements taken from VECTOR

(i.e. VECTOR[INT(expr_i)]). See, for example, the macro interp.

You can also use WORD([ expr [ , ... ]]) as part of
an expression, where WORD is a macro taking zero or more arguments.

The precedences are what you'd expect, with ** being highest, then
*, / and %, then + and -, then
CONCAT, then the bitwise and logical operators, and finally

?: has the lowest priority of all. You should not assume any
precedence between logical and bitwise operators, because if you do you'll
be fooled (e.g. 1||0 | 0x6 is 7, but 0x6 | 1||0 is 1);
if you use parentheses all will be well
(1||(0 | 0x6) is 1 and 0x6 | (1||0) is 7).

If you have defined an image file with the IMAGE command,

IMAGE(expr,expr) is an expression to extract values from your image.
The two expressions give the x and y values where the image is to be sampled.
For example SET x=0,1,.01 SET z=IMAGE(x,0.5) will extract a horizontal
cross section through an image. As an alternative, you can use (0-based)
indices to extract the values with IMAGE[expr,expr]; there are
examples under IMAGE (see section Image).

HISTOGRAM(expr1:expr2) constructs a histogram from a vector,
where the data is in expr1, and expr2 (which must be sorted)
gives the location of the bins.
If the values of expr2 are equally spaced, the `location' of the bin
means the centre; if they are not, a bin is defined by saying that points with
value (e2[i-1] + e2[i])/2 <= x < (e2[i] + e2[i+1])/2 go into the

ith bin.
Note that values on bin boundaries go into the higher bin.

a ? b : c is very useful if you want to treat some value of an
expression specially. You could do this with a loop but ?: is
much faster; for example

set y = lg(x > 0 ? x : 1e-37)
set y = sqrt(x >=0 ? x : 0)

Due to the way that SM evaluates these expressions you may see warnings from
the parts of the expressions that are not used (i.e. where the logical
expression is false). You can turn down the verbosity, of course, or you
could try sending mail us mail to see if we can't fix it (but it isn't easy,
or else we'd have done it already).

See `Logical' for the logical operators, `Strings' for string operators,
and `whatis' for finding out if strings are numbers, words, vectors, or
whatever.

Axis

Syntax: AXIS A1 A2 VSMALL VBIG AX AY ALEN ILABEL ICLOCK
        AXIS A1 A2 VSMALL VBIG VLAB AX AY ALEN ILABEL ICLOCK
        AXIS A1 A2 ASMALL ABIG AX AY ALEN ILABEL ICLOCK

Makes an axis labeled from A1 to A2 at location AX,
AY, length ALEN.
The first form (with VSMALL and VBIG) specifies the values
where you want small and big ticks explicitly; if you specify the string-valued
vector VLAB it will be used to label the big ticks.
The third form is more
obscure: If ABIG > 0 use that for spacing of large ticks.
If ASMALL < 0 make a logarithmic axis, if ASMALL = 0, do
the default. (See TICKSIZE for more on the meaning of negative

ASMALL and/or ABIG).
If ASMALL > 0 try to use that for the spacing of small ticks.

ILABEL is 0 for no labels, 1 for labels parallel to axis, 2 for
perpendicular to axis, and 3 for neither labels nor ticks.
ANGLE determines the angle of the axis.

ICLOCK is used for (too) many purposes; it's treated as three
integers of 1, 2, and 1 bits respectively.

ICLOCK      & 0x1:      Control the ticks orientation:
                        0       Anticlockwise from the axis
                        1       Clockwise from the axis
(ICLOCK>>1) & 0x3:      Control the tick direction:
                        0       Ticks are perpendicular to axis
                        1       Ticks are vertical
                        2       Ticks are vertical
                        3       Don't draw any ticks
(ICLOCK>>3) & 0x1:      Control which side of the axis the ticks appear:
                        0       The same size as the labels
                        1       The opposite side to the labels

If you prefer not to think in terms of bitwise operators, this can be
written as if ICLOCK is even the ticks are anticlockwise on the
axis, if odd they are clockwise. You usually want the ticks
perpendicular to the axes, and this is what you get with ICLOCK 0
or 1; if it is 2 or 3 the ticks are vertical, and if 4 or 5 they are
horizontal. The labels are on the opposite side of the axis from the
ticks unless you add 8 to the numbers given above.

For example, the following commands are equivalent to BOX:

ANGLE 0
AXIS $fx1 $fx2 0 0 $gx1 $gy1 $($gx2-$gx1) 1 $(0|8)
AXIS $fx1 $fx2 0 0 $gx1 $gy2 $($gx2-$gx1) 0 $(1|8)
ANGLE 90
AXIS $fy1 $fy2 0 0 $gx1 $gy1 $($gy2-$gy1) 2 $(1|8)
AXIS $fy1 $fy2 0 0 $gx2 $gy1 $($gy2-$gy1) 0 $(0|8)
ANGLE 0

(except that I set ICLOCK's 0x8 bit to draw the ticks
outside the box).

If you want to label the bottom axis of some
plot only at prime points try

SET b={1 2 3 5 7 11 13 17 19} SET s=0,20
AXIS 0 20 s b 3500 3500 27500 1 0

If you have used LIMITS to scale the axes and LOCATION or WINDOW
to move them, you could say something like

AXIS $fx1 $fx2 s b $gx1 $gy1 $($gx2-$gx1) 1 0

An example of using your own string valued labels would be:

set s=1,7,.5 set b=1,7 set labs={ O B A F G K M }
LIMITS 1 7 0 0
AXIS 0 10 s b labs 3500 3500 27500 1 0

which works as expected. If you don't have a shift key and try using
lower case (obafgkm) you'll be surprised as all the letters are not
at the same level (as they don't all have the same height). The easiest way
to deal with this is to make them all the same height:

set labs={ o b a f g k m } + '\\strut'

(a strut is a TeXism that has the height and depth of a parenthesis;
I'm afraid that you do have to escape the \ in the string). If that leaves
too much space try:

set labs='\\move 100' + { o b a f g k m } + '\\strut'

I think that you get the point.

If you want more control over placement and sizes of axis labels and
ticks, you can force SM to draw them separately:

        EXPAND 0.5
        AXIS $fx1 $fx2 0 0 $gx1 $gy1 $($gx2-$gx1) 0 $(1<<3)
        EXPAND 1.44
        AXIS $fx1 $fx2 0 0 $gx1 $gy1 $($gx2-$gx1) 1 $(3<<1)

gives smaller-than-usual ticks outside the box with larger-than-usual labels
(you could have used define default_font "2" to achieve the latter)

The distance of labels from axes is controlled by the SM variable
label_offset; increase it to move them further away.

Rather than use AXIS to draw all of your axes, it may be easier
to use BOX with some 3's to disable its axis-drawing habits. You'll
still get a box, but no ticks or labels. For example,

LIMITS 0 1 0 10 BOX 1 2 0 3 TICKSIZE 0 0 -1 0 BOX 3 3 1 3

will label the y-axis with both linear and logarithmic axes.

This was changed in V2.1: To specify logarithmic axes you should
now specify the logarithms, just as you do to BOX. For example, to
draw a logarithmic axis running from 1 to 1000,
specify A1 as 0 and A2 as 3, rather than 1 and 1000.

See NOTATION if you want to control the use of floating point
or exponential notation.
You can control the font used by setting
the variable default_font.
If you want your positive and negative exponents to line up
define the SM variable line_up_exponents; if it's 1 they'll
be padded with a space, if 2 or more, with a +
(you can do this in your `.sm' file).

Box

Syntax: BOX [ INTEGER1 INTEGER2 [ INTEGER3 INTEGER4 ] ]

BOX puts axes around the plot region, labelling the lower and left according
to the values set by LIMITS and TICKSIZE.
If arguments INTEGER1 and INTEGER2 are included (default 1 and 2)
they are used as ILABEL

arguments for the lower and left axes (see AXIS). An ILABEL of 0 means
to omit axis labels, 1 produces labels parallel to the axis, 2 perpendicular,
3 omits both labels and tickmarks, and 4 omits the axis entirely.
INTEGER3 and
INTEGER4 are
used for the top and right axes.

If you want to change the font used for axis labels, define the
variable default_font, either interactively (DEFINE
default_font oe), or by putting a line in your `.sm' file:

default_font oe. This affects regular as well as axis labels,
and only works if you use TeX_strings, which we recommend
anyway.

See section Notation if you want to control the use of
floating point or exponential notation, and some details on how to draw
exponents. If you want more control over your axis labels, see section Axis.

Break

Syntax: Break

Exit the current WHILE (see section While) loop, and continue executing
commands after it.

You cannot use BREAK to escape from a DO loop; either embed the loop in
a macro and use RETURN to exit early, or rewrite the DO as a WHILE loop.

Chdir

Syntax: CHDIR WORD

Set the current directory to be WORD, where WORD is any valid
directory. It might be wise to enclose it in quotes,
e.g. CHDIR "[-.more_data]", or use the cd macro.
The new directory only affects SM,
for example DATA or SAVE commands. When you exit
SM, you will be back
where you started. If the directory starts with a `~',
the `~' will be replaced by the name of your home directory. This
is the only
place that `~' is significant; in particular it will not be recognised
by the DATA command.(19)

Your current directory is always available as the $cwd variable.

Connect

Syntax: CONNECT WORD1 WORD2 [ IF (expr) ]

CONNECT draws line segments connecting the points in vectors WORD1 and
WORD2. If the IF clause is present, only connect those points for which
expr
(see the section on vector arithmetic) is non-zero. Only contiguous
points in the input vectors will be connected, resulting in a number of
line-segments. If you don't want this behaviour, say something like

set l = (z==1) ? 1 : 0  set x=xx if(l) set yy=y if(l) connect xx yy

In fact, either or both of the WORDs may be replaced by
`parenthesised expressions', i.e. expressions in parentheses. For example,

CONNECT x (2*y)

plots x against 2y.

If WORD1 and WORD2 have different dimensions CONNECT will
ignore the excess points in the longer vector. If you want to plot a
constant value you'll have to explicitly promote it, for example

CONNECT x (1+0*x)

which makes a rather boring plot.

To draw a line in a label you can either use CONNECT or DRAW, or use the
TeX-macro \line to directly insert your line.

Contour

Syntax: CONTOUR 

Makes a contour plot of an image read by the IMAGE command
(see section Image).
The contour levels are set using LEVELS;
plot coordinates are taken to be those set by the
LIMITS command, and contours are drawn in the current LTYPE. It is not
possible to produce labeled contours.

Any pixels whose value is NaN are ignored, as are any whose value
equals the SM variable $missing_data; by default this is some
very large number (usually 1e37). If a contour line runs into a missing
data point it simply stops, rather than being made to join up with some
other line that also runs into a missing point.

See also DITHER for dithering images, IMAGE CURSOR for using cursors to
get values from images, MINMAX for finding the minimum and maximum of
images, and Arithmetic for extracting cross-sections of images.

Ctype

Syntax: CTYPE WORD
        CTYPE INTEGER
        CTYPE = expr

With WORD, set the line colour to be WORD, if your
display device supports
coloured lines, where WORD must be one of default, white,
black, red, green, blue, cyan, magenta,
or yellow. The colours are those composed of three, zero, one, or two
of the primary colours red, green, and blue. When a device is opened
it sets default to some device specific value (e.g. white for
xwindows, black for sunwindows).

Initially, CTYPE INTEGER is another way of selecting the same colours
as are available with CTYPE WORD, where CTYPE 1
is the equivalent of the
first colour listed above, or white (so default is 0).
However, the CTYPE = expr
command redefines the available colours to be the elements of the array
given by expr. If it is arithmetic, each element of is interpreted as
RED + 256*GREEN + 256^2*BLUE for the given colour, where 0 is off,
and 255 corresponds to full intensity.
If the expr is string-valued it specifies the names to be
used for the colours that you have just defined. Any connection
between the names and colours is, of course, up to you.

You can get the current value of CTYPE with DEFINE ctype |,
and vectors of the current ctypes and their names as CTYPE() and
CTYPE(STRING).

So another way to get
white lines would be to say:

CTYPE = { 0 255 0 } + 256*({ 0 255 255 } + 256*{0 255 0 })
CTYPE 1

while

CTYPE 2

would give green lines.

CTYPE ={ black white green }

would make your colour names correspond to reality again. You can use any
names you like, you are certainly not restricted to the initial set.

You can reset the colours to their default (i.e. correct) values using the macro
reset_ctype.

If you want to add a new colour you can say:

CTYPE = CTYPE() concat 200 + 256*(100 + 256*100)
CTYPE = CTYPE(STRING) concat 'pink'

and delete one with

foreach f {"" string} {
   set ct=ctype($f) if(ctype(string) != 'pink') ctype = ct
}

(see also macros add_ctype and del_ctype).

Many devices (e.g. sunview) require you to specify
a number of colours that is a power of 2, so asking for 70 colours
will use up 128 slots. It is probably a good idea to
use as few colours as possible, as they are scarce resources on most displays.
You should also be aware that the display may use some of `your' slots
for the background, so specifying 63 colours on (e.g.) a sun actually
requires 64 (and asking for 64 will use up 128). If you specify more colours
than are physically available, or more than the device driver thinks
that you deserve, SM will interpolate your values of CTYPE for you.

If you are using X11 (see section Device), you will probably need to use the
-cmap flag when openinig your device if you want to allocate many
private colours.

The default colour is specified
in the device drivers, or in the DC (Default Colour) graphcap
capability, and is set whenever a device is opened, so don't try to
modify it with a CTYPE = expr command. You can, however, override
the default colour with a foreground entry in your `.sm' file;
it should be the name of a colour (as listed above). You may also be able to
specify a background colour (as background). This is either a colour
name or a set of three integers in the range 0-255 specifying
the red, green, and blue values. We allow you this chance to specify arbitrary
colours because it's your only chance to affect the background, and you can't
use a CTYPE = command to compose your own palette. On some devices
the name of the background colour may be chosen from a wider selection;
for example if you are using Xwindows you may use any name from the
colour database.

Cursor

Syntax: CURSOR 
        CURSOR WORD1 WORD2
        CURSOR READ

Display the cross-hair cursor to enable you to get positions (in user
coordinates). The current cursor position is typed on the screen every time
that you hit a key; some keys are special, specifically you can exit
the cursor routine by hitting `e' or `q'. If you exit with `e', CURSOR issues a
relocate command to set the current plot position to the cursor
position, and puts the command in the history buffer. If you exit with `q',
no entry is made in the buffer (but the current position is still updated).
Usually successive positions overwrite
each other, but if a digit is used to mark a point then the position is
followed by a newline, so the next time you hit a key its position
will appear on the next line. (You can remember that digits lead to
numerous values appearing). If the verbosity (see section Verbose) is one or
more, a message will be printed reminding you what keys to use.

If you simply want to read the current position of the cursor, you can
say CURSOR READ; this is mostly useful within macros (see, for
example, animate in the macro file `3d').

Many graphics devices have things called "GIN terminators".
SM usually expects that this be set to `Carriage Return' with
no extra characters, EOT is a popular (unacceptable) choice. If you
have trouble check your graphics setup screen, then with your
SM Guru who can look up in graphcap to see what is expected.
If the local Guru were very friendly, he could change your GIN
terminator to anything he wanted, even EOT, but he probably isn't.

The second form enables you to define a pair of vectors WORD1

and WORD2. SM provides you with a cursor, and every time that
you hit a key it prints its position (just as above). If the letter is
`e' it draws a point of the current type at the current position,
prints the current position, and enters the (x,y) coordinates in the
vectors; if you use `m' to mark a point the coordinates are not written
to the screen, but the point is still added to the vectors. `p' defines
the current point, and exits. Exit without defining another point with
`q', so the sequence `e' `q' is equivalent to `p'. You can also
abort with a control-C in which case WORD1 and
WORD2 are unchanged.

Note that if you want to use SPLINE on the vectors produced in this
way, you should take care that at least one of the vectors is monotonic and
increasing, or use the SORT command.

See also IMAGE CURSOR which returns the value under the cursor as well
as the position if an IMAGE (see section Image) has been defined.

For devices with mice, if the buttons do anything, they should generate
the characters `e', `p', and `q' (starting at the left).

The SunWindows cursor is slightly different. The cursor position is given
by a pointing finger (it's the best we could do), and
SM won't see any characters typed at
the keyboard until you hit a carriage return. Device sunwindows is
obsolete anyway, you should simply switch to using the sunview driver.
Its cursor has a bug, in that it only sees every other character
typed at the keyboard. If I knew why I'd fix it.

Data

Syntax: DATA file

Use file file as the source of data read with the READ command.
The file is assumed to have numerical data in columns separated by spaces,
or tabs. The range of lines specified by LINES is reset. If the file
can't be opened for read, you will be warned. The variable $data_file

is set to file.
See the READ command to see how to read the data.
You may need to quote the filename, e.g. DATA "/usr/file", which
you can do by using the macro da: da /usr/file.

Perverse people who wish to use filenames such as `12' or
`3.14' will find that they get syntax errors. If they must
persist DATA "3.14 " will work.

Define

Syntax: DEFINE name value
        LOCAL DEFINE name ...
        DEFINE name { value_list } [ \[ INTEGER, INTEGER \] ]
        DEFINE name < value_list > [ \[ INTEGER, INTEGER \] ]
        DEFINE name DELETE
        DEFINE name LOCAL
        DEFINE name ( expr )
        DEFINE name :
        DEFINE name |
        DEFINE name ? [ { prompt } ]
        DEFINE name ? [ < prompt > ]
        DEFINE name READ INTEGER
        DEFINE name READ INTEGER INTEGER2
        DEFINE name IMAGE
        IMAGE DEFINE name  value
        LIST DEFINE [ begin end ]

All of these varieties of DEFINE define variable name to have some
value, but
as variables can be defined in all sorts of ways there are a good
many possibilities. With the prefix LOCAL (which is allowed in front
of any of the DEFINE commands), the variable will be local to the
macro; (see section Local).

Name is a single word starting with a letter, and
containing only letters, digits, or `_', and may be a keyword.
Whenever SM comes across

$name, it is interpreted as a reference to variable name and
$name is replaced by its value.
(Note that some variables such as date are special as they always
contain an up-to-date value, for an example try echo $date sometime.
These variables are listed under DEFINE name |.)
You can also evaluate expressions with $(expr), for example

echo $(pi/2). The value can't be longer than about 80 characters,
except for the value_list form in which case its length can
be essentially infinite.

If you just want to know if a variable is defined, then $?name
is defined to have the value 1 if name is defined, and 0 otherwise.
Variables are not usually expanded within double quotes or {}, but if you use
the syntax $!name the variable will be expanded within double quotes;

$!!name will be expanded anywhere.

For the variants of DEFINE name value and DEFINE name value_list,
value is either a word or number, or a list.
The difference between using
{} and <> to delimit a list is that keywords can appear within {},
but variables are not usually expanded.

With the optional [ INTEGER, INTEGER ] clause (I apologise for the
notation in the manual; those [] are required) you can choose a
subrange, just as SUBSTR (see section Strings) can choose a part of a vector
element. For example,

  define s <"/abc/def">[1,-2]  echo $s

prints

  abc/d

Why is this useful? Because it provides a way of working around limits
on lengths of vector elements; otherwise this example is equivalent to

  define s (substr('/abc/def', 1,-2))  echo $s

DEFINE name DELETE, deletes a variable (see
also the macro undef to undefine variables).

DEFINE name LOCAL, which is only allowed within macros,
creates a variable which will only be visible from the current macro, and from
macros called by it (see section Local).
Such local variables are automatically destroyed when
leaving the macro within which they were created, and may not be explicitly
deleted. This is similar to the behaviour of numbered variables, except that
they really are local (i.e. they are only visible in the macro, and
not in its descendents; SM's LOCAL variables have nested scope rather than
being truly local).

An alternative is to prefix the DEFINE command itself with LOCAL;
DEFINE me LOCAL DEFINE me RHL is exactly equivalent to
LOCAL DEFINE me RHL.

A common use for DEFINE LOCAL is:

   define i local
   foreach i { sorbus aucuparia } { set $i local }

to protect a FOREACH (or DO) variable, and all local vectors, in one simple
line. It is because such loop variables are automatically destroyed that
attempts to delete local variables are not reported at VERBOSE levels of
1 or less.

DEFINE name ( expr ) defines a variable to have the value of
a (scalar) expression. When possible, it is more efficient to use
vectors to perform calculations on scalars, rather than putting them
into variables. It is also more efficient (and more obscure!) to use
numbered variables (macro arguments) than real named ones.
As a special dispensation, the expression can be an element of a
string-valued vector (elements of arithmetic vectors are allowed too
of course).

DEFINE name : defines the variable name from
the environment file. If name can't be found, and is capitalised,
SM will look for it in the environment (as a logical variable for VMS
users).

DEFINE name | is used to define a variable
from an internal SM variable such as expand or angle.
These variables can be listed with LIST DEFINE | (or by

LIST DEFINE if VERBOSE is two or more); a possibly incomplete
list is: angle, aspect, ctype, cwd,
date, exit_status, expand,

fx1, fx2, fy1, fy2,
gx1, gx2, gy1, gy2,
ltype, ltype_expand, lweight,

nx, ny, ptype,
sdepth, sheight, slength,
distance, theta, phi,

uxp, uyp, verbose,
xp, and yp. The
current plot limits are fx1 etc., (or gx1 etc. in device
coordinates), the size of the screen (in pixels, or dots, or whatever the
hardware uses) is nx * ny, the current position (in user
coordinates) is (uxp,uyp) ,
the current position (in plot
coordinates) is (xp,yp), exit_status is the return code from the
last ! command,

sdepth, sheight, and slength are the depth, height, and
length of the last string drawn to the screen,
distance, theta, and phi are the viewpoint for surface
plots (see section Viewpoint),
and the rest should be obvious. In the case of angle, expand,
and ptype, if you used a vector to set (e.g.) the expansion, the
value given will be that of its first element, and there's also
an extra value giving its dimension. This allows you to say things like

if(dimen(<$angle>) == 2) { echo You used a vector angle command }