@node Introduction, Description, Top, Top @chapter 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 @code{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 @copyright{}1987, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997 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 @emph{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 @code{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 @ref{Top, Tutorial, The SM Tutorial, tutorial, The SM Tutorial}. @node Description, Interpreter, Introduction, Top @chapter 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 @file{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. @chapter A simple plot @findex examples, basic Let us assume that you have a file called @code{mydata}, which looks like this: @example 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 @end example SM has a history mechanism, so first type @code{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 @code{dev tek4010}. If you don't know what to call your terminal, use the @code{LIST DEVICE} command, ask some local expert, look at the description of @code{DEVICE}, or (if desperate) read the manual (@pxref{Graphcap}). You'll know that you have succeeded if typing @code{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 @code{#} is a comment, you don't have to type this (or the @code{#}). @example 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 @end example @findex examples, parabola You should now have a graph. If you had wanted to plot the third column instead of the second you could have typed @code{LIMITS i iii POINTS i iii} instead. And of course you could plot @code{ii} against @code{iii} as a third alternative. You were not limited to only use squares as markers or solid lines to connect them - see @code{PTYPE} and @code{LTYPE} for details. If you want a logarithmic plot, SM makes that easy for you. You can take logs of a vector using the @code{LG} (or @code{LN}) commands on vectors; try it - @code{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 @code{TICKSIZE} command allows you to do this, and this is in fact the commonest use of it. Try @code{TICKSIZE 0 0 -1 0}, and then repeating the x-y plot. @findex logarithmic, getting nice axes What if you want hard copy of your hard-earned graph? There is a command (actually a macro) called @code{playback} which will repeat all the commands that you have typed. Type @code{ERASE} to clear the screen, then @code{HISTORY} to see the commands that you have issued. You probably don't want the @code{ERASE} command to be repeated, so type @code{DELETE} to delete it@footnote{There is a macro @code{era} defined as @code{DELETE HISTORY ERASE} that wouldn't have appeared on the list in the first place, similarly @code{lis} is like @code{HISTORY} but won't appear on the list of commands. As an alternative, you can use the macro @code{set_overload} to make lowercase @code{erase} the same as @code{DELETE HISTORY erase}, along with a number of other changes. This could be confusing for neophytes! See ``overloading''}. @findex hardcopy, example If there are any other mistakes use @code{DELETE m n} to delete the lines m to n containing them. Now type @code{playback} and your plot should reappear. But we wanted a hardcopy, so type @code{dev laser lqueue} (or whatever your friendly Guru recommends as a hardcopy device), then @code{playback}. This time, those plotting commands will appear on the laser printer not your terminal. To make them actually appear, type @code{hardcopy} or issue another @code{ dev} command. Be sure to say @code{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 @code{READ i 1}, you could have said @code{SET ii = i*i SET iii = i**3} and proceeded from there, or even skipped the file altogether by saying @code{set i = 1,8} instead of @code{READ}ing 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 @code{all} which @code{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@footnote{It is usually easier to use SM's editor to create macros, try @code{ed square} or read on.} @example MACRO square 2 @{ SET $1 = $2*$2 @} @end example @noindent So to calculate the vector @code{ii} we could now say @example square ii i @end example @noindent which is the same as saying @example SET ii = i*i @end example @noindent 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 @code{MACRO} command that you used to define @code{square}, so you can re-issue it. (Try exiting SM, then starting it up again and typing @code{HISTORY}, then @code{^nnn} where @code{nnn} is the number which is next to the desired command in the resulting list.) @findex macros, saving A brute force way is to say @code{SAVE filename} which will save almost all of your SM environment, to be recovered using the @code{RESTORE filename} command at some later time, or later SM session. Specifically, @code{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 @code{MACRO WRITE} command (see `Macros'). Then you can retrieve your macros with @code{MACRO READ}. You should note that your macro @code{all} will simply be a macro - to put it onto the history list say @code{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 @code{SAVE}, which will restore your playback buffer, while preparing files of useful macros is a use for @code{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 @code{MACRO READ}.