What is SM?

(SM) is an interactive ploting package for drawing graphs writen by Robert Lupton and Patricia
Monger. t has so!e capability to handle i!age data" but !ostly works with vectors. #e !ain
features of the package are$
one can generate a plot with a !ini!u! nu!ber of si!ple co!!ands"
one can view the plot on the screen and then with a si!ple set of co!!ands send the
sa!e plot to a hardcopy device"
one can build and save plot subroutines to be invoked with a single user%de&ned
co!!and"
the progra! keeps a history of plot co!!ands which can be edited and de&ned as a plot
subroutine" to be reused"
one can de&ne the data to be ploted fro! within the progra!" or read the! fro! an 'S(
&le.
How are data presented to SM?
SM is used as a ploting package" invoked a)er the data have been generated" to produce graphical
output as a second step. t can also be invoked fro! within a progra!" but at the sacri&ce of the
interactive capabilities that are its true strength. Plot vectors !ay be generated in several ways$
(a) *ne !ay read the values fro! an 'S( &le using the read co!!and (in row or colu!n
for!at" speci&ed colu!ns+rows are na!ed as vectors for ploting" while other colu!ns or
rows of infor!ation in the &le can be ignored and lines !ay be skipped in the &le). ,ata
can be nu!eric or alphabetic.
(b) *ne can de&ne vectors within SM using the set co!!and in several for!s$
de&ne a vector with a list of values
de&ne a vector in ter!s of arith!etic operations on previously%de&ned vectors
using built%in operators$ sin" cos" tan" acos" asin" atan" atan-" abs" int" lg" e.p" ln"
s/rt" concat" 00" 1 %" 0 and +
de&ne vectors with i!plied do%loops
de&ne vectors with rando! nu!bers" unifor! or gaussian
(c) one can rede&ne an e.isting vector" ele!ent by ele!ent" with a do loop
(d) one can create a set of values by &ting a spline function to previously de&ned values at
speci&ed inter!ediate points
(e) one can enter values with the graphics cursor on the screen
What are the steps in producing a basic plot?
#e steps to produce a graph" once data have been provided to SM are$ de&ne the plot device"
de&ne the data &le" read in data vectors" de&ne a.is li!its" draw a.es" plot the data (as points or as
a connected curve % type of line or of points can be selected)" label the a.es (various fonts
available). #ere are various other !ore elaborate co!!ands to enable logarith!ic a.es" labelling
curves" puting an , on the plot" reading positions fro! the plot with a cursor" geting statistics
on vectors (!ean" sig!a" kurtosis" linear regression coe2cients" 3ol!ogorov%S!irnov tests" etc)"
!anipulating -%d data and !uch !ore.
Handling 2-d data
SM has so!e capability to handle i!age data. ' few standard types of binary &les have been
de&ned which should" we hope" cover the !a4ority of cases. *nce one has read in the i!age" one
can contour it with the contour co!!and (&rst de&ning levels)" and one can take a slice through
it. #e newest release (-.5) also supports 6wire fra!e6 displays of i!age data" and greyscale.
Availability of SM
System Reuirements!
SM runs on 7ni. and 7ni.%variant syste!s (yes" including Linu.) and 8MS syste!s as well as on
,*S P(s" under 9indows (using :orland (11 v5)" and under *S+-. t also runs on Mac *S; but
not on previous versions of Mac*S ('+7; works" however). SM has drivers for Sunview" any for!
of ;<<" S=" various tek>?<. e!ulators" 8MS 7S" L@?5" !agen i!press" AMS /uic" BP Laser4et"
and Postscript laser printers (also color and encapsulated postscript)" raster devices" BP=L" RC=S
graphics" and several odd (and likely obsolete) graphics ter!inals. #e P( i!ple!entation uses
:orlandDs := drivers" so works for any devices supported by that library.
"ost!
SM is available for E5?? 7.S." E5FG (anadian to university depart!ents" or s!all colleges. '
university%wide site license is E<G?? 7.S." E<H?? (anadian. Prices for co!!ercial or govern!ent
agencies are EG?? 7.S. for a depart!ent" E-G?? 7.S. for an entire site.
Iou only buy it once % the license entitles you to unli!ited free upgrades. #e distribution
includes the source" docu!entation (Je; &les)" and per!ission to install the progra! on all the
!achines at your site.
Pay!ent is by check or !oney order in 7S dollars !ade payable to Patricia Monger" or by bank
transfer. #ere is a E5G additional charge to cover bank fees if you pay by bank transfer (unless
you are able to arrange through your bank that all fees will be covered by you)" or if the check
does not have the standard bank M(R encoding on it.
Restrictions!
SM is not for sale to groups who want to use it for weapons related research pro4ects for the
!ilitary agencies of any country.
#istribution!
SM is distributed by )p. f you absolutely !ust have a tape or Koppy we can probably arrange it.
"ontact!
f you have further /uestions" please send !ail to !ongerL!c!aster.ca.
Iou canDt beat SM
SM is a ploting progra!!e writen by Robert Lupton (MrhlLastro.princeton.eduN) and Patricia
Monger (M!ongerL!c!aster.caN)
SM is not freely distributableO for a brief description and details on how to order a copy see our
standard blurb.
Manuals!
#e SM !anuals are distributed with the distribution" in Je;info (which can be processed into
hardcopy (e.g. via postscript)" info" or BJML). RobertDs lastest BJML copies are$
SMDs Reference !anual (or you can get it by )p)
SMDs tutorial
Many thanks to :ohdan Pograf for this translation into :elorussian.
Release $otes
#ese release notes include changes that havenDt !ade it into an o2cial version. #e last o2cial
release was -.>.<.
%ug #atabase
#ereDs an SM bug databaseO youDll need to allow your browser to set at least so!e cookies (sorry)"
and login with any password that you feel like. #ere arenDt !any bugs in it" which either reKects
the stability of the code or the lack of interest in reporting the!.
Mailing &ist
#ereDs a (not very busy) SM !ailing listO to be added send !ail to Robert Lupton. 9hen he gets
his act together" thereDll be an archive available on this page.
'reuently As(ed )uestions
BereDs a very short Q'A listO suggestions for additions would be gratefully received.
*+ample ,lots
Bere are a few e.a!ples of SM plots" along with the co!!ands that generated the!. f you have
a favourite graph that youDd like to see here send Robert !ail.
Sine and (osine curves
<? ter!s of a s/uare waveDs Qourier series
Surface plot of a :essel Qunction

Star+C.ponential+Clliptical (lassi&cation (try s/uinting at this plot).
,ithered
!age of the =ala.y MG<
SM
*dition 2-.-/0 1or later if we didn2t update this page3
by Robert Lupton and Patricia Monger
4able of "ontents
ntroduction
,escription of SM
' si!ple plot
Qacilities within the (o!!and nterpreter
String 8ariables
(o!!and Bistory
(hanging 3ey%:indings
Jalking to the *perating Syste!
Macros
,* and Q*RC'(B loops" 9BLC loops" and Q state!ents
#e Belp (o!!and
Saving and Restoring a Session
8ectors and 'rith!etic
,rawing Labels and SMDs Je; C!ulation
'n ntroduction to Je;
'vailable Qonts
SMDs Je; (ontrol Se/uences
SMDs C.tensions to Je;
(aveats and (autions when using Je;
Bow to Stop the ,evice using its Qonts
*ld%style Labels
=eting Bardcopies of Plots
*verloading 3eywords
C.a!ples of 7seful Macros
More C.a!ples of Macros
9hat Rotes 9hat 9hen
=enerating SM interfaces fro! e.g. python
Python
Reserved 3eywords
=lossary of Jer!s used in this Manual
(o!!and Reference
'bort
'nd
'ngle
'propos
'spect
'rith!etic
'.is
:o.
:reak
(hdir
(onnect
(ontour
(type
(ursor
,ata
,e&ne
,elete
,evice
,ither
,o
,ot
,raw
Cdit
Cnviron!ent 8ariables
Crase
Crrorbar
C.pand
Q)
Qoreach
Qor!at
=rid
Belp
Bistogra!
Bistory
denti&cation
f
!age
3ey
Label
Levels
Li!its
Lines
List
Local
Location
Logical
Ltype
Lweight
Macro
Meta
Min!a.
@otation
*r
*verload
Page
Points
Print
Pro!pt
Ptype
Putlabel
Rit
Range
Read
Relocate
Restore
Return
Save
Set
Shade
Show
Sort
Spline
Strings
Surface
Jable
Jer!type
JicksiSe
7ser
8erbose
8ersion
8iewpoint
9hatis
9indow
9hile
9rite
;label
Ilabel
'ppendices
#e (o!!and nterpreter
Joken =eneration
Peculiarities of the =ra!!ar
#e Macro Processor
#e ,*" Q*RC'(B" and Q co!!ands
C.a!ples of Bow SM Parses nput
#e Stdgraph =raphics 3ernel
#e =raphcap Qile
StdgraphDs :inary Cncoder
C.a!ples of =raphcap Cntries
7sing (ursors with =raphcap
7sing (olours with =raphcap
Bow to Modify a =raphcap Cntry
9riting a @ew =raphcap Cntry
Support for Raster ,evices
(o!piling =raphcap
nde. to =raphcap (apabilities
(alling SM fro! Progra!!es
ntroduction to (allable SM
C.a!ple of (alling SM Qunctions
Qunction ,e&nitions$ <%,
Qunction ,e&nitions$ -%,
(alling the SM interactive Parser fro! Progra!!es
9hy do have to call sm_alpha " sm_graphics " sm_gflush " and
sm_redraw T
Bow to (hoose the @a!e for Qortran Subroutines
#e SM =ra!!ar
Jwo%,i!ensional =raphics
Qilecap
Reading and writing tables
Bow to read tables
Bow to write tables
Jer!cap %% ' Jer!inal ,atabase
@ew ,evices and @ew Machines
'dding @ew ,evices
Porting to @ew Machines
#e Syste! Macro Libraries
Jips for Mongo 7sers
,iUerences fro! Mongo
#e RC', *L, co!!and
#e co!patibility !acro
SMDs Qonts
7sing SM to write Vapanese
=eneral nde.
(o!!and nde.
5ntroduction
SM is still evolving slowly" and this docu!entation !ay not be true" helpful" or co!plete. n order
of increasing plausibility" infor!ation !ay be obtained fro! the BCLP co!!and" this docu!ent"
the authors" and the source code. RBL is prepared to guarantee that the e.ecutable code has not
been patched.
f you &nd bugs" (reasonable) features that you want" wrong docu!entation" or anything else that
inspires you please let us know. 't least under 7ni. the !acro gripe should be a convenient
way to send us !ail. Please also send us any clever !acros that you would like to share.
@e.t a disclai!er$ SM is copyright (()<HWF" <HWH" <HH?" <HH<" <HH-" <HH5" <HH>" <HHG" <HHX" <HHF"
<HHW" <HHH" -??? Robert Lupton and Patricia Monger. #is progra!!e is not public do!ain" e.cept
where speci&cally stated to the contrary" either in the code" or in the !anual. f you have a legally
ac/uired copy you !ay use it on any co!puter 6on the sa!e site6" but you !ay not give it away or
sell it. f you have a legal copy we will provide so!e support and allow you with as !any
upgrades as you provide tapes for (or wish to retrieve with ftp).
SM is provided Yas isD with no warranty" and we are not responsible for any losses resulting fro!
its use.
n addition to this !anual there is a tutorial introduction which you !ight &nd less inti!idating.
See section Y#e SM JutorialD in Te SM Tutorial.
#is should be uni!portant" but in case it isnDt you can sub!it SM bug reports (or re/uests for
new features) using the 7RL
http://www.astro.princeton.edu/cgi-bin/gnatsweb.plO you want to /uery on
category sm (and !aybe smdoc) fro! advanced queryO note that you can save this /uery"
set a book!ark" and so forth.
#escription of SM
SM is an interactive ploting progra!!e with a Ke.ible co!!and language. #e plot data !ay be
de&ned to SM in a nu!ber of ways. #ere is also a powerful !echanis! for de&ning and editing
plot `macros' (sets of SM plot co!!ands that are de&ned and invoked as plot
6subprogra!!es6).
#e features of SM are described fully in the ne.t few sections" but let us start with a description
of how to produce your &rst SM plot. :efore you start" notice that SM is case sensitive. 3eywords
!ay be typed in lower or uppercase (as we do in this !anual)" but we would reco!!end using
lowercase. t is in fact possible to change the !eanings of lowercase keywords" but this can be
confusing. f you are interested" see the section on 6overloading6. See YuppercaseD in the inde. if
you really want to use your shi) key.
A simple plot
Let us assu!e that you have a &le called mydata" which looks like this$
his is an e!ample file
" " "
# $ %
& ' #(
$ ") )$
* #* "#*
) &) #")
( $' &$&
% )$ *"#
SM has a history !echanis!" so &rst type +,-,, . ".... to tell SM to forget any co!!ands
that it has re!e!bered. #en choose a device to plot on. Iou do this with a co!!and like dev
te/$.".. f you donDt know what to call your ter!inal" use the -01 +,203, co!!and" ask
so!e local e.pert" look at the description of +,203," or (if desperate) read the !anual (see
section #e Stdgraph =raphics 3ernel). IouDll know that you have succeeded if typing 456 draws
a bo..
Iou should now have successfully chosen a graphics ter!inal. Jo actually plot so!ething" use the
following set of co!!ands. #e te.t a)er the 7 is a co!!ent" you donDt have to type this (or the
7).
+88 mydata 7 1pecify desired datafile
-09,1 & ".. 7 3hoose which lines to use
:,8+ i " 7 :ead column " into `i'
:,8+ ; ii # iii & < 7 :ead column # into `ii' and & into `iii'
-0=01 i ii 7 3hoose limits> based on i and ii
456 7 +raw the a!es
?@?, $ . 7 3hoose square point mar/ers
?5091 i ii 7 ?lot i against ii
3599,3 i ii 7 and connect the points
6-84,- his is i 7 -abel the 6-a!is
@-84,- his is ii 7 8nd the @
Iou should now have a graph. f you had wanted to plot the third colu!n instead of the second
you could have typed -0=01 i iii ?5091 i iii instead. 'nd of course you could plot
ii against iii as a third alternative. Iou were not li!ited to only use s/uares as !arkers or solid
lines to connect the! % see ?@?, and -@?, for details.
f you want a logarith!ic plot" SM !akes that easy for you. Iou can take logs of a vector using
the -A (or -9) co!!ands on vectorsO try it % 1, !B">". 1, yB!CC& set lyB-ADy)
-0=01 ! ly 359 ! ly bo!. Iou !ight have wanted the a.es to reKect the fact that you
had logged the y a.is. #e 03E10F, co!!and allows you to do this" and this is in fact the
co!!onest use of it. Jry 03E10F, . . -" ." and then repeating the .%y plot.
9hat if you want hard copy of your hard%earned graphT #ere is a co!!and (actually a !acro)
called playbac/ which will repeat all the co!!ands that you have typed. Jype ,:81, to clear
the screen" then G015:@ to see the co!!ands that you have issued. Iou probably donDt want
the ,:81, co!!and to be repeated" so type +,-,, to delete it(<).
f there are any other !istakes use +,-,, m n to delete the lines ! to n containing the!. @ow
type playbac/ and your plot should reappear. :ut we wanted a hardcopy" so type dev laser
lqueue (or whatever your friendly =uru reco!!ends as a hardcopy device)" then playbac/.
#is ti!e" those ploting co!!ands will appear on the laser printer not your ter!inal. Jo !ake
the! actually appear" type hardcopy or issue another dev co!!and. :e sure to say dev
te/$.". (or whatever device you chose) before you read any !ore of this docu!ent. t is
possible to edit the playback buUer" rather than si!ply deleting lines fro! within it. #e section
on Ye.a!plesD describes how to do this.
n fact" the sa!e plot could have been produced fro! a data &le which 4ust contained the &rst
colu!n. ')er saying :,8+ i "" you could have said 1, ii B iCi 1, iii B iCC&
and proceeded fro! there" or even skipped the &le altogether by saying set i B ">% instead
of :,8+ing it at all. Such possibilities" and a good deal !ore" are described in greater detail in the
rest of this !anual.
9hat we 4ust did was to de&ne a si!ple Y!acroD" in this case the special one called all which
playbac/ !anipulates. ' !ore e.plicit use of a !acro would be to de&ne a !acro to s/uare a
vector" that is to s/uare each ele!ent of a vector. Jo do this say(-)
=83:5 square # ; 1, H" B H#CH# <
So to calculate the vector ii we could now say
square ii i
which is the sa!e as saying
1, ii B iCi
So now that you have !et !acros" how do you save the!T #e si!plest and least reliable way is
to use SMDs history" and hope that the ne.t ti!e that you use SM it re!e!bers the =83:5
co!!and that you used to de&ne square" so you can re%issue it. (Jry e.iting SM" then starting it
up again and typing G015:@" then Innn where nnn is the nu!ber which is ne.t to the desired
co!!and in the resulting list.)
' brute force way is to say 182, filename which will save al!ost all of your SM
environ!ent" to be recovered using the :,15:, filename co!!and at so!e later ti!e" or
later SM session. Speci&cally" 182, will save all your !acros" variables" and vectors" along with
your history buUer. #is is a very convenient way in practice but it does !ean that you tend to
carry around lots of long%forgoten !acros" variables" and vectors.
'nother way is to write the !acros to a disk &le" using the =83:5 J:0, co!!and (see
YMacrosD). #en you can retrieve your !acros with =83:5 :,8+. Iou should note that your
!acro all will si!ply be a !acro % to put it onto the history list say +,-,, . "....
J:0, G015:@ all. (*f course" you could write a !acro to do this for you). Maybe saving
your playback buUer is so!ething beter done with 182," which will restore your playback
buUer" while preparing &les of useful !acros is a use for =83:5 :,8+. *nce the idea of !acros
gets into your blood" you can of course use an editor to create your own &les of !acros" to be read
with =83:5 :,8+.
'acilities within the "ommand 5nterpreter
#is is a guide to the use of SM variables" the !acro processor" the help co!!and" and the history
facilities. #e vector arith!etic and ploting facilities are described below. 8arious e.a!ples are
scatered throughout the te.t" to give so!e guidance on the use of SMDs capabilities.
Perhaps the !ost i!portant thing to know is how to escape fro! SM. f you have a pro!pt"
si!ply type KL0(5). f you are running so!e co!!and" try control-3 to get a pro!pt. Most
co!!ands will eventually return control to the keyboard following a control-3. n addition"
the parser is reset" and the input buUer cleared. So!eti!es control-3 leaves a Z on the buUer if
it thinks that itDll help get back to the pro!pt" which can generate an irrelevant synta. error.
*ccasionally it can still be confused %% try typing a few characters and !aybe a Z.
9hen you have interrupted SM with a control-3" a !acro called error_handler is
e.ecuted" if it is de&ned. #e one that we provide does things like seting the e.pansion back to <"
and reseting any window co!!ands that you !ight have issued" and then prints a !essage
handler... to tell you that itDs done its work. f you donDt like this" see Yprivate initialisationD in
the inde. for how to get your own handler loaded auto!atically.
f you !ake a !istake" and SM notices a synta. error" itDll print a !essage indicating where you
were and which !acro you were running. t is possible for the wrong !acro to be reported (if SM
has &nished reading the !acro before detecting the error)" in which case youDll be told that the
error occurred in a !acro that called the oUender. Seting 2,:451, (see section 8erbose) to 5 or
> provides a !ore direct way of &nding the true location of the error.
f you de&ne the variable tracebac/ to be < (!aybe with the line tracebac/ " in your
`.sm' &le) youDll get a traceback of what !acros were active when the error occurredO the sa!e
caveats about the wrong !acro being reported apply. n addition" the usual interrupt capabilities
of your operating syste! will work under SM" with a couple of /uirks.
7nder 7ni." in case of e!ergency" type control-M" and SM will ask you if you want to return
to the pro!pt" and if you donDt itDll oUer a core du!p" and then e.it. 's usual" typing control-F
(fro! the (%shell) will interrupt the process" which !ay be restarted later. 7nder 8MS"
control-F will interrupt SM" and return you to the co!!and interpreter (,(L). Jyping
35909L, will then allow you to restart SM(>).
f SM is running in a SP'9@ed sub%process" then control-F will re'JJ'(B you to its parent.
Jo continue SM" use the ,(L 'JJ'(B co!!and. 9e strongly suggest that you learn how to do
this" it !akes life !uch easier %% all you have to do is SP'9@ a process fro! ,(L and start SM
fro! there. ,o check with your 8MS syste! !anager to ensure that you have the right /uotas for
SP'9@ing (Process li!it !ust be at least 5" because SM will use one for itself and one for
hardcopies). 'n especially si!ple way to do all this is is to use the co!!and &le
`/ept_1=.com' in the !ain SM directory. tDll handle the spawning and ataching for you.
'nother fact to bear in !ind is that the characters I" H" and 7 are special" as I is used by the
history syste!" H introduces a variable" and 7 starts a co!!ent. #e special !eanings of all of
these characters e.cept [ can be turned oU by preceding the! with a \. Jo type a [" use the
/uote]ne.t character (initially control-K or CS(%/) to /uote the [O i.e. type ,13-q.(G) ' Mn is
interpreted as a carriage return" and a M 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. ' M preceding any other character
(e.cept a NO see ne.t paragraph) is si!ply a M. #is character is used to set font types in the
-84,- co!!ands" so it has no special !eaning to the co!!and interpreter" which si!pli&es the
entering of strings for -84,- co!!ands.
' further proble! is that sy!bols such as O" -" C" and / are used to separate words" which is
what you want for !athe!atics" but !aybe not what you had in !ind for &lena!es. Cnclosing a
word in double /uotes turns oU all special !eanings e.cept IO an e!bedded N !ay be escaped
with a M. Single /uotes are used /uite diUerentlyO enclosing a word in Dsingle /uotesD !akes it into
a string so '"#' is a two%character string and not an integer at all. #ere are ti!es when this is
i!portantO for e.a!ple ifDy BB 'yes') tests if the vector y is e/ual to the string YyesD"
whereas ifD'yes' BB 'yes') asks whether two identical strings are e/ual (they are). 9hen
you re!e!ber that can legally say set yesB'no' youDll appreciate the distinction.
#e characters ;< also perfor! /uoting" turning oU the special !eanings of all characters
(including single and double /uotes" but not I). #e diUerence between double /uotes and braces
is that the later have gra!!atical valueO they are part of the synta. that SM understands. n !ost
cases you can use angle brackets instead of curly ones if the gra!!ar needs the brackets but you
donDt want to turn oU e.pansions (see section String 8ariables).
SM is case%sensitive. t will accept keywords in either upper or lower case" but this is a special
dispensation on its part. f you insist on typing in uppercase say load uppercase when you
&rst start SM" or put the line uppercase " in your `.sm' &le. Qurther!ore keywords !ay not
be abbreviated. #is is not a great hardship as it is easy to de&ne !acros which !ake the
!ini!u! abbreviation a synony! for the full co!!and. Many such !acros are prede&ned for
you when you &rst use SMO see section #e Syste! Macro Libraries for details. n particular"
certain co!!on abbreviations of co!!ands have been prede&ned by the SM startup &le.
Cvery ti!e that SM is started" it looks for an environ!ent &le called `.sm' which consists of
na!es of variables and their values. Qro! ^ to the end of a line is taken to be a co!!ent. ' list of
directories to be searched in order for `.sm' &les is co!piled into SM" it usually consists of the
current directory" then your ho!e directory" and then so!e syste! directory. #e syste! default
can be over%ridden by de&ning the environ!ent variable 1=?8G which is a list of directories
separated by single spaces. Cach directory on the search path is tried in turn until a &le is found
containing the desired variable" which allows your choices to take preference over those of the
syste! ad!inistrator. n the list of directories . is taken to be the current directory" and P is your
ho!e directory unless you speci&ed a co!!and line -u name option" in which case it is taken to
be na!eDs ho!e directory instead. #is !eans that sm -u name will usually run SM as if you
were name. f name is null" then SM wonDt look for a `.sm' &le in anyones ho!e directory.
#e default path is e/uivalent to an 1=?8G of
e!port 1=?8GBN. P /u/sm/lib/N
(or an e/uivalent incantation). @ote that the directory /u/sm/lib/ ends in a / so that a
&lena!e can be directly appended (on a 8MS syste! it would probably end in a : or Q).
'n e.a!ple &le would be (the &lena!es are writen in 7ni.)
7 0'm a comment line
fonts //fonts.bin
graphcap //graphcap
help //help/
macro /usr/local/sm/macros/
name :obert 7 5r alternatively `+r._-upton'
#e fonts &le contains the SM fonts (in a binary for!)" the graphcap entry is used to de&ne
the &le used to describe graphics ter!inals (see section #e Stdgraph =raphics 3ernel)" help is
the directory used by the help co!!and" macro is the default directory where !acros reside" and
name is what SM will call you (you can put spaces into your na!e by using underscores" e.g.
=y_-ord will be referred to as =y -ord). #e &lena!es starting // instruct SM to search for a
&le of that na!e on the 1=?8G" so if 1=?8G is P:.:/usr/local/sm/ could have writen
macroDs value as //macros/. Iou can access entries in the environ!ent &le yourself" as
described in the section on variables. See the section section #e Syste! Macro Libraries to see
how entries in the `.sm' &le are used to inKuence the behaviour of SM" or consult your local
e.pert. Iou !ight want to borrow so!eones `.sm' &le when you &rst use SM" although you
should do &ne without one. Qor !ore detail" and further special entries" see section Cnviron!ent
8ariables. #e na!e of the `.sm' &le can be speci&ed on the co!!and line as 6-f name6 or
you can ask to use nameDs .s! &le with -u name. 8MS users should ensure that SM has been
installed as a foreign co!!and to take advantage of these capabilities.
SM then tries to read in any !acros in the &le `default' in the directory `macro' and
ate!pts to e.ecute the !acro startup if it e.ists. f -m filename appears on the co!!and
line" this is taken to be the na!e of another &le of !acros and these are read" and the epony!ous
!acro is e.ecuted (a)er any pre% or suf% &. has been re!oved. Qor instance if you start SM with
the co!!and sm -m /home/tst.m" it will &rst read the &le /home/tst.m" and then
ate!pt to e.ecute the !acro tst).(X)
'nything le) on the co!!and line is treated as if it had been typed at the pro!pt" for e.a!ple
sm restore vital.save will start by :,15:ing fro! the &le vital.save (see
:,15:, if you want to know what this !eans). #e -m option is not really a good way to
personalise SM. #e startup !acro discussed under Yuseful !acrosD" which is run every ti!e
that you start SM" looks for a directory macro# in your `.sm' &le" and if it is there reads a &le
`default' fro! it" and e.ecutes the !acro startup# which it e.pects to &nd there. *n
case%insensitive operating syste!s" such as 8MS" you !ay need to /uote the co!!and line to
prevent it being translated to upper case. SM then ate!pts to read a set of history co!!ands
fro! a &le in the current working directory" passes control to the input routine and issues a
pro!pt. #e &le is given by the entry hist_file in your `.sm' &le" and if it isnDt present then
no history will be re!e!bered.
Iou are then able to type co!!ands" as !any as will &t on one line(F)" and use the features
described below.
Iou can use a co!bination of these features to run SM in YbatchD !ode. f you had a history &le
that you 4ust wanted to run" then you could start SM" say playbac/" and /uit. Iou could have a
!acro called batch in batch.m that did 4ust that" and say sm -m batch.m to e.ecute it. n
fact" you donDt even need your own !acro as one is pre%de&ned for you so sm batch is
su2cient. Iou could write your own !acros along this lines to do !ore co!ple. tasks. ' !ore
convenient alternative (under uni.) would be sm -1 R history_file where the -1 is
e.plained in the ne.t paragraph.
Qor co!pleteness" we should !ention the other co!!and line Kags" -h" -l logfile" -n" -q"
-s" -1" -v7" and -2. #e -h prints a su!!ary of co!!and line options" if you specify a log&le
with -l everything that you type at the keyboard is copied into the log&le (e.cept editing
co!!ands). 9hen you start SM it usually runs a !acro startupO -n prevents this. #e -s (for
YstupidD" or YsilentD or YsuppressD) Kag disables the co!!and line editor (although the history list is
still saved" so co!!ands like playbac/ will work)" -q suppresses the initial YBelloD !essage"
and -1 is like -s but it also suppresses the pro!pt and stops SM fro! intercepting control-c.
Iou can get the sa!e eUect as -s fro! inside SM with the co!!and ,:=@?, none. f you
are reading fro! a &le or pipe SM behaves as if you had invoked it with the -1 Kag. #is is useful
if SM is being run fro! inside another progra!!e" via a pipe (8MS$ !ailbo.)" or on a very stupid
ter!inal. f you want to set a particular value of verbose" use -v for e.a!ple -v-& is e/uivalent
to the 2,:451, -& co!!and given interactively. f you want to know SMDs version string
without starting SM" you can use the -2 Kag.
String 6ariables
So!e SM users see! to be confused by variables and vectorsO if you are one of these" the section
on /uoting (see section 9hat Rotes 9hat 9hen) !ight help.
SM !aintains a set of variables which are de&ned with one of the state!ents
+,S09, name value
or
+,S09, name ; value_list <
or
+,S09, name D e!pression )
where name !ust consist of digits" leters and Y]D (but !ust not start with a digit)" and !ay be a
keyword.
2alue !ay be a word or a nu!ber. 2alue_list has no such restrictions and !ay contain
!any words. @ote that due to the presence of the _Z" variables are not e.panded (i.e. replaced by
their value) in value_list" whereas they are in value. n fact" the list can be deli!ited by RT
rather than ;<O see +,S09, for details.
#e e.pression in +,S09, variable D e!pr ) should be a scalarO if it is not" the &rst
ele!ent of the vector will be used and you will be warned" if 2,:451, (see section 8erbose) is
one or greater. So!eti!es you 4ust want to evaluate an e.pression and treat the answer as a
stringO in this case use the special vector for! HDe!pr) which is replaced by the value of the
e.pression %% for e.a!ple echo e is HDe!pD")). C.pressions are further discussed under
Y8ectors and 'rith!eticD.
#ere are a nu!ber of special variables whose value is always the current value of so!e internal
SM variable such as the current position or the point type. #e variable 6date6 is also special and
e.pands to give the current ti!e and date" %% try typing echo Hdate. Iou can freeSe these
variables at their current value by saying define name U (see below).
Cach ti!e SM reads Hname it replaces it by its value" considered as a character string. Qor
e.a!ple"
+,S09, hi hello
J:0, 189+8:+ Hhi
will print hello. #is e.pansion is done before even the lowest level of le. analysis" so if a
co!!and is ate!pting to read a value it is possible to give it the na!e of a SM variable. 'n
e.a!ple would be the 6-84,- co!!and" which writes a string as the .%a.is label of a graph"
+,S09, name 8elfred
6-84,- =y name is Hname
will invoke the 6-84,- co!!and" and write =y name is 8elfred below the .%a.is.
(ncidentally" +,S09, 8elfred 8ethelstan @-84,- HHname will write 8ethelstan
as the y%a.is label" which can be handy in !acros. #e use of the double EE indicates to SM to do a
double translation" as it &rst e.pands to H8elfred which then e.pands to 8ethelstan).
' variable can be deleted by +,S09, name +,-,, so for e.a!ple the !acro
=83:5 undef " ; +,S09, H" +,-,, <
invoked as
undef name
will unde&ne the variable name (see the section on !acros if you are confused).
#ere are also three special values" :" U" and V. #e co!!and define name : !eans Yget
the value of na!e fro! the environ!ent &leD. f this fails" and if the variable is all uppercase" SM
will then try to use the value of an environ!ent (8MS$ logical) variable of the sa!e na!e. 7sing
define name V !eans Yread the value of na!e fro! the keyboardD. Iou can specify a pro!pt
to be used" see +,S09, for details. #e for! with U has changed a litle with version -.<.<. #e
variables that you can use with U have not changed" but their usage has slightly. #ey are all
de&ned for you when SM starts and each is always correct" tracking the current value of the
corresponding internal variable. Qor e.a!ple" try echo Hangle angle $* echo Hangle.
f you now say define angle U" Hangle will cease to track the internal value and will
re!ain &.ed (the sa!e eUect can be achieved with define angle $*). 9hen you say
define angle delete it will once !ore track the internal value. Iour old code will continue
to work" but in !any cases it is possible to re!ove the e.plicit de&nition with U. #is special sort
of variable will not be 182,d" and will not show up if you list the currently de&ned variables. '
list of the U variables is given in the section on +,S09,.
So using the e.a!ple `.sm' environ!ent &le listed in the previous section of the !anual"
+,S09, name : will de&ne name to be :obert" +,S09, angle U will give the last value
set by the 89A-, co!!and" and +,S09, datafile V will ask you for the value of Ydata&leD"
which can be useful in !acros. Qor e.a!ple"
+,S09, noise V ; :ing bellV < 0SD'Hnoise' WB 'n') ; bell <
will e.ecute the !acro bell if you type anything but n in reply to the /uestion YRing bellTD.
9hen writing !acros" it is also so!eti!es useful to know if a variable has been de&ned. #e
variable HVname has the value < if name is de&ned" otherwise it is ?. Qor instance" there is a line
define term : ifDHVterm) ; termtype Hterm <
in the startup &le" to set a ter!type if present in the environ!ent &le.
#ere are also co!!ands to read the values of variables fro! data &les de&ned with the +88
co!!and.
+,S09, name :,8+ i
or
+,S09, name :,8+ i X
will set name to be the iDth line of the &le (or the 4Dth word of the iDth line). 'n e.a!ple is given in
the section on Yuseful !acrosD. Iou can read variables fro! the headers of binary &les (speci&ed
with the 0=8A, co!!and) using +,S09, name 0=8A," although this is only supported for a
li!ited class of file_typeDs (see section Jwo%,i!ensional =raphics).
'll currently de&ned variables !ay be listed with
-01 +,S09, Y begin end Q
where the optional begin and end de&ne the range of variables (alphabetically) to be listed. Iou
!ight prefer to use the !acro lsv which wonDt appear on your history list.
8ariables are usually not e.panded within double /uotes or _ Z. f for so!e reason you need to
force e.pansion within double /uotes" it can be done with HWname. #e !acro YloadD discussed
under useful !acros gives an e.a!ple of this !echanis!. f you need to e.pand a variable" with
no /uestions asked (and even within _Z)" use HWWname.
So!eti!es you !ay want to ter!inate a variable na!e where SM doesnDt want to" and this can be
done with a trick involving double /uotes. Say you are writing a !acro to &nd all the stars redder
than :%8 ` <.? in a set of data vectors" and you want to rena!e the! with a trailing 6]red6" so
star goes to star_red. So you write a foreach loop"
S5:,83G ! D L 4 2 : 0 Z E ) ; 1, H!_red B H! 0SD4-2 T")<
9ell" that wonDt work because SM thinks that you are referring to a previously de&ned variable
na!ed !_red" so it will co!plain that !_red is not de&ned. :ut if you write it as H!NN_red
the NN separate the ! fro! the _red until H! is e.panded" and then disappear" and all is well.
9hen a variable is read" SM skips over all whitespace before the de&nition" and this can cause
proble!s if you hit control-3 in the !iddle" as the rest of the co!!and will be thrown away.
f you ever hit a control-3" and canDt get a pro!pt" try typing any non%whitespace character.
8ariables are string%variables" and are not pri!arily designed for doing arith!etic (thatDs what
vectors are for). #is is a co!!on source of confusion so letDs consider so!e e.a!ples (at the risk
of anticipating so!e later sections of the !anual).
+,S09, a "#
de&nes a variable a which consists of the two characters Y<D and Y-D" and which can be used
anywhere %% for e.a!ple !label Ha. 9hat about vectorsT (onsider
1, !B".
which de&nes a single%ele!ent vector whose value is ten" ready to be used in e.pressions such as
1, yBHa O !C"#
@ote that the Ha is still 4ust the two characters Y<D and Y?D" but in this conte.t that is interpreted as
the nu!ber ten. So what does
+,S09, y HaO!C"#
doT 9ell" actually it results in a synta. error (the Y1D ends a word)" so try
+,S09, y RHaO!C"#T
#is de&nes the variable y as the string Y<?1.0<-D" it doesnDt evaluate the e.pression. Iou can
evaluate the e.pression if you want with
+,S09, y D HaO!C"# )
which de&nes y as the string Y<5?D. ncidently" you can so!eti!es get away without an e.plicit
variable with the synta. HDHaO!C"#) which also e.pands to the string Y<5?D.
#e fact that variables are si!ply strings can be used to build co!ple. co!!andsO consider for
e.a!ple the !acro
readem 7 read multiple lines columns with names in row "
:,8+ :5J names ".s
+,S09, rc RHDnamesYD.)Q) "T
+5 iB#>+0=,9Dnames) ;
+,S09, rc RHrc HDnamesYDHi - ")Q) HiT
<
-09,1 # .
:,8+ R Hrc T
which reads the na!es of a set of colu!ns fro! line <" builds a co!!and to read the data in the
variable rc" and then reads all the data in one co!!and. Iou could of course loop through
names reading each colu!n in turn" but this should be a good deal faster.
:y default variables are global" so if you have a variable Hi" and a !acro that you call also uses a
variable Hi" the !acro will change the value that you so carefully de&ned. Jo avoid this" it is
possible to force variables (and also vectors) to be local" using a co!!and like +,S09, i
-538-O in this case the variable Hi will so)ly and suddenly disappear when you leave the
current !acro (and therefore you cannot !ake variables local at the top!ost level" i.e. at the
co!!and pro!pt). n fact" such variables arenDt strictly local" they have whatDs called nested
scope" as they are visible fro! any !acros that you !ay call %% they si!ply do not propagate
backwards up the call stack. Iou are free to !ake a variable local in any (or all) !acros" thereDs no
restriction on how deep such local declarations !ay be nested.
"ommand History
t is o)en very useful to be able to repeat a co!!and" or perhaps correct a !istake in what you
have 4ust typed. 9ays of doing this are usually referred to as YhistoryD" and SM has two distinct
!echanis!s. *ne is very si!ilar to that of the 7ni. (%Shell" and the other allows you to edit
co!!ands using a synta. si!ilar to the popular editor Ye!acsD" or a generalisation of the ,(L
history under 8MS. f you are not fa!iliar with 7ni." e!acs" or 8MS donDt despairO a description
of the co!!ands and how to invoke the! follows in this docu!ent. :oth of these !echanis!s
are i!ple!ented by the routine which reads input lines. 's each line is sent to the parser" it is
copied onto a history list. #is list !ay be printed with G015:@" and the co!!ands !ay be
re%used by referring to the! by nu!ber" as Inn" or by a uni/ue abbreviation" as Iabbrev. n
addition" the last co!!and !ay be repeated by using II and the last word of the last co!!and
by IH.(W) #ese sy!bols are e.panded as soon as they are recognised (see e.a!ples" or
e.peri!ent)" and are then available for !odi&cation by the editor. So!eti!es a Istring will
retrieve a co!!and beginning string" but not the one that you want. 8ersion -.<.< no longer
supports the use of I84 to search for the ne.t%!ost%recent co!!and beginning string" but
you can use the search co!!ands (control-: and control-1) instead. So!e people really
donDt want I to be their history character" either because theyDre used to so!ething else (such
as a)" or because they want to type lots of real Is (e.g. you are using Je;%style strings)O if this
describes you" rebind the! %% see the ne.t section. f you are considering the history list as a sort
of progra!!e to be repeated you !ay think that G015:@ lists the co!!ands in the wrong
orderO if so use G015:@ -.
Qor e.a!ple" if type$
?:5=? [
echo 0 li/e 1=
G015:@
SM will set the pro!pt to be [" replace the !acro echo by its value J:0, 189+8:+ and
print
0 li/e 1=
and then
& G015:@
# echo 0 li/e 1=
" ?:5=? [
(#e actual nu!bers will be diUerent" depending on what other co!!ands you have e.ecuted"
and also because SM !ay have read a history &le. n that case thereDll be !any !ore co!!ands
on the list" but no !ater.) f then type
I# R3:T
(that is [- not control%-) the screen will look like
[ echo 0 li/e 1=
0 li/e 1=
as if had 4ust typed it in ([ is the pro!pt) . Jyping
II D@es> IH ) R3:T
will now result in SM printing (truthfully)
0 li/e 1= D@es> 1= )
t is possible to delete co!!ands fro! the history buUer with the +,-,, co!!and. f the
co!!and is given with Sero" one" or two argu!ents" then the speci&ed range is deleted (but their
nu!bers are not re%used). f no argu!ents are given" the last co!!and on the buUer is deleted"
and its nu!ber is released to be re%used. n other words" the co!!and +,-,, will delete &rst
itself" and then the previous co!!and fro! the history list. #e co!!and +,-,, G015:@
only re!oves itself fro! the history list" and several of the co!!on co!!ands are de&ned as
!acros which use it" for instance dev is de&ned as +,-,, G015:@ +,203,. #is !eans
that the co!!and will not appear on the history list" to confuse you when you do a playback. :ut
if you now innocently use dev in a !acro" that !acro wonDt appear on the list either. Still worse"
if you use dev twice in one !acro" the previous co!!and will be deleted as well which could be
/uite confusing. Iou can also delete lines of history using ,13-control-+ as described shortly.
#e nu!bering is consecutive" starting at Sero. Cach co!!and retains its nu!ber until you use a
G015:@ co!!and to list the re!e!bered co!!ands" in which case they are all renu!bered"
and it is these new nu!bers that are listed.
:y default only W? lines are re!e!bered" and as you continue typing earlier ones fall oU the list.
:ecause the history buUer is also used to co!pose co!ple. co!!ands" this li!it can be
aggravating. Iou !ay be able to defeat this by puting !any co!!ands on each line (you !ay
have to use Mn to ter!inate label co!!ands e.plicitly) or by writing !acros. 'lternatively you
can de&ne a longer history buUer when you start SM by including an entry history in your
environ!ent &le
which gives the nu!ber of co!!ands to be re!e!bered. f you set history to be . the history
list is !ade in&nitely long. ncidently" it is the total nu!ber of co!!ands that !aters" not the
range of history nu!bers present.
#is li!it on the nu!ber of history lines isnDt enforced while writing a !acro onto the history list
(using J:0, G015:@). Iou can use this fact to write a sneaky !acro that e.tends your
historyO type G,-? e!tend_history if you are interested.
So!e people see! to like their history editors to re!e!ber where they were" so that a)er they
retrieve and e.ecute a co!!and the ne.t control-? or will retrieve the co!!and one further
back on the history list (that is" if you have 4ust retrieved co!!and nu!ber <-5 and e.ecuted it as
co!!and nu!ber -5>" then control-? will get you co!!and nu!ber <->O you can e.ecute it
as co!!and nu!ber -5G). f this describes you" de&ne the variable
remember_history_line" which you can either do directly" or by puting a line
remember_history_line " in your `.sm' &le.
#e editor allows you to !odify co!!ands" either as you type the! or as you retrieve the! fro!
the history list. #e various editing co!!ands !ay be bound to keys of your choosing" but the
default bindings are given in this list of possible co!!ands$
control-8
=o to start of line.
control-4
=o back one character. (C/uivalent to ).
control-3
nterrupt (as usual).
control-+
,elete character under cursor.
control-,
=o to end of line.
control-S
=o forward one character. (C/uivalent to ).
control-G
dentical to control-V (,CL). ,elete character to le) of cursor.
control-0 D84)
nsert spaces up to the ne.t tab stop. :y default a tab is taken to be W characters wide" but
this !ay be changed by specifying tabsi\e in your `.sm' &le.
control-Z D-S)
C/uivalent to control-=.
control-E
,elete to end of line. #e deleted string is stored" and !ay be restored using control-@"
repeatedly if so desired.
control--
Redraw the current line.
control-= D3:)
Send line to be e.ecuted. So!e ter!inals see! to replace control-= with a linefeed
(control-Z)" thereby !aking it i!possible to !ake SM obey you. 9e therefore !ake
control-[ e/uivalent to control-= for e!ergency use. (#is is control%space on !any
ter!inals).
control-9
=et the ne.t co!!and on the history list" if it e.ists (see control-?). (C/uivalent to ).
control-5
C.ecute the previous co!!and on the history list. C/uivalent to
control-?control-,control-=.
control-?
=et the previous co!!and on the history list" if it e.ists (see control-9).(C/uivalent to ).
control-K
Rote ne.t characterO Jurn oU any special signi&cance to the editor. control-K is o)en
used by the ter!inal" so we have de&ned control-Y%/ (that is escape followed by /) as an
alternative.
control-:
Search backwards (reversed) for a stringO the opposite of control-1. #e YstringD can
actually be any regular e.pression (see the !anual entry for 8?:5?51). f you specify a
Sero%length string (i.e. si!ply hit carriage return) the previous search string will be reused.
control-1
Search forward for a stringO the opposite of control-:. control-1 is o)en used by the
ter!inal" so we have de&ned control-Y%s (that is escape followed by s) as an alternative.
control-
Joggle insert+overwrite. :y default" characters are inserted before the cursor. f overwrite is
set" they replace the character under the cursor. @ote that CS(%u will not correctly restore
words deleted with CS(%d in overwrite !ode.
control-L
,elete fro! the cursor to the start of the line.
control-2
=o forward G lines.
control-J
,elete the previous word. dentical to CS(%h
control-@
nsert the string !ost recently deleted with control-E a)er the cursor.
control-F
Return to the operating syste!" without killing SM. (7nder 8MS" if you are running SM in a
spawned subprocess control-F will atach you to ,(L. *therwise" SM returns you to
,(L.)
control-V D+,-)
C/uivalent to control-G.
,13-control-+
,elete this line and re!ove it fro! the history list. @ote that this is diUerent fro! 4ust
clearing a line with (e.g.) control-L" which only erases a copy of the line.
,13-R
=o to the &rst line of a !acro" or the oldest history co!!and.
,13-T
=o to the last line of a !acro" or the !ost recent history co!!and.
,13-g
=o to a given line of a !acro" or a given history co!!and. IouDll be pro!pted for the line
nu!ber" if you change your !ind you can get out with ,CL or control-G.
,13-q
Rote the ne.t character" turning oU any special signi&cance to the editor. dentical to
control-K.
,13-s
Search forward for a string. dentical to control-1.
,13-v
#e opposite of control-2" go back G lines.
,13-y
Like control-@" e.cept that it gets older deletions" cycling back through a collection of
(currently G) deleted lines.
So!e CS(%leter co!binations are available which operate upon co!plete words. ' word is
de&ned as a whitespace deli!ited string" so -.HHWeW is a perfectly good word. n addition" it is
possible to undelete words that have been deleted with an CS(%d or CS(%h.
,13-b
=o to the start of the previous word.
,13-d
,elete to the beginning of the ne.t word.
,13-f
=o to the beginning of the ne.t word.
,13-h
,elete back to the beginning of the current word. #e sa!e as control-J.
,13-u
Restore the last word deleted" puting it before the cursor. Qurther ,13-uDs will restore
!ore words. 9hen no !ore are available" the bell is rung.
'ny printing character is inserted before the cursor (unless overwrite has been set with
control- ). llegal characters ring the ter!inal bell. f you insert a non%printing character on a
line" the cursor !ay get confused.
f ever you are stuck at the co!!and interpreter" and you want to send a signal to the operating
syste! (e.g. a control-@ to ,(L)" but SM is catching the key and using it for its own purposes"
the easiest thing to do is to de&ne a !acro such as =83:5 aa ;aa< " and then run it. 9hile it
is running (i.e. until you type control-3) keys should have their usual functions.
"hanging 7ey-%indings
's !entioned above" it is possible to rede&ne the !eanings of keys to the history (and !acro)
editor. #e co!!and ,+0 /eyword /ey-sequence will !ake typing that se/uence of keys
correspond to the co!!and /eyword. Qor e.a!ple" to !ake control-: redraw the current
line" you could say ,+0 refresh control-:. #e keyword can be any in the list below" or
any single character. Cach character in the key%se/uence can be a single character" control-c"
or Mnnn where nnn is an octal nu!ber. 'lternatively" :,8+ ,+0 filename will read a &le
specifying the new bindings which has two lines of header" followed by pairs of /eyword
/ey-sequence. Lines starting with a ^ are co!!ents. 'n e.a!ple is the &le for 8MS users
given below.
' proble! can co!e up with !ultiple%key se/uences. !agine that you have bound so!e
function to control-6control-8" for e.a!ple
,+0 end_of_line I6I8
then what happens when you try itT SM sees the control-6 and uses its default binding"
e!it_editor" and then sees a control-8 and goes to the start of the line" which wasnDt the
desired eUect. #e solution is to tell SM that control-6 is not a legal key" in which case it will
either ring the ter!inal bell (if there are no key%se/uences starting with an control-6)" or wait
for the ne.t key. n short"
,+0 illegal I6
,+0 end_of_line I6I8
should work.
*n a so!ewhat si!ilar topic" the E,@ (see section 3ey) co!!and !ay be used to de&ne a key to
generate a string. See the end of the section on !acros for how this works.
'll the current key de&nitions !ay be listed using -01 ,+0" including the E,@ de&nitions.
#e na!es of operators" and their default bindings" are given in the following table$
control-8
start]of]line
control-4
previous]char
control-3
control-+
delete]char
control-,
end]of]line
control-S
ne.t]char
control-A
illegal
control-G> +,-
delete]previous]char
control-0
tab
control-Z
carriage]return
control-E
kill]to]end
control--
refresh
control-=> control-[
carriage]return
control-9
ne.t]line
control-5
insert]line]above
control-?
previous]line
control-K> ,13-q
/uote]ne.t
control-:
search]reverse
control-1
search]forward
control-
toggle]overwrite
control-L
delete]to]start
control-2
scroll]forward
control-J> ,13-h
delete]previous]word
control-6
e.it]editor
control-@
yank]buUer
control-F
atach]to]shell
,13-R
&rst]line
,13-T
last]line
M.&$
escape
,13-b
previous]word
,13-d
delete]ne.t]word
,13-f
ne.t]word
,13-g
goto]line
,13-u
undelete]word
,13-v
scroll]back
,13-y
yank]previous]buUer
,13-control-+
delete]fro!]history
I
history]char
' si!ple e.a!ple of a bindings &le for a hardened 8MS user !ight be
7 his is a set of +3--ish /ey maps for 1=
7 name /ey
toggle_overwrite I8
start_of_line IG
delete_previous_word IZ
yan/_buffer I:
search_reverse IYr
attach_to_shell I@
@ote that thatDs the two characters I and 8 not control%'. t could 4ust as well have been writen
M..". 9e need a new character for yan/_buffer now that control-@ is otherwise engaged"
and have chosen control-: (which !eans that canDt use control-: to search backwards"
so chose ,13-r for that). Iou should be warned that so!e ter!inal protocols !ap control-=
to control-Z" so this use of control-Z could render you unable to issue co!!ands. 's
!entioned above" in an e!ergency control-[ can be used instead of control-=.
9hen SM is started" or whenever the ,:=@?, co!!and is used to change ter!inals" the
arrow keys are bound to the co!!ands previous_line" e!t_line" previous_char" and
e!t_char. Qor ter!inals such as a Jelevideo%H<-" which uses characters such as control-E
for arrow !otion" these can supersede the previous !eanings (in this case /ill_to_end)O #e
only &. is to use the ,+0 or :,8+ ,+0 co!!and to get what you want" probably within a
!acro.
f you want to use ' as your history character instead of I you need to say edit
history_char ` edit I I. f you try to use a character special to SM such as a this wonDt
work (youDll get a synta. error) and youDll have to use the ne.t alternative" na!ely put the
co!!ands into a &le and say read edit filename" for e.a!ple$
7 3hange the history character
7 name /ey
history_char W
I I
:ecause this particular change is so co!!on" itDs possible to specify that ` be your history
character si!ply by including a line history_char ` in your `.sm' &le (or you can choose
your own character. (hoosing ? has the eUect of using the default" I).
SM needs to know so!ething about the ter!inal that you are using" so as to run the
history+!acro editor. #is is entirely separate fro! the proble! of describing the ter!inalDs
graphics. t will try to discover what sort of ter!inal youDre on by using the value of term fro!
your `.sm' &le" or failing that the value of the environ!ent variable ,:= (7ni.) or the logical
variable ,:= (8MS). ' term entry of selanar -#" is e/uivalent to a ,:=@?, selanar
-#" co!!and. Iou can also use the ,:=@?, co!!and directly. SM then uses the ter!inal
type speci&ed to look up its properties in the ter!cap database (see section Jer!cap %% '
Jer!inal ,atabase). Iou can also use ,:=@?, to specify the siSe of the screen" or to turn oU
SMDs idea of where the cursor is. *n so!e ter!inals" you can only send a cursor to an absolute
position and this is chosen to be the boto! of the screen. #is is not what you want for" e.g." a
8J->? as it will lead to your graph scrolling oU the screen. #e use of a negative screen siSe to
,:=@?, will disable this cursor !otion" but will also !ake editing lines slower. f a line of
your graph is being deleted when the SM pro!pt appears" you !ay need to use ,:=@?,
dumb or ,:=@?, none.
4al(ing to the 8perating System
'ny line fro! a to the newline is passed to your shell (,(L under 8MS" the :ourne shell under
uni.. f you set the variable 1G,-- in either your `.sm' &le or the environ!ent it will be used
insteadO the for!er takes priority).(H) Qor e.a!ple" Wls or Wdirectory will list the current
directory. #e return code fro! the co!!and is available in the variable He!it_status" on
uni. syste!s it will be ? for success" for weirder syste!s you should look in the syste! !anual
for the return value of the ( function system. He!it_status is one of the variables that can
be set with +,S09, e!it_status U.
t is also possible to change the directory that SM uses to look for data or !acro &les with the
3G+0: co!!and % for instance 3G+0: N../more_dataN(<?). f a directory na!e starts with
YbD" 3G+0: replaces the YbD with your ho!e directory. #is is the only place that YbD is treated
specially" for instance it is not interpreted by the +88 co!!and. :ecause directory na!es o)en
contain !athe!atical characters such as Y or /" it is wise to /uote the directory" or use the !acro
cd which /uotes it for you.
Macros
n SM" it is possible to de&ne sets of plot co!!ands as 6subprogra!!es6" which can be used 4ust
like a plot co!!and" to generate a standard plot. #ese plot macros allow variables (e.g. na!e of
the data &le" plot label or li!its" etc) to be supplied at e.ecution ti!e.
Iou can also bind co!!ands to keys to save typingO for e.a!ple usually bind YcursorD to the PQ<
key of !y ter!inal. Such keyboard !acros are discussed under E,@ and at the boto! of this
section.
#e !acro facility consists of co!!ands to de&ne !acros" delete the!" write the! to disk &les"
read the! fro! disk &les" delete all those !acros de&ned in a speci&ed disk &le and list all
currently de&ned !acros. n addition" the help co!!and applied to a !acro prints out its
de&nition. t is possible to pass up to H argu!ents to a !acro" referred to as E<" ... " EH" and in
addition E? gives the na!e of the !acro. 9hile !acro argu!ents are being read they are treated
as if they are in sets of _Z" e.cept that variables are e.panded. f you want to include a space in an
argu!ent" enclose it in /uotes. f the nu!ber of declared argu!ents is <? or !ore" the !acro is
treated as having a variable nu!ber of argu!ents. f it is <?? or !ore the last argu!ent e.tends to
the end of the line. Qor further discussion see the discussion of how !acros are used.
' !acro is de&ned by the state!ent
=83:5 name nargs ; body-of-macro <
or
=83:5 name nargs R body-of-macro T
where name !ay be up to W? characters" and !ust not be a keyword(<<)" and body-of-macro
is the state!ents within the !acro" and !ay be up to -??? characters long. Macros de&ned using
an editor on a &le !ay be up to <???? characters. f nargs" the nu!ber of argu!ents" is ? it !ay
be o!ited. Macros !ay also be created using the =83:5 ,+0 co!!and" which is discussed
below" and which is probably easier. Jo de&ne the !acro in a disk &le" the &le for!at !ust be$ the
na!e of the !acro starts in the frst colu!n" followed by a tab or spaces" followed by the nu!ber
of argu!ents" if greater than ?" followed by co!!ands" followed by co!!ents if any. #e ne.t
line and any necessary subse/uent lines contain the !acro de&nition (starting in a column other
than the frst one). 'ny nu!ber of !acros !ay appear in the sa!e &le" as long as the !acro na!e
is given in the &rst colu!n and the de&nition starts in so!e other colu!n. #e &rst two blanks or
tabs are deleted in continuation lines" but any further indentation will survive into the !acro
de&nition. Jabs will be replaced by spaces as the !acro is read. :y default a tab is taken to be W
characters wide" but this !ay be changed by specifying tabsi\e in your `.sm' &le.
9hen a !acro is invoked" by typing its na!e wherever a co!!and is valid" for e.a!ple at a
pro!pt" it &rst reads its argu!ents fro! the ter!inal (if they are not in the lookahead buUer" it
will pro!pt you for the!)" and de&nes the! as the variables E<" ..." EH" before e.ecuting the
co!!ands contained within the !acro. #e nu!ber of argu!ents !ust be declared correctly. 's
an alternative it is possible to declare that a !acro has a variable nu!ber of argu!ents by
declaring <? or !ore(<-). #e !acro will then e.pect between ? and the nu!ber declared !odulo
<? argu!ents" all on the sa!e line as the !acro itself. (i.e. the argu!ent list is ter!inated by a
newline" which !ay either be a YrealD one" or an \n). f the nu!ber of argu!ents is <?? or !ore it
is still reduced !odulo <?" but the last argu!ent is taken to be the rest of the line (which !ay
consist of !any words). #e !acro !ay &nd out if a particular argu!ent is provided by using HV
to see if the variable is de&ned. Qor e.a!ple the !acro chec/" in the for!at in which it would
appear in a &le"
chec/ "" ifDHV" BB ") ; echo 8rg " is H" <Mn
will echo its argu!ent" if it has one" and
split ".# ifDHV# BB .) ; +,S09, # NDnone)N <
echo H":H#:
if invoked as split word many arguments will print word:many arguments:. f you
add an e.plicit newline" split word manyMn arguments" youDll get word:many: and
then a co!plaint that arguments is not a !acro.
f you try to e.ecute a non%e.istent !acro" if it is de&ned SM will call a special !acro called
macro_error_handler. t has two argu!entsO the &rst is the string 95_S5L9+" and the
second is the na!e of your non%e.istent !acro. 9hen you start SM" the error handler is$
macro_error_handler # 77 handle errors associated with macros
ifDHVmissing_macro_continue) ;
echo H# is not a macro
:,L:9
<
ifD'H"' BB '95_S5L9+') ;
del"
define & NH# is not a macro] abortingN
< else ;
define & NLn/nown macro error for H#: H"N
<
L1,: 845: H&
which causes an i!!ediate synta. error (the L1,: 845:)" and re!ove the errant co!!and
fro! the history list (the del"). Iou can turn this oU by de&ning the variable
Hmissing_macro_continue" which you can do in your `.sm' &leO this was the default in
SM versions -.<.? and earlier" and is what you get if the !acro macro_error_handler isnDt
de&ned.
7nfortunately we can get into trouble with 0SDs at the end of !acros" for !uch the sa!e reason
that :,L:9 can get into trouble (see section #e (o!!and nterpreter). #e sy!pto!s are that
a !acro either gets the argu!ents that were passed to the !acro that called it" or co!plains that
it canDt handle nu!bered variables at all because it isnDt in a !acro at all. Jo avoid this" there is an
e.plicit \n at the end of the !acro chec/. t is possible to rede&ne the values of argu!ents (it
wonDt aUect the values you originally speci&ed" argu!ents are passed by value)" or to +,S09,
values for argu!ents that you didnDt declare. #e later case allows you to have te!porary
variables" local in scope to the !acro. 'n e.a!ple is the rel !acro" which is de&ned as
rel # +,S09, " DH") +,S09, # DH#) :,-538, H" H#
which allows you to specify e.pressions to the relocate co!!and. Qor !ore e.a!ples see the
Yuseful !acrosD section.
@ewlines are allowed within !acros" and as usual any te.t fro! a 7 to the ne.t newline is taken
to be a co!!ent. f a 7 is needed within a !acro" escape the 7 with a M or enclose it in double
/uotes. f a !acro starts with a co!!ent the co!!ent will not aUect the !acroDs speed of
e.ecution. Macros starting with 77 are treated specially by 182, (they are not saved) and =83:5
-01 (they are not listed if 2,:451, is ?).
f the !acro co!!and is given as
=83:5 name ; +,-,, <
or
=83:5 name +,-,,
the !acro will be deleted (you can also delete a !acro fro! the !acro editor by specifying a
negative nu!ber of argu!ents). f the na!e is already de&ned" it will be silently rede&ned.
Macros !ay be nested freely" and even called recursively. Qor e.a!ple" the de&nition
=83:5 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-3.) #e de&nition
=83:5 \\ ; \\ \\ 7 comment: not recommended <
is also legal" but in this case if you e.ecute it SM will &ll its call and !acro stacks and co!plain
when it grabs !ore space. 's before" it will think about it forever. More useful e.a!ples of
recursive !acros are compatible (see section Jips for Mongo 7sers)" which starts
0SDHV" BB .) ; compatible " :,L:9 < ...
providing a default value for its argu!ent" and repeat which is discussed under +5.
Jo &nd how a particular !acro is de&ned" type G,-? macroname. Qor a listing of the &rst line
of all currently de&ned !acros" type
-01 =83:5
or
-01 =83:5 ! y
#e optional ! and y are the alphabetical (actually asciial ) range of !acro na!es to list. 's
!entioned above" if 2,:451, is ?" !acros starting with 77 are not listed by this co!!and. #ere
is a !acro ls de&ned as +,-,, G015:@ -01 =83:5 which will list !acros without
appearing on the history list. (*r you could overload listO see under overload in the inde.).
' related co!!and is 8?:5?51 pattern which lists all !acros and help &les(<5) whose
na!es or initial co!!ents contain the pattern" for e.a!ple
8?:5?51 histogram
would list bar_hist and get_hist as well as the abbreviations hi and hist. f you wanted
to &nd all !acros starting with a single co!!ent character which !entioned histogram you
could say
8?:5?51 NI7YI7Q .ChistogramN
where the double /uotes prevent the 7Ds being interpreted as co!!ent characters.
8?:5?51 IYa-\Q
will list all !acros beginning with lowercase leters %% this is si!ilar to =83:5 -01 a \" but
pays no atention to the value of 2,:451,.
t is also possible to read !acros in fro! disk" and in fact when SM is started" it tries to read the
&le `default' in the directory speci&ed by macro in the environ!ent &le `.sm'. #e
co!!and to read a &le of !acros is
=83:5 :,8+ filename
'ny line with a ^ in the &rst colu!n is treated as a co!!ent" and is echoed to the ter!inal if
2,:451, is greater than Sero. 'll the currently de&ned !acros !ay be writen to a &le with the
co!!and
=83:5 J:0, filename
f the &le e.ists" it will be overwriten (under 8MS" a new version of the &le will be writen).
Macros are writen out in alphabetical order.
#e co!!and
=83:5 J:0, macroname filename
writes the !acro macroname to the &le filename. #is co!!and re!e!bers which &le it last
wrote a !acro to" and if the current &lena!e is the sa!e then it appends the !acro to the end of
the &le" otherwise it overwrites it (or creates a new version under 8MS) unless the filename is
preceded by a O" in which case the !acros will always be appended. #is allows a set of related
!acros to be writen to a &le.
=83:5 +,-,, filename
unde&ned all !acros which are de&ned in filename. #is allows a &le of !acros to be read in"
used and forgoten again. #e diUerence between this co!!and and =83:5 macroname
+,-,, should be noted. #e 182, co!!and is probably a beter way of saving all current
!acros. #e for!at of !acros on disk is name nargs te!t" where nargs !ay be o!ited if it
is ?. (ontinuation lines start with a space or tab. See the &les in the directory speci&ed by macro
in your `.sm' &le for e.a!ples.
t is possible to de&ne !acros fro! the history list. #e co!!and
=83:5 name i X
de&nes a !acro name to be lines i to X inclusive of the history list" as seen using G015:@. #e
opposite of this co!!and" which places a !acro upon the history list" is J:0, G015:@
name. C.a!ples of these co!!ands are the !acros playbac/ and edit_hist given in the
section Y' Si!ple PlotD. #is way of de&ning !acros can be convenient if you have created a
useful set of co!!ands on the history buUer" and now want to save it in a !acro and go on to
other things. Cditing the playback buUer" and then changing its na!e to so!ething else (see ne.t
paragraph) is a convenient way of saving it that i!plicitly uses this co!!and.
Macros !ay be edited" using essentially the sa!e keys as described above for the history editor.
#e co!!and =83:5 ,+0 name starts up the editor" which works on one line at a ti!e.(<>)
#e Seroth line has the for!at
.T =acro name : 9umber of arguments: n
where name is the na!e of the !acro" and n is the nu!ber of argu!ents to the !acro. f this line
is changed" e.cept to change name or n" any changes !ade to the !acro will be ignored (note
that the space a)er name is re/uired). #is can be useful if you decide that you didnDt want to
!ake those changes a)er all. (hanging name or n has the obvious eUect" e.cept that if n is
negative the !acro is deleted when you e.it the editor. 'n e!pty !acro is also deleted when you
leave the editor (i.e. one with no characters in it" not even a space). #e &rst line that you are
presented with is the &rst line in the !acro rather than this special one. 7se control-9 (or ) to
get the ne.t line" control-? (or ) to get the previous line. (arriage return (control-=) inserts
a new line before the cursor" breaking the line in the process" while control-5 inserts a new
line before the current line. Jo save the changes and return to the co!!and interpreter use
control-6. 'll other keys have the sa!e !eaning as for the history editor (e.g. control-8 to
go to the beginning of a line). @ote that control-E and control-@ can be used to copy lines"
and that the bindings can be changed with ,+0 or :,8+ ,+0.
t wouldnDt be hard to write a !acro that wrote out a !acro to a &le" invoked your favourite te.t
editor" then read the new de&nition back inO see the !acro emacs_all for ideas.
t is so!eti!es convenient to de&ne a key to be e/uivalent to typing so!e string" such as
playbac/ or cursor. #is can be done with the E,@ co!!and" whose synta. is E,@ /ey
string. f you 4ust type E,@ R3:T youDll be pro!pted for the key and string. n this case you
are not using the history editor to read the key" and you can si!ply hit the desired key followed
by a space and the desired string" ter!inated by a carriage return. f you put E,@" /ey and
string on one line youDll probably have to /uote the /ey with control-K or CS(%/" or write
the escape se/uences out in the way used by ,+0. f this sounds confusing" here is an e.a!ple.
Jype E,@R3:T" then hit the PQ< key on your ter!inal" type a space" and type Necho Gello
JorldM9N. @ow 4ust hit the PQ< key and see what happens. (#e closing \@ !eant Yand put a
newline at the endD). #ese keyboard !acros are not generally ter!inal independent" but they can
be convenient. ,e&nitions for the YPQD keys on your keyboard can be !ade in a
ter!inal%independent way by specifying the /ey as pfn or ?Sn where n is <" -" 5" or >. f you
always use the sa!e ter!inal you !ight want to put so!e E,@ de&nitions in your private startup
&le (see the discussion of startup# in the section on useful !acros). #e current E,@
de&nitions are listed with the -01 ,+0 co!!and" along with the other key bindings.
#8 and '8R*A"H loops9 WH5&* loops9 and
5' statements
Related to the !acro facility are the +5" S5:,83G" and JG0-, co!!ands. 0S is included here as
a Kow%of%control keyword.
#e synta. for a +5 loop is
+5 variable B e!pr" > e!pr# Y > e!pr& Q ; command_list <
where the third e.pression is optional" defaulting to <. #e value of variable (Hvariable) is in
turn set to e!pr"" e!pr"Oe!p&" ..." e!pr#" and the co!!ands in command_list e.ecuted.
(hanging the value of Hvariable within the co!!and list has no eUect upon the loop. ,o
loops !ay be nested" but the na!e of the variable in each such loop !ust be distinct. ' trivial
e.a!ple would be
+5 val B "#&> "#&O".> # ; J:0, 189+8:+ Hval <
while a !ore interesting e.a!ple would be the !acro square discussed in the section on
e.a!ples.
Qor loops within !acros" itDs o)en a good idea to !ake the loop variable local$ ,CQ@C val
L*('L ,* val ... (see section ,e&ne).
:ecause the body of the loop !ust be scanned (and parsed) repeatedly" loops with !any circuits
are rather slow. f at all possible you should try to use vector operations rather than +5 loops. Qor
e.a!ple the loop
+5 iB.>+0=,9D!)-" ;
0SD!YHiQ TB .) ;
1, !YHiQB1K:D!YHiQ)
< ,-1, ;
1, !YHiQB.
<
<
is beter writen as
1, !BD! TB .) V 1K:D!) : .
where the ternary operator V: is discussed in the section on vectors (see section 8ectors and
'rith!etic). f you only wanted the ele!ents with ! TB ." youDd have said
1, !B1K:D!) ifD! TB .)
<
's an alternative to ,* loops" SM also has a general looping co!!and" a while loop" for
e.a!ple
set iB.
while ;i R ".< ;
commands
set iBiO"
<
is e/uivalent to a ,* loop. n addition to being !ore Ke.ible" 9BLC loops !ay also be
interrupted with the :RC'3 co!!and" so the previous e.a!ple could have been writen (using
variables instead of vectors)
define i .
while;"< ;
echo Gi Hi
define i DHiO")
ifDHi BB ".) ; brea/ <
<
Qoreach loops are si!ilar to do loops" with synta.
S5:,83G variable D list ) ; command_list <
"
S5:,83G variable ; list < ; command_list <
" or
S5:,83G variable vector ; command_list <
where the list !ay consist of a nu!ber of words or nu!bers. a vector. Cach ele!ent in the list (or
of the vector) is in turn de&ned to be the value of Hvariable" and then the co!!ands in
command_list are e.ecuted" so that for e.a!ple the co!!ands$
S5:,83G i D one # three ) ; J:0, 189+8:+ Hi <
1, str B ;one # three<
S5:,83G i str ; J:0, 189+8:+ Hi <
will print out$
one
#
three
twice. Qoreach loops !ay be nested" but again the variables !ust be distinct. Iou can deli!it the
list with ;< so that it can include keywords (and other things that you want treated as strings
such as .." or Hdate)" but even then you canDt have the word delete in the list of a foreach.
Sorry. tDs o)en helpful to !ake the foreach variable L*('L (see section Set) inside !acros" e.g.
+,S09, var -538- S5:,83G var ...
f state!ents look si!ilar" with synta.
0S D e!pr ) ; list < ,-1, ; list# <
where the ,-1, clause is optional" but if it is o!ited the closing Z must be followed by a newline
(or e.plicit \n) (see section #e (o!!and nterpreter).
f the (scalar) e.pression is true (i.e. non%Sero)" then the co!!ands list are e.ecuted" otherwise
list# is" if present. t is also possible to use 0S state!ents directly in ploting co!!ands" for
e.a!ple ?5091 ! y 0SD\ T "/!).
Iou can use logical operators within the e!pr (see section f). @ote that ^^ and UU do
notYshort%circuitDO that is" in the e.pression e!pr" ^^ e!pr# both e!pr" and e!pr# are
evaluated. n a scalar conte.t (e.g. in an Q state!ent)" the operators 89+ and 5: are available
instead" and they do only evaluate the right hand side if itDs value is re/uired.
t is possible to write general loops in SM by using of tail%recursive !acros. (<G) #e si!plest
e.a!ple would be
macro aa ;echo hello> worldMn 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-3. #e absence of a space before the closing brace is very
i!portant" as it allows SM to discard the !acro before calling it again" which !eans that it wonDt
&ll up its call stack and start co!plaining. ' !ore interesting e.a!ple is the !acro repeat
which repeats a given !acro while the given condition is true. Qor e.a!ple" if you say
macro aa ; set iBiO" calc i <
set iB. repeat aa while i R ".
it will print the integers fro! ? to H. 9ith a few checks" bells" and whistles the !acro looks like$
repeat ".& 7 :epeat a macro `name' while the condition is true
7 synta!: repeat name while condition
7 ,!ample: set iB. repeat body while i R ".
ifD'H#' WB 'while') ;
echo 1ynta!: H. macro while condition
return
<
ifDintDDwhatisDH")-$CintDwhatisDH")/$))/#) BB .) ;
echo H" is not a macro
return
<
macro _H" ;
ifDDHWW&) BB .) ; return <
HWW"
_HWW"<
_H"
macro _H" delete
and is one of SMDs default !acros (type 6help repeat6 if you donDt believe !e).
4he Help "ommand
#ere is an online help co!!and. Jyping G,-? R3:T or G,-? G,-? gives a list of the help
!enu" or G,-? /eyword gives help with that keyword. #e help !enu consists of any &les in
the directory speci&ed by the entry help in the environ!ent &le" so for e.a!ple G,-? data
types the &le data in that directory. Qor all cases e.cept G,-? help" the &le is &ltered through
a version of the 7ni. utility `more' which pages the &le. 9hen `more' oUers you a `...'
pro!pt" type V to see your options. #e sa!e &lter is used by e.g. -01 =83:5 . f the
co!!and is G,-? word" a)er G,-? tries to print the &le word" it looks to see if word is a
!acro" and if so prints its de&nition. f word is a variable" its value is then printed" and if word is
also a vector G,-? prints the di!ension" followed by the help string associated with the vector
vector_name (see section on vectors).
#e 8?:5?51 co!!and is also useful when you need help. 8?:5?51 string scans all the
help &les (if your operating syste! allows SM to do such things) and !acro headers looking for
the string. #e string !ay actually be a patern (see the description of 8?:5?51 for details). f
2,:451, (see section 8erbose) is Sero only the lines fro! the help &les !atching the patern are
printedO if it is larger you are given a couple of lines of conte.t on each side.
t is worth re!e!bering that the inde. to this !anual has an entry under weird" wherein are
listed all sorts of strange happenings" with e.planations and suggestions for workarounds.
Saving and Restoring a Session
f for so!e reason you want to stop a SM session for later resu!ption" and si!ply suspending the
process" Ycontrol-FD" is not su2cient" (for instance the !achine is going down)" then the 182,
co!!and will write a &le containing all your currently de&ned !acros" variables" and vectors"
along with your current history buUer as the !acro all. Iou will be pro!pted before each class
of ob4ects is saved" or you can put the answers on the co!!and line. #e &le is ascii" and can be
edited if you so desire. #e &lena!e defaults to `sm.dmp' if not speci&ed" or to the value of
save_file fro! your `.sm' &le. f so!e bug has crawled unbeknownst to us into SM" and
results in so!e sort of panic (such as a seg!entation violation)" a save &le called `panic.dmp'
is writen to your te!porary directory" no /uestions asked.
Jo restart" :,15:, filename will read the! all back" using the sa!e default &le as for 182,
if no &lena!e is speci&ed" and replace the current history buUer with the value of all fro! the
save&le. *f course" you could write a !acro to preserve the current buUer (see the de&nition of
edit_all for hints). f the &le wasnDt writen by 182, it is assu!ed to be a SM history &le" one
of those writen when you /uit SM" and each line is assu!ed to be a co!!and and writen to the
end of the history buUer. #is is generally useful when you started SM in the wrong directory. t
wouldnDt be hard to write a !acro to use :,15:, to read a history &le into a !acro.
*ne proble! with 182, is that it saves lots of !acros" including so!e of the syste! ones.
Speci&cally" all !acros are saved e.cept those beginning with 6^^6. #is can be avoided with the
=83:5 +,-,, filename co!!and" e.g. =83:5 +,-,, utils 182, " " " =83:5
:,8+ utils. #e !acro sav discussed under Yuseful !acrosD will do this for you" and indeed
not 182, any !acros that have been read with the load !acro. #is is probably the best way to
use the 182, co!!and. n addition" sav also decides to save variables and !acros" only
pro!pting you about saving vectors. sav is a good candidate for overloading (as save)" and
indeed is one of the !acros rede&ned by the set_overload co!!and.
6ectors and Arithmetic
#e basic unit of data in SM is the `vector'" a na!ed set of one or !ore nu!bers or strings.
#ere is no li!it to the nu!ber of vectors that !ay be de&ned. SM allows the user to read vectors
fro! &les or de&ne the! fro! the keyboard" to plot the! and to perfor! arith!etic operations
upon the!. SMDs string%valued vectors are less generally useful" but can be used for such purposes
as labelling points on a graph.
Jo read a vector vec fro! a colu!n of nu!bers in a &le" where the &lena!e has been speci&ed
using +88 and" possibly" the range of lines in the &le to be used has been speci&ed using the
-09,1 co!!and" use :,8+ vec nn where nn is the colu!n nu!ber" or :,8+ ; vec" n"
vec# n# ... < to read !any vectors. t is also possible to read a row" using :,8+ :5J vec
nn" where nn is the row nu!ber in the &le. See :,8+ for how to read a string%valued vector.
nstead of using si!ple colu!n%oriented input it is possible to specify a for!at like those used by
(Ds scanf functions (Qortran for!ats are not supported)O if you provide your own for!at string
you can only read nu!bers. Qor e.a!ple" if your data &le has lines like
":"#:&. -$*:&.:""
you could read it with read '_d:_d:_d _f:_f:_f' ; hr min sec deg dmin dsec
<.
' vector !ay also be de&ned as 1, vec B !">!#>d! to take on the values
!">!"Od!>...>!#" where d! defaults to < if o!ited. f a scalar is encountered where a vector
is e.pected" it is pro!oted to be a vector of the appropriate di!ensionO all other di!ension
!is!atches are errors. C.a!ple$
1, value B *
1, ! B .> *.> #
1, y B !
1, y B !C. O value
1, yY.Q B #Cpi
1, y B value
1, !B.>">." 1, yB0=8A,D!>".*)
1, sBstr
1, sB'str'
1, sY.QB".#&
1, !B".#&
1, sB!
1, sB1:09AD!)
will de&ne a scalar" value" with a value of G" then de&ne a vector" !" with -X ele!ents" valued ?"
-" >" X"..." G?" then de&ne another vector" y with siSe -X and the sa!e values as !" set all -X
ele!ents of y to have the value G" set the &rst ele!ent of y to be - pi" set y to be a vector with one
ele!ent with value *" and &nally set y to be a vector with the values taken fro! a horiSontal
cross%section fro! ? to < through the current i!age. 7nless a vector str is de&ned 1, sBstr
is an errorO to !ake s a string%valued vector use 1, sB'str'. 1, sY.QB".#& !akes
sY.Q have the value N".#&N (a string)" as s is now a pre%e.isting string vector. 'n arith!etic
vector ! is then de&ned" and s is rede&ned as an arith!etic vector too %% you !ust be careful
when dealing with string vectorsa Qinally" we e.plicitly convert an arith!etic vector to a
string%valued one with the 1:09A operator. #is is a so!ewhat contrived e.a!ple" designed
!ainly to illustrate the convenience of the 1, co!!and. #e ability to set particular ele!ents is
!ostly used in !acros such as smirnov# which calculates the 3ol!ogorov%S!irnov statistic
fro! a pair of vectors.
f you donDt have !any data points" rather than type the! into a &le" and use :,8+ vec nn to
de&ne a vector" you can use the co!!and
1, vec B ; list <
Qor e.a!ple
1, r B .>".
is e/uivalent to
1, r B ; . " # & $ * ) % ' ". <
n fact" ; list < is an e.pression" so 1, vec B #C;" & "< is also legal. f the &rst
ele!ent of a list is a word" the vector is taken to be string%valued$ 1, sB; Jilliam
Jilliam Genry 1teven < de&nes a >%ele!ent string vector" or you can use a string in
/uotes$ 1, sBR'"' # & $T (if you used 1, sB;'"' # & $< the &rst ele!ent would be
'"' rather than "). *nce a vector is de&ned" you can write it to a &le for later study using the
?:09 co!!and.
' scalar !ay be an integer" a Koating point nu!ber" a scalar e.pression" +0=,9Dvector)" or
J5:+Ye!prQ. #e last two are the di!ension of a vector" and an ele!ent of the vector with
e!pr a scalar subscript. ote that subscripts start at ! and that [ ] `not' () are used to
subscript variables. #e e.pression J5:+Ye!prQ is in fact allowed even if e!pr is not a scalar" in
which case the result is a vector with the sa!e di!ension as e!pr" and with the values taken
fro! J5:+ in the obvious way.
*nce vectors are de&ned" they !ay be co!bined into e.pressions using the operators O" -" C" /"
CC" 35938 and the functions 351D)> 109D)> 89D)> 8351D)> 8109D)> 889D)>
889#D)> 841D)> +0=,9D)> 09D)> -AD)> ,6?D)> -9D)> 1K:D)>
1:09AD)> 1:-,9D)" and 1L=D). #e !eaning of !ost of these is obvious" 889# is like
889 but takes two argu!ents" ! and y and returns an angle in the proper sector. +0=,9 returns
the nu!ber of ele!ents in a vector" 1L= gives the su! of all the ele!ents" 35938 concatenates
two vectors" 09 gives the integral part of a vector" 1:09A converts a nu!ber to a string" and
1:-,9 gives the length of a string (in ploting units" not 4ust the nu!ber of characters).
1:09A uses the sa!e code as the a.is%labelling routines" so S5:=8 can be used to !odify its
behaviourO whether the .% or y%a.is for!ats is used depends on whether the label is !ore nearly
horiSontal or vertical. 'n e.a!ple would be
set !B&..%e") define s DstringD!)) relocate ..* ..* putlabel * Hs
#e precedence and binding are as for ( (or Qortran)" and !ay be altered by using parentheses
(35938 has a binding 4ust below O and -). 'll of these operators work ele!ent by ele!ent" so
y B # O sinD!)
is interpreted as
f there is a siSe !is!atch the operation will only be carried out up to the length of the shorter
vector and a !essage is printedO if 2,:451, is < or !ore" the line where the error occurred will
be printed too. #e constant ?0 is prede&ned.
Iou can also use J5:+DY e!pr Y > ... QQ) as part of an e.pression" where J5:+ is a
!acro taking Sero or !ore argu!ents. Suppose we de&ne a !acro pow with two argu!ents as
1, H. B H"CCH#
then the co!!and
1, y B ". O #CpowD" O !>&)
is e/uivalent to 1, y B ". O #CD" O !)CC&.
n addition to these arith!etic operations" there are also logical operators BB (e/uals)" WB (not
e/uals)" T" TB" R" RB" ^^ (logical and)" and UU (logical or). #e !eanings of the sy!bols are the
sa!e as in (" and as in ( the value ? is false while all other values are true. @ote that ^^ and UU
do notYshort%circuitDO that is" in the e.pression e!pr" ^^ e!pr# both e!pr" and e!pr# are
evaluated. n a scalar conte.t (e.g. in an Q state!ent)" the operators 89+ and 5: are available
instead" and they do only evaluate the right hand side if itDs value is re/uired (see section f).
String vectors !ay only be concatenated" added" or tested for (in)e/uality. 'dding two
string%valued vectors concatenates their ele!ents" so
; a b c < O ; ! y \ <
results in the vector a! by c\.
Jesting e/uality for string vectors see!s to cause so!e confusion. (onsider
set strBR'a' b c dT
ifD'a' BB 'str') ; 7 test if the strings `a' and `str' are equal
ifD'a' BB str) ; 7 test if the string `a' equals the vector `str'
ifDa BB str) ; 7 test if the vector `a' equals the vector `str'
#e second of these tests will succeed" but if you then try
ifD'b' BB str) ; 7 try to see if `b' is an element of str
the test will fail as 'b' BB str is the >%ele!ent vector ; . " . " < and only its &rst
ele!ent is used by the if testO what you want is
ifDsumD'b' BB str)) ; 7 is `b' an element of strV
#ere are also a nu!ber of less !athe!atical operations. f you have an 0=8A, (see section
!age) de&ned" you can e.tract a set of values using the e.pression 0=8A,De!pr>e!pr)"
where the two e!prs give the coordinates where the values are desired. @ote that this !ay be
used as a way of reading large data &les that are stored unfor!ated. #e e.pression
G015A:8=De!pr : e!pr) can be used to convert a vector into a histogra!. #e second
e.pression is taken to be the centres of the desired bins$ bin boundaries are taken at the !ean
points (and points in the &rst e.pression lying on a boundary are taken to fall into the lower bin.
@ote the use of Y$D not Y"D).
8ectors !ay be assigned to" using the synta.
1, vec B e!pr
or
1, vecY e!pr Q B e!pr
or
1, vec B J5:+De!pr)
or
1, +0=,9Dvec) B number
or
1, vec B e!pr" 0SDe!pr#)
or
1, vec B e!pr" V e!pr# : e!pr&
#e &rst for! sets vec to have the value e!pr" ele!ent by ele!ent" vec is the na!e of the new
vector. #e for! vecYe!prQ !ay be used to assign to an ele!ent of a vector" as usual the inde.
starts at ?. :efore you can use 1, to assign values to the ele!ents of a vector" you !ust create it
using one of the other for!s of the 1, co!!and.
f you want to de&ne a vector to which you will subse/uently assign values using 1,
vecY e!pr Q B e!pr" you !ay use 1, +0=,9Dvec) B number which declares vec to
be a vector of siSe number" and initialises it to Sero. Iou can optionally supply a /uali&er to the
number" either a .f (the default)" or a .s to specify that the vector is string valued.
f the 0S clause is present" only those ele!ents of e!pr" for which the corresponding ele!ent of
e!pr# is true (non%Sero) are copied into vecO in general vec will have a s!aller di!ension than
e!pr". #e last 1, state!ent (with T$) again borrows fro! (. f e!pr"_i is true" then vec_i
is set to e!pr#_i" otherwise it is set to e!pr&_i. n this for! of conditional assign!ent" the
di!ension of vec is the sa!e as that of the right hand side. t !ay look strange" but it can be 4ust
what you want.
Cach vector also has a help &eld" which !ay be used to provide a string describing the vector. #e
&eld is set by
1, G,-? vec str
and viewed by
G,-? vec
or via the string%valued e.pression G,-?Dname).
f 2,:451, is one or !ore" if a vector is arith!etic or string will also be noted. 8ectors !ay be
printed using the
?:09 Y file Q YformatQ ; vec"> ...> vecn <
co!!and" where if the optional file is !issing" the values are typed to the keyboardO if the
optional format is o!ited" a suitable one will be chosen for you. 'ny co!bination of string%
and arith!etic%vectors !ay be printed. f a value e.ceeds <e5X (or <e5?? if you chose
double%precision vectors in set_opts)" it is printed as a C. #is is consistent with the
convention used in reading data that a Y!issingD nu!ber is represented as <.??<e5X (<.??<e5??)O
see :,8+ for details. 8ectors !ay be deleted with the co!!and
+,-,, vec
and listed with the co!!and
-01 1,
8ectors are listed in ascii order along with their di!ension" and any help string speci&ed using
the 1, G,-? co!!and
*nce you start writing (or using) co!plicated !acros youDll get biten by the fact that a !acro
called by a !acro called by a friendDs !acro uses a scratch vector called ! or i" and that this
vector /uietly overwrites your vector called ! or i. Jo avoid this" conscientious !acro writers
!ake their vectors L*('L. (<X). ')er the co!!and 1, ! -538- in a !acro" any rede&nitions
of ! within that !acro" or any !acros called by it" will be discarded when the !acro e.its. #e
vector isnDt strictly speaking local to the !acro as itDs visible fro! !acros that are !ore deeply
nested" but the eUect is si!ilar. ' word on caution$ a !acro can e.it sooner than you e.pectO the
classic e.a!ple is
cube "" 7 print a vector's cube for people we li/e
define name local define name :
ifD'Hname' WB 'hatcher') ;
set ! local set ! B H"
set ! B !C!C!
print he answer is HD!)
<
:ecause the if !ight be followed by an else" the !acro is read and popped fro! the input
stack be"ore itDs e.ecuted" causing confusion.
'n 0S clause has been added to the ploting co!!ands" to allow only those ele!ents of a vector
which satisfy so!e condition to be ploted" for e.a!ple
?5091 ! y 0SD\ T &C!)
*f course" you could have used the 0S co!!and and the regular ?5091 co!!and if you had
preferred. n fact"
3599,3 ! y 0SD\ T &C!)
isnDt /uite the sa!e as
1, log B \ T &C! 1, ! B ! 0SDlog) 1, y B y 0SDlog)
3599,3 ! y
as the for!er will only connect contiguous points.
#rawing &abels and SM2s 4e: *mulation
#ere are two separate ways to specify special characters to SM" by using a synta. very si!ilar to
Je; (the type%seting syste! created by ,onald 3nuth that we used for this !anual)" or the
traditional Mongo way. Iou !ight ask what are the advantages of Je;T *ne is that sub% and
super% scripts are handled !uch !ore naturally" !aking it !uch harder to type when you !eant
'nother is that you no longer have to re!e!ber that is hidden in the =reek font as Y/D" you can
si!ply type Mtheta. ' third would be that you !ay well know Je; already.
f you want to !ake SM understand Je; strings you should de&ne the variable e6_strings (if
you put a line e6_strings " in your `.sm' &le this will be done auto!atically). Iou can" of
course" unde&ne it at any ti!e to revert to the old%fashioned strings described below. 7sing
Je;%style strings is strongly reco!!ended by the authorsO all future and !ost recent
i!prove!ents to SMDs labels are only supported in Je; !ode.
f you want to change the default font used for labels" de&ne the variable default_fontO if you
wanted to use the Moe (*ld Cnglish) font you could either say (+,S09, default_font oe)
interactively" or put a line in your `.sm file'$ default_font oe. #is aUects a.is as well
as regular labels and only works if you use e6_strings (of course).
Qor so!e devices with hardware fonts (for e.a!ple" postscript printers or a Jektroni. >?<?
ter!inal)" if e!pand is e.actly <" and angle is e.actly ?" the hard fonts will be used for speed.
8arious strategies to defeat this are discussed below.
Je; ntro$ 'n ntroduction to Je;
Je; Qonts$ 'vailable Qonts
Je; (ontrol Se/uences$ SMDs Je; (ontrol Se/uences
Je; C.tensions$ SMDs C.tensions to Je;
(aveats$ (aveats and (autions when using Je;
,efeating Bardware Qonts$ Bow to Stop the ,evice using its Qonts
*ld Labels$ *ld%style Labels
An 5ntroduction to 4e:
(Je;sperts should skip this section.) f you donDt know Je; letDs start with an e.a!ple$
label MpiI;M-#"/#< B ;M&Mint<eI;-!I#<M>d!
will print a well%known result (IouDll have to :,-538, so!ewhere where the label will be
visible &rst" of course). (f you want to try it now" you should be careful typing those [Ds" as they
are special to the history editor" dealing with this is discussed below.) n this e.a!ple the
characters M" ;" <" and I are special (and so is _ which wasnDt used). Postponing M for the
!o!ent" I !eans Y!ake the ne.t group a superscriptD" _ !eans Y!ake the ne.t group a subscriptD"
where a group is either a single character" a single control se/uence (wait a !o!enta)" or a string
enclosed in braces. So 8_aI;1=<4 would appear as ' M can serve one of two functions" either
turning oU the special !eaning of the ne.t character (so M_ is si!ply a _ with no special
signi&cance)" or to introduce a na!ed Ycontrol se/uenceD. #ese fall into three groups" those that
change fonts" those that serve as abbreviations for single characters (e.g. Mpi in the e.a!ple)" and
those that are !acros. #e font changes persist until the end of the string" or the current group"
whichever co!es &rst.
Available 'onts
#e available fonts are YgreekD" Yold englishD" YprivateD" Yro!anD" YscriptD" and YtinyD. #ey !ay be
referred to either by a two%character control se/uences (Mgr" Moe" Mpr" Mrm" Msc" or Mti) or
si!ply by the &rst character (e.g. Mr for the ro!an font). n addition Mi or Mit can be used to
!ake the current font italic (re!e!ber to use italics within ;< so that their eUect is li!iteda). #e
YboldD font Mb or Mbf is !akes the current font bold" and can be toggled oU with a second Mbf if
you didnDt si!ply group it. Dd strongly reco!!end treating Mbf like any other font change" and
group the! rather than relying on this toggling action.
#e slant of Mit leters can be controlled by the co!!and se/uence Mslant" which takes an
argu!ent which is the tangent of the desired slope (i.e. it is the degree of shear). Iou can also
co!press all leters along the direction that they are being writen using McondenseO for
e.a!ple ;Mslant..$Mcondense..* Gello Jorld<.
Iou can alter the siSe of the leters by using an escape such as M) which scales the current group
(any font change is local to a group). M) corresponds to !ultiplying the siSe by or about 5" M-$
scales by or ?.>W. #is is si!ilar to the Y!agstepD used in scaling fonts in Je;. #ese scale factors
are in addition to the e.pansion produced by going up or down (I or _)" or seting ,6?89+.
SM2s 4e: "ontrol Seuences
*ther control se/uences either consist of one non%alphabetic character" or else a na!e consisting
only of leters" so M> or Mpalmtree is valid but Mone#three is not. f a alphabetic na!e is
followed by a space" the space is treated as si!ply deli!iting the na!e and is discarded. Qor
e.a!ple" 84I;Malpha_Mbeta 3+< will appear as (note that the space a)er beta
disappeared). Bow do you !ake 4ust a few characters italic (script" old english" etc.)T Jry
843;Mit +,S<AG0. Iou canDt read a subscript" and want it in YtinyD fontT Jry M-ambda_;Mti
ab<. 'll of the =reek leters are de&ned" as Malpha%Momega"M8lpha%M5mega" there are
various !athe!atical sy!bols (e.g. Mint" Minfty" or Msqrt)" so!e astrono!ical (e.g. M88 for
and so!e !iscellaneous characters (e.g. Msnow to draw a snowKake). Iou can generate a
co!plete list of de&nitions by saying load fonts e6_defs.
So!e of these de&nitions are !ore co!ple. than 4ust special characters" if you know Je; !ost of
the! should be fa!iliar.
Mbar str
,raw a bar over str.
Mborder n str
'dd an n%pi.el border of whitespace to str and draw it.
Mcentre
Mcenter
(enter a string horiSontally
Mcolour
Mctype
Mcolor
(hange to the speci&ed colour.
Mover str" str#
,raw str" over str#" separated by a horiSontal line. #is isnDt nearly as sophisticated as
Je;Ds Mover" and never will be. tDs writen in SMDs Je; e!ulator which is prety li!ited. f
you are a LaJe; user" SMDs \frac !ay be !ore fa!iliar.
Mphantom str
,onDt actually draw str" but take up as !uch space as str would have if you had drawn it.
Msmash str
,raw str but pretend that it took up no space.
Mstrut
Make the current for!ula have at least the depth and height of a parenthesis.
Iou can also de&ne your own Je; de&nitions by using the special co!!and
MdefMname;value< inside a label. t produces no output" but de&nes name to e.pand to
value. Qor e.a!ple" could de&ne Me6 to produce Je; by saying
-84,- MdefMe6;Mraise-#..M/ern-#.,Mraise#..6<.
*nce a de&nition has been !ade it is re!e!bered forever (well" until you leave SM actually)
whatever devices you plot on. Iou !ust !ake sure that all curly brackets are properly paired
inside your de&nition. Iou can have argu!ents 4ust like real Je;" referred to as 7"" 7#" 7& and so
forth" for e.a!ple
MdefMsub7";_;7"<<
Iour SM guru can co!pile Je;%de&nitions into the binary fonts &le" instructions are given in the
fonts appendi..
SM2s *+tensions to 4e:
9e have !ade a nu!ber of e.tensions to Je; that are useful in a ploting package" but wouldnDt
be especially valuable in a printed docu!ent. 9e have also distorted the !eanings of so!e of
Je;Ds control wordsO sorry.
Mpoint n s
Mapoint angle n s
nsert a points (such as would be drawn with +5) into a label. #e string Mpoint$& (or
Mpoint $ &) will draw a point at the current position in the string" of ptype Y> 5D. #is
se/uence" fro! the M to the &" is treated as a single character as regards things like
subscripts. f you want to specify an angle" use so!ething like Mapoint $* $ ..
Mhrule width
,raw a horiSontal line at the level of the current baseline" of length width in screen units.
t will be !ultiplied by the current e.pansion.
M/ern d!
M/ern 7 !oves the current plot position by 7 horiSontally" where the distance 7 is
speci&ed in screen units (the whole screen is 5-FXW across). t is !ultiplied by the e.pansion
currently in eUect" and !ay be positive or negative. See also Mraise.
Mline type length
Mline inserts a line into a label" at about the level of the !iddle of a lower%case character.
e.g. Mline " "... will draw a line of length <??? (in screen units" so the screen is 5-FXW
across)" of ltype <. See also Mhrule.
Mmove d! dy
Move a group by Dd!>dy)" but donDt disturb SMDs current idea of where it is. #is !eans
that we can draw a line over a character with a string such as Mmove . &..;Mline .
$..<8. t is possible to use the co!!ands such as Mwidth to take the guesswork out of
such co!!ands" for e.a!ple the de&nition of Mbar is
MdefMbar7";Mmove.MadvanceMheight;7"<by"..;MruleMwidth;7"<<7"<
Mraise dy
Mraise 7 !oves the current plot position by 7 vertically" where the distance 7 is speci&ed
in screen units (the whole screen is 5-FXW across). t is !ultiplied by the e.pansion
currently in eUect" and !ay be positive or negative. See also M/ern.
Mvrule depth height
,raw a vertical line at the current position of depth d and height h (and width ?) in screen
units. ,i!ensions are !ultiplied by the current e.pansion.
#ere are also a nu!ber of control se/uences that can be used whenever a nu!ber is e.pected (by
M/ern" Mline" Mmove" or Mraise)O for an e.a!ple of their use see Mmove in the preceding
table.
Madvance num" Y by Q num
ncre!ent &rst nu!ber (which can be of the for! Mwidth;...<) by the second. #e by is
optional.
Mdepth;...<
#e depth a group would have if it were drawn.
Mdivide num" Y by Q num#
,ivide the num" by num#+<???. 's for Madvance" num" and num# need not be Ysi!pleD
nu!bers but can be co!binations of widths" advances" and so on. #e by is optional.
Mheight;...<
#e height a group would have if it were drawn.
Mmultiply num" Y by Q num#
Multiply the num" by num#+<???. See Mdivide for the lack of restrictions on nu!< and
nu!-. #e by is optional.
Mwidth;...<
#e width a group would have if it were drawn
f you want to know the di!ensions of the string that you have 4ust drawn (or 4ust not drawn" /.v.
P7JL':CL ?) you can look at the internal variables Esdepth" Esheight" and Eslength.
"aveats and "autions when using 4e:
@ow for a few caveats$ Qirstly" because Mn is a newline" you !ust type MMnu or NMnuN to get a
Secondly" the superscript character I is special to the history editor" so to type it interactively you
!ust /uote it with the quote_ne!t key (usually control-K or CS(%/" i.e. type
control-KI). 'lternatively" you could change your history character to so!e under%used
character such as d or D (which is the solution that use$ you can choose a new character such as D
by si!ply puting a line history_char ' in your `.sm' &le). #irdly" Je; (and our
pseudoJe;) are rather verbose and labels !ay not &t on one line. #e solution is to continue the
line by ending it with a \. #is is probably best done within a !acro" as the continuation line
wonDt appear on your history list if typed at the pro!pt. Iou can currently have about -G
continuation lines (-??? characters).
' &nal point will only worry Je;ies" na!ely that the e!ulation isnDt perfect$ for e.a!ple
Msum_i wonDt put the i beneath the su!!ation sy!bol. So!e of the other discrepancies were
listed in the previous section.
How to Stop the #evice using its 'onts
f C;P'@, is set to e.actly <" and '@=LC is e.actly ?" then SM will use hardware fonts" when
available" in writing labels. #is is faster" but can lead to two styles of labels in one plot which is
ugly.
#ere are various ways to trick SM into always using its own fonts$ you can say say 6'@=LC 5X?6"
or use a \? to select a font with (e.plicitly) no e.pansion. Jo aUect the a.is tick labels too" using
the ';S or :*; co!!ands" youDll have to say 6C;P'@, <.???e<6 or so!esuch.
Rather than always e.panding your plots" you could ask your SM =uru to edit the `graphcap'
&le to prevent a given device (usually a printer) fro! ever using hardware fonts. Jell her to see
section #e Stdgraph =raphics 3ernel. f she wonDt oblige" you can de&ne your own device in your
own graphcap &le" and put yours &rst in the `.sm' &le. Qor e.a!ple" !y `.sm' &le includes the
line
Ographcap /d/rhl/graphcap
and the &le `/d/rhl/graphcap' looks like$
7 ?rivate overrides for :G-:
7
postscriptUpostscript O no hardware fonts:M
:4[:,[:3Bpostscript:
#en set Hprinter to postscript (also in `.sm') and all is well.
'n alternative is to specify the device as
+,203, postscript :4[:,[:tcBpostscript:
which is perhaps si!pler (youDd 4ust de&ne your value of printer properly).
8ld-style &abels
f you insist on using old%style labels (which are still the default)" hereDs a /uick su!!ary. Jype
Ma or MMa to change to font a for one character (&rst for!) or per!anently (second for!). #e
possible fonts are g> o> p> r> s> and t for YgreekD" Yold englishD" YprivateD" Yro!anD" YscriptD"
and YtinyD respectively. n addition" the pseudo%fonts u and d !ove te.t YupD and YdownD
respectively" and i produces YitalicD (actually 4ust slanted) characters. SiSe changes are 4ust like
any other font change" so M) and M-$ will aUect one character and the rest of the string
respectively. #is is really so!ewhat si!pler than it sounds % try
label MgpMuM-#"/#M#Md B M&Mg:eMu-!Mu#MdMs d!
@ote that YtinyD is a !isno!er" it is (nowadays) 4ust a font that look beter if you need s!all leters
( MtM-) will produce a shrunken YtinyD font" 4ust like the old days). Spaces are treated diUerently
in diUerent fonts" as a greek space is a negative space (i.e. a backspace)" and a script space is only
half as wide as a nor!al space.
;etting Hardcopies of ,lots
#ere isnDt really any need for this section because SM doesnDt distinguish between hardcopy
devices such as laser printers and other devices such as graphics ter!inals" e.cept that it saves up
ploting co!!ands for hardcopy devices and sends the! all when you are &nished. #ere are"
however" hard and easy ways to do anything and this section is intended to !ake your life a litle
si!pler.
9hen a device that can produce hardcopy is closed the plot is sent oU to the printer (using the
co!!and given as 1@ in the deviceDs graphcap entry). #e only way to close a device is to open
another" any other" so it is 4ust as good to say dev !"" as it is to say hardcopy dev !"" as
the !acro hardcopy does no !ore than open the null device. So one way to produce a plot is to
say
device postscript
plotting commands
device !""
#ere are !any diUerent printers available" and even if you are using a postscript printer you
!ight want portrait (postport) or landscape (postland) plots" so it is traditional to put the
na!e of the desired printer into a variable printer. t is so traditional" indeed" that it can be
done with a line such as
printer postport
in your `.sm' &le.
#e two co!!onest incantations are probably
device Hprinter
playbac/
device !""
or
device Hprinter
my_macro
device !""
which can be si!pli&ed to hcopy and hmacro my_macro respectively. #e for!er can be
given a single history nu!ber (e.g. hcopy "#) to only !ake a hardcopy of the one co!!and" or
a range of nu!bers (hcopy " "#) to plot those lines (inclusive). #e later" if you o!it the na!e
of the !acro" will pro!pt you to create a te!porary !acro that is then printed. f you want to
!ake a hardcopy of the last line you have a choice" either hcopy -" or hmacro" and then use
the history editor to retrieve the desired line.
So!e sites have !any hardcopy devices of the sa!e type" in which case they usually set up the
1@ co!!and to e.pect an argu!ent which is the na!e of the desired printer. Iou can deal with
this by including it in your printer variable$ define printer Npostscript
latypusN but this can be a nuisance" especially as uni. already has a special (environ!ent)
variable ?:09,: that speci&es your default printer. #e resolution is that both hcopy and
hmacro are /uite carefulO if you have an SM variable ?:09,: it is taken to be your default
printerO if you don#t have one they look for one in your `.sm' &le" if they donDt &nd one there
they look for an environ!ent (8MS$ logical) variable. f all of these fail they take the &rst
argu!ent (hcopy) or last argu!ent (hmacro) to be the na!e of the printer.
So if you have a ?:09,: variable anywhere" hcopy and hmacro macro_name will work as
before" if you donDt then youDll have to say hcopy printer_name or hmacro macro_name
printer_name.
8verloading 7eywords
So!eti!es you !ight wish that SMDs authors had decided to !ake a co!!and behave a bit
diUerently" for instance that ,:81, or KL0 didnDt appear on the history list" or that 182,
deleted all the syste! !acros before saving your environ!ent. *f course" you can (usually) write
!acros to get around these annoyances" but you can#t easily give the! the sa!e na!es as the
original co!!ands (for these e.a!ples the !acros are called era" q" and sav).
t is possible to change the !eaning of keywords (to YoverloadD the!)" but it can be confusing"
pri!arily because your new co!!ands !ay not behave the sa!e way that this !anual clai!s.
Qor e.a!ple" if you were perverse" you could de&ne points to !ean KL0. 'nother danger is
that you could end up with a recursive call %% for instance if you wrote your own version of bo!
that did all sorts of cunning things" then drew a bo.. f you said bo! in your !acro" then
overloaded the keyword" youDd have a !acro that called itself. f you tried to use it" nothing would
happen for a while" and then youDd start geting !essages about 6e.tending i+o stack6 until you hit
control-3. *r if you rede&ned help to !ean +,-,, G015:@ G,-? (in upper case to
avoid recursive calls" and in case delete has been overloaded)" then set help vec Gelp
string wonDt work (youDd have to use set G,-? vec ...).
,espite these warnings" overloading the !eaning of SMDs keywords can be very convenient.
#ere are two sets of syste! !acros that do 4ust this" the co!patibility ones (see section Jips for
Mongo 7sers)" and one called set_overload that is described below.
n addition to the se!i%trivial use of overloading to allow you to type erase not era" it is
possible to add e.tra functionality to si!ple co!!ands. Qor e.a!ple" set_overload de&nes
window to save the window para!eters in variables" and bo! then uses these values to label
appropriate a.es in touching bo.es. 'nother e.a!ple is that (when overloaded) lines saves the
line nu!bers used" so that you can write a !acro to print the top <? lines of a &le (itDs called
head).
So how do you do itT #e co!!and 52,:-58+ /eyword 7 will re!ove the special !eaning
of lowercase /eyword if 7 is non%Sero" or reinstate it otherwise. Iou can still use the uppercase
for! %% you canDt overload that. So now that e.g. bo! has no special !eaning you can de&ne it to
be a !acro. 9hat the set_overload !acro does is to de&ne new !eanings for a nu!ber of
keywords" the new de&nitions are in the !acro &le `overload'. f you intend using the! (and
do all the ti!e) you should look at this &le. Iou can get the! loaded by default by having a line
overload " in your `.sm' &le. f you donDt like so!e" e.g. bo." you can si!ply say
52,:-58+ bo! . in your private startup &le (see Yprivate initialisationD) which is run a)er the
syste! startup.
Most of the changes are benign" but not all. Qor e.a!ple" the new de&nition of relocate allows
e.pressions" but itDll break if you try to say relocate D ".. "... ) to !ove to absolute
screen coordinates. Iou can still say :,-538, D ".. "...) of course" and thatDs why !ost
of the syste! !acros are actually writen in uppercase. #e de&nition of bo! (actually bo" which
bo! calls) !ay see! very co!ple." but it has to deal with bo! Mn as well as bo! " #" and it
!ust know if you have used the J09+5J co!!and. #is brings up another point %% if you
overload keywords" you could slow SM down. t isnDt that overloading is ine2cient" itDs 4ust that
the !acros that replace the old keywords !ay do a good deal of work" bo! is a case in point.
Cven when the !acro is short and to the point" itDs still e.tra work to parse the original word and
&nd its value as a !acro.
*+amples of <seful Macros
9hen you start SM the directory speci&ed as macro in your `.sm' &le is searched for a &le
`default'" and then the !acro startup fro! that &le is e.ecuted. 't the ti!e of writing of
this !anual" startup was de&ned as$
startup 77 macro invo/ed upon startup
S5:,83G " ; default_font device edit file_type history_char M
macro macro# overload printer prompt prompt# 1G,-- < ;
+,S09, H" :
<
S5:,83G " ; e6_strings case_fold_search fan_compress M
line_up_e!ponents noclobber overload M
remember_history_line tracebac/ uppercase < ;
+,S09, H" :
0SDHVH") ;
0SD'HH"' BB '.') ;
+,S09, H" +,-,,
<
<
<
0SDHVprompt) ; ?:5=? HpromptMn +,S09, prompt +,-,,
< ,-1, ; ?:5=? : <
0SDHVdevice) ; +,203, Hdevice
< ,-1, ; +,S09, device nodevice <
0SDHVdefault_font ^^ HVe6_strings BB .) ;
echo @ou can only define a default font if you use e6
<
0SDHVhistory_char) ; 7 use Hhistory_char as history character
0SD'Hhistory_char' WB '.' ^^ 'Hhistory_char' WB '"') ;
,+0 history_char Hhistory_char
<
,+0 I I
+,S09, history_char +,-,,
<
7 load the default macros
+,S09, mfiles R stats utils T 7 Hmfiles is used by `sav'
S5:,83G f D mongo Hmfiles ) ; =83:5 :,8+ NHWmacroNHf <
S5:,83G var D !_col y_col data_file ) ; +,S09, Hvar . <
7 load uppercase if defined in .sm file
0SDHVuppercase) ;
=83:5 :,8+ NHWmacroNuppercase
<
7 and overload /eywords such as erase> if so desired
set_overload HVoverload
7 and some /eymaps
0SDHVedit) ; :,8+ ,+0 NHWeditN <
7 and an optional macro file> with macro startup#
0SDHVmacro#) ;
=83:5 :,8+ NHWmacro#Ndefault
0SDis_setDstartup#>")) ; startup# < 7 startup# is defined
<
7 provide a Mn after the 0S
's this !acro is e.ecuted every ti!e that you run SM" let us consider it in so!e detail. ')er
seting the pro!pt" it looks for entries for a nu!ber of variables in your `.sm' &le. So!e (such
as printer) are si!ply +,S09,d" while so!e (such as e6_strings) are only +,S09,d if
they have a non%Sero value. :ecause so!e of the values !ight not be nu!eric" the co!parison is
forced to be done on strings by enclosing the /uantities in single /uotes. 'n entry prompt is
interpreted as a pri!ary pro!pt" !ostly for co!patibility with the use of Hprompt# to set the
secondary pro!pt. f device is de&ned it is used to set the default ploting device" and both it
and printer are used by a couple of !acros (hcopy and hmacro) that produce hardcopy. #e
variables e6_strings and default_fonts are used in producing labels (see section SMDs
Qonts). :ecause Je; uses I for superscripts" we allow you to put a history_char line in
`.sm' to specify a character to use rather than I for history ( use `). f you use ." or o!it the
value (so it is set to ")" no history character is de&ned to replace I. #e variable file_type is
used by the 0=8A, co!!and to deter!ine the &le for!at that you use (e.g. (" or unfor!ated
fortran).
1tartup doesnDt have to check that macro was successfully de&ned as it !ust have been found
for startup to have been read in the &rst place. =acro speci&es where to look for !acro
libraries" and startup ne.t sets the variable mfiles containing the na!es of so!e of the
syste! !acros to be loaded" and reads the!. #e !acro load de&ned below also !aintains the
mfiles list" as does unload. t is used by the sav !acro" which is discussed below the !ain
listing of !acros that follows. 9e also set so!e variables used by the id !acro.
's part of our eUort to be nice to users" if you have uppercase " in your `.sm' &le" we also
load the uppercase !acros. @e.t startup overloads so!e keywords if overload is in your
`.sm' &le" reads a &le of keybindings (if edit is given in `.sm')" and &nally tries to read a
second optional !acro directory macro#" and e.ecutes a !acro startup# if itDs de&ned (thatDs
what the !acro is_set is checking). #is is /uite i!portant" as it provides a way to custo!ise
SM to your personal taste without convincing the local SM guru that your taste should be foisted
on everyone. f you want a pro!pt that is diUerent" or a de&nition of q that 4ust /uits without
asking /uestions" you can get the! by using macro#. Iou can see that it is possible to tailor SM
prety !uch as you wish without changing a line of code" 4ust by playing with the startup
!acro.
SM provides various co!patibility !acros" and so!e to package o)en%used functions. #e !acro
&les `stats' and `utils'" which are read when SM is started" provide various useful !acros"
a few of which are presented here. Jo see a current list" either look at the &les directly" set
2,:451, to Sero and list all the !acros" look at the listing in this !anual (see section #e Syste!
Macro Libraries)" or use lsm to list !acro &les (this only works if you are running 7ni.O try lsm
demos). 9e give here a nu!ber of !acros taken fro! the &les `default'" `mongo'"
`stats'" and `utils'. '!ong those not listed are those like lin de&ned to be lines that
are pure abbreviations" those like !logarithm de&ned as 1, !BlgD!) which provide
functionality in a perhaps fa!iliar for!" and !any !ore like those that are given here which
provide enhance!ents (e.g. the !acro barhist). ' discussion of a few of the !ore interesting or
obscure follows. 3eywords are writen in uppercase" because you !ight have been playing tricks
with overloading the lowercase e/uivalents. Many of these !acros" in fact all fro! `default'
and `mongo'" start with 77 so as not to show up in listings !ade when 2,:451, is ?" and so as
not to be 182,d. n the interest of brevity we have o!ited !ost of these initial co!!ents.
cumulate # 7 Sind the cumulative distribution of H" in H#
+,S09, sum . 1, H#B.CH" 1, G,-? H# 3umulation of H"
+5 iB.>+0=,9DH")-" ;
+,S09, sum D Hsum O H"YHiQ )
1, H#YHiQ B Hsum
<
define sum delete
da " +88 NH"N
del" " +,-,, G015:@ Mn
dev " del" +,S09, device H" +,203, H"
dra # 7 +raw> accepting e!pressions
define " DH") define # DH#) draw H" H#
edit_hist 7 ,dit the history list
del" =83:5 all . "..... 7 define NallN from buffer
J:0, 189+8:+ ,diting Gistory 4ufferMn
=83:5 ,+0 all 7 do the editing
+,-,, . "..... 7 empty history buffer
J:0, G015:@ all 7 replace history by NallN
era del" ,:81,
gauss " 7 ,valuate a Aaussian : 9DHmean>Hsig)
1, H. B "/D1K:D#C?0)CHsig)C,6?D-DDH"-Hmean)/Hsig)CC#/#)
get # 7 1ynta!: get i X. :ead a column from a file.
7 9ame of vector is Xth word of line i.
+,S09, nn :,8+ H" H# echo reading HnnMn
:,8+ Hnn H#
1, G,-? Hnn 3olumn H# from Hdata_file
+,S09, nn +,-,,
hardcopy +,203, nodevice 7 close old device
hcopy "& 77 hcopy YprinterQ Yl"Q Yl#Q =a/e hardcopy of playbac/ buffer
7 optionally specify printer DH") and desired lines DH#-H&)
7 if the printer DH") is omitted Di.e. H" is missing or a
7 number)> it will be ta/en from the value of the environment
7 variable ?:09,:> if defined.
0SDHVprinter BB .) ;
+,S09, printer V ; what /ind of printerV <
<
0SDHV") ;
0SDJG801DH") BB .) ; 7 a number
ifDHV#) ; +,S09, & H# <
+,S09, # H"
+,S09, " +,-,,
<
<
0SDHV") ;
+,203, Hprinter H"
< ,-1, ;
0SDHV?:09,: BB .) ; +,S09, ?:09,: : < 7 which oneV
0SDHV?:09,:) ;
+,203, Hprinter H?:09,:
< ,-1, ;
+,203, Hprinter
<
<
0SDHV# BB .) ;
+,S09, # . +,S09, & "....
< ,-1, ;
0SDHV& BB .) ; +,S09, & H# <
<
playbac/ H# H& Mn +,203, Hdevice
bell
hmacro "# 77 hmacro YmacroQ YprinterQ =a/e hardcopy of a macro
7 0f only " argument is present> it is ta/en to be the printer
7 unless an environment ?:09,: variable is defined> when
7 that's used as a printer> and the argument is ta/en to be
7 a macro. 0f no macro is specified> ma/e a temp one
0SDHVprinter BB .) ;
+,S09, printer V ; what /ind of printerV <
<
del"
0SDHV# BB .) ; 7 only one arg
0SDHV?:09,: BB .) ; +,S09, ?:09,: : <
0SDHV?:09,:) ;
+,S09, # H?:09,:
<
<
0SDHV") ;
ifDHV#) ; 7 # args
+,S09, _mac H"
+,S09, _temp . 7 no temp macro
< ,-1, ; 7 " arg> ta/e as printer
+,S09, # H" 7 printer
+,S09, _temp " 7 need temp macro
<
< ,-1, ; 7 no H"
0SDHV# BB .) ; +,S09, # N N <
+,S09, _temp " 7 need temp macro
<
0SDH_temp) ;
+,S09, _mac _mac
echo N3reate temporary macro> e!it with I6N
=83:5 ,+0 H_mac
0SDis_setDH_mac>") BB .) ;
+,S09, _mac +,-,, +,S09, _temp +,-,,
+,S09, _test +,-,,
:,L:9
<
<
+,203, Hprinter H#
H_mac Mn +,203, Hdevice
0SDH_temp) ; =83:5 H_mac +,-,, <
+,S09, _mac +,-,, +,S09, _temp +,-,, bell
load 7 load macros in default directory
+,S09, macro : 7 get default directory
=83:5 :,8+ NHWmacroNH" 7 read macro file
0SDHVmfiles BB .) ;
+,S09, mfiles H"
< ,-1, ;
+,S09, & .
S5:,83G # D Hmfiles ) ;
0SD'H#' BB 'H"') ; +,S09, & " <
<
0SDH& BB .) ; +,S09, mfiles R Hmfiles H" T <
<
load# " 7 load macros in Dsecond) default directory
+,S09, macro# : 7 get directory
0SDHVmacro#) ;
=83:5 :,8+ NHWmacro#NH" 7 read macro file
< ,-1, ;
echo +irectory macro# is not defined
<
logerr & 7 logerr ! y error> where y is logged> and error isn't
1, _y B ".CCH#
1, d_y B -AD_y O H&) - H# ,::5:48: H" H# d_y #
1, d_y B H# - -AD_y - H&) ,::5:48: H" H# d_y $
+,-,, _y +,-,, d_y
lsq "* 7 do a least squares fit to a set of vectors
7 synta!: lsq ! y Y !# y# YrmsQQ Sit line y#BHaC!#OHb to ! y
7 optionally> calculate rms residual as Hrms
7 see r!y to find product moment correlation coeff>
7 and spear for 1pearman's corr. coeff.> and significance
1, _n B +0=,9DH") 7 number of points
1, _s! B 1L=DH") 7 sigma !
1, _sy B 1L=DH#) 7 sigma y
1, _s!y B 1L=DH"CH#) 7 sigma !y
1, _s!! B 1L=DH"CH") 7 sigma !!
+,S09, a D D_nC_s!y - _s!C_sy)/D_nC_s!! - _s!C_s!) )
+,S09, b D D_sy - HaC_s!)/_n )
0SDHV& ^^ HV$) ;
1, H$BHaCH&OHb
0SDHV*) ;
+,S09, H* D sqrtDsumDDHaCH" O Hb - H#)CC#)/dimenDH#)) )
<
<
S5:,83G v D _n _s! _sy _s!y _s!! ) ; +,-,, Hv <
playbac/ 77 define NallN from buffer> and run it
7 with args> only playbac/ those lines
0SDHV" BB .) ;
+,S09, " . +,S09, # "....
< ,-1, ;
0SDHV# BB .) ; +,S09, # H" <
<
del" =83:5 all H" H# all
read_old " del" 7 read a =ongo file onto the history buffer
:,8+ 5-+ temp H"
J:0, G015:@ temp =83:5 temp ; +,-,, <
rel # 7 :elocate> accepting e!pressions
define " DH") define # DH#) relocate H" H#
reverse " 7 reverse the order of a vector
1, _i B +0=,9DH")>">-" 15: R _i H" T +,-,, _i
sav " 7 1ave to a file H"> don't save from files `Hmfiles'
_save H"
_save " 7 1ave to a file H"> don't save from files `Hmfiles'
del"
S5:,83G # D Hmfiles ) ; =83:5 +,-,, NHWmacroNH# <
+,S09, # . define # V ; save vectorsV <
182, NHW"N " H# "
S5:,83G # D Hmfiles ) ; =83:5 :,8+ NHWmacroNH# <
3umulate is given as a way not to write !acros if you can help it (in this case" couldnDt). '
beter e.a!ple is reverse which reverses the order of the ele!ents in a vector without
resorting to a +5 loop.
#e !acro da could have been de&ned to be +88" but there are various special characters that
appear in &lena!esO try data /usr/spool/Xun/ or data dis/Hdata:
Y,G,-:,+QXun/.dat. #e !acro da provides a set of double /uotes to escape these
unwanted interpretations. ncidently" da N/usr/spool/Xun/N wonDt work.
+,-,, G015:@ deletes the last co!!and on the history buUer" so del" alone on a line will
delete itself" which can be used to prevent a co!!and fro! appearing on the history list" for
e.a!ple changing devices with devO dev also de&nes a variable device which is used by the
hcopy and hmacro !acros to !ake hardcopies" while returning you to your initial device. #e
startup !acro listed above also sets device" if it is speci&ed in your `.sm' &le. Iou should
be careful not to include !ore than one del" !acro in any !acro that you write yourself" as each
del" will re!ove a co!!and fro! history and you could &nd co!!ands !ysteriously
disappearing.
Aauss evaluates a =aussian" e.g. 1, !B-&>&>...* 1, gBgaussD!) lim ! g bo!
con ! g" an e.a!ple of using a !acro like a function de&nition. (Qor this e.a!ple to work" you
have to de&ne variables mean and sig &rst).
#ere is an e.a!ple of reading variables fro! &les and using the! in !acro get. #is reads a
word fro! a line in a &le with the +,S09, nn :,8+ i X co!!and" which sets Hnn to be the
Xth word on line i of the current data &le. #is variable is then used to :,8+ a vector" which is
given the appropriate na!e. So if a &le looks like$
his is an e!ample file
alpha beta gamma delta
" ". .." "e"
# #. ..# "e#
& &. ..& "e&
$ $. ..$ "e$
* *. ..* "e*
then the co!!ands
A, # " A, # # A, # & A, # $
will read Y< - 5 > GD into vector alpha" Y<? -? 5? >? G?D into beta and so forth. @ote that
+,S09, :,8+ file_id " -84,- Hfile_id
will write out Y#is is an e.a!ple &leD to the current position of the plot pointer (see" e.g.
:,-538,). ncidently" :,8+ :5J omega * would set the vector omega to have values Y5 5?
?.5 <e5D.
#e !acros hcopy and hmacro !ake hardcopies of" respectively" the playback buUer and a
!acro. :oth assu!e that the variables device and printer are set. device is set fro! your
`.sm' &le and by the dev !acroO printer is assu!ed set in `.sm'. (See YstartupD &le above).
f all is well" the !acros switch to device printer (with an argu!ent to specify which
sub%printer is desired. 9e have so !any laser printers heref)" e.ecute the desired co!!ands" and
return to the initial device. 9hen the printer device is closed" hardcopy will result. @ote the
use of Mn to ensure that no nasty things happenO if there were no Mn and the buUer ended with
-84,- Gi" the plot could appear with a label Gi device te/$.".. #e versions of hcopy
and hmacro given here accept a variable nu!ber of argu!ents (Y<5D !eans up to 5 argu!ents).
#e &rst (if present) is taken to be the desired laser printer(<F)" the ne.t argu!ent is the nu!ber
of the &rst line that you want played back" and the third is the last line nu!ber. (f you o!it both
line nu!bers youDll get the whole buUerO if you o!it the second youDll 4ust get the one line). #e
!acro sees what it has been given by using HV to see which variables are de&ned" and acts
accordingly. hmacro is so!ewhat si!ilar" e.cept that if you o!it an argu!ent it is taken to be
the !acro na!e" and a te!porary one is created for you. #e playbac/ !acro deals with its
argu!ents in a si!ilar way" and is discussed further in the e.a!ples at the end of this section.
load enables you to read a set of !acros fro! a directory speci&ed as macro in your
environ!ent &le. -oad# is si!ilar" but it looks in directory macro#. #e !acro unload (not
listed here) will unde&ne the loaded !acros. @ote that a list of all the loaded !acros is kept in
Hmlist" which is used by the sav !acro to avoid 182,ing lots of syste! !acros. sav is
writen in ter!s of a !acro _save so that it wonDt itself be forgoten (by =83:5 +,-,,) while
in the !iddle of saving !acros.
f you want to put errorbars on logarith!ic plots" logerr is the !acro youDve been looking for. t
calculates the correct length for the errorbars" and plots the! de%logging and re%logging as
appropriate.
#e !acros rel and dra illustrate a !ethod of using e.pressions" rather than nu!bers" in the
co!!ands :,-538, and +:8J. #ere are =ood Reasons why +:8J wonDt accept an e.pression
directly (see section #e (o!!and nterpreter). #ese !acros e.ploit the fact that the argu!ents
to a !acro are whitespace deli!ited" so a string such as "O#/H! co!prises one argu!ent.
Rede&ning the argu!ents !eans that the !acros donDt have to de&ne" and then delete" a couple of
variables to hold the e.pressions.
@ow that you have had your appetite wheted" we strongly reco!!end that you take the ti!e to
look through the other !acros that are available (see section #e Syste! Macro Libraries).
*therwise how would you know that there are !acros to draw arrows on plots" do 3S and
9ilco.on tests on vectors" and a host of other good thingsT
More *+amples of Macros
n all these e.a!ples" weDll use the del" !acro discussed above to keep co!!ands oU the history
list. LetDs start with a Qourier series" to de!onstrate SMDs ability to !anipulate vectors. 'll
keywords are capitalised for clarity. Start SM" choose a ploting device (with the dev !acro)" and
erase all the co!!ands on the history (or playback) buUer with +,-,, . "..... #en type
the following co!!ands$
1, p!B-?0/".>#C?0>?0/#..
1, yB109Dp!) O 109D&Cp!)/& O 109D*Cp!)/* O 109D(Cp!)/(
1, yBDyT.)Vy:.
-0=01 -" ( y
456
3599,3 p! y
#e vector p! could 4ust as well have been read fro! a &le. Iou should now have a part of a
s/uare%wave" truncated at ?.
@ow consider a si!pler way of doing the sa!e thing. Qor the present" clear the history buUer
again (+,-,, . "....)" and type$
1, p!B-?0/".>#C?0>?0/#..
1, yB109Dp!)
+5 iB">& ;
1, val B #CHi O "
1, y B y O 109DvalCp!)/val
<
+,-,, val
-0=01 -" ( y
456
3599,3 p! y
Bere we use a vector val to save a value" an e/uivalent (but slower) loop using SM variables
would be
+5 iB">& ;
+,S09, val D#CHi O ")
+,S09, y B y O 109DHvalCp!)/Hval
<
+,S09, val +,-,,
#at is all very well if you only ever wanted to su! the &rst four ter!s of the series. Qortunately
there is a way to change this" using the !acro editor. Qirst de&ne a !acro consisting of all the
co!!ands on the history list$
del" =83:5 all . "....
will de&ne the !acro all to be history lines ?%<????. (Iou need the del" to avoid having the
=83:5 all . ".... in your !acro). #en you can edit it using
del" =83:5 ,+0 all
when you have !ade the desired changes (e.g. changing +5 iB">& to +5 iB">#.) use
control-6 to leave the editor and return to the co!!and editor. @ow you could type all to
run your new !acro" or put it back onto the history list. Jo do the later" delete the co!!ands
now on the history list (the now%fa!iliar +,-,, . "....)" then del" J:0, G015:@
all to put the !acro all onto the list. @ow the playbac/ co!!and will run all those
co!!ands" and produce a beter s/uarewave. ('s discussed in a !o!ent" playbac/ is a !acro
so type it in lowercase" unless you have de&ned your own ?-8@483E !acro.)
#is ability to edit the history buUer is convenient" and there is a !acro provided called
edit_hist which goes through e.actly the steps that we took you through. #e trick of
including a del" in !acros is prety co!!on" for e.a!ple h is de&ned as del" G,-? so that it
wonDt appear on the history list. #e !acro playbac/ is rather si!ilar to edit_hist" but
instead of editing and then writing all" it e.ecutes it. 9e discussed the possibility of 4ust playing
back a li!ited nu!ber of lines while talking about hcopy" 4ust say playbac/ n" n#.
@ow that you have a set of co!!ands which produce a Qourier plot" it would be nice to de&ne a
!acro to !ake plots" taking the nu!ber of ter!s as an argu!ent" and then free the history buUer
for other things. ')er a playback" the !acro all is de&ned" so letDs change its na!e to square.
#ere is a !acro ed de&ned !ore%or%less as del" =83:5 ,+0" so type ed all to enter the
!acro editor. 7se or control-? to get to line ? and change the nu!ber of argu!ents fro! ? to
<" and the na!e of the !acro fro! all to square (the space between the na!e and the $ is
re/uired.) #en go to the +5 iB">#. line" and change #. to H". C.it with control-6" clear
the screen with era and type square ".. @ow how do you save your nice !acroT J:0,
=83:5 square filename will write it to &le `filename'" and ne.t ti!e you run SM
=83:5 :,8+ filename will de&ne it. n fact there is a co!!and 182, to save everything
which can be a !indless way of proceeding. ' !acro si!ilar to this Qourier !acro called square
is in the &le demos in the default !acro directory (and was used to produce the top le) bo. of
the cover to this !anual). Jo try it yourself" type so!ething like load demos square #..
(#. is the nu!ber of ter!s to su!.)
f your wondering why ed is only Y!ore%or%lessD de&ned as del" =83:5 ,+0" itDs because the
real ed checks to see if you have provided a !acro na!e" and if you havenDt it edits the sa!e
!acro as last ti!e.
:ut enough of !acros which &ddle with the history buUer. Bere are four sets of !acros which do
useful things" and !ay give so!e idea of the power available. Qirst a !acro to use the values of a
third vector to !ark points" then one to do least%s/uares &ts to data points" then a !acro to 4oin
pairs of points" and &nally so!e !acros to handle histogra!s and =aussians. #ese !acros are
given in the for!at that SM would write the! to disk (ready for a =83:5 :,8+)" with the na!e"
then the nu!ber of argu!ents if greater than ?" then the body of the !acro.
Qirst the points.
alpha_poi & 7 alpha_poi ! y \. -i/e poi ! y> with \ as labels for points
+5 iB.>+0=,9DH")-" ;
+,S09, _! DH"YHiQ) +,S09, _y DH#YHiQ)
:,-538, H_! H_y
+,S09, _\ DH&YHiQ)
?L-84,- * H_\
<
S5:,83G v D_! _y _\) ; +,S09, Hv +,-,, <
Bere we use the te!porary variables _! _y _\ to get around restrictions on e.pressions in
:,-538, co!!ands. @ote the +5 loop running fro! . to +0=,9DH")-"" produced by array
indices starting at ? not <. f you wanted to use character strings as labels" this could be done by
using the +,S09, :,8+ co!!and" but this would be a good deal slower as SM would have to
rescan the &le for each data%point. #e top right bo. of this !anualDs cover was !ade using this
!acro. #e use of alpha_poi (and also the !acro &le called ascii) has been superseded by
the introduction of string%valued vectors into SM. @owadays youDd si!ple read the colu!n that
you want to label the point with as a string (e.g. :,8+ lab &.s)" set the point type to that
string (e.g. ?@?, lab)" and plot the points as usual (e.g. ?5091 ! y).
#e least%s/uares !acro !akes heavy use of the 1L= operator. t could be used to &nd the
di!ension of a vector too" but only clu!sily" and +0=,9 is provided anyway. #e !acro is$
lsq $ 7 +o a least squares fit to a set of vectors
7 1ynta!: lsq ! y !# y# Sit line y#BHaC!#OHb to ! y
+,S09, _n D+0=,9DH")) 7 number of points
+,S09, _s! D1L=DH")) 7 1igma !
+,S09, _sy D1L=DH#)) 7 1igma y
+,S09, _s!y D1L=DH"CH#)) 7 1igma !y
+,S09, _s!! D1L=DH"CH")) 7 1igma !!
+,S09, a DDH_nCH_s!y - H_s!CH_sy)/DH_nCH_s!! - H_s!CH_s!))
+,S09, b DDH_sy - HaCH_s!)/H_n)
1, H$BHaCH&OHb
S5:,83G v D _n _s! _sy _s!y _s!! ) ;+,S09, Hv +,-,, <
#is does a linear &t" leaving the coe2cients in Ha and Hb. t could be easily generalised to deal
with weights" &ts constrained to pass through the origin" /uadraticsf
*ur third e.a!ple connects pairs of points. #is was writen to deal with a set of data points
before and a)er a certain correction had been applied.
pairs $ 7 pairs !" y" !# y#. 3onnect D!">y") to D!#>y#)
+5 iB.>+0=,9DH")-" ;
+,S09, _! DH"YHiQ) +,S09, _y DH#YHiQ)
:,-538, H_! H_y
+,S09, _! DH&YHiQ) +,S09, _y DH$YHiQ)
+:8J H_! H_y
<
S5:,83G v D _! _y ) ; +,S09, Hv +,-,, <
')er the introduction of vectors for 89A-, and ,6?89+ (in version -.<) this !acro can be
rewriten to be !uch faster$
pairs $ 7 pairs !" y" !# y#. connect D!">y") to D!#>y#)
+,S09, ) ; ptype angle e!pand aspect <
S5:,83G * ; HWW) < ; +,S09, H* U <
S5:,83G * ;f!" f!# fy" fy# g!" g!# gy" gy#< ;
+,S09, H* +,-,,
<
81?,3 "
1, _d!H.BDH& - H")CDHg!# - Hg!")/DHf!# - Hf!")
1, _dyH.BDH$ - H#)CDHgy# - Hgy")/DHfy# - Hfy")
?@?, # .
1, _aH.BD_d!H. BB . V D_dyH. T . V ?0/# : -?0/#) : M
D_dyH. T . V 889D_dyH./_d!H.) : 889D_dyH./_d!H.) O ?0))
89A-, "%./piC_aH.
,6?89+ 1K:D"e-* O _d!H.CC# O _dyH.CC#)/D#C"#%)
?5091 DDH" O H&)/#) DDH# O H$)/#)
S5:,83G * ; HWW) < ; H* HH* +,S09, H* +,-,, <
S5:,83G * D _a _d! _dy ) ; +,-,, H*H. <
@ote how +,S09, name U is used to save things like the angle and e.pansion" while +,S09,
name +,-,, is used to ensure that the up%to%date versions of things like f!" are used (i.e. that
they haven#t been ,CQ@Cd with a W). #e na!e of the !acro (H.) is used to !ake uni/ue vector
na!es" or at least na!es like _d!pairs that are very unlikely to be in use.
SM allows you to plot a pair of vectors as a histogra!" but what if you have only got the raw data
points" not yet binned togetherT Qortunately" SM can do this binning for you. (onsider the
following !acro$
get_hist ) 7 get_hist input output-! output-y base top width
7 given H"> get a histogram in H&> with the centres of the
7 bins in H#. 4ins go from H$ to H*> with width H).
1, H# B H$OH)/#>H*OH)/#>H)
1, G,-? H# 6-vector for H&
1, H&B.CH# 1, G,-? H& Gistogram from H"> base H$ width H*
+5 iB.>+0=,9DH")-" ;
+,S09, X D DH"YHiQ - H$)/H) )
1, H&YHXQ B H&YHXQ O "
<
+,S09, X +,-,,
Since this was writen" a new feature was added to SM" the e.pression G015A:8=D!:y)" to
!ake histogra!s. #e !acro we discussed above can now be writen !uch !ore e2ciently as$
get_hist ) 7 get_hist input output-! output-y base top width
7 given H"> get a histogram in H&> with the centres of the
7 bins in H#. 4ins go from H$ to H*> with width H).
1, H# B H$OH)/#>H*OH)/#>H)
1, G,-? H# 6-vector for H&
1, H&BG015A:8=DH":H&)
1, G,-? H& Gistogram from H"> base H$ width H*
Suppose that your data is in vector ." for want of a beter na!e" and it has values between ? and
-?. #en the co!!and
get_hist ! !! yy . #. "
will produce a histogra! in yy" bin centres in !!" running fro! ? to -? with bins < unit wide. So
you could plot it with lim !! yy bo! hi !! yy " and !aybe it looks like a =aussian. So
what is the !ean and standard deviationT #e co!!and
stats ! mean sig /urt echo Hmean Hsig H/urt
will answer that" and &nd the kurtosis too. (Macro stats consists of lines such as define H#
D sumDH")/dimenDH") ) ). #en we could use the !acro gauss to plot the corresponding
=aussian"
set \B.>#.>." set ggBgaussD\) set ggBggCdimenD!) con \ gg
#e boto! le) bo. of the cover was !ade this way. 9hat if you donDt like the way that the
histogra! looksT Jry the !acro barhist. @ow" if you wanted to plot a lognor!al" youDd have to
write your own !acro" and you could use 15: to &nd !edians and add another !acro to
utils" followed by one to &nd 9ilco.on statisticsf (Since this was writen a wilco!on !acro
was donated to stats).
What )uotes What When
#is chapter is not really needed as all of its contents can be found elsewhere in this !anual" but
as people !anage to beco!e confused anyway" hereDs a su!!ary. #ere are three ways in which
characters can alter SMDs behaviour$ they can aUect the way that characters and keywords are
interpreted" they can be special to the gra!!ar" and they can perfor! both functions. f you are
confused" you !ight &nd a verbosity of four or &ve helpful.
N...N
Jurn oU the e.pansion of variables" the signi&cance of !athe!atical operators such as / or
:" and the recognition of keywords. Qor e.a!ple" a)er +,S09, rhl ?atricia"
/data/Hrhl would be interpreted as four tokens (/" data" /" and ?atricia)" while
N/data/HrhlN is only one (/data/Hrhl). @ote that in the for!er case" the data will
be taken to be part of a +88 co!!and" and !ay well lead to a synta. error. f you need to
force a variable to be e.panded within double /uotes" use an e.cla!ation !ark$ NHWrhlN.
,ouble /uotes have no syntactical signi&cance. ncidently" N"#N is a number as the closing
N is read before the characters "# are parsed. Iou need to say N"# N to !ake "# a wordO in
a diUerent package you !ight call that a bug.
'...'
Single /uotes surround strings which !ay contain white space (spaces or tabs)" characters
such as O or /" or keywords. #ey donDt aUect variable e.pansion" so you have to enclose
the! in double /uotes if you want to protect the!. *f course" you !ust !ake sure that you
are not /uoting the single /uotes %% use 'NHabcdN' rather than N'Habcd'N . Strings are
signi&cant to the gra!!ar so only use single /uotes where they are needed. Qor e.a!ple
+88 'my_file' is a synta. error" and 1, sB'abc' and 1, sBabc !ean /uite
diUerent things.
;...<
Jurn oU all interpretation of special characters and keywords" 4ust like double /uotes. n
fact" braces even turn oU the e.pansion of HWvar" to e.pand a variable within braces you
need to say HWWvar but you only very seldo! need this. :races have syntactical
signi&cance" deli!iting lists. 9herever you can use braces you can use angle brackets.
R...T
'l!ost identical to _...Z" but donDt turn oU variable e.pansions. n fact" RT donDt always turn
oU keyword interpretation %% speci&cally they only do so in str_listDs (if you want to
know what this !eans youDll have to read SMDs gra!!ar in &le `control.y'). n practice
youDll probably only !eet this if you try saying Soreach f R quit when ahead T
; echo Hf <.
D...)
Parentheses donDt turn oU any sort of e.pansion" but can have syntactical signi&cance. Iou
are !ost likely to see this in +,S09, var D " O # ) where the parentheses tell SM to
evaluate the e.pression before de&ning the variable var as &. @ote that +,S09, var R
" O # T de&nes var as " O # .
Hname
C.pand name as a variable. C.pansion is turned oU within single and double /uotes and
within braces. :ecause the e.pansion happens before the parser sees the input" variables
cannot have any syntactical signi&cance as the parser never knows about the!. #is !eans
that variables could be used to !ake SM look like so!ething /uite diUerentO for e.a!ple
a)er +,S09, begin N; N +,S09, end N< N" you can say
=83:5 hi Hbegin echo Gello Jorld HWWend
(#is is a litle tricky. #e spaces in +,S09, begin N; N are needed so that SM is still in
/uote !ode when it processes the ;. Iou can probably &gure out why need to say HWW
end %% the WW should be a Belpful Bint.)
HDe!pr)
Cvaluate the e.pression e!pr and substitute the resulting value. #is is identical to
+,S09, temp D e!pr ) Htemp" but !uch !ore convenient.
's a reasonably co!ple. e.a!ple" try to guess the output fro!$
+,S09, hi ;RNHWD'Gello')N JorldT< +,S09, hello Hhi echo :Hhi:Hhello:
f you are not sure" try it (you !ight &nd 2,:451, * helpful)(<W).
;enerating SM interfaces from e-g- python
S9= (the Si!pli&ed 9rapper and nterface =eneratorO see http://www.swig.org/) is a
utility that allows you to use a pre%e.isting library as an e.tension to a scripting language such as
python or perlG. SM now supports pythonO with a !odicu! of eUort it could be used with perl (or
ruby or ...). Jo use this feature" si!ply select a language when you run set_opts. IouDll need to
have swig installed (yesO set_opts checks)" and !aybe also so!e additional packages.
Jo try this out" say (with the python port) python" and then
import sm
sm.demoD'!""')
Python$ Python
,ython
Jo use SM with python" you !ust have the numpy package installed. ')er installing SM" youDll
have to add your destination library (e.g. /usr/local/lib) to your ?@G59?8G.
Reserved 7eywords
3eywords are reserved" so donDt try to use the! as !acro na!es or whatever. Iou can use the
lowercase for!s if you e.plicitly ask to be allowed to overload the!. #e control words are $
J5:+ 1:09A S-58 09,A,: D ) ; < Mn W 8?:5?51 4:,8E 3G+0: +,S09, +,-,, +5
,+0 ,-1, S5:,83G G,-? G015:@ 0S E,@ -01 -538- =83:5 5-+ 52,:-58+ ?:09
?:5=? KL0 :,8+ :,15:, :,L:9 :5J 182, 1, 189+8:+ 84-, ,:=@?, L1,:
2,:451, JG0-, J:0,
'rith!etic words are $
841 8351 8109 889 889# 35938 351 +0=,9 ,6? SS 09 -A -9 ?0 :89+5=
109 1K: 1:-,9 1L= 89 JG801 ?5J,:_1@=45- Y Q B O - C CC / R T U ^ V :
SM ploting keywords are$
89A-, 81?,3 8601 456 3599,3 3595L: 3@?, 3L:15: +88 +,203, +5 +:8J
,:81, ,::5:48: ,6?89+ S5:=8 A:0+ G015A:8= 0=8A, -84,- -,2,-1 -0=01
-09,1 -538059 -@?, -J,0AG =09=86 958059 ?5091 ?@?, ?L-84,- :89A,
:,-538, 1G8+, 15: 1?-09, 03E10F, JG801 J09+5J 6-84,- @-84,-
9ith the e.ception of ?5J,:_1@=45- (which is e/uivalent to CC) these are described below"
with the convention that argu!ents between s/uare brackets are optional. #is has nothing to do
with their use in subscripting arraysa
;lossary of 4erms used in this Manual
.sm
See Cnviron!ent Qile.
Environment File
9hen you start SM it looks in a &le (by default called `.sm') to discover where to &nd &les
that it needs (such as the default !acros" the help &les" and the font &les). Iou can access
variables stored in the environ!ent &le yourself" although this is probably seldo! done by
non%gurus. Qor !ore details" see section Cnviron!ent 8ariables.
Expression
'n SM e.pression is so!ething that can appear on the right hand side of a 1, co!!and.
More speci&cally" it is so!ething that can appear as part of the right hand side of a 1,
co!!and (this e.cludes i!plied do loops$ 1, !B">".>#). C.pressions !ay also appear
in other conte.ts" such as in the 89A-, co!!and" or in +,S09, name D e!pression
). ' for!al de&nition of an e.pression is given by the I'(( gra!!ar in `control.y' as
the non%ter!inal sy!bol e!pr.
Filecap
:inary &les produced by diUerent progra!!es (and languages" and even co!pilers) are not
identical" Qortran Yunfor!atedD &les being a glaring e.a!ple. ' &lecap &le is a database
used to describe the byte%by%byte for!at of binary &les" to allow SM to read the! (using the
0=8A, co!!and).
Graphcap
#ere are a very large range of graphics ter!inals (and laser printers and so forth) in this
world" and each see!s to have its own set of co!!ands. ' graphcap &le is a database that is
able to describe (al!ost) all of these dialects" allowing SM to plot on a wide range of devices
History
SM re!e!bers co!!ands as you type the!" so that you can repeat the! or !odify the!
(which includes correcting !istakes). #e set of re!e!bered co!!ands is referred to as the
history buUer.
List
#e word list is used in a few places in the !anual in the speci&c sense de&ned by the
I'(( gra!!ar in `control.y'. ' list is si!ply a list of words or nu!bers" and its
!eaning depends on the conte.t. Qor e.a!ple" 1, !B&C;" # &< will set the vector ! to
be # $ )" while =83:5 hi ; echo Gello< will de&ne the !acro hi.
Macro
' !acro is an abbreviation for a set of co!!ands" so instead of typing a co!plicated
se/uence of co!!ands you can si!ply type the !acroDs na!e. Iou can either think of
!acros as a new co!!ands in their own right or as subroutines.
Mongo
Mongo is a ploting package writen by Vohn Jonry" and widely used in astrono!y
depart!ents. SMDs co!!and language was based on MongoDs" and we have provided so!e
support for an easy transition fro! Mongo to SM.
p_expr
' parenthesised e.pression. Many co!!ands e.pect to be passed the na!e of a vector" but
will accept an e.pression in parenthesesO for e.a!ple in the co!!and ?5091 ! Dy O
#/\)" Dy O #/\) is a p]e.pr.
s_expr
' scalar e.pression. #is is a ter! used in so!e of the co!!and descriptionsO e.a!ples
would be #"."*(" !Y"#Q" or !. n the later case" the &rst ele!ent of the vector ! would
be used" so it is e/uivalent to !Y.Q.
Stdgraph
SM uses the stdgraph device driver for !ost devices" using the infor!ation in the graphcap
&le (see section #e Stdgraph =raphics 3ernel).
String
' string to SM is a se/uence of characters enclosed in single /uotes$ 'his is a
string'. Strings are pri!arily used in vector e.pressions" but are also used in a few other
places (e.g. to specify a for!at for a ?:09 or :,8+ co!!and). @ote that characters in
double /uotes are not strings to SM" !erely characters protected fro! variable e.pansion.
Termcap
Jer!inals co!e in !any" !any" Kavours and types. #eir peculiarities are described by a
ter!cap &le" allowing SMDs co!!and editor to run on (al!ost) any ter!inal.
TeX
Je; is a typeseting language developed by ,onald 3nuth. 9e provide an e!ulation of
certain parts of Je;Ds !athe!atics !ode in SMDs label co!!ands.
Overload
' keyword (such as +,S09, or 1,) is said to be overloaded if its !eaning has been
changed. 7sually this will be by adding functionality" rather than by actually changing what
it does.
aria!le
' variable is an abbreviation for a se/uence of characters" and !ay appear anywhere that
the characters in /uestion could appear. Cven if the variable contains a nu!ber (e.g.
).)#**'e-&$) it is still 4ust a characters" although SM !ay choose to treat the! as a
nu!ber in so!e conte.ts (e.g. the right%hand side of a 1, co!!and).
ector
' set of one (actually" Sero) or !ore ele!ents. #e ele!ents can be either nu!erical
(Koating point) or strings. 8ectors are SMDs pri!ary data type. ,o not confuse a <%ele!ent
vector (a scalar) with a variable (see section String 8ariables).
"#$$
#e SM co!!and language is writen in a language called I'(( (which is supported on
7ni. syste!s). 9e have provided an i!ple!entation of I'(( called :ison in the SM
distribution.
"ommand Reference
#is is the reference !anual to SMDs co!!ands
'bort$ 'bort the current plot without producing a hardcopy
'nd$ Logical '@, with short%circuiting
'ngle$ ,raw Points and Je.t at an 'ngle
'propos$ List all (o!!ands and Macros Matching a String
'rith!etic$ 'rith!etical *perations
'spect$ Print or Set the PlotDs 'spect Ratio
'.is$ Bow to ,raw a Single '.is (see also :o.)
:o.$ ,raw a :o. around a =raph
:reak$ :reak out of a 9hile loop
(hdir$ (hange ,irectories
(onnect$ (onnect a Set of Points
(ontour$ (ontour an M'=C
(type$ Set the (olour of Lines
(ursor$ ,isplay a (ursor
,ata$ Specify the ,ata Qile to 7se
,e&ne$ ,e&ne a 8ariable
,elete$ ,elete So!ething
,evice$ (hose an *utput ,evice
,ither$ Qloyd%Steinberg ,ither an !age
,o$ ,o%Loops
,ot$ ,raw a ,ot of the (urrent Jype
,raw$ ,raw a Line to the (urrent Plot Position
Cdit$ (hange 3ey :indings for the Cditor
Cnviron!ent 8ariables$ 8ariables CUecting SMDs :ehaviour
Crase$ (lear the Screen
Crrorbar$ ,raw Crrorbars
C.pand$ (hange the SiSe of Points and Je.t
Q)$ Qourier Jransfor! a 8ector
Qoreach$ ,o So!ething to each Me!ber of a List
Qor!at$ Specify the '.is Label Qor!at
=rid$ ,raw a =rid at the '.is Jicks
Belp$ Belp Me Please
Bistogra!$ ,raw a Bistogra!
Bistory$ List the (o!!ands that you have C.ecuted
denti&cation$ 9rite an +, string on your Plot
f$ ,o So!ething f an C.pression is Jrue
!age$ Read a :inary !age
3ey$ ,e&ne a 3ey to C.ecute a (o!!and
Label$ ,raw a Label on a Plot
Levels$ Specify the Levels for a (ontour Plot
Li!its$ Set the '.is Li!its
Lines$ Set which Lines of a Qile should be Read
List$ List So!ethingO Macros" 8ariables" 8ectors" ...
Local$ Make a 8ariable or 8ector Local to a Macro
Location$ Specify where on the Screen the Plot Should 'ppear
Logical$ #e Possible Logical *perators
Ltype$ Set the Patern 7sed to ,raw Lines
Lweight$ Set the 9idth of Lines
Macro$ ,e&ne a Macro" or Read or 9rite a Macro Qile
Meta$ SMDs Support for Meta&les
Min!a.$ Qind the Mini!u! and Ma.i!u! of an !age
@otation$ (hose between Qi.ed and C.ponential '.is Labels
*r$ Logical *R with short%circuiting
*verload$ (hange the Meaning of a 3eyword
Page$ Start a @ew Page
Points$ ,raw so!e Points
Print$ Print so!e 8ectors
Pro!pt$ Set the Pro!pt
Ptype$ (hoose the Jype of Markers for Points
Putlabel$ ,raw a Label on the Plot
Rit$ Leave SM
Range$ Specify a Range for the '.es
Read$ Read 8ectors fro! a Qile
Relocate$ Move the (urrent Plot Pointer
Restore$ Restore a S'8Cd SM Cnviron!ent
Return$ Return fro! the (urrent Macro
Save$ S'8C your SM Cnviron!ent
Set$ Set a 8ector to an C.pression
Shade$ Shade a Region of a Plot
Show$ Print the 8alue of 8arious Rantities
Sort$ Sort a @u!ber of 8ectors
Spline$ Qit a (ubic Spline to Jwo 8ectors
Strings$ String *perations
Surface$ ,raw a Surface fro! an !age" with Bidden Line Re!oval
Jable$ Read fro! tables
Jer!type$ Set the Jer!inal Jype
JicksiSe$ Specify the Style of '.is Jicks
7ser$ ' 7ser%Provided (o!!and
8erbose$ 'd4ust SMDs (hatiness
8ersion$ 9hat version of SM are you RunningT
8iewpoint$ (hoose the ,irection used to 8iew Surfaces
9hatis$ Qind the Jype of a String
9hile$ Repeat (o!!ands while an C.pression is Jrue
9indow$ (hoose a Plot 9indowO 7se 4ust Part of the ,evice
9rite$ 9rite a String to a Qile
;label$ ,raw an ;%a.is Label
Ilabel$ ,raw an I%a.is Label
Abort
1ynta!: 845:
':*RJ closes the current device without producing any hardcopy. f you are writing an output
&le it will be re!oved. Iou are le) talking to the null device" so you probably want to follow
':*RJ with a ,C8(C co!!and.
And
1ynta!: 89+
n a scalar conte.t" you can use '@, instead of ^^. #e diUerence is that '@, doesnDt evaluate
the right%hand%side of the e.pression if the le)%hand%side is falseO See section f" for e.a!ples.
Angle
1ynta!: 89A-, e!pr
Qor !ost purposes only the &rst ele!ent of the e.pr is used" letDs call it + as itDs an angle in
degrees.
'@=LC will cause te.t fro! L':CL to co!e out + degrees anti%clockwise fro! horiSontal. t also
causes points to be rotated counter%clockwise by + degrees.
f + is non%Sero it will force a.is and other labels to be writen with SMDs internal fonts" and will
overrule the tendency to put .%a.is labels horiSontal" and y%a.is labels vertical.
Qor ploting points the full vector of values is used" with the point rotated by the value of e.pr. f
!ore points are speci&ed than the di!ension of e.pr" the &rst ele!ent will be used for the e.cess.
#e current value of 89A-, is (al!ost) always available as the variable Hangle (it is one of the
special variables that are aUected by the +,S09, variable U co!!and).
Apropos
1ynta!: 8?:5?51 pattern
'propos lists all !acros whose na!e or introductory co!!ents !atch the given patern.
Probably the !ost co!!on use for the co!!and is si!ply to look for a word %% e.g. 8?:5?51
histogram.
f your syste! supports it" 'PR*P*S will also search the help &les for the given patern (in this
case !atches !ay not e.tend over !ore than one line). f 2,:451, is Sero only the line
containing the !atch is printedO if 2,:451, is one or !ore then a couple of lines on each side of
the !atch are printed too. f the patern !atches !ore than once each !atch will be printed"
!erged together if appropriate and separated by line of dashes otherwise. f you use Y/D to stop
looking at the help &les 'PR*P*S will i!!ediately proceed to search the !acros.
#e patern is a slightly restricted version of a nor!al 7ni. regular e.pression" speci&cally$
.
Matches any character e.cept \n.
Y...Q
Matches any of the characters listed in the Y Q. f the &rst character is a [ it !eans use
anything e.cept the range speci&ed (in any other position [ isnDt special) ' range !ay be
speci&ed with a % (e.g. g?%Hh)" and if a h is to be part of the range" it !ust appear &rst (or a)er
the leading [" if speci&ed). ' % !ay appear as the special range ---.
I
Matches only at the start of the string. @ote that you !ust /uote the I with an ,1K-q if
you use it as your history character %% look in the inde. under history to learn how to
change it.
H
Matches only at the end of a string.
Mt
Jab
Mn
@ewline
M.
(any other character) si!ply escapes the character (e.g. \[)
C
'ny nu!ber of the preceding character (or range)
V
*ne or !ore of the preceding character or range
:y default searches are case insensitive" but you can !ake searching sensitive to case by deleting
the variable case]fold]search (you can do this by puting a line case_fold_search . in your
`.sm' &le if you so desire).
#e na!e and the co!!ents are searched separately" so you could list all !acros beginning with
a" b" c" d" e" or S by saying
8?:5?51 IYa-e\Q
(which works because all co!!ents start with a 7)" or
8?:5?51 NI7YI7QN
to list all !acros that start with a single 7 (the /uotes are needed to stop the 7Ds fro! being
treated as co!!ent characters).
Aspect
1ynta!: 81?,3 8
Set the aspect ratio (I+;) to be 'O #is is used in drawing characters and points and is reset when
a new ,C8(C co!!and is issued.
#e current values of the .% and y% di!ensions of the current device are (al!ost) always available
as the variables Hn! and Hny" and the current aspect ratio is Haspect (they are so!e of the
special variables that are aUected by the +,S09, variable U co!!and).
f ' is e.actly ?" the current aspect ratio is printed %% this is e/uivalent to echo Haspect and is
retained as a curiosity.
7sually the aspect ratio is calculated by SM to !ake characters look right (and to !ake s/uare
points s/uare)" but it is so!eti!es useful to override this" especially when positioning labels on
graphs that will be ploted on printers of diUerent aspect ratios.
t !ight be worth going through an e.a!ple. Suppose that you want to !ake a plot that really is
s/uare when printedO how should you proceedT
#e available ploting area runs fro! ?%%5-FXF on each a.is. So a plot set up as
location *... #.... *... #....
will have the sa!e aspect ratio as the ploting device" in general rectangular. 9e can write this as
define len "*... 7 a!is length> 13:,,9 units
location *... HD*... O Hlen) *... HD*... O Hlen)
if we feel sophisticated.
#e variable Haspect tells you the I+; ratio of the current deviceO so the location
location *... HD*...OHlen) *... HD*...OintDHlen/Haspect)) bo!
will be a s/uare bo.. *f course" youDd probably really want to say
ifDHaspect T ") ;
location *... HD*...OintDHaspectCHlen)) *... HD*...OHlen) bo!
< else ;
location *... HD*...OHlen) *... HD*...OintDHlen/Haspect)) bo!
<
#ere is a proble! with thisO the siSes of points and labels are varied to look right with the
current aspect ratio. #is !eans that a
putlabel * Gello Jorld
co!!and that looks &ne on the screen of your workstation will look awful on the printer. #atDs
where the 'SPC(J co!!and co!es into play$ on your workstation lie to SM and tell it that the
aspect ratio is that of the printer. Bow do you do thatT 9ell" the slick way is to say
macro aspect_as_device " ;
+,203, H"
define " Haspect
845:
+,203, Hdevice
81?,3 H"
<
which assu!es that you use a version of the device co!!and that saves the current device as
HdeviceO the !acro dev does this" and you can overload device to !ean dev. #en you can
say
aspect_as_device postport
to force the sa!e aspect ratio as the postport device.O your plots will look ugly on the
screen but beautiful when printed.
Arithmetic
8rithmetic
'rith!etic is allowed on vectors and scalars in SM" using the following operators" where e.pr is a
e.pression" s]e.pr is a scalar e.pression (e.g. a nu!ber)" and vector the na!e of a vector.
9onary DV):
?0 ?i
Lnary:
-e!pr 3hange sign 841De!pr) 8bsolute value
8351De!pr) 8rccosine 8109De!pr) 8rcsine
889De!pr) 8rctangent 351De!pr) 3osine
3@?,D) :eturn 3@?,s +0=,9Dvector) +imension of a vector
,6?De!pr) ,!ponential S-58De!pr) 3onvert to float
A8==8De!pr>e!pr) 0ncomplete gamma fn 09De!pr) 0ntegral part
-ADe!pr) -og_". -9De!pr) -og_e
:89+5=Ds_e!pr) :andom numbers 109De!pr) 1ine
15:De!pr) 1ort 1K:De!pr) 1quare root
1:09ADe!pr) 3onvert to a string 1L=De!pr) 1um_i e!pr_i
89De!pr) angent 2,35:Ye!prQ ,lements of an array
; list < 1et vector to list R list T 1et vector to list
D e!pr ) :aise precedence
4inary:
e!pr O e!pr 8dd e!pr - e!pr 1ubtract
e!pr 35938 e!pr 3oncatenate e!pr C e!pr =ultiply
e!pr / e!pr +ivide e!pr CC e!pr ,!ponentiate
e!pr ^ e!pr 4itwise 89+ e!pr U e!pr 4itwise 5:
e!pr RR e!pr 4itshift left e!pr TT e!pr 4itshift right
e!pr _ e!pr =odulus 889#De!pr_y>e!pr_!) 8tan#
(note that a bitwise ;*R !ay be achieved as U - ^).
#ere are also so!e special operators$
G015A:8=De!pr:e!pr) 3onstruct histogram
0=8A,De!pr>e!pr) ,!tract cross section D!> y coordinates)
0=8A,Ye!pr>e!prQ ,!tract cross section D!> y indices)
e!pr" V e!pr# : e!pr& e!pr# if e!pr" is true> else e!pr&
+5Ds_e!pr> s_e!pr) 0mplicit +5 loop
+5Ds_e!pr> s_e!pr> s_e!pr) 0mplicit +5 loop with increment
A8==8 returns an inco!plete =a!!a function" so ='MM'(a"in)y) ` <.
:89+5= generates a vector of s_e!pr rando! nu!bers in the range g?"<h. f you donDt specify a
seed (using 1, :89+5=) one will be chosen for you based on the current ti!e.
889# is the sa!e as (Ds function of the sa!e na!e" and is e/uivalent to 889Dy/!). t gives a
result in the range -pi -- pi dealing correctly with divisions by Sero.
3@?, returns a vector of red 1 -GX0green 1 -GX[-0blue" giving the currently de&ned coloursO
(JIPC(SJR@=) returns their na!es (see section Strings).
+5 generates a range of values" e.g. set !BdoD">*) sets . to have the values " # & $ *O
this is the sa!e as set !B">*O but set yB".. O sinDpiCdoD.>".)/".) is !ore
interesting. Iou can specify an incre!ent" so doD*>">-") is * $ & # ".
#e e.pression 2,35:Ye!prQ results in a vector of the sa!e di!ension as the e!pr" with
ele!ents taken fro! 2,35: (i.e. 2,35:Y09De!pr_i)Q). See" for e.a!ple" the !acro
interp. Iou can also use J5:+DY e!pr Y > ... QQ) as part of an e.pression" where
J5:+ is a !acro taking Sero or !ore argu!ents.
#e precedences are what youDd e.pect" with CC being highest" then C" / and _" then O and -"
then 35938" then the bitwise and logical operators" and &nally V: has the lowest priority of all.
Iou should not assu!e any precedence between logical and bitwise operators" because if you do
youDll be fooled (e.g. "UU. U .!) is (" but .!) U "UU. is <)O if you use parentheses all will be
well ("UUD. U .!)) is " and .!) U D"UU.) is F). f you have de&ned an i!age &le with the
M'=C co!!and" 0=8A,De!pr>e!pr) is an e.pression to e.tract values fro! your i!age. #e
two e.pressions give the . and y values where the i!age is to be sa!pled. Qor e.a!ple 1,
!B.>">.." 1, \B0=8A,D!>..*) will e.tract a horiSontal cross section through an i!age.
's an alternative" you can use (?%based) indices to e.tract the values with 0=8A,Ye!pr>e!prQO
there are e.a!ples under M'=C (see section !age). G015A:8=De!pr":e!pr#) constructs
a histogra! fro! a vector" where the data is in e!pr"" and e!pr# (which !ust be sorted) gives
the location of the bins. f the values of e!pr# are e/ually spaced" the YlocationD of the bin !eans
the centreO if they are not" a bin is de&ned by saying that points with value De#Yi-"Q O
e#YiQ)/# RB ! R De#YiQ O e#YiO"Q)/# go into the ith bin. @ote that values on bin
boundaries go into the higher bin.
a V b : c is very useful if you want to treat so!e value of an e.pression specially. Iou could
do this with a loop but V: is !uch fasterO for e.a!ple
set y B lgD! T . V ! : "e-&()
set y B sqrtD! TB. V ! : .)
,ue to the way that SM evaluates these e.pressions you !ay see warnings fro! the parts of the
e.pressions that are not used (i.e. where the logical e.pression is false). Iou can turn down the
verbosity" of course" or you could try sending !ail us !ail to see if we canDt &. it (but it isnDt easy"
or else weDd have done it already).
See YLogicalD for the logical operators" YStringsD for string operators" and YwhatisD for &nding out if
strings are nu!bers" words" vectors" or whatever.
A+is
1ynta!: 8601 8" 8# 21=8-- 240A 86 8@ 8-,9 0-84,- 03-53E
8601 8" 8# 21=8-- 240A 2-84 86 8@ 8-,9 0-84,- 03-53E
8601 8" 8# 81=8-- 840A 86 8@ 8-,9 0-84,- 03-53E
Makes an a.is labeled fro! 8" to 8# at location 86" 8@" length 8-,9. #e &rst for! (with
21=8-- and 240A) speci&es the values where you want s!all and big ticks e.plicitlyO if you
specify the string%valued vector 2-84 it will be used to label the big ticks. #e third for! is !ore
obscure$ f 840A N ? use that for spacing of large ticks. f 81=8-- M ? !ake a logarith!ic a.is" if
81=8-- ` ?" do the default. (See J(3SPC for !ore on the !eaning of negative 81=8-- and+or
840A). f 81=8-- N ? try to use that for the spacing of s!all ticks.
0-84,- is ? for no labels" < for labels parallel to a.is" - for perpendicular to a.is" and 5 for
neither labels nor ticks. 89A-, deter!ines the angle of the a.is.
03-53E is used for (too) !any purposesO itDs treated as three integers of <" -" and < bits
respectively.
03-53E ^ .!": 3ontrol the tic/s orientation:
. 8nticloc/wise from the a!is
" 3loc/wise from the a!is
D03-53ETT") ^ .!&: 3ontrol the tic/ direction:
. ic/s are perpendicular to a!is
" ic/s are vertical
# ic/s are vertical
& +on't draw any tic/s
D03-53ETT&) ^ .!": 3ontrol which side of the a!is the tic/s appear:
. he same si\e as the labels
" he opposite side to the labels
f you prefer not to think in ter!s of bitwise operators" this can be writen as if 03-53E is even
the ticks are anticlockwise on the a.is" if odd they are clockwise. Iou usually want the ticks
perpendicular to the a.es" and this is what you get with 03-53E ? or <O if it is - or 5 the ticks are
vertical" and if > or G they are horiSontal. #e labels are on the opposite side of the a.is fro! the
ticks unless you add W to the nu!bers given above.
Qor e.a!ple" the following co!!ands are e/uivalent to 456$
89A-, .
8601 Hf!" Hf!# . . Hg!" Hgy" HDHg!#-Hg!") " HD.U%)
8601 Hf!" Hf!# . . Hg!" Hgy# HDHg!#-Hg!") . HD"U%)
89A-, '.
8601 Hfy" Hfy# . . Hg!" Hgy" HDHgy#-Hgy") # HD"U%)
8601 Hfy" Hfy# . . Hg!# Hgy" HDHgy#-Hgy") . HD.U%)
89A-, .
(e.cept that set 03-53EDs .!% bit to draw the ticks outside the bo.).
f you want to label the boto! a.is of so!e plot only at pri!e points try
1, bB;" # & * ( "" "& "( "'< 1, sB.>#.
8601 . #. s b &*.. &*.. #(*.. " .
f you have used LMJS to scale the a.es and L*('J*@ or 9@,*9 to !ove the!" you could
say so!ething like
8601 Hf!" Hf!# s b Hg!" Hgy" HDHg!#-Hg!") " .
'n e.a!ple of using your own string valued labels would be$
set sB">(>.* set bB">( set labsB; 5 4 8 S A E = <
-0=01 " ( . .
8601 . ". s b labs &*.. &*.. #(*.. " .
which works as e.pected. f you donDt have a shi) key and try using lower case (obafgk!) youDll
be surprised as all the leters are not at the sa!e level (as they donDt all have the sa!e height). #e
easiest way to deal with this is to !ake the! all the sa!e height$
set labsB; o b a f g / m < O 'MMstrut'
(a strut is a Je;is! that has the height and depth of a parenthesisO D! afraid that you do have to
escape the \ in the string). f that leaves too !uch space try$
set labsB'MMmove "..' O ; o b a f g / m < O 'MMstrut'
think that you get the point.
f you want !ore control over place!ent and siSes of a.is labels and ticks" you can force SM to
draw the! separately$
,6?89+ ..*
8601 Hf!" Hf!# . . Hg!" Hgy" HDHg!#-Hg!") . HD"RR&)
,6?89+ ".$$
8601 Hf!" Hf!# . . Hg!" Hgy" HDHg!#-Hg!") " HD&RR")
gives s!aller%than%usual ticks outside the bo. with larger%than%usual labels (you could have used
define default_font N#N to achieve the later)
#e distance of labels fro! a.es is controlled by the SM variable label_offsetO increase it to
!ove the! further away.
Rather than use ';S to draw all of your a.es" it !ay be easier to use :*; with so!e 5Ds to
disable its a.is%drawing habits. IouDll still get a bo." but no ticks or labels. Qor e.a!ple"
-0=01 . " . ". 456 " # . & 03E10F, . . -" . 456 & & " &
will label the y%a.is with both linear and logarith!ic a.es.
Tis was changed in $%&'( To speci"y logarithmic a)es you should now speci"y the logarithms* +ust as
you do to ,-.& Qor e.a!ple" to draw a logarith!ic a.is running fro! < to <???" specify 8" as ?
and 8# as 5" rather than < and <???.
See @*J'J*@ if you want to control the use of Koating point or e.ponential notation. Iou can
control the font used by seting the variable default_font. f you want your positive and
negative e.ponents to line up de&ne the SM variable line_up_e!ponentsO if itDs " theyDll be
padded with a space" if # or !ore" with a O (you can do this in your `.sm' &le).
%o+
1ynta!: 456 Y 09,A,:" 09,A,:# Y 09,A,:& 09,A,:$ Q Q
:*; puts a.es around the plot region" labelling the lower and le) according to the values set by
LMJS and J(3SPC. f argu!ents 09,A,:" and 09,A,:# are included (default < and -)
they are used as 0-84,- argu!ents for the lower and le) a.es (see ';S). 'n 0-84,- of ?
!eans to o!it a.is labels" < produces labels parallel to the a.is" - perpendicular" 5 o!its both
labels and tick!arks" and > o!its the a.is entirely. 09,A,:& and 09,A,:$ are used for the
top and right a.es.
f you want to change the font used for a.is labels" de&ne the variable default_font" either
interactively (+,S09, default_font oe)" or by puting a line in your `.sm' &le$
default_font oe. #is aUects regular as well as a.is labels" and only works if you use
e6_strings" which we reco!!end anyway.
See section @otation if you want to control the use of Koating point or e.ponential notation" and
so!e details on how to draw e.ponents. f you want !ore control over your a.is labels" see
section '.is.
%rea(
1ynta!: 4rea/
C.it the current 9BLC (see section 9hile) loop" and continue e.ecuting co!!ands a)er it.
Iou cannot use :RC'3 to escape fro! a ,* loopO either e!bed the loop in a !acro and use
RCJ7R@ to e.it early" or rewrite the ,* as a 9BLC loop.
"hdir
1ynta!: 3G+0: J5:+
Set the current directory to be J5:+" where J5:+ is any valid directory. t !ight be wise to
enclose it in /uotes" e.g. 3G+0: NY-.more_dataQN" or use the cd !acro. #e new directory
only aUects SM" for e.a!ple +88 or 182, co!!ands. 9hen you e.it SM" you will be back
where you started. f the directory starts with a YbD" the YbD will be replaced by the na!e of your
ho!e directory. #is is the only place that YbD is signi&cantO in particular it will not be recognised
by the ,'J' co!!and.(<H)
Iour current directory is always available as the Hcwd variable.
"onnect
1ynta!: 3599,3 J5:+" J5:+# Y 0S De!pr) Q
(*@@C(J draws line seg!ents connecting the points in vectors J5:+" and J5:+#. f the Q
clause is present" only connect those points for which e!pr (see the section on vector arith!etic)
is non%Sero. *nly contiguous points in the input vectors will be connected" resulting in a nu!ber
of line%seg!ents. f you donDt want this behaviour" say so!ething like
set l B D\BB") V " : . set !B!! ifDl) set yyBy ifDl) connect !! yy
n fact" either or both of the J5:+s !ay be replaced by Yparenthesised e.pressionsD" i.e.
e.pressions in parentheses. Qor e.a!ple"
3599,3 ! D#Cy)
plots . against -y.
f J5:+" and J5:+# have diUerent di!ensions (*@@C(J will ignore the e.cess points in the
longer vector. f you want to plot a constant value youDll have to e.plicitly pro!ote it" for e.a!ple
3599,3 ! D"O.C!)
which !akes a rather boring plot.
Jo draw a line in a label you can either use (*@@C(J or ,R'9" or use the Je;%!acro Mline to
directly insert your line.
"ontour
1ynta!: 3595L:
Makes a contour plot of an i!age read by the M'=C co!!and (see section !age). #e contour
levels are set using LC8CLSO plot coordinates are taken to be those set by the LMJS co!!and"
and contours are drawn in the current LJIPC. t is not possible to produce labeled contours.
'ny pi.els whose value is 9a9 are ignored" as are any whose value e/uals the SM variable
Hmissing_dataO by default this is so!e very large nu!ber (usually <e5F). f a contour line
runs into a !issing data point it si!ply stops" rather than being !ade to 4oin up with so!e other
line that also runs into a !issing point.
See also ,JBCR for dithering i!ages" M'=C (7RS*R for using cursors to get values fro!
i!ages" M@M'; for &nding the !ini!u! and !a.i!u! of i!ages" and 'rith!etic for
e.tracting cross%sections of i!ages.
"type
1ynta!: 3@?, J5:+
3@?, 09,A,:
3@?, B e!pr
9ith J5:+" set the line colour to be J5:+" if your display device supports coloured lines" where
J5:+ !ust be one of default" white" blac/" red" green" blue" cyan" magenta" or
yellow. #e colours are those co!posed of three" Sero" one" or two of the pri!ary colours red"
green" and blue. 9hen a device is opened it sets default to so!e device speci&c value (e.g.
white for .windows" black for sunwindows).
nitially" (JIPC 09,A,: is another way of selecting the sa!e colours as are available with
(JIPC J5:+" where (JIPC < is the e/uivalent of the &rst colour listed above" or white (so
default is ?). Bowever" the (JIPC ` e!pr co!!and rede&nes the available colours to be the
ele!ents of the array given by e.pr. f it is arith!etic" each ele!ent of is interpreted as RC, 1
-GX0=RCC@ 1 -GX[-0:L7C for the given colour" where ? is oU" and -GG corresponds to full
intensity. f the e!pr is string%valued it speci&es the na!es to be used for the colours that you
have 4ust de&ned. 'ny connection between the na!es and colours is" of course" up to you. Iou
can get the current value of (JIPC with +,S09, ctype U" and vectors of the current ctypes
and their na!es as 3@?,D) and 3@?,D1:09A).
So another way to get white lines would be to say$
3@?, B ; . #** . < O #*)CD; . #** #** < O #*)C;. #** . <)
3@?, "
while
3@?, #
would give green lines.
3@?, B; blac/ white green <
would !ake your colour na!es correspond to reality again. Iou can use any na!es you like" you
are certainly not restricted to the initial set.
Iou can reset the colours to their default (i.e. correct) values using the !acro reset_ctype.
f you want to add a new colour you can say$
3@?, B 3@?,D) concat #.. O #*)CD".. O #*)C"..)
3@?, B 3@?,D1:09A) concat 'pin/'
and delete one with
foreach f ;NN string< ;
set ctBctypeDHf) ifDctypeDstring) WB 'pin/') ctype B ct
<
(see also !acros add_ctype and del_ctype).
tDs also possible to add a single private colour using the synta.
ctype M7::AA44
(e.g. 7ff..ff)" which !ay be referred to ctype HDdimenDctypeD))) (i.e. one inde. past
the o2cially supported colours). #is was i!ple!ented to allow the ; server to talk about white
as 7......" but !ight prove useful to you" too.
Many devices (e.g. sunview) re/uire you to specify a nu!ber of colours that is a power of -" so
asking for F? colours will use up <-W slots. t is probably a good idea to use as few colours as
possible" as they are scarce resources on !ost displays. Iou should also be aware that the display
!ay use so!e of YyourD slots for the background" so specifying X5 colours on (e.g.) a sun actually
re/uires X> (and asking for X> will use up <-W). f you specify !ore colours than are physically
available" or !ore than the device driver thinks that you deserve" SM will interpolate your values
of (JIPC for you.
f you are using ;<< (see section ,evice)" you will probably need to use the -cmap Kag when
openinig your device if you want to allocate !any private colours.
#e default colour is speci&ed in the device drivers" or in the +3 (,efault (olour) graphcap
capability" and is set whenever a device is opened" so donDt try to !odify it with a 3@?, B
e!pr co!!and. Iou can" however" override the default colour with a foreground entry in
your `.sm' &leO it should be the na!e of a colour (as listed above). Iou !ay also be able to
specify a background colour (as bac/ground). #is is either a colour na!e or a set of three
integers in the range ?%-GG specifying the red" green" and blue values. 9e allow you this chance to
specify arbitrary colours because itDs your only chance to aUect the background" and you canDt use
a (JIPC ` co!!and to co!pose your own palete. *n so!e devices the na!e of the background
colour !ay be chosen fro! a wider selectionO for e.a!ple if you are using ;windows you !ay
use any na!e fro! the colour database.
"ursor
1ynta!: 3L:15:
3L:15: J5:+" J5:+#
3L:15: :,8+
,isplay the cross%hair cursor to enable you to get positions (in user coordinates). #e current
cursor position is typed on the screen every ti!e that you hit a keyO so!e keys are special"
speci&cally you can e.it the cursor routine by hiting YeD or Y/D. f you e.it with YeD" (7RS*R issues
a relocate co!!and to set the current plot position to the cursor position" and puts the co!!and
in the history buUer. f you e.it with Y/D" no entry is !ade in the buUer (but the current position is
still updated). 7sually successive positions overwrite each other" but if a digit is used to !ark a
point then the position is followed by a newline" so the ne.t ti!e you hit a key its position will
appear on the ne.t line. (Iou can re!e!ber that digits lead to nu!erous values appearing). f the
verbosity (see section 8erbose) is one or !ore" a !essage will be printed re!inding you what
keys to use.
f you si!ply want to read the current position of the cursor" you can say 3L:15: :,8+O this is
!ostly useful within !acros (see" for e.a!ple" animate in the !acro &le `&d').
Many graphics devices have things called 6=@ ter!inators6. SM usually e.pects that this be set to
Y(arriage ReturnD with no e.tra characters" C*J is a popular (unacceptable) choice. f you have
trouble check your graphics setup screen" then with your SM =uru who can look up in graphcap
to see what is e.pected. f the local =uru were very friendly" he could change your =@
ter!inator to anything he wanted" even C*J" but he probably isnDt.
#e second for! enables you to de&ne a pair of vectors J5:+" and J5:+#. SM provides you
with a cursor" and every ti!e that you hit a key it prints its position (4ust as above). f the leter is
YeD it draws a point of the current type at the current position" prints the current position" and
enters the (."y) coordinates in the vectorsO if you use Y!D to !ark a point the coordinates are not
writen to the screen" but the point is still added to the vectors. YpD de&nes the current point" and
e.its. C.it without de&ning another point with Y/D" so the se/uence YeD Y/D is e/uivalent to YpD. Iou
can also abort with a control-3 in which case J5:+" and J5:+# are unchanged.
@ote that if you want to use SPL@C on the vectors produced in this way" you should take care
that at least one of the vectors is !onotonic and increasing" or use the S*RJ co!!and.
See also M'=C (7RS*R which returns the value under the cursor as well as the position if an
M'=C (see section !age) has been de&ned.
Qor devices with !ice" if the butons do anything" they should generate the characters YeD" YpD" and
Y/D (starting at the le)).
#e Sun9indows cursor is slightly diUerent. #e cursor position is given by a pointing &nger (itDs
the best we could do)" and SM wonDt see any characters typed at the keyboard until you hit a
carriage return. ,evice sunwindows is obsolete anyway" you should si!ply switch to using the
sunview driver. /ts cursor has a bug" in that it only sees every other character typed at the
keyboard. f knew why Dd &. it.
#ata
1ynta!: +88 file
7se &le file as the source of data read with the RC', co!!and. #e &le is assu!ed to have
nu!erical data in colu!ns separated by spaces" or tabs. #e range of lines speci&ed by L@CS is
reset. f the &le canDt be opened for read" you will be warned. #e variable Hdata_file is set to
file. See the RC', co!!and to see how to read the data. Iou !ay need to /uote the &lena!e"
e.g. +88 N/usr/fileN" which you can do by using the !acro da$ da /usr/file.
Perverse people who wish to use &lena!es such as `"#' or `&."$' will &nd that they get
synta. errors. f they !ust persist +88 N&."$ N will work.
#efine
1ynta!: +,S09, name value
-538- +,S09, name ...
+,S09, name ; value_list < Y MY 09,A,:> 09,A,: MQ Q
+,S09, name R value_list T Y MY 09,A,:> 09,A,: MQ Q
+,S09, name +,-,,
+,S09, name -538-
+,S09, name D e!pr )
+,S09, name :
+,S09, name U
+,S09, name V Y ; prompt < Q
+,S09, name V Y R prompt T Q
+,S09, name :,8+ 09,A,:
+,S09, name :,8+ 09,A,: 09,A,:#
+,S09, name 0=8A,
0=8A, +,S09, name value
-01 +,S09, Y begin end Q
'll of these varieties of ,CQ@C de&ne variable name to have so!e value" but as variables can be
de&ned in all sorts of ways there are a good !any possibilities. 9ith the pre&. L*('L (which is
allowed in front of any of the ,CQ@C co!!ands)" the variable will be local to the !acroO (see
section Local).
9ame is a single word starting with a leter" and containing only leters" digits" or Y]D" and !ay be
a keyword. 9henever SM co!es across Hname" it is interpreted as a reference to variable name
and Hname is replaced by its value. (@ote that so!e variables such as date are special as they
always contain an up%to%date value" for an e.a!ple try echo Hdate so!eti!e. #ese variables
are listed under +,S09, name U.) Iou can also evaluate e.pressions with HDe!pr)" for
e.a!ple echo HDpi/#). #e value canDt be longer than about W? characters" e.cept for the
value_list for! in which case its length can be essentially in&nite.
f you 4ust want to know if a variable is de&ned" then HVname is de&ned to have the value < if
name is de&ned" and ? otherwise. 8ariables are not usually e.panded within double /uotes or _Z"
but if you use the synta. HWname the variable will be e.panded within double /uotesO HWWname
will be e.panded anywhere.
Qor the variants of ,CQ@C name value and ,CQ@C name value_list" value is either a
word or nu!ber" or a list. #e diUerence between using _Z and RT to deli!it a list is that keywords
can appear within _Z" but variables are not usually e.panded.
9ith the optional g @JC=CR" @JC=CR h clause ( apologise for the notation in the !anualO
those gh are re/uired) you can choose a subrange" 4ust as S7:SJR (see section Strings) can choose
a part of a vector ele!ent. Qor e.a!ple"
define s RN/abc/defNTY">-#Q echo Hs
prints
abc/d
9hy is this usefulT :ecause it provides a way of working around li!its on lengths of vector
ele!entsO otherwise this e.a!ple is e/uivalent to
define s DsubstrD'/abc/def'> ">-#)) echo Hs
,CQ@C name ,CLCJC" deletes a variable (see also the !acro undef to unde&ne variables).
,CQ@C name L*('L" which is only allowed within !acros" creates a variable which will only
be visible fro! the current !acro" and fro! !acros called by it (see section Local). Such local
variables are auto!atically destroyed when leaving the !acro within which they were created"
and !ay not be e.plicitly deleted. #is is si!ilar to the behaviour of nu!bered variables" e.cept
that they really are local (i.e. they are only visible in the !acro" and not in its descendentsO SMDs
L*('L variables have nested scope rather than being truly local).
'n alternative is to pre&. the ,CQ@C co!!and itself with L*('LO +,S09, me -538-
+,S09, me :G- is e.actly e/uivalent to -538- +,S09, me :G-.
' co!!on use for ,CQ@C L*('L is$
define i local
foreach i ; sorbus aucuparia < ; set Hi local <
to protect a Q*RC'(B (or ,*) variable" and all local vectors" in one si!ple line. t is because such
loop variables are auto!atically destroyed that ate!pts to delete local variables are not reported
at 8CR:*SC levels of < or less.
,CQ@C name D e!pr ) de&nes a variable to have the value of a (scalar) e.pression. 9hen
possible" it is !ore e2cient to use vectors to perfor! calculations on scalars" rather than puting
the! into variables. t is also !ore e2cient (and !ore obscurea) to use nu!bered variables (!acro
argu!ents) than real na!ed ones. 's a special dispensation" the e.pression can be an ele!ent of a
string%valued vector (ele!ents of arith!etic vectors are allowed too of course).
,CQ@C name : de&nes the variable name fro! the environ!ent &le. f name canDt be found"
and is capitalised" SM will look for it in the environ!ent (as a logical variable for 8MS users).
+,S09, name U is used to de&ne a variable fro! an internal SM variable such as e!pand or
angle. #ese variables can be listed with -01 +,S09, U (or by -01 +,S09, if 2,:451,
is two or !ore)O a possibly inco!plete list is$ angle" aspect" ctype" cwd" date"
e!it_status" e!pand" f!"" f!#" fy"" fy#" g!"" g!#" gy"" gy#" ltype"
ltype_e!pand" lweight" n!" ny" ptype" sdepth" sheight" slength" distance"
theta" phi" u!p" uyp" verbose" !p" and yp. #e current plot li!its are f!" etc." (or g!" etc.
in device coordinates)" the siSe of the screen (in pi.els" or dots" or whatever the hardware uses) is
n! C ny" the current position (in user coordinates) is Du!p>uyp) " the current position (in
plot coordinates) is D!p>yp)" e!it_status is the return code fro! the last W co!!and"
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
8iewpoint)" and the rest should be obvious. n the case of angle" e!pand" and ptype" if you
used a vector to set (e.g.) the e.pansion" the value given will be that of its &rst ele!ent" and
thereDs also an e.tra value giving its di!ension. #is allows you to say things like
ifDdimenDRHangleT) BB #) ; echo @ou used a vector angle command <
#is sort of variable changed a litle with version -.<.<. #e variables that you can use have not
changed" but their usage has slightly. #ey are all de&ned for you when SM starts and each is
always correct" tracking the current value of the corresponding internal variable. Qor e.a!ple" try
echo HangleMn angle $* echo Hangle. f you now say define angle U" Hangle
will cease to track the internal value and will re!ain &.ed (the sa!e eUect can be achieved with
define angle $*). 9hen you say define angle delete it will once !ore track the
internal value. Iour old code will continue to work" but in !any cases it is possible to re!ove the
e.plicit de&nition with U. #is special sort of variable will not be 182,d" and will not show up if
you list the currently de&ned variables (unless 2,:451, is two or !ore).
,CQ@C name V will pro!pt you for the value of name at the keyboard" using the pro!pt string
if given" otherwise the na!e of the variable. #e old value of the variable (if de&ned) is printed
within gh" and is taken to be the default if you si!ply hit carriage return. 's previously discussed"
the diUerence between _Z and RT is in the treat!ent of keywords and variables. f you donDt want
to use _Z (probably because of so!ething weird to do with when variables are e.panded)" you can
always use /uotes within RT.
#e versions of the ,CQ@C co!!and including RC', de&ne variables fro! the current data &le.
,CQ@C name RC', 09,A,: sets name to be line 09,A,: of the current data &le" while
,CQ@C name RC', 09,A,: 09,A,:# de&nes name to be word 09,A,:# of line
09,A,:. name is sub4ect to the usual restrictions. f the line begins with a 7 the &rst character
is si!ply ignored when de&ning variables.
,CQ@C name M'=C de&nes a variable fro! a &le read with the M'=C or J':LC co!!and.
(urrently this only works for 96" 9@" 6." 6"" @." @"" or any keyword fro! a QJS header. 'ny
!inus signs (-) appearing in name are converted to underscores (_)" as SM doesnDt allow - in a
variable na!e.
Iou can de&ne further such variables using M'=C ,CQ@C na!e value" a facility that is chieKy
useful in connection with the 9RJC M'=C co!!and (see section !age).
LSJ ,CQ@C lists all currently de&ned variables" or all those which are between begin and end
alphabetically (asciily). Iou can use LSJ ,CQ@C i to list internal variables" or LSJ ,CQ@C
M'=C to list i!age variable (see section List).
C.a!ples
+,S09, v" *.''&
+,S09, label" E?95
+,S09, label" R 9ational 5ptical 8stronomical 5bservatory T
+,S09, v# DHv" O &.$)
+,S09, v" +,-,,
+,S09, age V ; Gow old are youV <
+,S09, macros : J:0, 189+8:+ NHWmacrosN
(@ote that we couldnDt have used RT to pro!pt for your age" because then the T a)er you would
be treated as a keyword).
Jo illustrate the +,S09, name :,8+ co!!ands" consider a &le with the following lines$
his is a file containing astronomical data
=agnitude 0ntensity Javelength ,rror
#en using the +,S09, co!!ands as follows$
+,S09, title :,8+ "
+,S09, label! :,8+ # &
will assign the string his is a file containing astronomical data to the
variable title" and the word Javelength to the variable label!" so you can say 6-84,-
Hlabel!.
#elete
1ynta!: +,-,, Y 09,A,:" Y 09,A,:# Q Q
+,-,, G015:@ Y W Q
+,-,, G015:@ Y 09,A,:" Y 09,A,:# Q Q
+,-,, J5:+
,elete co!!ands 09,A,:" to 09,A,:# (inclusive) fro! the history buUer. f the 09,A,:s
are not present" delete the last co!!and. ,CLCJC ? will delete all history co!!ands. f the
09,A,:s are negative they are interpreted relative to the current co!!and" so -" is the last
co!!and.
#e ,CLCJC BSJ*RI co!!ands are identical to the ,CLCJC co!!ands" e.cept they
the!selves do appear on the history listO they are preserved for backwards co!patibility and
because ,CLCJC BSJ*RI \n can be used to prevent a co!!and fro! appearing on the history
list (the !acro del"). f a !acro contains a +,-,, G015:@" or calls a !acro that contains
one" or ... the !acro will not appear on the history list. Jraditionally" this !eant that if there were
two (or !ore) occurrences of ,CLCJC BSJ*RI the previous co!!and(s) were also be deleted"
but in SM version -.-.< this has been changed" and ,CLCJC BSJ*RI will only delete the last
co!!and typed at the keyboard. f for so!e nefarious purpose you really do want to delete older
co!!ands too" you can say ,CLCJC BSJ*RI a and the co!!and will work the old way.
,CLCJC 9*R, deletes the vector J5:+ (see SCJ J5:+ or RC', J5:+ for how to de&ne
vectors)" =83:5 name +,-,, is used to delete a !acro" +,S09, name +,-,, deletes a
variable.
#evice
1ynta!: +,203, J5:+ Y rest_of_line Q
+,203, 09,A,: Y J5:+ Q Y rest_of_line Q
+,203, =,8 J5:+
+,203, =,8 3-51,
(#e +,203, 09,A,: for! is retained for historical interest and backwards co!patibility
only.)
(hoose a device to plot to. C.actly which devices are available depends on your hardware
con&guration and how SM was co!piled. Iou can list available devices with the -01 +,203,
co!!and (see section List). 9hen you specify a device the previous device is closed" which !ay
lead to so!e action being taken (for e.a!ple" sending a plot to a printer).
9hen a device is opened it is looked up by na!e in the `graphcap' &le (see section #e
Stdgraph =raphics 3ernel). n so!e cases all the infor!ation that SM needs to plot to the device is
available there (for e.a!ple !term or postscript)O such devices are referred to as stdgraph
devices. *therwise the graphcap entry will contain the na!e of the real device driver" for e.a!ple
!"". 'nything else on the line is passed to the device driver. n particular" for the stdgraph
devices an argu!ent that is not speci&cally processed by the device is taken to be the na!e of a
&le to save the plot in. #us device postscript foo.ps creates a plot in a &le called
`foo.ps'(-?)
#e pseudo%device MCJ' is special (see section Meta). t is used to support !eta&les" which allow
you to save a plot as you display it" and &nally send it to a diUerent device.
Cspecially for hardcopy devices" you !ay have to specify which one you want" e.g. +,203,
postscript latypus. :ecause this depends on how your local graphcap was con&gured"
youDll have to see your =uru for guidanceO see section #e Stdgraph =raphics 3ernel.
9hen a device is opened" it is set to the current (JIPC" L9C=BJ" and LJIPC" and the proper
aspect ratio is chosen to !ake te.t and ploted points look nice. t also looks for an entry
foreground in your `.sm' &le" and uses it as the default colour for the device (this overrides
any default that the device driver !ay have speci&ed). #e device driver !ay (or !ay not) choose
to honour a bac/ground entry as well. #ese colours !ay be speci&ed either as na!es (see
(JIPC)" or the background colour !ay be given as a set of three nu!bers" which are interpreted
as the red" green" and blue intensities in the range ? % -GG. So!e devices !ay allow you a wider
selection of background na!esO for e.a!ple the ;windows driver allows any na!e fro! the
colour database.
f you want to use so!e foreground colour that 3@?, doesnDt usually understand you !ust
de&ne it before opening the device. Qor e.a!ple" a)er de&ning the !acro
add_colour $ 77 add a colour to the standard set. Lsage: name r g b
3@?,BR. #** . #** . . . #** #** H#T O M
#*)CDR. #** . . #** . #** . #** H&T O M
#*)CR. #** . . . #** #** #** . H$T)
ctypeBRdefault white blac/ red green blue cyan magenta yellow H"T
you could say add_colour gray #.. #.. #.." a)er which YgrayD would be a perfectly
good YforegroundD colour.
,iUerent ways of ploting to the sa!e device (e.g. portrait or landscape) are acco!!odated by
using diUerent drivers (e.g. postport and postland for postscript devices) rather than so!e
!agic co!!and to SM.
@odevice$ #e @7LL device
:orland$ :orland =raphics on a P(
Meta&le$ =raphics Meta&les
*S+-$ *S+- Presentation Manager
Postscript$ Postscript ,evices
S=$ #e Silicon =raphics (and RS%X???) ,evice
Stdgraph$ #e =eneral ,evice ,river" using =raphcap
Sun8iew$ #e Sun8iew (and Sunwindows) ,evices
Jk$ ' Jk 9idget
7ni.P($ #e 7ni.%P( ,evice
MS%9indows$ P( =raphics under MS%9indows
8';%7S$ 8';+8MS 7SE device
;9indows$ #e ;%9indows ,evices (;<? and ;<<)
#e @7LL device
,C8(C nodevice is always availableO it is a bit bucket where plot co!!ands !ay be sent
never to be seen again" the e/uivalent of /dev/null (under uni.) or nl: under 8MS.
t is useful because it is always availableO itDs the current device when SM is started. :ecause SM
sub!its plots only when the current device is closed" and because opening nodevice closes the
current device" it is also used by the hardcopy co!!and (in fact hardcopy is a !acro that
e.pands to +,203, nodevice).
:orland =raphics on a P(
SM works on a P( running ,*S either by using :orlandDs graphics or windows (see the section
on MS%9indows)O this section describes the for!er. SM was ported to run under ,*S by Laurent
:artholdi" who also wrote the := and MS%9indows device drivers. Be gets all the credit for the
P( version of SM" but of course he is not responsible for any re!aining bugs (so!e of which we
al!ost certainly created while !erging the P( and regular versions).
#e graphics drivers" the `.bgi' &les" are assu!ed to be in a directory given by the ,*S
4A0?8G environ!ent variableO alternatively you can specify a bgipath variable in your
`.sm' &le.
#e ,C8(C co!!and takes two optional argu!ents$ +,203, bgi devtype mode. #e
&rst" devtype" is the type of hardware that you are running. f you want the driver to try to
&gure this out for itself" use +,203, bgi detect (this is the default if you o!it devtype
entirely)O for a listing of possibilities say +,203, bgi V. #e second argu!ent" mode"
deter!ines how SM switches between screen and graphics !odes. Iour options are none" swap
(the default)" or switchO e.peri!ent to see which works beter for you. 't present" a certain
a!ount of YsnowD is le) at the top of the graphics screen. #is is very dependent on the details of
your graphics card" and we see no general way to prevent its appearance.
*nce you have decided what options you like best" you can set a variable stdmode in your
`.sm' &le (e.g. to detect swap) to save yourself so!e typing.
#ere is a Yhot keyD" 8--S"" that can be used to toggle between te.t and graphics !ode.
#e current return value of the function coreleft is available as Hcoreleft (which is like
any other +,S09, var U variable).
*S+- Presentation Manager
#e *S-PM driver is used to display graphics in a Presentation Manger graphics window under
*S+- v-.. (you should specify your ter!inal as os#pc). Jwo optional argu!ents are currently
supported$
-n
,isable all backing for the graphics window. #is will signi&cantly increase the drawing
speed" but the contents of the graphics window will not be redrawn when portions of the
window are uncovered or when the window is resiSed.
-gJ!G
Specify the window geo!etry. #e 9 and B para!eters should contains the 9,JB and
BC=BJ of the graphics window in pi.els.
f ,C8(C os-p! is speci&ed without the %g9.B argu!ent the graphics window will be created
the sa!e siSe as the last previously displayed window. f this is the &rst ti!e the graphics window
is created it will default to X?? . >?? pi.els.
Qor e.a!ple"
+,203, os#pm -g%..!*..
.
.
.
+,203, os#pm -n
#e &rst ,C8(C state!ent will produce an W?? . G?? pi.el graphics window with backing
enabled. #e second will again produce an W?? . G?? pi.el window but with no backing.
=raphics Meta&les
's described elsewhere (see section Meta) SM can save graphics co!!ands to a !eta&le while
producing a plot on your screen.
Postscript ,evices
Strictly speaking" there are no postscript devices" !erely postscript drivers in stdgraph (see
section #e Stdgraph =raphics 3ernel). *n the other hand" SM is able to drive postscript printers
in a totally transparent way" so a user can think of SMDs postscript capability as discrete drivers. n
the following descriptions the argu!ents to the device co!!and are referred to as H"" H#" and so
on. 'liases are listed in parentheses a)er the device na!e" so post_colour can also be called
post_color. #ose currently supported are$
postscript D?5113:0?)
#e basic driverO produces W.Winch output on the default printer.
postport D?51?5:)
' full%page portrait%!ode plot.
postland D?51-89+)
' full%page landscape%!ode plot.
post_colour Dpost_color)
Like postscript" but generates a colour postscript plot" and sends it to a printer called
ps]colour?.
blac/postscript
Like post_colour" but uses a black background.
postfile Dpostencap)
Like postscript" but generate an encapsulated postscript &le in E<.
postlandfile
Like postland" but generate an encapsulated postscript &le in E<.
post_remote Dpostscript_remote)
Like postscript" but prints to a printer H# on host H".
postland_remote
Like postscript" but prints to a printer H# on host H".
postport_remote
Like postport" but prints to a printer H# on host H".
Qor an e.a!ple of de&ning your own postscript device that takes a printer na!e as an argu!ent"
see section #e Stdgraph =raphics 3ernel.
#e Silicon =raphics (and RS%X???) ,evice
#e Silicon =raphics device driver works. f you read this and want !ore docu!entation" send
!ail to us and weDll get to it.
#e =eneral ,evice ,river" using =raphcap
:y far the !a4ority of devices that SM supports are driven through the stdgraph deviceO a
partial list includes te/$."." te/$."#" pericom" selanar" (or hire\ )" versaterm (or
macvt )" vt)$. (a vt<?? with retrographics )" vt#$. in RC=S !ode" hard$."# or
hard$.". for a tek>?<? that really has no decent ascii !ode" te/$.#*" wyse"*(*" cit$"$a
or ><>a. 9e also support graphcap drivers for Postscript" AMS" and L@?5 laser printers" (device
na!es postscript> qms and ln.&). Stdgraph can also cooperate with raster devices" for
instance to plot on a lineprinter.
Qor the stdgraph (i.e. default) device driver the &nal word on the co!!and line (if present) is
taken to be the na!e of a &le to receive the output that would ordinarily go to the screen" so if
you say
device graphon outfile
and then create a plot nothing will see! to happen. Bowever" if you close the device and write
`outfile' to the ter!inal (!aybe using +passall if you are running 8MS) your plot will appear.
n addition" any word beginning with a colon will be taken to be part of a graphcap entry (see
section #e Stdgraph =raphics 3ernel)" and prepended to the entry in the graphcap &le for your
chosen device. Qor e.a!ple" if you wanted to save your postscript output in a &le you could say
dev postscript N:1@Becho Sile is HS:N
which would replace the 1@ entry that sent the output to the printer by a new one that !erely
tells you what the &le is called. f youDd prefer to give it a !e!orable na!e" you could say
dev postscript N:1@Becho Sile is MHS:5SBname:N
or
dev postscript :1@[: :5S[: name
(it doesnDt !ater if the entries are all in the sa!e word). #e for!er rede&nes the output &le 5S
to be 6na!e6" and !akes 1@ tell you so. #e later disables both 5S and 1@" so the generated
postscript would ordinarily go to the ter!inal (4ust like any other graphics ter!inal)" but a &le
`name' is speci&ed" so the output is sent there instead.
f you &nd yourself fre/uently wanting to use a custo!ised stdgraph device" this !echanis! can
beco!e rather tediousO youDd rather si!ply invent the device and be done with it. #e proper way
to do this is to create a local graphcap &le (see section #e =raphcap Qile)" and add your new
device to it. Qor e.a!ple" if you wanted to de&ne a postscript device that took the na!e of the
printer as its argu!ent" youDd put an entry
mypostscriptUli/e postscript> but specify the printer as its argument:M
:1@Blpr -r -?H" HS:3Bpostscript:
in your &le" and !errily proceed with !aking beautiful plots using +,203, mypostscript
fred. f you always want to use your new device you could call it postscript and in eUect
rede&ne the old postscript device (note carefully that said :3Bpostscript: not
:tcBpostscript:O if hadnDt" an in&nite loop would have resulted).
#e Sun8iew (and Sunwindows) ,evices
's the sunwindows driver is now obsolete" and !ay well disappear in so!e future release" you
should use the sunview driver instead. f you insist on using the old driver" it !ust be run fro!
within a gf.tool.
#e Sun8iew window driver supports a subset of the usual Sun8iew co!!and line argu!ents"
speci&cally$
-JG
Su!!arise options
-Ji
*pen window as an icon
-Jl label
Specify label for the window (default$ SM)
-Jn
,onDt label window
-J? ! y
Position of icon
-Jp ! y
Position of window %9s w h SiSe of window
#e standard Sun8iew popup Yfra!eD !enu has been !odi&ed to allow you to erase the graphics
screen. t is perfectly safe to use the !enu to quit the graphics window" in this case the ne.t
device sunview co!!and will create a new one. f SM thinks that the window is active when
you try to kill it" it will warn youO failing to believe it !ay result in a cascade of co!plaints to the
console window. #ere is a bug in the cursor routine ( clai! that it is a Sun8iew bug) that !eans
that SM sees only every other key%stroke.
' Jcl+Jk 9idget
tDs possible to build SM to support a Jk widget (on uni. bo.es onlyO the SM Jk graphics are based
on ;<<). f this interests you" specify the E device when building SM" then build tkSM in the
callable directory and say
t/1= smt/.tcl
to run an e.a!ple that we wrote. #e source code should be easily !odi&able to add features that
your application needs.
#e 7ni.%P( ,evice
*n a 7ni.%P( +,203, upc opens a window of 5?> by <H- pi.els" which is about > by > inches.
Jo /uote the author (Peter Jeuben" teubenLastro.u!d.edu)"
<. #is whole 7ni.pc version is an e.peri!ental version" take it as is" it works on !y
con&guration" but !ay not work on yours.
-. D! playing with allowing a second and third para!eter to the upc device na!e" which
would allow you to change the default siSe of 5?> by <H- pi.els (#e siSe in ; !ust be a
!ultiple of <X though). Right now have it check environ!ent variables @8??_6 and
@8??_@" but this !ay not work satisfactorily.
5. spawn windows using the public do!ain progra! YwloginD" this !ay be of so!e
i!portance if your YupcD device in SM fails.
donDt have a 7ni. P(" so canDt work on this driver.
P( =raphics under MS%9indows
#is section needs !ore workO send !ail to rhl[astro.princeton.edu.
8';+8MS 7SE device
the 8';7S driver is used to display graphics on a 8'; 9orkstation using the 8'; 7SE library
routines. #e optional ; and I para!eters specify the siSe of the graphics window ( in
centi!eters ) created on the workstation screen.
f called without the optional ; and I para!eters the graphics display window will be the sa!e
siSe as that previously displayed.
f the ; and I para!eters are not speci&ed the &rst ti!e the ,C8(C va.uis co!!and is issued"
the graphics display window will occupy <+- the height and <+- the width of the workstation
screen.
Qor e.a!ple" to create a <G c! wide . <? c! tall display window say$
+,203, va!uis "* ".
#e ;%9indows ,evices (;<? and ;<<)
#ere are two ;%9indows drivers" one for ;<? and one for ;<< and they diUer in their treat!ent
of co!!and line argu!ents. #e ;<< driver is considerably !ore sophisticated and will be treated
&rst.
#e ;<< window driver (device !"") supports a subset of the standard co!!and line argu!ents"
speci&cally (the ;%resources na!es appear in parentheses at the ends of the descriptions)$
7geom
Specify icon geo!etry (.icongeometry)
-bd n
:order width (.borderwidth)
-bg colour
:ackground colour (.bac/ground)
-device n D.device)
7se ;<<%device n
-cmap
7se a private colour !ap for this device (.colormap)
-colormap
7se a private colour !ap for this device (sa!e as %c!ap). (.colormap)
-colourmap
7se a private colour !ap for this device (sa!e as %c!ap). (.colormap)
-cmap
7se a private colour !ap for this device (.colormap)
-display name
@a!e of display to open (.display)
-fg colour
Qoreground colour (.foreground)
-fn fontname
@a!e of hardware font to use (.font)
-geometry geom
Specify window geo!etry (.geometry)
-help
Su!!arise options
-/bdfocus
Preserve keyboard focus (the sa!e as %focus). 9ithout this" so!e window !anagers transfer
focus to the graphics window when it is createdO probably not what you want
(./bdfocus)
-iconic
*pen window as an icon (.iconic)
-name name
-ndevice n D.ndevice)
'llow up to n ;<< devices
-nocurswind
,o not show the cursor position while in cursor !ode (sa!e as %nocw) Specify na!e of
window (.name)
-preopened display_id:window_id
Specify device and window idDs
-synchronise
Synchronise with server (debugging only) (.synchronise)
-title title
Specify title of window (.title)
9here geom is a standard geo!etry string of the for! J!GO-6O-@" and the preopened
option is for a progra!!e calling SM non%interactively. 'll options !ay be abbreviated" so
device !"" -i 7-"O" -g *"#!*"#O"..O"..
speci&es that the graphics window be created as an icon in the top right hand corner of the
screen" and that the real window should be G<-0G<- and positioned near the top le) corner.
SM is able to open !ore than one .<< device (by default it can handle G)O see the -device and
-ndevice options. Iou can say device !"" -dev O to switch to the ne.t open ;<< deviceO
device !"" -dev - switches to the previous one.
f you want to raise your graphics window so that you can see it" you can either use the window
!anager" reopen the device (dev !"")" erase the screen" or use the ?8A, co!!and.
*n hardware that doesnDt support a backing store (or if you have chosen to disable a backing store
when co!piling the ;<< driver) the screen will only be refreshed when it is active or when SM is
waiting for input. f your operating syste! doesnDt support the selectD) syste! call you !ay
be even worse oU" but reopening the device (device !"") should still result in the screen being
redrawn.
f you use 3@?, B e!pr to ask for !ore than a s!all nu!ber of special colours (see section
(type)" you will probably need to specify -cmap to get your own colour !apO if you donDt SM
!ay well co!plain about being unable to allocate colours.
#e ;<? driver is known as !window" and you can optionally specify a device to open" and a
window ," on the co!!and line. Qor e.a!ple
device !windows +,203, uni!:.
will open a graphics window on device uni!:.. (Iou can optionally include a 0+ number a)er
the ,C8(C if you are calling SM fro! a progra!!e" and have already opened the window). #e
;<? driver doesnDt bother to re!e!ber any hardware characters that you !ay have writen on a
graph" so that if you refresh the window they wonDt appear. f this worries you can" as always"
force the so)ware character set with an e!pand "...".
#ither
1ynta!: +0G,: ! y min ma! fac
=enerates a dithered represention of an i!age read by the M'=C co!!and (see section !age).
#e vectors . and y are set to points whose density is proportional to the i!ageDs intensity (only
values between !in and !a. are considered).
'ny pi.els whose value is 9a9 are ignored" as are any whose value e/uals the SM variable
Hmissing_dataO by default this is so!e very large nu!ber.
#e dithering algorith! used is Qloyd%Steinberg" and each pi.el of the i!age is represented by (up
to) fac0fac points" where (of course) all fac0fac points are only used for intensities greater than
e/ual to !a.. Cven the case fac `` < can produce nice output for suitably sa!pled i!ages.
#e resulting vectors are usually ploted as ptype " ".
'n e.a!ple of dithering an i!age would be$
0=8A, image_file
+0G,: ! y . &... $
?@?, " "
?5091 ! y
*f course" you can be !ore sophisticatedO for e.a!ple$
define min &... define ma! ).... define gamma #
set ii B imageYC>CQ
set iiBDii R Hmin V . : ii T Hma! V " : Dii-Hmin)/DHma! - Hmin)
set imageYC>CQ B D" O Hgamma)Cii/D" O HgammaCii)
dither ! y . " $
define v local foreach v D! y) ;
set HvBHv O ..*CrandomDdimenDHv))
<
?5091 ! y
or
+0G,: ! y . &... "
e!pand ..& O 0=8A,D!>y)/&...
?@?, $ &
?5091 ! y
See also M'=C for reading i!ages" (*@J*7R for contouring the!" M'=C (7RS*R for using
cursors to get values fro! i!ages" M@M'; for &nding the !ini!u! and !a.i!u! of i!ages"
and 'rith!etic for e.tracting cross%sections of i!ages.
#o
1ynta!: +5 variable B start> end Y > incr Q ; commands <
9hile the value of Hvariable runs fro! start to end" the co!!ands are e.ecuted. #e
optional incre!ent defaults to <. t is not possible to change the value of the loop variable inside a
loop (or at least it has no eUect on the ne.t iteration). Jo break out of a loop you have to break out
of the current !acro as well with RCJ7R@ (see section ,* and Q*RC'(B loops" 9BLC loops"
and Q state!ents).
Qor e.a!ple"
+5 iB">".>..* ; J:0, 189+8:+ Hi <
will write " ".* # #.* ... ". to the ter!inal. #e co!!ands !ay be spread over several
lines.
#ot
1ynta!: +5
,raw a point at the current location (set by RCL*('JC" ,R'9" etc.) in the style deter!ined by
PJIPC. #e pointDs siSe and rotation are governed by C;P'@, and '@=LC.
Jo insert dots into labels" it !ay be easier to use the YJe;D de&nition Mpoint or Mapoint which
inserts a dot of a speci&ed PJIPC into a string (see section SMDs Qonts).
#raw
1ynta!: +:8J 7" 7#
+:8J D 7" 7# )
,raw a line fro! the current position (set with" for e.a!ple RCL*('JC) to (^<" ^-) in user
coordinates. f the parentheses are present" use screen coordinates.
*dit
1ynta!: ,+0 function /ey_stro/es
:ind a function to a set of /ey_stro/es for the editor. Qor e.a!ple" ,+0 refresh
control-: !akes the control-: key refresh the screen. ' co!plete list of functions is given
in the Y(hanging 3ey%:indingsD section in the !ain part of this !anual (see under YbindingsD in
the inde.). Cach character in the key se/uence can be speci&ed as a character" e.g. YaD or the single
character Ycontrol-8D" as Ycontrol-cD representing the single character control-c as the
two character se/uence YID followed by YcD" or by YMnnnD where nnn is an octal nu!ber (e.g.
,+0 refresh M.##).
n order to use !ultiple key se/uences (e.g. control-8control-4control-3) you !ust
&rst unde&ne any sub%se/uences" in this case control-8 and control-8control-4" by
!aking the! illegal %% ,+0 illegal control-8.
See :,8+ for how to de&ne a set of keys fro! a &le" and E,@ for how to de&ne keys to e.ecute
co!!ands.
*nvironment 6ariables
,nvironment D`sm') 2ariables
SM environ!ent variables are de&ned in `.sm' &les" which are searched for along a path which
typically consists of the current directory" your ho!e directory" and then so!e syste! place. Iou
can specify your own search path by seting the environ!ent (8MS$ logical) variable 1=?8G. f
b appears in a path it is interpreted as your ho!e directory unless you speci&ed -u 98=, when
starting SM" in which case it will be interpreted as @'MCDs ho!e directory instead. 'lternatively"
you can specify the na!e of the environ!ent &le using the Y%fD Kag on the co!!and lineO if it
starts with a `/' it will be taken to be an absolute path na!e" otherwise it will be taken relative
to the current path.
f you invoke SM with the -f or -u Kags" the are not passed on to raster devices" so if you plot to
a device that invokes rasterise it will use the .sm &les speci&ed by H1=?8G.
Cach line of the &les is taken to consist of a variable na!e" and the rest of the line which is taken
to be its value. 'ny variable !ay be accessed using the ,CQ@C name : co!!and" which
de&nes name fro! the environ!ent &le.
(o!!ents run fro! Y^D to the end of the line. f the &rst character of a line is a YLD or Y1D the
na!e is taken to start with the second character. ' YLD !eans that the entry isnDt present" and
that SM should stop searching the path for it. ' Y1D !eans that SM should keep on searching the
current `.sm' &le" and then the rest of the search path" looking for !ore entries with the sa!e
na!e. f it &nds one" the second value is added to the end of the &rst (and if the second occurrence
also had a Y1D speci&ed the search continues).
So!e entries in the environ!ent &le are special to SM" although you are free to use the! to your
own ends as well. Qor !ost of those for which SM is only interested in whether the variable is
de&ned" a value of ? !eans that it shouldnDt be de&ned. #e variables are$
bac/ground
#e background colour for plots
case_fold_search
f non%Sero" !ake searches case insensitive
default_font
#e default font for labelsO you can also set this interactively" e.g. e!pand "..."
define default_font NMoeM&N.
device
Iour initial graphics device
edit
' &le of keybindings to read (see section (hanging 3ey%:indings).
fan_compress
'pply fan co!pression when connecting lines. #is was donated by a user" and is intended
to reduce the nu!ber of lines actually ploted to the deviceO whether it is useful is not clear.
#e reference is /000 1omputer 2raphics and 3pplications* March '454* 67aster Plots by 7an
8ata91ompression#* by R&3& 7owell and 8&8& Mceil.
file_type
#e type of -%, i!age for the M'=C co!!and
filecap
#e &lecap &le to use (default$ sa!e as graphcap)
line_up_e!ponents
Qorce an e.tra space before single%digit e.ponents in a.is labels
fonts
#e na!e of the binary fonts &le
foreground
#e foreground colour for plots
graphcap
#e graphcap &le to use
help
#e help directory
history
#e length of the history list (default$ W?)
history_char
#e character used to recall co!!ands (default$ [)
history_file
Qile to save history in
macro
#e default !acro directory
macro#
Iour private !acro directory
missing_macro_continue
f de&ned" a reference to a !issing !acro isnDt a synta. error
name
#e na!e SM calls you by
noclobber
Refuse to overwrite e.isting &les with M'(R* 9RJC or PR@J.
overload
f non%Sero" overload so!e co!!ands
printer
#e default printer (see hcopy and h!acro)
prompt
#e initial value of SMDs pro!pt
prompt#
#e initial value of SMDs secondary pro!pt
remember_history_line
Re!e!ber which line you last reused
save_file
,efault &le to save a SM session in
save_read_ptr
Save the position of the read pointer between RC', co!!ands
temp_dir
#e directory for te!porary &les
term
,efault ter!inal" over%ruling ,:=
termcap
#e &le describing ter!inals to SM
e6_strings
7se Je;%style strings for labels
tracebac/
Print the !acro stack following an error
uppercase
,e&ne uppercase versions of so!e !acros
!_gutter
y_gutter
Modify the spacing between windows when using the 9@,*9 co!!and. (#ese are not
actually read fro! the `.sm' by the default startup !acro" you have to set the! yourself).
7nder 7ni." you should o!it the termcap entry" or point it at Y+etc+ter!capD. 'lso under 7ni."
SM knows how to look up your na!e" so you can o!it the name entry. f you try to use a na!e
with !ore than one word" SM will use the &rst so youDll have to call yourself Y!y]lordD rather
than Y!y lordD (the Y]D will be replaced by a space).
So!e of these are used directly by SM (e.g. help" fonts" but so!e are !erely used by the
startup !acro to set the initial value of SM variables (e.g. e6_strings" file_type).
*ther na!es !ay be used by the default startup !acro" e.g. macro# to specify a private
!acro directory or term to specify the ter!inal that you are using. See the discussion of
startup under Yuseful !acrosD.
*rase
1ynta!: ,:81,
CR'SC erases the graphics screen. #e !acro era erases the screen without appearing on the
history buUer. f you want to start a new output page on a hardcopy device use the P'=C
co!!and.
Iou !ay be able to erase individual lines with LJIPC CR'SC" if you can you should look at the
!acro undo.
f the variable raise_on_erase is set and false" the graphics window wonDt be deiconi&ed and
raised when it is erased. Iou !ay set this variable in your `.sm' &le.
*rrorbar
1ynta!: ,::5:48: J5:+" J5:+# e!pr 09,A,:
CRR*R:'R is analogous to P*@JSO it draws one%sided error bars on all points de&ned by
vectors J5:+" and J5:+#" where the length of each errorbar is set by the corresponding value
in e!pr. 09,A,: is < to put the bar along the 1. direction" - for 1y" 5 for %." and > for %y. 7se
C;P'@, to govern the siSe of the caps. n fact" instead of either or both of J5:+" and J5:+#
you can use an e.pression in parentheses" for e.a!ple CRR*R:'R DlgD!)) DlgDy)) "#.
".
See also the !acros ec and err for backwards co!patibility with Mongo" and error_! and
error_y to produce (sy!!etrical) two%sided errorbars. #ere is also a !acro logerr to draw
errorbars on logarith!ic plots.
*+pand
1ynta!: ,6?89+ e!pr
C;P'@, e.pands all characters and points" its default is <.?. @ote that the C;P'@, factor is used
in deter!ining the plot window siSe in the 9@,*9 co!!and. #is !eans you should declare
your C;P'@, siSe to SM (if other than the default) before you use 9@,*9. #e current value
of C;P'@, is available as a +,S09, e!pand U.
f C;P'@, is set to e.actly <" and '@=LC is e.actly ?" then SM will use hardware fonts" when
available" in writing labels. #is is faster" but if you donDt like it say 6C;P'@, <.???e?<6" or
6'@=LC ?.???e ?<6" or use a \r e.plicitly to select the ro!an font.
C;P'@, can in fact be given a vector of values" which are used for each point in a P*@JS
co!!and. #is supersedes the use of a fractional PJIPC (although we still support it as a /uaint
anachronis!). 7sing vectors for both '@=LC and C;P'@, !akes it easy to draw a vector &eld"
see (for e.a!ple) the vfield !acro. f !ore points are speci&ed than the di!ension of e.pr" the
&rst ele!ent will be used for the e.cess.
'ft
1ynta!: SS n pe!pr" pe!pr# J5:+" J5:+
Qourier transfor! - vectors (treated as the real and i!aginary parts of a co!ple. vector)"
returning the answer in the two vectors J5:+" and J5:+#. #e input vectors !ay be the na!es
of vectors or e.pressions in parentheses. #e direction is speci&ed by n" either 1< for a forward
transfor!" or j< for an inverse.
#e di!ension of the vectors need not be a power of -" but the transfor! is !ore e2cient if it is.
#e worst case is when n is pri!e" in which case this co!!and perfor!s a slow Qourier
transfor! in -(n:%) ti!e.
'oreach
1ynta!: S5:,83G variable D list ) ; commands <
S5:,83G variable ; list < ; commands <
S5:,83G variable J5:+ ; commands <
n the &rst two for!s" the value of variable is set to each ele!ent of list in turn" and then the
co!!ands are e.ecuted. 'n e.a!ple would be
var D alpha # gamma ) ; J:0, 189+8:+ Hvar <
which would write alpha" #" and then gamma to the ter!inal (see section ,* and Q*RC'(B
loops" 9BLC loops" and Q state!ents).
#e for! with _Z can be useful if you want the list e.actly as you type it" for e.a!ple
S5:,83G f ; .." Hdate < ; echo Hf <
#e for! Q*RC'(B variable 9*R, ... is used to iterate over a vector" either arith!etic or
string. Qor e.a!ple"
1, strB;1orbus 8ucuparia +avid =onger<
S5:,83G f str ; echo Hf <
t is o)en useful to de&ne the Q*RC'(B variable to be L*('L (see section ,e&ne)" e.g. ,CQ@C
f L*('L in the last e.a!ple.
'ormat
1ynta!: S5:=8 Y !-format-string y-format-string Q
'llow the user to specify the a.is tick label for!ats. #e for!at should be given as a standard (
(e.g. d>.<g) or Qortran (e.g. Q<?.>). #is for!at will be in eUect until unset by issuing the Q*RM'J
co!!and with no argu!ent" in which case SM will &gure out the best for!at for you" or until
you issue a new Q*RM'J co!!and with new for!at strings.
f a for!at is speci&ed as 6?6" the for!at string is le) unchangedO if it is given as 6<6" the default
value is reinstated. #e co!!and Q*RM'J < < is thus e/uivalent to Q*RM'J.
;rid
1ynta!: A:0+ Y 09,A,:" Y 09,A,:# Q Q
=rid draws a grid at either !a4or ( 09,A,:" B . ) or !inor ( 09,A,:" B " ) tick!arks
within a bo.. #e default is 09,A,:" B .. Iou can use 09,A,:# to specify only drawing an
.% or y%a.is grid$ if 09,A,:# is o!ited or ?" draw both . and yO if itDs < only draw .O if itDs -
only draw y (5 is e/uivalent to ?).
Help
1ynta!: G,-? Y word Q
#e BCLP co!!and tries to help you with word. f possible" it prints the entry fro! the help
directory speci&ed in your `.sm' &le" the de&nition of word if itDs a !acro" the value of word if
itDs a variable" and the BCLP string if it is a vector. f none of these are de&ned" BCLP confesses
defeat. Iou !ight want to use the abbreviation h which will not appear on your history list (or
you could overload help itself). Qurther discussion of the G,-? co!!and is given in See section
#e Belp (o!!and.
f word is o!ited it is assu!ed to be G,-?.
Iou can associate a help string with a vector with the co!!and 1, G,-?.
See also 'PR*P*S and LSJ.
Histogram
1ynta!: G015A:8= J5:+" J5:+# Y 0S De!pr) Q
BSJ*=R'M connects the points in vectors J5:+" and J5:+# as a histogra!. #e ith bin of
the histogra! is taken to run fro! D!Yi-"Q O !YiQ)/# to D!YiQ O !YiO"Q)/#O for the
case of e/ually spaced .%values" this reduces to saying that the . values are the bin centres.
f the Q clause is present" only use those points for which e!pr (see the section on vector
arith!etic) is true (i.e. non%Sero). *nly contiguous parts of the histogra! are connectedO if you
donDt want this behaviour" say so!ething like
set l B D\BB") V " : . set !B!! ifDl) set yyBy ifDl) histogram !! yy
n fact" either or both of the J5:+s !ay be replaced by Yparenthesised e.pressionsD" i.e.
e.pressions in parentheses. Qor e.a!ple"
G015A:8= ! D# O y)
to plot . against % ; y. #ere is a !acro barhist for drawing bar charts. See 'rith!etic for how
to convert vectors of data into histogra!s" and 1G8+, for how to shade the!.
#e for! with 89A-, is used for drawing a histogra! of y against ." when the averaging is done
in the y% not the .% direction. (o!pare
set y B ;. & " & " .< set ! B-..#*>-#.(*>-..* lim y !
,:81, bo! histogram y !
with
,:81, bo! histogram angle y !
History
1ynta!: G015:@ Y - Q
List the current co!!ands stored in the buUer. Qor details on the history syste!" see section
(o!!and Bistory. 9ith the optional !inus sign" the history list is printed backwards which is
probably what you want if you are thinking of it as a set of co!!ands to repeat. tDs possible to
overload list to be a synony! for BSJ*RI" see YoverloadingD in the inde..
5dentification
1ynta!: 0+,90S038059 str
,C@JQ('J*@ puts the current date and ti!e followed by str outside the upper right hand
corner of the plot region. ('ctually" identification is a !acro" which RCL*('JCs to a point
above the right%hand a.is" and half way between the top a.is and the top of the page" and then
writes a string with a P7JL':CL >.) @ote that the variable Hdata_file is set to the na!e of
the current data &le" and Hdate always e.pands to the current date and ti!e.
5f
1ynta!: 0S D e!pr ) ; list <
0S D e!pr ) ; list < ,-1, ; list <
f the e!pr is true (non%Sero)" then the list of co!!ands are e.ecuted" otherwise the ,-1,
clause is e.ecuted. Qor various co!plicated reasons" the ,-1,less co!!and !ust end with a
newline (or as usual a \n) (see section ,* and Q*RC'(B loops" 9BLC loops" and Q state!ents).
*ne co!!on use for Q tests is when the e.pression tests if a variable has been de&ned" e.g.
0SDHVfile_name BB .) ; +,S09, file_name V <
within so!e !acro.
@ote that you can write Q%CLSC Q%CLSC blocks as
ifD':obert' BB '?atricia') ;
echo 1omething's wrong
< else ; ifD'?atricia' BB ':alph') ;
echo 1till wrong
< else ;
echo Ao @an/ees
<<
#e usual SM logical operators ^^ and UU do not Yshort%circuitD" unlike e.g. ( (9hyT :ecause they
are intrinsically vector state!ents" so SM cannot si!ply evaluate the le) hand side of the
e.pression and" based on the result" decide to skip the right). Qortunately" in a scalar conte.t you
can use the 89+ and 5: operators instead" and they don#t evaluate the right hand side if its value
is irrelevant. n other words"
ifDHVone ^^ Hone BB ") ; echo 5ne < else ; echo 9o-one <
generates an error if thereDs no Hone variable$
variable one is not defined
1ynta! error at NBN
if D . ^ ^ B
I
ifDHVone 89+ Hone BB ") ; echo 5ne < else ; echo 9o-one <
is *3.
#ere are also co!!ands using Q to de&ne vectors conditionally (see SCJ)" and to plot parts of
vectors (See (*@@C(J" BSJ*=R'M" P*@JS).
5mage
1ynta!: 0=8A, YnQ file
0=8A, YnQ file !min !ma! ymin yma!
0=8A, YnQ file Y C : CQ
0=8A, YnQ file Y !"> !" : CQ
0=8A, YnQ file Y C : y.> y"Q
0=8A, YnQ file Y !"> !" : y.> y"Q
0=8A, D n! > ny )
0=8A, D n! > ny ) !min !ma! ymin yma!
0=8A, 3L:15:
0=8A, 3L:15: J5:+ J5:+ J5:+
0=8A, +,-,,
0=8A, +,S09, variable value
J:0, 0=8A, J5:+
Read an i!age fro! file" optionally specifying the range of coordinates covered by the data
values. f you do not specify the! they will be taken to be . n!-" . ny-" where n. and ny
are the di!ensions of the i!age. f you specify D n!> ny ) instead of a &lena!e an e!pty
i!age of the desired siSe will be created (see section Jwo%,i!ensional =raphics).
f you specify n the nDth M'=C e.tension of a &ts &le will be readO the pri!ary data unit (i.e. the
start of the &le) is n `` ?.
f you want to read part of an i!age you can specify the desired part using g ... $ ... hO (n.b. those gh
are part of the co!!and you type" not optional para!eters). f you want the whole range use 0"
otherwise a pair of ?%inde.ed integers. n other words"
0=8A, file
and
0=8A, file Y C : C Q
are identicalO you can read only the &rst <?? ele!ents of the &rst row of an i!age into a vector
with
0=8A, file Y .>'' : .>.Q 1, !B0=8A,YC>CQ
M'=C (7RS*R is identical to the (7RS*R co!!and (see section (ursor)" e.cept that value of
the i!age under the cursor is returned in addition to the positionO M'=C (7RS*R 9*R,
9*R, 9*R, is e/uivalent to (7RS*R 9*R, 9*R," but it also generates a vector of i!age
intensities.
M'=C ,CLCJC will forget the current i!age and levels.
#e &le for!at is speci&ed using a `filecap' &le" si!ilar to `graphcap'" and the entry to
use in this &le is given by the variable file_type (see section Jwo%,i!ensional =raphics). #e
&le is unfor!ated" and should start with two integers giving the di!ensions of the data array"
followed by the data values writen row by row.
#e current entries in `filecap' support &les writen fro! (" or fro! fortran in one of a
variety of ways. Qor ( progra!!ers" ,CQ@C file_type 3" the &le should be writen with
open+write+close. Qor Qortran" there are a variety of options depending on operating syste!s and
the details of how the &le was opened. 7nder 7ni." si!ply ,CQ@C file_type uni!. 7nder
8MS you have a choice. Iou can either create a variable record type &le
(recordtypeB'variable' in the 5?,9 state!ent) and choose file_type vms_var" or
set recordtypeB'fi!ed' choose recl to be the .%di!ension of the array and de&ne
&le]type to be vms_fi!ed. Iou must set recordtype in one of these two ways. :y default"
data is taken to be real (Koat in ()" but this can be overridden in the &lecap entry for a &le type.
#ere is also an entry for QJS &les (QJS is the YstandardD i!age transport for!at for
astrono!ical i!ages). f you want to use a diUerent &le type youDll have to learn about
`filecap' (see section Jwo%,i!ensional =raphics)" or else see your local SM =uru.
So under 8MS either your code should look like (&le]type ` vms_var)
integer i>X
real arrD"..>".)
c
openD#>fileBfilename>formB'unformatted'>recordtypeB'variable')
i B "..
X B ".
c now write your data into arr
writeD#) i>X
writeD#) arr
end
or" with &le]type ` vms_fi!ed"
integer i>X
real arrD"..>".)
c
openD#>fileBfilename>formB'unformatted'>reclB"..>recordtypeB'fi!ed')
i B "..
X B ".
c write your data into arr here
writeD#) i>X
do " XB">".
writeD#) DarrDi>X)>iB">"..)
" continue
end
7nder 7ni." either of these progra!!e frag!ents would work a)er o!iting the record
infor!ation fro! the open state!ent.
See section Set for an e.a!ple of creating an i!age fro! scratch or a vector.
f you have an i!age de&ned (using the M'=C co!!and)" you can e.tract a cross%section using
the 1, name B 0=8A, D e!pr > e!pr ) co!!and. #e two e.pressions give the (."y)
coordinates where you want the i!age to be sa!pled. Qor e.a!ple"
1, !B.>">.." 1, \B0=8A,D!>..*)
will e.tract a horiSontal cross section through an i!age. Iou can also use 0=8A,Ye!pr>e!prQ
to e.tract values via their indices" where either or both of the e!prs !ay be C !eaning 6all
values6O this is especially useful to those who like to use SMDs i!ages as a way of reading binary
data.
'n e.a!ple of creating an i!age fro! scratch would be
image D*">%") . " . "
define 96 image define 9@ image
set i!B.>H96CH9@-" set iyBi!
set iyBintDiy/H96) set i!Bi! - H96Ciy
set !Bi!/DH96-") set yBiy/DH9@-")
set imageYi!>iyQ B sinD!)CsinDy)
f you have a vector v of siSe 96C9@" you can say
set imageYC>CQ B v
to convert it to an i!age. #e data is arranged row%by%row (i.e. in the fortran order).
f you wanted to e.tract the top row of an i!age" a)er
define 9@ 0=8A, define 96 0=8A,
set i!B.>H96-"
you can get the top row with any one of
set rrBimageYi!>H9@-"Q
set rrBimageYdoD.>H96-")>H9@-"Q
set rrBimageYC>H9@-"Q
f you want to add <?? to every value of an i!age" you can say
set imageYC>CQ B imageYC>CQ O "..
tDs obviously prety easy to use SM to !anipulate i!ages point%by%point in this way.
Iou can write the current i!age to a &le using 9RJC M'=C &lena!e. *nly a s!all subset of
the i!ages that SM can read can be writenO currently your choices are 6(6" 6(B6" and 6QJS6O all
of these will write out Koating point values (as i!ages are stored as Koats)" and the QJS writer
assu!es that you have CCC arith!etic" in confor!ity to the QJS standard. 'll current i!age
keywords (i.e. those available via ,CQ@C na!e M'=C) are writen to the QJS headerO you can
de&ne further keywords with M'=C ,CQ@C na!e value.
9riting and reading i!ages is an space% and ti!e%e2cient way of saving+rereading vectors in a
binary for!atO if you use the QJS &le for!at (i.e. set file_type to QJS) the data will be
suitably byteswapped if necessary. Qor e.a!ple"
data file.dat
read ; ! " y # \ & <
image D&> dimenD!) )
set imageY.>CQ B !
set imageY">CQ B y
set imageY#>CQ B \
image define filename file.dat
define file_type fits
write image save.fts
and then" in so!e other SM session$
define file_type fits
image file.dat
define filename 0=8A,
set ! B imageY.>CQ
set y B imageY">CQ
set \ B imageY#>CQ
@ote well that de&ning the i!age as imageDdimenD!)> &) would be "ar less e2cient.
See also 'RJBMCJ( for how to e.tract a cross%section into a vector and ,CQ@C for de&ning a
variable fro! the i!age header. !ages !ay be displayed with (*@J*7R or ,JBCR" and
e.a!ined with M'=C (7RS*R.
7ey
1ynta!: E,@
E,@ /ey string
,e&ne a key to generate a string. #is is !ost o)en used si!ply to save typing so!e co!!on
co!!and such as edit_hist. 9ith the co!!and 3CI" you are pro!pted for the /ey to de&ne"
and the string. :ecause you are not using the history editor when you type the key" you can
si!ply hit the key that you want de&ned" type a space" and then type the string ter!inated by a
carriage return. #e other for!" where the whole co!!and appears on one line" is probably !ore
suitable for use in a !acro such as your private startup !acro (see under startup# in the
inde.). f you try entering it at the keyboard any special characters in /ey" such as CS(" will be
interpreted by the history editor so youDll probably have to /uote the /ey with control-K or
CS(%/. 'lternatively you can use [ and printing characters " or octal nu!bers" to represent the
escape characters in the sa!e way as for C,J (see section Cdit). f /ey is given as pf7 or ?S7
(where 7 is <" -" 5" or >) it will be interpreted as a special function key on your keyboard in a
ter!inal%independent way (see the description of ter!cap (see section Jer!cap %% ' Jer!inal
,atabase) to see how these keys are de&ned). 3CI de&nitions are listed along with other key
bindings by the LSJ C,J co!!and.
f the string ends in a \@" it will be e.ecuted the !o!ent that the key is struck. (@ote that this
is \@ not \n" which would have been interpreted as a newline.)
*nly <? keys can be de&ned" a)er that youDll start overwriting earlier de&nitions (this is a result of
the way that 3CI was i!ple!entedO if it is a serious nuisance send us !ail).
&abel
1ynta!: -84,- str
L':CL writes the string str" which starts one space a)er L':CL and continues to the last
non%space character" at the current location (set by RCL*('JC" etc). ')er the label is writen the
current location is on the baseline" 4ust to the right of the last character drawn. Iou can of course
use /uotes to include trailing white space. L':CL str is e.actly e/uivalent to P7JL':CL H str (see
section Putlabel).
#e stringDs siSe and angle are deter!ined by C;P'@, and '@=LC. Qor !ore infor!ation on
fonts and such like" See section ,rawing Labels and SMDs Je; C!ulation.
&evels
1ynta!: -,2,-1 J5:+
-,2,-1 e!pr
Set the levels for the (*@J*7R co!!and to be the values of the vector J5:+ or to the values of
the e.pression.
&imits
1ynta!: -0=01 J5:+ J5:+
-0=01 J5:+ @" @#
-0=01 6" 6# J5:+
-0=01 6" 6# @" @#
LMJS sets the coordinates of the plot region. 'll coordinates in RCL*('JC" ,R'9" etc" are
referred to these li!its. #e various for!s specify e.plicit li!its for the . or y a.is (6" 6# or @"
@#)" or default (specify the na!e of the vector to be used).
n fact" either or both of the J5:+s !ay be replaced by Yparenthesised e.pressionsD" i.e.
e.pressions in parentheses. Qor e.a!ple"
-0=01 . * DlnDy))
will scale the y a.is according to the logarith! of vector y (but not produce a logarith!ic a.is %
see J(3SPC for this capability).
#e current value of the !ini!u! and !a.i!u! values on the . and y a.es can be obtained with
a ,CQ@C i co!!and" e.g. +,S09, f!" U.
f the two li!its speci&ed for an a.is are the sa!e" the li!its for that a.is will not be changed.
Iou can specify that the li!its on one or both a.es have a desired range using the R'@=C
co!!and. #is co!!and aUects the perfor!ance of the LMJS co!!and. f a non%Sero R'@=C
has been set" LMJS will ensure that the upper and lower li!its diUer by that a!ount. (e.g. a)er
R'@=C # . " LMJS . " . " is e/uivalent to LMJS -..* ".* . " ). f you specify a
vector" the range is centred on the !edian value. f you have speci&ed a range" and then ask for
logarith!ic a.es with J(3SPC" you !ay get co!plaints that logarith!ic a.es are i!possible.
Si!ply unset R'@=C" and the proble! should go away.
&ines
1ynta!: -09,1 09,A,: 09,A,:
7se only lines 09,A,:" to 09,A,:# fro! the current data &le (speci&ed with the ,'J'
co!!and). f 8CR:*SC is greater than ?" the lines actually read will be reported. L@CS ? ? will
use the entire &le" which is also the default following a ,'J' co!!and. #e variables H_l" and
H_l# will be set to the &rst and last lines speci&ed.
&ist
1ynta!: -01 +,S09, Y begin end Q
-01 +,S09, U
-01 +,S09, 0=8A,
-01 +,203, Y pattern Q
-01 ,+0
-01 =83:5 Y begin end Q
-01 1,
-01 84-,
list all the currently de&ned variables (,CQ@C) or !acros (M'(R*)" optionally only within the
range begin - end . f 8CR:*SC is ? !acros beginning ^^ wonDt be listed. Iou can list the
internal variables (i.e. those such as Hf!" that track SM internal variables) with LSJ ,CQ@C i"
or by seting 8CR:*SC to be two or !ore.
LSJ ,CQ@C M'=C lists all M'=C variables (as read fro! &les with M'=C or J':LC" or
de&ned with M'=C ,CQ@C na!e val). QJS keywords are o!ited if verbose is ?. Iou can use
,CQ@C na!e M'=C to convert these to regular SM variables. #e variables listed when verbose
is ? are those writen to the headers of &les writen using the 9RJC M'=C or 9RJC J':LC
co!!ands.
LSJ C,J will list all the keybindings. f 8CR:*SC is ? only the keys that donDt generate
the!selves are listed (i.e. because ' is bound to ' it isnDt listed). f 8CR:*SC is <" in addition all
non%printing keys are listed" and if 8CR:*SC is - or greater all keys are listed. :oth the C,J and
the 3CI bindings are listed.
LSJ ,C8(C will list all the devices known to SM. #e devices are listed with each device on an
(indented) line" &rst the pri!ary na!e" then a list of aliases in parentheses" then a full na!e. f
pattern is provided only those lines that !atch the given patern will be printed" for details on
SMDs regular e.pressions See section 'propos. 'n e.a!ple would be
-01 +,203, Ipost
to list all devices whose principle na!e begins YpostD.
LSJ SCJ lists all currently de&ned vectors. Qor each vector the na!e" the di!ension and the
G,-? &eld are given. See 1, for how to set the later.
LSJ J':LC lists all colu!ns available in the current J':LCO this currently only works for QJS
binary tables.
Qor a list of the history buUer use BSJ*RI (!acro lis)" to list a !acro use BCLP (!acro h). t
can be useful to overload YlistD so that it doesnDt appear on the history list" and so that YlistD by
itself corresponds to the co!!and BSJ*RI (this is done for you if you use set_overload or
put overload in your `.sm' &le).
&ocal
1ynta!: -538- +,S09, name value
+,S09, name -538-
-538- set name B e!pr
1, name -538-
7sually" SMDs variables (see section ,e&ne) and vectors (see section Set) have global scope"
!eaning that if you de&ne one in a !acro it is still de&ned when you return to the co!!and
pro!pt. #is is o)en what you want" but not alwaysO for e.a!ple !acros o)en de&ne scratch
vectors that !ust be e.plicitly deleted before returning. #is is annoying" but a !ore serious
proble! is that two diUerent !acros can each set a vector called i" but !ean diUerent things.
#e solution to this is to !ake your vectors and variables local to a !acro" !eaning that they are
only visible within that !acro" and fro! any called fro! it. #is is really a nested scope rather
than local" but L*('L is easier to type. Such local ob4ects are auto!atically destroyed when they
go out of scope.
Qor e.a!ple" if you de&ne the !acro bar as
macro bar # ;
echo HDgoo)
set goo local
set gooBH"
ifDgoo R H#) ;
bar HDgooO") H#
<
echo HDgoo)
<>
the co!!and set gooB. bar " * will count fro! ? to G and down again" and if you run the
!acro yar (de&ned as macro yar ; set foo local set fooB"Mn<) the vector foo
will not be de&ned at global scope.
@ote that" as usual" you !ay have to be a litle careful to ensure that you donDt e.it a !acro before
you e.pect. #e sy!pto!s would be that your local variable or vector was already destroyed" or
that it referred to one at less restrictive scope (see section #e (o!!and nterpreter). #e easiest
&. is to add a co!!ent line to the end of the !acro.
&ocation
1ynta!: -538059 A6" A6# A@" A@#
Set the physical location of the plot. #e plot region is the rectangle inside the bo. drawn by :*;.
8ectors and points are truncated at the bounds of the plot region. L*('J*@ speci&es (in device
coordinates) where the plot region is located. L*('J*@ can be used to !ake an arbitrary siSe
and shape plot" providing that you want it rectangular.
:ecause all devices have the sa!e coordinate syste! in SM (?%5-FXF)" this co!!and is
considerably !ore useful than it used to be. #e default L*('J*@ is 5G?? 5<??? 5G?? 5<???.
Iou can get at the current values of A6" etc. using the ,CQ@C i co!!and.
9hile you are using 9@,*9 (see section 9indow)" L*('J*@ co!!ands have no eUect. SM
re!e!bers the!" however" and obeys the !ost recent one when you are &nished with 9@,*9.
See the RCL*('JC D ! y ) co!!and to draw labels outside the plot region" and ,R'9 D !
y ) to draw lines there.
f you want to increase the .%location by G?? (say)" you can say$
-538059 HDHg!" O *..) Hg!# Hgy" Hgy#
#is is so!eti!es useful to !ake roo! for an a.is labelO if your verbosity is < or higher youDll be
advised of the appropriate displace!ent.
&ogical
1ynta!: -ogical 5perators
#e following logical operators are allowed on vectors and scalars in SM" where non%Sero !eans
true$
Lnary:
We!pr -ogical 3omplement
4inary:
e!pr BB e!pr ,qual to e!pr WB e!pr 9ot equal
e!pr R e!pr -ess than e!pr RB e!pr -ess than or equal
e!pr T e!pr Areater than e!pr TB e!pr Areater than or equal
e!pr ^^ e!pr -ogical and e!pr UU e!pr -ogical or
*nly W" BB" and WB are allowed for string valued vectors. 'll arith!etic vectors test une/ual to all
string%valued vectors. nvalid Koating point values (those which print with a C) always co!pare
non%e/ual" even to the!selves (this is the sa!e behaviour as CCCDs 9a9s).
Qor string vectors" there are three cases to consider$ vstr" BB vstr# generates a vector of the
sa!e length as vstr" (with !ust be the sa!e length as vstr#) by co!paring the two vectors
ele!ent by ele!entO 'str"' BB vstr generates a vector of the sa!e length as vstr by
co!paring each ele!ent of the vector vstr to the string str"O and 'str"' BB 'str#'
which returns a scalar by co!paring the strings str" and str# (so itDs false in this e.a!ple).
's in (" BB has a higher precedence than ^^" which in turn has higher precedence than UU. 's
noted in See section f" ^^ and UU evaluate both the le)% and right% hand e.pressions. f this is a
proble!" you can use 89+ and 5: instead.
@ote that there is also a ternary operator" De!pr") V e!pr# : e!pr& which has the value
e!pr# if e!pr" is true" and e!pr& if it is false.
See Yarith!eticD for the arith!etical operators See section 'rith!etic. Iou can test to see if a
variable is de&ned by looking at the value of HVvar (see section ,e&ne).
&type
1ynta!: -@?, 09,A,:
-@?, ,:81,
-@?, ,6?89+ number
'll lines e.cept for those !aking up a.es and characters are drawn with line type 09,A,:"
!eaning$
. solid " dot
# short dash & long dash
$ dot - short dash * dot - long dash
) short dash - long dash
the default is a solid line" LJIPC ?. #e current value of LJIPC is available as an internal variable
(e.g. +,S09, ltype U)
LJIPC CR'SC and will erase any lines that are redrawn (e.g. LJIPC ? :*; LJIPC CR'SC :*;
will &rst draw a bo." and then erase it). @ot all devices can support erasing individual lines" if
yours doesnDt youDll have to CR'SC the whole screen. ' convenient way to use LJIPC CR'SC is
the undo !acro. (in fact" LJIPCs <? and << are used to i!ple!ent LJIPC CR'SC" LJIPC <? to
start erasing" LJIPC << to notify a device that youDve &nished doing so).
LJIPC C;P'@, !akes all dots" dashes" and spaces in the chosen ltype larger (or s!aller) by the
value speci&ed.
&weight
1ynta!: -J,0AG number
Set all lines to have a weight of number" where the bigger the blacker. =enerally" an lweight of ?
is taken to be the hardwareDs preferred width. #e current value of L9C=BJ is available as an
internal variable (e.g. +,S09, lweight U)
Macro
1ynta!: =83:5 ,+0 name
=83:5 -01 Ybegin end Q
=83:5 name Y narg Q ; body <
=83:5 name Y narg Q R body T
=83:5 name +,-,,
=83:5 name 7" 7#
=83:5 :,8+ file
=83:5 J:0, file
=83:5 +,-,, file
=83:5 J:0, name Y O Q file
M'(R* C,J na!e allows you to edit a !acro. 'll the co!!ands available to the history editor
area available (including the [ history)" e.cept that control-= inserts a line before the cursor"
control-9 and control-? get the ne.t and previous lines respectively" and control-2 and
CS(%v !ove forwards and backwards G lines at a ti!e. Jo e.it use control-6 (or whatever you
have bound to e!it_editor). #e !acro need not e.ist" and both its na!e and nu!ber of
argu!ents can be changed by editing the Seroth line of the !acro (control-? fro! the &rst
line. f this line is corrupted" or deleted" no changes are !ade to the !acro when you e.it. f the
nu!ber of argu!ents is negative" the !acro will be deleted when you e.it.) Iou !ay prefer to use
the !acro ed instead of M'(R* C,J" as it doesnDt appear on the history list and" if invoked
without a !acro na!e will edit the !acro that you edited last. ncidently" hm (Yhelp !acroD) will
list the last !acro that you edited with ed. #e keybindings !ay be changed with RC', C,J.
LSJ M'(R* lists all currently de&ned !acros" or all those which are between begin and end
alphabetically (asciily). f 8CR:*SC is ?" !acros starting with ^^ are not listed.
M'(R* name YnargQ ; body < de&nes name to be body" where name is a single word"
and body !ay be anything (!ost users need not worry about the for! in angle bracketsO it is
occasionally useful when writing clever !acros). ' !acro is invoked by typing its na!e. #e
optional nargs is the nu!ber of argu!ents the !acro e.pects" default ?.
f the !acroDs body is de&ned to be delete" the !acro is deleted. M'(R* name ,CLCJC also
deletes a !acro.
'rgu!ents are referred to as E<" E-" ... En" up to a !a.i!u! of EH. E? gives the na!e of the !acro.
f the nu!ber of argu!ents has !ore than one digit (e.g. ?5 or <-)" the !acro is taken to have a
variable nu!ber of argu!ents" between the YtensD digit and the YunitsD digit. Qor e.a!ple" "#
!eans < or - argu!ents" &' !eans between 5 and H argu!ents" and .# !eans ?" <" or -.
(onfusedT G,-? will tell you what SM knows about a !acroDs argu!ents. #ereDs one proble!
hereO if you say
=83:5 woosie ." ;
ifDHV") ;
echo 8n argument: H"
< else ;
echo 9o arguments
<
<
SM will interpret that ." as the integer " before the !acroDs de&ned" so thatDs e/uivalent to
=83:5 woosie " ; ... <. So you cleverly say =83:5 woosie N."N ; ... <O but
that wonDt work either as the closing N is seen before the ?<Ds parsedO you have to say =83:5
woosie N." N ; ... < %% and that does work. (-<) Iou donDt have to go through any such
contortions in &les read by =83:5 :,8+" but they have their own proble!s.
f the nu!ber declared is greater than HH the last argu!ent will e.tend to the end of the line" and
!ay consist of !any words. 9hen called" all the argu!ents !ust appear on the sa!e line as the
!acro itself. #is line !ay" as usual" be ended with an e.plicit \n. #e !acro can deter!ine
whether it has been supplied a given argu!ent by using the HV construction (see ,CQ@C). t is
also possible to change the values of argu!ents using ,CQ@C 4ust as usual" and even to ,CQ@C
argu!ents that you didnDt declare. #ese are te!porary variables" local to the !acro" and will
disappear when you e.it the !acro.
Macros !ust end in space or newline" and if they donDt SM will silently add one (whyT to prevent
the !acro stack being popped pre!aturely see section #e (o!!and nterpreter). f you want to
defeat this" end your !acro with an e.plicit ^" e.g. macro echo ;J:0, 189+8:+7<O a
slightly less e2cient alternative would be macro echo """ ;J:0, 189+8:+ H"<.
M'(R* name 7" 7# de&nes !acro na!e to consist of lines ^< %% ^- of the history buUer. f ^<
or ^- is negative it is interpreted relative to the current co!!and" so saying =83:5 last# -"
-# will de&ne a !acro last# consisting of the last - co!!ands issued.
M'(R* RC', file reads the !acros in file and de&nes the!. See RCSJ*RC for how to also
restore the history buUer fro! !acro all.
M'(R* ,CLCJC file has the eUect of deleting all !acros de&ned in file.
M'(R* 9RJC file writes all currently de&ned !acros to file in alphabetical order. f the
&le e.ists" and Hnoclobber is de&ned" SM will refuse to overwrite the &le. Iou can set
noclobber by specifying it in your `.sm' &le.
M'(R* 9RJC name Y O Q file writes the !acro name to file. f the O is speci&ed" or
the &le is the sa!e as for the previous use of this co!!and" the !acro is writen to the boto! of
the &le" otherwise the &le is created. f the &le e.ists and you arenDt si!ply appending" and
Hnoclobber is de&ned" SM will refuse to overwrite the &le. Iou can set noclobber by
specifying it in your `.sm' &le.
Meta
1ynta!: +,203, =,8 J5:+
+,203, =,8 3-51,
=,8 :,8+ J5:+
f you open the special device called MCJ' it doesnDt close the current device" !erely intercepts
ploting co!!ands and stores the! away as well as e.ecuting the! i!!ediately. #is continues
until you issue a (L*SC co!!and.
#e co!!and MCJ' RC', reads a !eta&le and e.ecutes it on the current device. So to !ake
hardcopy of a plot you could say so!ething like$
device !""
device meta metafile.dat
my_cunning_macro
more_brilliance
device meta close
a)er which (!aybe a)er e.iting SM and restarting it)" you could say$
device postscript
meta read metafile.dat
device .
to !ake a hardcopy.
t is safe to concatenate !eta&les together" if the fancy takes you.
:ecause of the way that SM interrogates devices about their abilities" while using MCJ' all ltypes"
lweights" and fonts will be e!ulated in so)ware (this guarantees that the device you playback on
will be able to handle the code). f the current device can handle dots (i.e. ?@?, . .) then
MCJ' will ate!pt to use the! too" but if it canDt then MCJ' will be reduced to faking the!. #is
could be a serious proble!" so good luck. Meta&les do not support colour" again due to the
i!possibility of knowing if they will have the sa!e behaviour as the original device.
Minma+
1ynta!: =09=86 min ma!
Set variables min and ma! to the the !a.i!u! and !ini!u! values of an i!age read by the
M'=C co!!and. *nly that portion of the i!age within the current LMJS is e.a!ined. #is
!ay be useful for seting contour levels" or doing a hal)one plot (see the !acro greyscale).
Qor e.a!ple" the co!!ands$
=09=86 min ma!
1, levs B Hmin>Hma!>DHma!-Hmin)/'
-,2,-1 levs
will choose a set of <? levels which cover the co!plete range of the data.
$otation
1ynta!: 958059 6-5 6G0 @-5 @G0
Set a.is label for!at (e.ponential or Koating). :y default" all nu!bers between <e%> and <e> are
writen as Koating point nu!bers" and all nu!bers outside this range are writen with an
e.ponent. #is corresponds to a 958059 -$ $ -$ $ co!!and.
f you set 6-5`6G0 and+or @-5`@G0" all values on that a.is will be ploted using e.ponents
(including <)O as a special case if both 6-5 and 6G0 are ? @*J'J*@ will be reset for this a.is.
f you want your positive and negative e.ponents to line up de&ne the SM variable
line_up_e!ponentsO if itDs " theyDll be padded with a space" if # or !ore" with a O (you can
do this in your `.sm' &le).
8r
1ynta!: 5:
n a scalar conte.t" you can use *R instead of UU. #e diUerence is that *R doesnDt evaluate the
right%hand%side of the e.pression if the le)%hand%side is trueO See section f" for e.a!ples.
8verload
1ynta!: 52,:-58+ /eyword 09,A,:
'llow 6keyword6 (in lowercase) to be used as a !acro na!e if integer is non%Sero. Qor e.a!ple"
overload set " overload define "
macro set ; +,S09, < macro define ; 1, <
would interchange the !eanings of the SCJ and ,CQ@C co!!ands. #e uppercase for!s of the
keywords retain their usual !eanings. overload set . would reinstate the usual !eaning of
set. Iou !ay be surprised by the eUects of overloading certain keywords. Qor e.a!ple" if you
overload help to !ean +,-,, G015:@ G,-?" then set help vec help_string
wonDt work (youDd have to say set G,-? vec ...).
#is co!!and is intended to be used for changing the default action of co!!ands" rather than
for a wholesale rena!ing of keywordsa ' !ore practical e.a!ple than the above would be
overload erase " macro erase ; del" ,:81, <
to prevent erase co!!ands fro! appearing on the history list. See the !acro set_overload
for a set of de&nitions like this. t can be auto!atically e.ecuted by including an 6overload6 line
on your `.sm' &le.
,age
1ynta!: ?8A,
P'=C starts a new page for a hardcopy plot (n.b. the device driver for raster plots is unable to
support !ultiple page plots).
*n window syste!s (;<<" Sun8iew) page will raise the window and refresh it if necessary.
,oints
1ynta!: ?5091 J5:+" J5:+# Y 0S De!pr) Q
P*@JS !akes points of the current style (PJIPC)" linetype (LJIPC)" colour ((JIPC)" siSe
(C;P'@,)" and rotation ('@=LC) at the points in vectors J5:+" and J5:+#. f the Q clause is
present" only use those points for which e!pr (see the section on vector arith!etic) is non%Sero.
n fact" either or both of the J5:+s !ay be replaced by Yparenthesised e.pressionsD" i.e.
e.pressions in parentheses. Qor e.a!ple"
?5091 ! DlgDy))
to plot . against the logarith! of y.
n case you ever need to know" the distance fro! the centre of a point to a corner is <-W screen
units when une.panded" if the 'SPC(J (see section 'spect) ratio is unity.
,rint
1ynta!: ?:09 YOQ Y file Q Y 'format' Q ; list <
?:09 YOQ Y file Q Y 'format' Q R list T
Print the vectors speci&ed by list to file" if file is absent" print to the ter!inal (the output
is paged" sort of). #e na!e of each vector is printed at the head of the appropriate colu!n. f the
output is going to a &le" each line of the header starts with a Y^D" so the &le can be read without
using the L@CS co!!and.
#e header is not printed if the variable print_noheader is de&ned and non%Sero. Qor
e.a!ple" have a !acro
p """ 77 print a vector or e!pression. ,.g. Np !N or Np sinD!)N
local define print_noheader "
local set fooBH"
ifDwhatisDfoo) ^ #CC*) ;
print '_g ' ; foo <
< else ;
print '_s ' ; foo <
<
7
to print vectors on a single line. n addition" no header is printed if you are not actually printing
any vectors" in this case no newline is appended to the string. #is provides a way of controlling
string output" and suppressing newlines" e.g. ?:09 '1' ;< ?:09 '=Mn' ;<. Iou
probably will usually want to use 9RJC SJ'@,'R, instead (see section 9rite).
9ith the optional Y1D the vectors are appended to the &le" otherwise it is overwriten unless
Hnoclobber is de&ned" in which case SM will refuse to touch the &le. Iou can set noclobber
by specifying it in your `.sm' &le.
#e optional for!at string is of the type accepted by the ( function YprintfD" and you should see a
book on ( (or !aybe the online syste! !anual or help co!!and) for !ore details. :asically" the
for!at string is copied to the &le with for!at speci&ers beginning with _ signs replaced by the
nu!bers that you want printed. #e for!at speci&ers to use are the Koating point ones" _e
(e.ponential)" _f (Koating point)" and _g (co!puterDs choice)" d" o" ! for printing nu!bers as
integers (the later two are octal and he.adeci!al)" or _s for strings. f you have long ints" you
will need to use e.g. .!_l! (note the lO ell) if youDre specifying your own for!ats. Qields are right
4usti&ed by default" you can insert a - 4ust a)er the _ to le) 4ustify the!. ' _ !ay be writen as _
_" and a tab as Mt. Lines are not ter!inated by a newline by default" you have to write the!
e.plicitly as Mn.
Qor e.a!ple"
1, !B">". 1, yB!CC#
?:09 file '_".f D_"..#e)Mn' ; ! y <
will produce
7........!............y
7
.."........D.."...eO..)
..#........D..$...eO..)
..&........D..'...eO..)
Detc.)
where have replaced each space by a . for clarity. f you say
?:09 '_g ' ; ! <
you will get
..........!
".#.&.$.*.).(.%.'."..
f you want very long output lines youDll run into one of SMDs internal li!itsO the !a.i!u! length
of a string (currently <X? characters). Iou !ight try to work around this by puting part of the
for!ated output into string vectors and then using a ds for!at to write it outO such an approach
can be !ade to work" for e.a!ple instead of
print file '+ate: _#d _#d _$dMn' ; dd mm yy <
you can write
set date B sprintfD'+ate: _#d'>dd) O M
sprintfD' _#d'>mm) O M
sprintfD' _$d'>yy)
print file '_sMn' ; date <
f you think that this is a hack rather agree with you" but it does per!it for!ated output of up
to >?? characters.
,rompt
1ynta!: ?:5=? new_prompt
#e current pro!pt is replaced by new_promptO the default is :. 'ny occurrences of the
character Y0D are taken as instructions to ring the ter!inal bell. 9hen you start SM your pro!pt is
set to the value of the entry prompt in your `.sm' &le (if you have one).
f you enter a partial co!!and (e.g. macro foo ; or echo 843M) SM switches to a diUerent
pro!pt. :y default this is TT" but if you de&ne the variable prompt# that will be used instead.
Iou can set prompt# in your `.sm' &le.
,type
1ynta!: ?@?, n s
?@?, J5:+
?@?, D e!pr )
?@?, ; list <
PJIPC n s causes points to be drawn as n sided polygons of a style s" where s refers to$
.
open
"
skeletal (center connected to vertices)
#
starred
&
solid
Qor e.a!ple" ?@?, " " (or ?@?, . .) !akes points appear as dots" ?@?, $ " (the
default) !akes (diagonal) crosses" and ?@?, ) & !akes &lled he.agons. Points !ade up of
lines (types ." "" and #) are drawn using the current LJIPC.
9hen possible ?@?, . . will draw the s!allest possible dots that the device is capable ofO
these !ay or !ay not be diUerent fro! ?@?, " ".
#e current value of PJIPC is available as an internal variable (e.g. +,S09, ptype U)
PJIPC J5:+ or PJIPC D e!pr ) use vector J5:+ or the e.pression e!pr as its source of n
and s" ( so you !ay de&ne diUerent point types for each point) e.cept that the nu!bers are
contracted together. f the entry has a fractional part" it is treated as an e.pansion factor" relative
to the current e.pansion (no fractional part !eans default e.pansion)O so if n is a vector giving
the desired nu!ber of sides for a set of points" s is a vector giving the desired types" and e is a
vector giving the desired relative siSes (. RB e R ")" youDd want to say ?@?,
D".CnOsOe). Qor e.a!ple" an an entry of <?5.G in J5:+ is the sa!e as PJIPC <? 5" C;P'@,
?.G" but if you now say C;P'@, - the net e.pansion will be unity. tDs !uch easier to use a vector
of e.pansions directly to the C;P'@, co!!and" but fractional ptypes are preserved for
backwards co!patibility. &b& due to a bug in .'!R< "or the Sun* PT=P0 n 3 does not wor> "or dev
xwindows on a sun. f !ore points are speci&ed than the di!ension of e.pr" the &rst ele!ent
will be used for the e.cess.
f J5:+ is a string%valued vector" its ele!ents are used to label the points of the graph. #ey are
drawn at the current e.pand and angle (vector%valued C;P'@,s and '@=LCs are ignored)" and
in the current default font. Qor Je;%string users this can be speci&ed with the variable
default_font" which can either si!ply be de&ned" or set in your `.sm' &le.
PJIPC ; list < de&nes the sy!bol to use with the P*@JS co!!and to be so!e creation of
the user. #e list consists of a set of c ! y where c is a leter" and ! and y are integers. f c is
Y!D or YrD (!ove or relocate) the plot pointer is !oved to the point (."y)" if it is YdD (draw) or absent
a line is drawn fro! the current position to the point (."y). #e coordinates are !easured relative
to the current point being ploted" and are !easured in screen coordinates (i.e. ?%5-FXF). :oth
C;P'@, and '@=LC are applied to the (."y) values as usual.
's an e.a!ple the co!!and
?@?, ; m . *.. *.. . . -*.. -*.. . . *.. <
will de&ne the !arker to be a dia!ond" so!ething like$
/M
/ M
M /
M/
(but with unbroken lines). 's a !ore useful e.a!ple" there is a !acro upper which de&nes a
variable Eupper to draw an upper li!it sign" used as
?@?, Hupper
(if '@=LC were <W?" theyDd be lower li!its).
,utlabel
1ynta!: ?L-84,- 09,A,: str
P7JL':CL writes a label at the current location with rotation and siSe speci&ed by '@=LC and
C;P'@, (e.actly like L':CL). #e label is centered with respect to the current location
according to the argu!ent 09,A,: which can be < % H !eaning that the label is$
left centre right
above ( % '
centered $ * )
below " # &
(cf. a vt<?? keyboard) Jo be a litle !ore precise" YaboveD !eans that the stringDs baseline (the
boto! of characters such as YaD that have no descender) is at the level of the current point" while
YbelowD !eans that the top of the tallest character in the string is level with the current point. f
you donDt like this neglect of descenders" try
=83:5 myputl ".# ;label MraiseMadvanceMdepth;H#<by"..;<Mn putlabel H" H#<
myputl ( his is a -abel
(Iou can then say overload putlabel " macro putlabel ;myputl< if the !ood
takes you). ')er the label is writen the current location is on the baseline" 4ust to the right of the
last character drawn. f 09,A,: is ? the string isnDt actually drawn" but the stringDs di!ensions
are calculated (and are available as Hswidth" Hsheight" and Hsdepth)" and any Je;
de&nitions are re!e!bered. f P7JL':CL G isnDt /uite what you want (as it centres vertically as
well as horiSontally)" try -84,- Mcentre;G_Malpha< instead.
See section ,rawing Labels and SMDs Je; C!ulation" for a description of how to enter a label
with funny characters" sub% and super%scripts" and so forth.
f C;P'@, is set to e.actly <" and '@=LC is e.actly ?" then SM will use hardware fonts" when
available" in writing labels. #is is faster" but if you donDt like it say 6C;P'@, <.???e?<6" or use a \r
e.plicitly to select the ro!an font. *r ask your SM =uru to edit the `graphcap' &le to stop
your printer fro! ever using hardware fonts (or read the discussion under L':CL).
)uit
1ynta!: KL0
Rits the progra!!e entirely.
#e !acro Y/D is de&ned as so!ething like
+,-,, G015:@ +,S09, " . 7 default value
+,S09, " V ; 8re you sureV ,nter " to really quit <
0SDH") ; KL0 <
so you wonDt /uit accidently" and the A7J wonDt appear in the history &le. #is is an obvious
candidate for overloading.
Range
1ynta!: :89A, number_! number_y
f nu!ber is non%Sero" set the range on the . or y a.is to be nu!ber" so LMJS will choose two
values that diUer by nu!ber. @othing will happen until you issue a LMJS co!!and.
Qor instance" if you wanted to ensure that the y a.is of a logarith!ic plot spans e.actly two
decades the co!!ands R'@=C . # LMJS ! y would choose suitable y li!its" with actual
values appropriate for the y vector. f the YnaturalD li!its are less then range then the li!its will
be chosen about the centre of that interval" otherwise theyDll be centred on the !edian value of
the data.
Read
1ynta!: :,8+ J5:+ 09,A,:
:,8+ Y W Q ; J5:+ 09,A,: J5:+ 09,A,: ... <
:,8+ Y W Q ; ... J5:+ range ... <
:,8+ :5J J5:+ 09,A,:
:,8+ Y W Q 'format' ; J5:+ J5:+ ... <
:,8+ ,+0 J5:+
:,8+ 5-+ J5:+ J5:+
=,8 :,8+ J5:+ J5:+
RC', J5:+ 09,A,: reads a colu!n of data fro! the &le speci&ed by the ,'J' co!!and"
using the lines speci&ed by L@CS. (olu!ns !ay be separated by white space (blanks or tabs) or
by a co!!a" or by so!e co!bination of the two. tDs *3 if so!e of the colu!ns contain te.t"
providing that you donDt try to read the!. Iou can read te.t colu!ns into string vectors" as
described in the ne.t paragraph. #e data is read into the vector J5:+" which will be created"
fro! colu!n 09,A,:. 'ny &eld beginning with a C is taken to be Ye!ptyD" and is assigned the
value <.??<e5X (or <.??<e5?? if you chose double precision vectors in set_opts). 'ny line
beginning with a ^ is skipped over (and printed if 8CR:*SC is greater than <)" any line beginning
with a a is skipped and always writen to the ter!inal. Long (logical) lines !ay be spread over
several (physical) lines by ending the line with a Y\DO no line !ay e.ceed a total of <G?? characters.
f you use continuation lines" note that SMDs line nu!bers (for e.a!ple" as set with the -09,1
co!!and) apply to logical not physical linesO a continued line counts as only one line.
Iou can optionally specify a type of vector by adding a su2. onto the integerO Y.fD (the default) or
Y.gD !eans Koating point" Y.dD" Y.oD" Y.iD" or Y..D !eans integer" Y.sD !eans string%valued. String valued
vectors can be used as input to PJIPC co!!ands" or si!ply for reading colu!ns fro! data &les
that you want to PR@J.
RC', _ J5:+ 09,A,: J5:+ 09,A,: ... Z is the sa!e as repeating RC', J5:+ 09,A,:
for each vector" but !ore e2cient as it only has to read the &le once.
:,8+ ; ! " s *.s y #.f \ &.i <
will read colu!ns < and - into Koating point vectors ! and y" colu!n 5 into an integer%valued
vector S" and colu!n G into string%valued vector s. 's noted below" you can o!it the @JC=CRs
by specifying an e!pty for!at$ RC', 6 _ . y.d Z (those are two single /uotes).
7sually SM stops reading at the &rst invalid line" but if you say :,8+ W all the lines speci&ed
with -09,1 (or the entire &le) are read. Missing nu!erical &elds are set to be invalid (i.e. they are
treated as 0)O !issing string values are le) blank. #is is probably !ost useful with the _n for!at
speci&er.
f 09,A,: is invalid (M` ?)" the contents of the &le are writen to the standard output. RC',
R*9 is very si!ilar" but the values are read fro! row 09,A,: of the &le (any L@CS co!!and
is ignored). #e sa!e type /uali&ers are allowed as for reading colu!ns. #ere is no li!it to the
nu!ber of ele!ents in the vector" e.cept that i!plied by the !a.i!u! length of a line. Iou
cannot specify a range of colu!ns to read with RC', R*9" but try
1, iB#>*
:,8+ :5J ! "
1, !B!YiQ
f the &rst &eld is a string" you can say RC', R*9 s <.s SCJ .`'J*Q(sgih).
f your data is in a nu!ber of colu!ns (e.g. you have writen it out to a &le ten values to a line)
you can specify a range of colu!ns" for e.a!ple
:,8+ ; ! "-$ y * \ )-". <.
Iou can only use ranges for nu!erical vectors" and only with the list for! of :,8+. Ranges wonDt
work if there is a short line at the end" but you can still say so!ething like
-09,1 . "..
:,8+ ; ! "-$ <
:,8+ :5J _! "."
1, !B! 35938 _!
which will be al!ost as e2cient if you have de&ned Hsave_read_ptr.
n order to speed up !ultiple reads of the sa!e &le" SM usually re!e!bers where it got to in a
&leO this is disabled if you unde&ne the variable Hsave_read_ptr (which can be done in your
`.sm' &le by seting it to ?). #e re!e!bered position is forgoten every ti!e that you issue a
+88 co!!and" or try to re%read part of the &le. Iou can get into trouble if you read part of a &le"
!odify the &le without reissuing a +88 co!!and" and then read so!e !ore" but in nor!al
usage it should be safe to leave saving the read pointer enabled.
nstead of using si!ple colu!n%oriented input it is possible to specify a for!at si!ilar to those
used by (Ds scanf functions (Qortran for!ats are not supported)O if you donDt know ( then !ost
of what you need to know is that characters in the input !ust !atch those in the input &le" e.cept
that ite!s to be read are speci&ed with for!at strings that start _. Qor e.a!ple" a for!at abc_f:
_f e.pects the input to consist of YabcD then two Koating point nu!bers separated by a colon. f
the _ is followed by a C the &eld is read but isnDt assigned to a vector. Iou can specify a newline as
Mn or a tab as Mt.
's a further e.a!ple" if your data &le has lines like
":"#:&. -$*:&.:""
you could read it with
read '_d:_d:_d _f:_f:_f' ; hr min sec deg dmin dsec <.
#e type of the vector is deduced fro! the for!at stringO you canDt use .f or .s in the vector list
(why would you want to specify a type twiceT).
's a special case" of you specify an e!pty for!at (6) the na!ed vectors are read as Koats fro! the
&rst n colu!ns of the &le" so
:,8+ N ; ! y \ <
is e/uivalent to
:,8+ ; ! ".f y ".f \ &.f <
or si!ply
:,8+ ; ! " y " \ & <
Iou can use the usual /uali&ers" e.g.
:,8+ N ; ! y \ flags.! <
and o!it colu!ns entirely by replacing the vectorDs na!e with .$
:,8+ N ; ! . \ <
said that the d%for!ats were Ysi!ilarD to scanfDsO they diUer in the way that they treat &eld
widths and white space. f you donDt specify a width at all SM follows the usual ( behaviour of
skipping white space between ite!sO if you do specify a &eld width no space is skipped over
before the &eld begins. Iou can always e.plicitly skip spaces with a _CY Q for!at. #e _n for!at
returns the nu!ber of &elds !atched rather than the nu!ber of characters.
#e supported for!at leters are d" e" f" g" o" n" s" !" and Y" their !eanings are$
_d
Read an integer into a Koating vector (YdD stands for Ydeci!alD). f a &eld width is speci&ed
trailing spaces are treated as spaces not Seros %% this isnDt fortran you know. #e &eld N
"#&$ N (i.e. a &eld width of X" _)d) has the value "#&$ not "#&$..
_e
_g
Read a Koating point nu!ber with or without an e.ponent into a Koating vector. 's for _d"
trailing spaces in a &.ed%width &eld are treated as spaces not Seros.
_f
Read a Koating point nu!ber without an e.ponent into a Koating vector. 's for _d" trailing
spaces in a &.ed%width &eld are treated as spaces not Seros.
_n
Return the nu!ber of &elds that are already correctly !atched in the current lineO this is
only useful in con4unction with RC', a.
_o
Like dd" but the nu!berDs taken to be octal.
_s
Read a string into a string%valued vector. f a &eld width is speci&ed the entire &eld is read
spaces and allO if there is no width initial spaces are skipped as usual and the string is
ter!inated by the &rst white space character.
_!
Like dd" but the nu!berDs taken to be in he..
_Y...Q
Read a string consisting of the characters ... into a string valued vector. Iou can specify a
range as a-\ so _Ya-\843.-'Q would read a string consisting of any lower case
character or digit" or one of '" :" or (. f the &rst character is [" read any characters e)cept
those speci&ed (e.g. dg[abch reads anything but the leters a" b" or c). f a &eld width is
speci&ed characters that donDt !atch those speci&ed at the end of the &eld are ignored.
__
@ot a conversion for!at" but a literal d.
RC', C,J J5:+ reads a new set of keybindings fro! the &le J5:+. #e for!at and synta. are
given under Bistory (see section Bistory) in the introduction.
RC', *L, J5:+" J5:+# de&nes !acro J5:+" to be the the contents of &le J5:+#. #is is
provided for co!patibility with Mongo (see section Jips for Mongo 7sers) and the read_old
!acro. Iou no longer need use read_old to read SM history &les" use RCSJ*RC instead.
f 8CR:*SC (see section 8erbose) is greater than ?" the lines actually read will be reported.
MCJ' RC', J5:+ reads a !eta&le" as produced with the pseudo%device MCJ'" and e.ecutes the
enclosed co!!ands on the current device.
Relocate
1ynta!: :,-538, 6 @
:,-538, D 6 @ )
#e &rst for! sets the current position to (6>@) in user coordinates without drawing a line. #e
second (with parentheses) sets the position in YscreenD coordinates" i.e. ?%5-FXF. #e current
position is used by the ,R'9" L':CL" and P7JL':CL co!!ands.
#ere are a couple of pairs of internal variables DHu!p>Huyp) and DH!p>Hyp) that give the
current position of the plot pointer" either in user or screen coordinates.
Restore
1ynta!: :,15:, Y filename Q
Restore all the current !acros" variables" and vectors fro! &le filename (if o!ited the default
is to use the value of save_file in your `.sm' &le" or failing that `sm.dmp'). n addition"
the current history buUer is replaced by the !acro all if de&ned in the RCSJ*RCd &le.
#e &le should have been writen by the S'8C co!!and" and RCSJ*RC will treat any other &le
type as if it were a SM history &le and add its co!!ands to the end of the current history list.
f 8CR:*SC (see section 8erbose) is greater than ?" so!e e.tra infor!ation is printed.
Return
1ynta!: :,L:9
Return fro! the current !acro" which includes breaking out of ,* and Q*RC'(B loops. f you
are not e.ecuting a !acro" si!ply return to the pro!pt (this is !ore or less e/uivalent to typing
control-3).
' RCJ7R@ can be useful while playing with &ddling with data interactively. Qor e.a!ple" if you
want to playback a set of co!!ands" but then do other things when the plot has appeared" you
could put a RCJ7R@ a)er the desired part of the playback buUer. (#is doesnDt work /uite the
way that you !ight naively think. ?laybac/ works by de&ning a !acro all fro! the history
list" and then e.ecuting it. #e RCJ7R@ is actually returning fro! this !acro" rather than directly
fro! the co!!and list" but the eUect is the sa!e. f RCJ7R@ always returned directly to the
pro!pt" !acros such as hcopy wouldnDt work.)
f 8CR:*SC is - or !ore" the na!e of the !acro being returned fro! is output.
/" the very last command in a macro is R0T?R then the R0T?R will ta>e place* not "rom the
desired macro* but "rom where the macro was called "rom& =ou can wor> around this by pu@ing a
space aAer the R0T?R* or simply omi@ing it as it isn#t doing anything anyway& /" a R0T?R comes
last on a history list* this problem will lead to macros such as hcopy not wor>ing correctly.
Save
1ynta!: 182, Y filename Q
Save so!e or all of the current !acros" variables" and vectors in &le filename (if o!ited the
default is to use the value of save_file in your `.sm' &le" or failing that `sm.dmp'). #e
current history buUer !ay also be saved" as the !acro all.
Iou are pro!pted for whether you want to save variables" vectors" and !acros (which includes
all" the current playback buUer). Macros beginning ^^ are not saved" as they are assu!ed to be
syste! !acros. 8ariables and vectors whose na!es start with a Y]D are assu!ed to be te!poraries"
and are not saved either.
#e opposite to S'8C is RCSJ*RC (see section Restore). Iou !ay want to use the M'(R*
,CLCJC 9*R, co!!and to unde&ne !acros fro! e.g. the `utils' !acro &le. See" for
e.a!ple" the !acro sav (which can be overloaded).
f 8CR:*SC (see section 8erbose) is greater than ?" so!e e.tra infor!ation is printed.
Set
1ynta!: 1, name B e!pr
-538- 1, name B ...
1, name B ; e!pr <
1, name B R e!pr T
1, name B e!pr 0S D e!pr )
1, name B e!pr"> e!pr# Y> e!pr& Q
1, name B e!pr" V e!pr# : e!pr&
1, name -538-
1, +0=,9 D name ) B 09,A,:
1, name B J5:+ D Y J5:+ Y > J5:+ ... Q Q )
1, name Y e!pr Q B e!pr
1, name Y e!pr> e!pr Q B e!pr
1, 0=8A,Ye!pr> e!prQ B e!pr
1, G,-? J5:+ Y rest Q
1, :89+5= s_e!pr
(onduct various operations on vectors of data. #e si!plest" SCJ name B e!pr sets vector
name to be e/ual to the e.pression e!pr. f the Q clause is present" name will only contain those
ele!ents of e!pr for which it is true (non%Sero). ' special case of an e.pression is si!ply a list of
values within braces (or angle brackets).(--) Qor string%valued vectors" the only allowable
e.pressions are a string%valued vector" the (*@('Jenation of two string vectors" the addition (i.e.
ele!ent%by%ele!ent concatenation)" or a string in single /uotes (e.g. 1, sB'Gello> Jorld'
or 1, ssB'n_;' O R e cl co g T O '<').
9ithin a !acro" any of these co!!ands that set an entire vector !ay be preceded by the word
L*('L. #is ensures that the vector name is only visible within that !acro" and any called fro!
it (see section Local). Quture references to the na!e auto!atically refer to the local vector" so only
the &rst occurrence need be preceeded by L*('L. Such local vectors are auto!atically destroyed
when they go out of scopeO in fact it is illegal to delete one e.plicitly.
'n e/uivalent way to achieve this is with the co!!and 1, name -538-" a)er which the
vector !ay be SCJ in local scope (so 1, ! -538- 1, !B". 1, !B#. is e/uivalent to
-538- 1, !B". 1, !B#.).
@ote that" as usual" you !ay have to be a litle careful to ensure that you donDt e.it a !acro before
you e.pect. #e sy!pto!s would be that your local vector was already destroyed" or that it
referred to one at less restrictive scope (see section #e (o!!and nterpreter). #e easiest &. is to
add a co!!ent line to the end of the !acro.
9ith e.pressions separated by co!!as the SCJ co!!and is like a ,* loop" seting name to be
the values between e!pr" and e!pr#" at incre!ents of e!pr& (which defaults to <). Iou can
also use an i!plicit ,* as part of an e.pression" e.g. SCJ .`< 1 do(?"<?"-)+<? (see section
'rith!etic).
#e co!!and with T and $ is si!ilar to the ( ternary operator. f e!pr" is true" take the
corresponding value of name for e!pr#" otherwise use e!pr&. #is co!!and is worth learning"
as it can o)en be used to replace a ,* loop. #is co!!and is in fact si!ply a special case of SCJ
! B e!pr.
f you have a ,* loop that calculates each ele!ent of a vector in turn" so!ething that is possible
if ine2cient in SM" (-5) you need to de&ne a vector before you use it. Iou will also need to declare
a vector (or create it by puting it on the le) of a SCJ co!!and) if you want to use a
vector%valued subscript on the le) of an e.pression. #is can be done with the SCJ ,MC@(name)
` 09,A,:" which also initialises it to ?. #us SCJ ,MC@(y) ` ,MC@(!) is e/uivalent to SCJ y
` .C!. Iou cannot use e.pressions as the di!ension" but SCJ y ` HD$ O $) works perfectly
well. Iou can optionally specify a /uali&er to the di!ension" in 4ust the sa!e way that you can
specify a /uali&er to a colu!n in a RC', co!!and" so SCJ ,MC@(s) ` "..s declares a
<?%ele!ent string%valued vector. See also SCJ J5:+ g e!pr " e!pr h ` val.
SCJ name ` J5:+ ( g arg g > arg ... h h ) allows you to use a !acro as a sort of function
de&nition. 9ithin the !acro 9*R, any assign!ent to H. has the eUect of assigning to name"
and the other argu!ents behave as nor!al. #e argu!ents arg can be words or nu!bers (but
not general e.pressions) and are separated by co!!as. ote that this is a change to the synta) o"
this commandB Previously only one argu!ent was per!ited" but it could be an e.pression" and the
result was returned by assigning to H" in a rather confusing way.
SCJ wordYe!prQ B e!pr sets the ele!ents e!pr of vector word to the values of the vector
on the right hand side. f the le) hand side is a string but the right hand side is nu!erical it will
be converted. #e &rst e!pr is converted to an integer before being used as an inde.O if it is too
s!all itDs set to ?" if too large to the largest allowable inde.. Qor e.a!ple"
set iB.>". set !B"..Ci
set dimenDy) B dimenD!)
set yYi-"Q B !
will result in a co!plaint that j< is an invalid inde. and set y B ; ".. #.. &.. ... <.
@ote that arrays are subscripted with g h not ()" and that" as always" indices start at ? not at <. #e
word !ust e.ist before you can do this to it.
f your range of indices is contiguous you can say$
set !Y.>".Q B y
instead of
set i B .> ".
set !YiQ B y
's a bonus the vector . will be e.tended as needed to acco!odate the new ele!ents. #is !eans
that
set ! B ! 35938 y
is e/uivalent to
set !YdimenD!)> dimenD!) O dimenDy) - "Q B y
f you have pre%allocated . to be large enough" the later is (!aybe !uch) !ore e2cient.
#is also provides a way to generate a vector initialised to a desired value$
set !Y.> "..Q B ".
SCJ M'=Cgi."iyh is used to set ele!ents of an i!age to the speci&ed values. #e i!age !ust
e.ist (see section !age)" and the vectors i. and iy are interpreted as integer subscripts into the
i!age (?%inde.ed" of course). #is is the inverse of the SCJ S`i!agegi." iyh and isn#t /uite the sa!e
as the SCJ S`M'=C(."y) co!!and" as . and y are interpreted with using the (optional) .!in"
.!a." y!in" and y!a. values. n the old days" this co!!and was set imageDi!>i!)
B ..." but this was confusing and is now deprecated.
SCJ BCLP sets the help string for a vectorO the rest of the line is read" and will be returned in
response to a BCLP J5:+ re/uest. t can also be used in the string%valued e.pression
BCLP(name)" for e.a!ple IL':CL E(BCLP(yvec)).
SCJ R'@,*M nu!ber sets the seed of the rando! nu!ber generator used by the R'@,*M
operatorO if you donDt set it yourself itDll be set to so!e value based on the ti!e since <HF?.
LetDs look at so!e e.a!ples.
1, y B Hv" O *.. C !
#is sets each ele!ent of the vector y to be the value of the scalar Hv" plus G.? ti!es the
corresponding ele!ent of the vector ! (assu!ing that ! has been de&ned previously)
1, data_set_" B lgD!) 0S D lgD!) T .)
#is sets the ele!ents of the vector data_set_" to be the (co!!on) logarith! of the
corresponding ele!ent of the vector !" if that logarith! is N ?. #us data_set_" will in general
be of s!aller siSe than !.
1, data B DlgD!) T .) V lgD!) : .
n this case" data_set_" will be the sa!e siSe as !" and any ele!ents of data_set_" where
the corresponding ele!ent of ! is less than or e/ual to <" will be set to ?.
1, vec B $C; " ".* # #.* & <
will de&ne a vector vec" with G ele!ents" with the values given by four ti!es those in the list.
1, vec B ">"#>#
an alternative way of de&ning the sa!e values.
1, i B ; # & <
1, ! B vecYiQ
will set the vector ! to have be % ". (i.e. vecY#Q and vecY&Q).
=83:5 pow # ; 1, H. B H" CC H# <
1, vec B powDvec > &)
cube the vector vec.
1, vecY.Q B #Cpi
(hange your !ind about the &rst ele!ent of vec.
1, G,-? pam Jichita> Eansas> Zuly (> "'*&
will set the help string for vector pam to be the string Jichita> Eansas> Zuly (> "'*&"
so when you type G,-? pam" this string will be printed out.
1, rhlB:obert
de&nes a string vector with one ele!ent.
1, +0=,9Drhl) B "..s
de&nes a string vector with ten ele!ents (all blank)" while
1, rhlB;:obert Gorace -upton<
de&nes a string vector with initialised ele!ents" and
1, rhlY"QBGugh
corrects it.
See the (7RS*R co!!and for de&ning a pair of vectors using the cursor to !ark the points" and
SPL@C for how to &t splines to pairs of vectors.
Shade
1ynta!: 1G8+, number pe!pr pe!pr
1G8+, G015A:8= number pe!pr pe!pr
1G8+, G015A:8= 89A-, number pe!pr pe!pr
(YPe.prD is the na!e of a vector" or an e.pression in parentheses" e.g. 1G8+, "... !
DsqrtDy))).
Shade YinsideD a curve de&ned by the e.pressions. #e shading is rotated through the current
value of 89A-," and lines are spaced by the integral part of dnumber apart (screen coordinates"
so the full screen is 5-FXW across). f number is ? the shading is done as an area &ll (and is !uch
!ore e2cient than specifying <a).
f number has a fractional part" the lines are oUset by that fraction of the spacing (try shade
".. ! y ctype red shade "...* ! y).
#e !eaning of YinsideD is that as the shading is done" fro! le) to right taking the value of 89A-,
into account" lines are drawn fro! every odd to every even crossing of the curve. #e curve is
considered as being closed by 4oining the &rst to the last point. f a shading line 4ust touches the
curve the algorith! !ay be confused" change number slightly" or try adding <W? to '@=LC.
So!eti!es 4oining the ends of the curve !ay not be what you want" try using 35938 to add
points on the end yourself. Qor e.a!ple"
1, !B.>". 1, yB!CC# -0=01 ! y 1G8+, "... ! y
looks like a new !oon" but
1G8+, "... D! 35938 ".) Dy concat -"e".)
shades beneath the curve" for 89A-, ? that is. Iou could also try the !acros scribble and
shading in de!os" e.g. type load demos scribble.
1G8+, G015A:8= is si!ilar" but it shades the histogra! that would be drawn by G015A:8=
fro! the sa!e set of points. n this case the area to be shaded lies between the histogra! and the
line y`?. f this oUends you" oUset the whole graph and lie about the a.es.
#e for! with 89A-, is used for shading a histogra! of y against ." when the averaging is done
in the y% not the .% direction. (o!pare
set y B ;. & " & " .< set ! B-..#*>-#.(*>-..* lim y !
,:81, bo! shade histogram . y !
with
,:81, bo! shade histogram angle . y !
Show
1ynta!: 1G5J
List the values of so!e of the internal variables" including current location and plot region li!its
in user and device coordinates" the value of the e.pansion and angle variables" the line type and
weight" and the physical li!its. Show is actually a !acro" so you could !odify it to your own
ends" for e.a!ple listing the current data &le too.
Sort
1ynta!: 15: ; vector_list <
15: R vector_list T
1, vec B 15: D e!pr )
Sort the &rst vector in the list into increasing nu!erical order" and rearrange the others in the
sa!e way. #e !a.i!u! nu!ber of vectors that can be sorted is <?. Qor e.a!ple" following the
co!!ands
1, e B ; # ( " % # % " % # < 1, p B ; & " $ " * ' # ) * <
15: ; e p <
the vectors e and p would be " " # # # ( % % % and $ # & * * " " ' ) . #e order
within the p vector is not de&ned when the e values are identical.
'ny !i.ture of string% integral% and arith!etic%valued vectors is allowed.
Iou can also use S*RJ to sort a single e.pression" returning an e.pressionO e.g.
1, !B.>". 1, y B 15:DS-58D!)) O 15:D109DpiC+5D.>">..")))
(actually" you donDt need the S-58" but youDll get a warning if 2,:451, is - or !ore).
Spline
1ynta!: 1?-09, !" y" !# y#
Qit a natural cubic spline through the points speci&ed by vectors !" and y". #e di!ensions of
!" and y" !ust be the sa!e and !ust e.ceed -" !" !ust be !onotonic increasing (use S*RJ if
necessary). 9hen the spline has been &t" take the points speci&ed in vector !#" and &ll the (new)
vector y# with the corresponding values. Linear interpolation is used beyond the ends of !".
Strings
1trings
SM supports a nu!ber of string operations on vectors and scalars. n the following descriptions
e.pr is a e.pression and vector the na!e of a vector.
Lnary:
85SDe!pr)
#e value of e.pr converted to a Koating point nu!ber. f an ele!ent of the e.pression
cannot be so interpreted (i.e. it doesnDt start with an optional sign followed by a digit)" the
value returned will be ?.
3@?,D1:09A)
Return a vector with the na!es of all currently de&ned coloursO there is also (JIPC() to
recover their values (see section 'rith!etic).
G,-?Dname)
#e help string associated with vector name (set with SCJ BCLP)
-,9AGDe!pr)
#e length (S(RCC@ units) that a string would have if ploted
1:-,9De!pr)
#e nu!ber of characters in a string
1:09ADe!pr)
(onvert a nu!ber to a string. Iou !ight prefer to use sprintf(DdtD"e.pr) instead" as it gives
you !ore control.
1:09ARJ5:+T
(onvert a string to a string" /uoting 6. Iou donDt usually need to use this (si!ple write 'my
string')" but if your string already contains /uotes this doesnDt work.
D e!pr )
Raise precedence
4inary:
e!pr O e!pr
'ddO concatenate ele!ent by ele!ent
e!pr 35938 e!pr
(oncatenate the two vectors
09+,6De!pr_">e!pr_#)
Return the starting inde. of e.pr]- in e.pr]<" or j< if not found.
1?:09SDe!pr_">e!pr_#)
Qor!at e.pr]- using the standard ( for!at string e.pr]<. #e additional for!at dt or dJ is
identical to de" but for!ats the string as a power of <? in Je; for!at. @ote that only one
e.pr !ay be for!ated" but that you can say sprintfDe!pr>e!pr) O
sprintDe!pr>e!pr) ... to work around this restriction.
vectorYe!prQ
#e ele!ents of vector given by e.pr.
ernary:
1L41:De!pr_">e!pr_#>e!pr_&)
Return the substring of e.pr]< that starts at e.pr]- and is e.pr]5 characters long. f e.pr]-
is negative" count fro! the end of the stringO if e.pr]5 is ? return the rest of the string. Qor
e.a!ple" '+r. ' O substrD':alph =onger'>-)>.) would return '+r.
=onger'.
e!pr" V e!pr# : e!pr&
e.pr- if e.pr< is true" else e.pr5
@ode that this is si!ilar to the corresponding SCJ co!!and" but it needs parentheses if used as
an e.pression.
'll indices" as elsewhere in SM" start at ?O e.g. substrD'8lgonquin'>.>") is 8.
#e e.pression 2,35:Ye!prQ results in a vector of the sa!e di!ension as the e!pr" with
ele!ents taken fro! 2,35: (i.e. 2,35:Y09De!pr_i)Q). Iou can also use J5:+DY e!pr
Y > ... QQ) as part of an e.pression" where J5:+ is a !acro taking Sero or !ore argu!ents.
#e argu!ents are restricted to be either the na!es of vectors or nu!bersO sorry.
Iou can use the usual logical operators (see section Logical) with string%valued vectors O thereDs a
discussion in that section of the confusions that people con4ure up about when they need to use N.
#e BCLP(name) string operator is o)en useful in labels" for e.a!ple
1, G,-? si\e Nr_eN
...
6-84,- HDG,-?Dsi\e))
#e precedences are what youDd e.pect" with O being higher than 35938. #e logical operators
have even lower precedence than 35938.
Surface
1ynta!: 1L:S83, type \" \#
or 1L:S83, type \" \# J5:+ J5:+
,raw a wire%fra!e surface of the current 0=8A, fro! the point de&ned by 20,J?509. f the
9*R,s are o!ited a line in the surface will be drawn for each row and colu!n of the i!ageO if
the 9*R,s are present they will be taken to be the !% and y% coordinates of the desired lines" and
SM will interpolate in the i!age to deter!ine the corresponding values (see also the hundreds
digit of type" below).
#e co!!and 20,J?509 speci&es the position of the observer and the type of pro4ection used
(see section 8iewpoint).
#e last digit of JIPC is used to deter!ine which surface to draw$
. no hidden line removal
" draw top surface
# draw bottom surface
& draw both top and bottom surfaces
f typeDs tens digit is set" 1L:S83, will use the current li!its (as set with -0=01) rather than
autoscaling the! fro! the data.
f typeDs hundreds digit is set" the two J5:+s are taken to be the !% and y% coordinates
corresponding to the rows and colu!ns of the M'=C" but no interpolation is done. Qor e.a!ple"
a)er
0=8A, D"">"")
1, i!B.>".
set !sB.>".>#
do yB.>". ;
1, 0=8A,Di!>Hy) B cosD..#Ci!)CsinD..$CHy)
<
20,J?509 &. -". -"
1L:S83, & -"." "." !s !s
will draw a -%sided surface" drawing -< lines in each direction on the surface. f" on the other
hand" the data were really only known on at irregular set of !% and y%values" you could say
so!ething like
0=8A, D"">"")
1, i!B.>".
1, ! B ; . ".& #.$ & $ $.* $.) ).( %.# '.) ". <
1, y B ; . ..$ ..' ".# #.("% &."$ $.# *.$ ).))( '." ". <
do iB.>". ;
1, 0=8A,Di!>Hi) B cosD..#C!)CsinD..$CyYHiQ)
<
3@?, cyan
1L:S83, ".& -"." "." ! y
3@?, default
to draw the sa!e surface.
f JIPCDs thousands digit is set" the surface is not clipped to the S%a.is li!its \" and \#.
\" and \# are the li!its used for the S%a.isO you !ight want to set the! with =09=86. #e
surface drawn will be truncated at \" and \# unless you are using an a.ono!etric pro4ection (see
section 8iewpoint).
#ere are so!e useful !acros in the &le `surfaces'O say load surfaces to read the!. f
8CR:*SC is one or !ore" a helpful header will be printed when you load the &le.
4able
1ynta!: 84-, YsubtableQ Y'format'Q file
84-, subtable Mn
:,8+ 84-, ; J5:+ YJ5:+ ...Q <
:,8+ 84-, 'format' ; J5:+ YJ5:+ ...Q <
:,8+ 84-, 'byname' ; J5:+ YJ5:+ ...Q <
:,8+ 84-, 'bycolumn' ; J5:+ id YJ5:+ id ...Q <
-01 84-,
SM is able to read a wide range of table for!ats" using tricks si!ilar to those used for the M'=C
co!!and. #e variable table_type is used to specify which you want (and !ay be set in your
`.sm' &le). (o!!on values are bintable and ctable. 8alues Kagged as bad in the table !ay
be (in the case of bintable" are) set to SMDs invalid value" and this are not even e/ual to
the!selves.
J':LC Y...Q &le is the e/uivalent of the ,'J' co!!and" and sets &le file to be the source of
data read with the RC', J':LC co!!andO if the &le canDt be opened for read" you will be
warned. f the subtable argu!ent is provided" it speci&es which table in a J':LC &le is to be readO
this is only currently supported for QJS tables (Htable_type is bintable or a type derived
therefro!O for such tables you probably want to use a subtable of <). #e for!at" if provided"
speci&es the types of the colu!ns in the tableO so!e tables !ay provide this either in the table
header (e.g. QJS binary tables) or in the &lecap &le" as the S= /uantity. 'llowable for!at strings
are speci&ed at the end of this &le. #is for!at applies to RC', J':LC co!!ands for this table"
unless speci&cally overridden.
#e range of lines speci&ed by L@CS is resetO the L@CS co!!and !ay be used to select portions
of J':LCs to read.
f you donDt specify the &lena!e" and if SM knows how to skip tables" it will skip over B,7s that
it has already read" provided that the SM variable save_read_ptr is set (which it is by defaultO
see section Read).
#e RC', J':LC co!!and is used to read data fro! a table. f you specify a for!at string and a
list of na!es" a vector will be read fro! each colu!n speci&ed in the for!at and assigned to the
corresponding vector (for e.a!ple" :,8+ 84-, '!")if#' ; i ! y < will skip <X bytes
at the start of the row" then read an integer into i" and two colu!ns of Koats into ! and y).
Qor!at strings are described at the end of this section.
f you specify the for!at as 'byname'" the na!es of the vectors will be taken to be the na!es of
colu!ns in the &le" and the corresponding colu!ns will be read. f the colu!n na!e" say :+-"
speci&es an array" the vector will be &lled fro! colu!n :+-Y.QO as an alternative to this you can
specify the na!e as (e.g.) :+-Y#Q in which case vector :+-# will be created fro! colu!n
:+-Y#Q. Iou can also say :+-Y.-#Q to read vectors :+-." :+-"" and :+-#. :yna!e access is
only currently supported for QJS binary tables (as a special case" you can specify byname as the
for!at in a &lecap &le).
#e na!e that you give will be used as the na!e of the vector" but the !atching with the binary
table is done without regard to case" so
read table 'byname' ; 8lAo9qLi9 <
and
read table 'byname' ; 8lgonquin <
will read the sa!e colu!n of the table into two diUerent vectors" 8lAo9qLi9 and 8lgonquin.
Qor tables where byname for!ats are acceptable" you can list the available colu!n na!es with
LSJ J':LC.
f you specify the for!at as Dbycolu!nD" the list is e.pected to be a list of pairs of values (si!ilar to
the regular :,8+ ; ! " y # ... < co!!and). #e &rst ele!ent of each pair is the na!e of
a vector" the second !ay be either a nu!ber or a colu!n na!e (if supported). #e nu!ber gives
the desired colu!n with respect to the current for!at string. Qor e.a!ple"
84-, 'dC' file
:,8+ 84-, 'bycolumn' ; ! " y # <
will read ! and y fro! the &rst two colu!ns of the &le" whereas
84-, '!%dC' file
:,8+ 84-, 'bycolumn' ; ! " y # <
will read ! and y fro! the second and third colu!ns of the &le" assu!ing that a double (the d) is
eight bytes wide.
nstead of a nu!ber" you !ay be able to specify a colu!n na!e" for e.a!ple
:,8+ 84-, 'bycolumn' ; !_u rowcY.Q !_g rowcY#Q <
but this depends on your chosen Htable_type having support for byna!e access. n general
you will not be able to !i. na!e% and colu!n% orientated access (for e.a!ple" we do not support
colu!n orientated access to QJS binary tables unless you provide a for!at).
J':LCDs for!ats are strings (i.e. they !ust be enclosed with 6). consisting of a set of types
followed by optional repeat counts" for e.a!ple '!"#f*dC' would specify a table" each of
whose rows had <- unwanted bytes" G Koats" and the rest integers. Qor!at leters are$
a
' <%byte ascii string
c
' <%byte char
d
'n W%byte double
f
' >%byte Koat
i
' >%byte int
l
' long int (!ay be W bytes on so!e !achines)
s
' -%byte int
!
< byte to skip (a space !ay be used instead of an .)
and each !ay be followed by a repeat count (default$ <)" or a 0" !eaning to repeat as !any ti!es
as &ts into a row. n all cases e.cept a" the repeat count refers to how !any colu!ns there are (so
d$ !eans > doubles)O for a it refers to the length of the string (so a> is one >%byte string). @ote
that the !a.i!u! length of an a table is the length of an ele!ent of a string%valued vector
(usually >?" but con&gurable by whoever built your copy of SM).
Beader keywords !ay be available with the ,CQ@C na!e M'=C co!!and.
4ermtype
1ynta!: ,:=@?, word Y 09,A,: Q
Set the ter!inal type to be J5:+. #is has nothing to do with graphics" but is to do with the
history and !acro editors. J5:+ is case%sensitive. 9ith two e.ceptions" the properties of the
ter!inal will be read fro! the ter!cap &le (see section Jer!cap %% ' Jer!inal ,atabase). f J5:+
is dumb SM tries to support editing on a (very) stupid ter!inal. f this isnDt what you want" for
e.a!ple you are running SM fro! within e!acs ,:=@?, none is e/uivalent to starting SM
with the -s Kag and entirely disables input line editing (although co!!ands are still re!e!bered
so co!!ands like playbac/ and hcopy will still work). Iou can turn editing back on by
issuing a ,:=@?, co!!and with a valid ter!inal na!e.
Qor !ost purposes you donDt even need to use this co!!and" as when SM starts up it reads the
value of the environ!ent variable ,:= (under 7ni.) or logical variable (under 8MS) it
eUectively issues a JCRMJIPC co!!and with its value as argu!ent. f you have a term entry in
your `.sm' &le this takes precedence over any ,:= variable. Qor e.a!ple" a term entry of
selanar -#" is e/uivalent to the co!!and ,:=@?, selanar -#".
Iou also should not have to use the optional 09,A,: argu!ent" which speci&es the nu!ber of
lines that will appear at a ti!e when LSJing things" as this infor!ation is usually derived fro!
ter!cap. f you are using a window syste!" then ter!cap !ay be wrong and this argu!ent !ay
be useful. 'nother e.ception occurs when you wish to disable cursor !otion to avoid having your
graphs scrolling oU the screen. f this concerns you see section Jer!cap %% ' Jer!inal ,atabase.
4ic(si=e
1ynta!: 03E10F, 1=8--6 40A6 1=8--@ 40A@
,eter!ine tick intervals for :*;. 1=8--6 refers to the interval between s!all tick !arks on the
. a.is" 40A6 refers to the interval between large ticks and so forth. f 40A is ?" the a.is routine
will supply its own intervals according to the label li!its. f 1=8-- M ?" the a.is will have
logarith!ic tick spacing and :*; assu!es that the li!its are logarith!s" e.g. j- and - refers to
li!its of ?.?< and <??. f both 40A and 1=8-- are ?" youDll get SMDs default behaviour.
@egative values of 1=8-- and 40A are interpreted as specifying the tickspacing in the decade
<$<?" and are scaled to &t the decades actually ploted. Qor instance" if you say
-0=01 . " & $
03E10F, -" ". -.." " 456
then the .%a.is will have s!all ticks at -" 5" ..." H and big ticks at < and <?" while the y a.is will
have s!all ticks at <<??" <-??" <5??" ... and big ticks at <???" -???" 5???" ... (Iou !ight want to use
@*J'J*@ to stop SM using e.ponential notation for the <???? label). #e !ost usual J(3SPC
is probably -" "." and this !ay be writen -" . for backwards co!patibility.
*ccasionally you !ay want to use the sa!e tickspacing in all decades of your plot. Jo do this
!ake 40A negative also in which case the spacing used for the &rst decade ploted will be used
for all decades. (@ote that this !eans that if the a.is is ploted backwards then the value fro! the
largest decade will be used)$
-0=01 ".' #." #." ".'
03E10F, -.." -" -.." -" 456
this is a good way to !ake an a.is very crowdeda
f you really cannot use J(3SPC to acco!plish your needs" you can use ';S and provide
vectors specifying the positions of the big and litle ticks" and even the a.is labels.
<ser
1ynta!: L1,: 845: Y string Q
L1,: integer string
#e &rst for!" 7SCR ':*RJ" is used to generate a synta. error" and return to the pro!pt (with a
traceback if youDve re/uested one with the tracebac/ variable). #e co!!and reported as the
oUender is string if provided" otherwise L1,: 845:.
f you want to catch these errors you can de&ne a !acro abort_handler which will be called
with the !essage as all of its argu!ents instead of causing SM to return to the co!!and pro!pt.
Qor e.a!ple" use
abort_handler """ 7 catch L1,: 845:
echo 3aught user abort: H"
7
@ote that the argu!ent e.tends to the end of the line %% this is i!portanta f abort_handler
took a single argu!ent" what would the co!!and L1,: 845: good bye world doT Qirst
the handler would be called as abort_handler good bye world. tDd pull oU the &rst
argu!ent good and print it and SM would continue to process bye as a co!!and. tDs neither a
co!!and nor a !acro" so the default macro_error_handler e.ecutes L1,: 845: bye
is not a macro] aborting. :est of line: world. #e abort handler pulls of the
bye" and tries to e.ecute is %%% and we have an in&nite recursion that is broken only by a I3 or
by reaching the !a.i!u! depth to which SM will nest abort handlers.
#e other" with an integer" calls a function called YuserfnD" passing the integer and the string as
argu!ents" both are passed by address as if SM were writen in fortran (string is passed as a @7L
ter!inated ( string" though).
#is function is provided to allow users without ( co!pilers to !ake additions to the !ain
gra!!ar" but whether it is really useful is a diUerent !ater. (urrently" if integer is non%Sero
then both integer and string are printed unless integer is "" in which case the co!!and
L1,: " r ".#& is e/uivalent to 1, rB".#& (only constants are allowed).
f string is dump youDll get a !acro stack trace" and if itDs segv youDll get a seg!entation
violation (on purpose). f you really want so!e new functionality" send us !ail.
6erbose
1ynta!: 2,:451, 09,A,:
Make SM produce output on what it is doing if 09,A,: is N ?. Seting 8CR:*SC to ? is a way of
only listing Yi!portantD (non%syste!) !acros" and generally geting a litle peace and /uiet. t has
the considerable disadvantage that you can think that you are reading data fro! &les" while
actually so!ething is wrong. Qor this reason the default value is <. ' value of - or !ore is
basically useful for debugging. f you get so!e nondescript synta. error and donDt know where it
is co!ing fro!" 8CR:*SC of 5 or > will trace your progra!!e" and should help &nd the proble!.
#e original error !essage will tell you which !acro SM thinks it is processing when the error
occurred but it will be wrong if the !acro had been fully scanned when the error is detected. n
this case it will report a parent of the current !acro. #e reason for this behaviour is related to
why :,L:9 can return fro! the wrong place (see section #e (o!!and nterpreter).
f you want to know the current value of 8CR:*SC you can use the SB*9 co!!and (actually a
!acro)" or try
+,S09, verbose +,-,, echo 2erbose: Hverbose
which is (of course) what SB*9 does anyway.
f verbose is one or !ore SM will$
(o!plain about things like division by Sero" and logs of negative nu!bers the &rst ti!e
that they occur in a given e.pression
(orrect you when you use the wrong for!at to print a vector
dentify the ;<< device that you switch to with -dev g1%h
nclude all !acros in !acro listings" even those starting ^^
ndicate line where arith!etical errors occur
List all non%printing key%bindings with LSJ C,J
@ote !ore than >? curve crossings in SB',C
@otify user when a control-3 stopped the production of a hardcopy
*utput a litle e.tra about RCSJ*RC and S'8C
Print lines beginning ^ while reading !acro &les
Provide so!e conte.t with 'PR*P*S on help &les
Realise that a 9@,*9 nu!ber is out of range
Report which lines are read fro! a &le using RC',
Re!ind you that !i.ing L*('J*@ with 9@,*9 confuses people
Say so!ething about for!at and siSe of M'=C &les
Suggest that you change L*('J*@ to !ake roo! for a.is labels
Jell you what keys to use with the cursor
9arn about Sero%length vectors
9hinge about !issing &elds with ,CQ@C var RC', ^ ^
9rite a note when it &nds out%of%range values while contouring M'=C &les
if 09,A,: is two or greater" then also $
'nnounce when the do" foreach" input" or !acro stacks are e.tended
(o!plain if an environ!ent or SM variable is not de&ned
Ccho lines in data &les that start with ^
nclude YinternalD variables in LSJ ,CQ@C output
nfor! you when it seeks to a line in a data &le
List all key%bindings with LSJ C,J
@ote ate!pts to YunputD oU boto!s of buUers (this is related to the i!ple!entation of
!acros and variables)
Point out ate!pts to delete local variables and vectors
Print the fraction of a.es covered by the tick labels
Pro!pt for variables" even if they are on the !acro buUer
Protest if you reference an unde&ned history nu!ber
Re!ark if a variable is referenced in a graphcap SI string" but not provided
Re!ind you that only a &nite nu!ber of 3CI co!!ands can be processed
Repeat co!plaint about things like division by Sero" and logs of negative nu!bers every
ti!e that they occur
Report vectors of diUerent lengths in PR@J
Say when a vector is used as a scalar.
Jell you when vectors are rede&ned.
9rite a note when it &nds out%of%range values while contouring M'=C &les.
if 09,A,: is three or greater" then also $
List each !acro na!e 4ust prior to e.pansion.
if 09,A,: is four or greater" then also $
Print each token as it is recognised along with its te.t. #e nu!ber in
colu!n < is the value of Ynoe.pandD" the level of nesting of _Z loops.
Show e.pansions of variables.
if 09,A,: is &ve or greater" then also $
Print the contents of ,*" Q*RC'(B" Q" and M'(R* co!!and lists.
Pro!pt for ,CQ@Cing variables and the values of !ulti%word variables.
f you set a negative verbosity" then if the parser was co!piled with ,C:7= de&ned" youDll get a
veritable torrent of debugging infor!ation. 7se another negative 8CR:*SC co!!and to turn it
oU again.
6ersion
1ynta!: 2,:1059
Return a string identifying the version of SM in use. f you have any reason to co!!unicate with
SMDs authors" weDll want to know which version you are running. 's a !ater of fact" version is a
!acro to print Hversion.
6iewpoint
1ynta!: 20,J?509 theta phi l
Surfaces are drawn fro! a direction DG,8>?G0)" and pro4ected onto a surface passing
through the origin. #e pro4ection is fro! a point - away fro! the nearest corner of the cube
containing the i!age. f - is positive a perspective pro4ection is usedO if it is ? the viewpoint is
taken to be in&nitely far fro! the surface" and if it is negative an a.ono!etric pro4ection is used
(i.e. the surface is pro4ected fro! in&nity onto the .%S plane).
#e coordinate syste! is such that the S%a.is is G,8B'." the .%a.is is DG,8>?G0) B
D.>.)" and the coordinate syste! is right handed. 'ngles are taken to be in degrees" with theta
lying in gjH?"H?h and phi lies in gj<W?"<W?h. #e nearest corner of the cube containing the surface
is pro4ected onto the point (?"?).
#ere are so!e useful !acros in the &le `surfaces'O say load surfaces to read the!. f
8CR:*SC is one or !ore" a helpful header will be printed when you load the &le.
Whatis
1ynta!: Jhatis D e!pr )
9B'JS(so!ething) has a value depending on what so!ething is$
a number: .
not a number: set ." bit Dbit .)
a macro: set .# bit Dbit ")
a variable: set .$ bit Dbit #)
a vector: set .". bit Dbit &)
a float vector: set .$. bit Dbit *)
a string vector: set .".. bit Dbit ))
a long vector: set .#.. bit Dbit ()
a /eyword: set .#. bit Dbit $)
So if 6aa6 is the na!e of a string vector" 9B'JS(aa) has the octal value ?<<<" or F5" whereas
9B'JS(BCLP) has the value ?-<" or <F" and 9B'JS(<) is ?. #ere is a !acro in `utils'
called is_set that tests if 9B'JS sets a particular bit" for e.a!ple
ifDis_setD///>&)) ; echo /// is a vector <
tests if bit 5 (vector) is set for 6kkk6 and prints its &ndingsO itDs easier to say
ifDis_vectorD///)) ; echo /// is a vector <
which does the test for you.
Window
1ynta!: J09+5J n! ny ! y
9@,*9 !akes the current plot location the window at (."y)" where there are n. windows
across and ny windows up and down. 9@,*9 < < < < resets the plot location to the entire plot
area. #e siSe and place!ent of the windows is decided by the value of C;P'@, when the
9@,*9 co!!ands are issued" so be sure that C;P'@, has the sa!e value for every window
in a set. (tDs used to &gure out the a.is labels" and spacings between bo.es). 9hile ploting to a
given window you can of course change C;P'@, to your heartDs content.
f the nu!ber of windows in either the . or y direction is negative no space is le) between the
bo.es in that direction (try ,* i`<"5 _ 9@,*9 " -& " Hi :*; Z). tDs possible to overload
YwindowD and Ybo.D to only label e.ternal a.es in blocks of touching bo.es.
f either . or y is speci&ed as" e.g. -$>" the window is set to cover the range -%> (i.e. the part of the
screen covered by windows -" 5" and >). @ote that this feature can be used to split the screen in
arbitrary ways" e.g.
window -" -) " ":* bo!
window -" -) " ) bo!
(or you could say window -#. -#. "*:"' "*:"' as an alternative to a L*('J*@
co!!and).
f you donDt want bo.es that touch" but you donDt like the gaps le) between bo.es by the J09+5J
co!!and" you can now do so!ething about it legally" without lying to SM. ')er we calculate the
widths of the YgutersD between the windows that we think that you need" they are !ultiplied by
the values of the SM variables !_gutter and y_gutter" so if you think that the spacing is too
large in the . direction you can say
define !_gutter ..*
window # # " " bo!
window # # " # bo!
to !ake things look beter. 9ithin a !acro it can be convenient to say local define
!_gutter ..*" as then the guter value so)ly and suddenly vanishes at the end of the !acro.
tDs confusing to change L*('J*@s while using 9@,*9sO you probably want to say
9@,*9 < < < < &rst.
While
1ynta!: JG0-, ; e!pr < ; commands <
Repeat the commands while the e!pr is true. Iou can break out of the loop early with the
:RC'3 co!!and (see section :reak).
#ere is further discussion in section See section ,* and Q*RC'(B loops" 9BLC loops" and Q
state!ents.
Qor e.a!ple"
define i .
while;Hi R ".< ;
echo Gi Hi
define i DHiO")
<
is e/uivalent to either
do iB.>' ;
echo Gi Hi
<
and
set iB.
while;i WB "..< ;
ifDi BB ".) ; brea/ <
echo Gi HDi)
set iBiO"
<
e.cept in so !uch as which variables and vectors are de&ned at the end.
Write
1ynta!: J:0, 189+8:+ string
J:0, YOQ J5:+ string
J:0, G015:@ J5:+
9RJC SJ'@,'R, writes a string" followed by a newline" to the standard output. #e string is
taken to be the rest of the line up to a carriage return (which !ay be writen e.plicitly as \n). #e
!acro echo is usually used as an abbreviation for this co!!and. 9RJC J5:+ is si!ilar" e.cept
that the string is writen to &le J5:+. f the &lena!e is the sa!e as the previous 9RJC" or if you
preface the &lena!e with a O" the string is appended" otherwise the &le is overwriten.
9RJC BSJ*RI J5:+" writes !acro J5:+ onto the end of the history list.
Qor M'(R* 9RJC" see under !acros.
:label
1ynta!: 6-84,- str
9rite the label str centered under the . a.is !ade by :*;. #e string is taken to be the rest of
the line up to a carriage return (which !ay be writen e.plicitly as \n). f you think that the label
is badly positioned you can say things like
6-84,- Mraise-*..=y 6-a!is -abel
(providing that you use Je;%style fonts" of course)
f the label is too tall it !ay overlap with the nu!erical tick!ark labels. f 8CR:*SC is one or
!ore" youDll be warned about this" and a suggested change to the plot L*('J*@ will be
suggested. #is !oves the entire plotO it is your responsibility to reset it later if appropriate.
f '@=LC is non%Sero" it will be used to deter!ine the direction of the label" otherwise it is
parallel to the . a.is.
See section ,rawing Labels and SMDs Je; C!ulation" for a description of how to enter a label
with funny characters" sub% and super%scripts" and so forth.
f C;P'@, is set to e.actly <" and '@=LC is e.actly ?" then SM will use hardware fonts" when
available" in writing labels. #is is faster" but if you donDt like it say 6C;P'@, <.???e?<6" or start the
string with a \? which does nothing" but forces the so)ware character set.
>label
1ynta!: @-84,- str
9rite the label str centered to the le) of the ya.is !ade by :*;. #e string is taken to be the
rest of the line up to a carriage return (which !ay be writen e.plicitly as \n). f you think that the
label is badly positioned you can say things like
@-84,- Mraise*..=y @-a!is -abel
(providing that you use Je;%style fonts" of course)
f the label is too tall it !ay overlap with the nu!erical tick!ark labels. f 8CR:*SC is one or
!ore" youDll be warned about this" and a suggested change to the plot L*('J*@ will be
suggested. #is !oves the entire plotO it is your responsibility to reset it later if appropriate.
f '@=LC is non%Sero" it will be used to deter!ine the direction of the label" otherwise it is
parallel to the y a.is ('@=LC 5X? will achieve horiSontal labels).
See section ,rawing Labels and SMDs Je; C!ulation" for a description of how to enter a label
with funny characters" sub% and super%scripts" and so forth.
f C;P'@, is set to e.actly <" and '@=LC is e.actly ?" then SM will use hardware fonts" when
available" in writing labels. #is is faster" but if you donDt like it say 6C;P'@, <.???e?<6" or start the
string with a \? which does nothing" but forces the so)ware character set.
Appendices
(o!!and nternals$ Bow #e (o!!and nterpreter 9orks
=raphcap$ Bow SM uses =raphcap to Plot to al!ost any ,evice
(alling SM$ (alling SM fro! Progra!!es
=ra!!ar$ #e SM =ra!!ar
-%, =raphics$ Jwo%,i!ensional =raphics
Jables$ Reading and writing tables
Jer!cap$ Jer!cap %% ' Jer!inal ,atabase
@ew ,evices$ 'dding @ew ,evices" and Porting to @ew Machines
Libraries$ #e Syste! Macro Libraries
Mongo$ Jips for Mongo 7sers
Qonts$ SMDs Qonts
4he "ommand 5nterpreter
#e basis around which the co!!and interpreter is writen is a gra!!ar which is passed a set of
tokens ( analogous to words in Cnglish ) which it parses" given a set of gra!!atical rules. 's it
recognises each rule" it e.ecutes the code associated with that rule. See section #e SM =ra!!ar.
'n e.a!ple would be$
aa : 44 33
;
printfDN:ule 44 33 foundMnN)]
<
which speci&es that the rule aa consists of the token 44 followed by 33" and that if rule aa is
recognised the progra!!e should print that fact out. (onventionally" uppercase na!es are
reserved for Yter!inal sy!bolsD" and lowercase for Ynon%ter!inal sy!bolsD where ter!inal
sy!bols are those that are passed to the parser ( analogous to words )" and non%ter!inal sy!bols
are tokens that the parser has constructed out of ter!inal sy!bols (analogous to phrases). #e
right hand side of a rule !ay contain a !i.ture and non%ter!inal sy!bols" and sy!bols !ay be
assigned a value(->).
4o(en ;eneration
SM generates tokens for the gra!!ar roughly as follows$ 9hen characters are typed at the
keyboard" they are read by a routine which runs in (:RC'3 !ode (P'SS'LL for 8MS)" and
receives each character as it is typed. t is this routine that handles co!!and line editing" the
history syste!" and key bindings.(-G) Qollowing a carriage return" it passes the whole line to the
le.ical analyser" which divides the input strea! into integers" Koats" strings" or words. n addition
it recognises H;<I as having special !eanings (see below under variables (H) and history (I)). 's
in (" the escape se/uence Y\nD is replaced by a newline" which !eans that co!!ands which read
to the end of the line !ay be fooled into thinking that they have found itO see the e.a!ples at the
end of the section. ' ; sets the Kag Ynoe.pandD" which turns oU the interpretation of all special
sy!bols" and causes all tokens to be returned as J5:+. #e !atching < unsets this Kag. #is
!echanis! is used in de&ning !acros and various lists. ' word is anything which is not
otherwise recognised" so for e.a!ple Yhello]there.cD or Y<.-eD would be considered words. Sy!bols
are separated by white space" taken to be spaces tabs or newlines" or the characters W" ;" <" O" -"
C" /" B" V" W" >" R" T" D" or ). #is behaviour can be !odi&ed by enclosing a string in double
/uotes" when no characters (e.cept I) are special" and tokens are deli!ited only by the end of the
line" or so!e character a)er the closing /uote. Cnclosing in /uotes is rather si!ilar to enclosing in
_Z" e.cept that /uotes have no gra!!atical signi&cance. ' string in double /uotes is always
treated as a word" but the /uotes !ust not have been discarded by the ti!e that the le.ical
analysis occurs. Qor e.a!ple" N#.%.N is a Koat" as SM will have digested the N before looking at
the string. Iou can fool it with N#.%. N. ' string begins with a ' and continues to the ne.t '$
they are used in certain conte.ts where SM needs to know if a J5:+ or 1:09A is involved" for
e.a!ple in a ?:09 co!!and. tDs worth noting that the '...' are stripped when the string is
recognised %% if you need to preserve the! !ake sure that noe!pand is set (e.g. 1, sB; 'a'
'b' 'c'< ).
#e output fro! this progra!!e is passed to a second stage of le.ical analysis. #is passes
integers and Koats through unaltered" while words are passed through a &lter to see if they are
e.ternal tokens(-X) fro! the gra!!ar (such as 3599,3). f a word is recognised as being a
token then that token is returned" otherwise the token J5:+ is passed" and the te.t of the word is
stored. Jokens !ay be writen in either lower or upper case" but for clarity they are writen in
upper case in this docu!ent. #e overloading of lowercase tokens is achieved at this stage by
si!ply refusing to recognise the! as keywords.
#e input strea! is now fully analysed into tokens and is passed to the parser" which is writen in
I'((. f the se/uence of tokens seen corresponds to a gra!!ar rule" the parser e.ecutes the
appropriate section of code" which is writen in (. f the parser doesnDt understand" it tells you
that you have a synta. error and prints the last logical line that it was processing" with the error
underlined. f you canDt &gure out which co!!and it really failed on" try seting the 2,:451,
Kag to be > or !ore. #is produces a volu!inous output" which will stop suddenly when the error
re%occurs. *ne si!ple rule in the gra!!ar is that a J5:+ should be treated as a possible !acro.
,eculiarities of the ;rammar
f the co!!and interpreter is faced with a pair of gra!!ar rules such as
88 44 33
and
88 44
it !ay not know whether to treat the tokens 88 44 as the &rst part of 88 44 33 or as the
co!plete co!!and 88 44 followed by the token 33 beginning the ne.t co!!and without
e.a!ining the ne.t token. #is a!biguity only arises if a co!!and can begin 33" and !ay be
dealt with by de&ning the second rule as
88 44 Mn
#is should be borne in !ind whenever SM co!plains about a synta. error in an apparently valid
co!!and (such as -01 =83:5 G,-?" intended as &rst -01 =83:5 and then the valid
co!!and G,-?). #e presence of a re/uired carriage return also so!eti!es re/uires that !acros
be spread over a nu!ber of lines rather than as one long list of co!!ands" although a carriage
return !ay always be writen as Y\nD" which !akes SM think that it has found a carriage return.
#ere is a also re/uire!ent that an ,-1,less 0S state!ent should end with a newlineO this is
produced by a subtlety of the way that 0SDs are processed and is discussed under 0S.
SM places a restriction upon co!!ands such as :,-538, which e.pect !ore than one
argu!ent" which is that the argu!ents !ust be nu!bers rather than (scalar) e.pressions. #is is
re/uired by the unary !inus" as if the gra!!ar sees e!pr" - e!pr# it cannot know whether
this is the two e.pressions e!pr" and -e!pr#" or the single e.pression e!pr"-e!pr#. 7nless
the gra!!ar is changed" for instance by using co!!as to separate argu!ents" this restriction
cannot be li)edO it can" however" fre/uently be circu!vented using !acros such as rel discussed
under Y7seful MacrosD. 's an alternative" in al!ost all cases the e.pression can be enclosed in
parentheses" for e.a!ple connect DlgD!)) D-lgDrho)).
4he Macro ,rocessor
C.ecuting a !acro consists of substituting the te.t of the !acro for its na!e. n order to
understand how SM does this you have to know a bit !ore about how it processes input
characters. 9e said above that it Ypassed the whole lineD to the le.ical analyser. 9hat it actually
does is to pass a pointer to the line" and starts reading fro! the beginning of the line. @ow if you
e.ecute a !acro" all that is done is that we now pass a pointer to the te.t of the !acro" and start
reading fro! it instead. #e old pointer is pushed onto the top of a stack. 9hen SM co!es to the
Y\?D at the end of the !acro te.t" the stack is popped and input continues as if the !acro had never
been seen. 9hen we co!e to the end of the Ywhole lineD pushed at the top of this paragraph" it is
popped" and SM gives you a pro!pt for !ore input. *f course" if a !acro had been seen while the
&rst !acro was being e.ecuted" the &rst one would get pushed onto the stack" and atention
transferred to the the new one. f a !acro has any argu!ents" their de&nitions are pushed onto an
argu!ent stack which is popped at the proper ti!es. Jo 4u!p ahead a litle" variables are
i!ple!ented in a very si!ilar way" being pushed onto the stack" as are +5 and S5:,83G loops"
and perhaps !ore surprisingly 0S state!ents.
#e strange behaviour of :,L:9 at the end of !acros co!es about because when the input
routine is reading the :,L:9 it has to read one character beyond it" so as to know that it isnDt
dealing with" say" :,L:9_5S_G,_9802,. :ut in looking for the ne.t character it has to pop
the !acro oU the stack" so when the :,L:9 is acted upon we have already returned fro! where
we wanted to return fro!" and we now :,L:9 fro! the wrong place. n a si!ilar way" an 0S at
the end of a !acro will cause the parser to look for an ,-1," thereby popping the !acro stack if
there isnDt one. f the 0S test was true" and contained references to !acro argu!ents" there will be
a proble! as either there will be no !acros de&ned" or the argu!ents to the previous !acro on
the stack will be supplied.
Tis behaviour is changed in SM%&<&C and aboveD an automatic space or newline is added at the end o"
every macro* avoiding this problem&
Macro de&nitions are currently stored in the for! of a weight%balanced tree (actually a tree). #is
!eans that the access ti!e for a given !acro only grows as the logarith! of the total nu!ber
de&ned. n the future it !ay be possible to choose the weights depending on the access
probability for a given !acro" but this is not currently possible. ,e&nitions of variables and
vectors are stored in the sa!e way.
4he #89 '8R*A"H9 and 5' commands
t see!s worth discussing the i!ple!entation of these co!!ands. :oth loops consist of a
de&nition of a variable" together with instructions about what to do with it" followed by a list of
co!!ands within a set of _Z" while 0S 4ust has the co!!and list. t is not possible for the !ain
gra!!ar to e.ecute co!!ands or !acros" as the I'(( i!ple!entation is non%reentrant" so the
best that it can do is to push the co!!ands onto the input stack as a sort of te!porary !acro"
a)er de&ning the initial value of the loop para!eter. 9hen the Y\?D at the end of the loop appears"
instead of popping the !acro stack we si!ply de&ne the loop para!eter to have its ne.t value"
and 4u!p back to the beginning. #is !eans that you canDt change the value of a loop para!eter"
as itDll be reset anyway" but you can use it as a sort of local variable.
0S state!ents are si!ilar" in that we read the entire list before e.ecuting it. *nce !ore" a
te!porary buUer is pushed onto the stack" with instructions to delete it a)er use. #e reason that
a newline is re/uired a)er an ,-1,less 0S is that the gra!!ar will have already read the ne.t
token to see if it was ,-1,. f it wasnDt" then it will see! to have been typed before the body of
the 0S. Qor e.a!ple" 0SD test ) ; echo Gello < ?:5=? : will be parsed as
0SD test ) ; ?:5=? echo Gello < : if test is true" but correctly as 0SD test ) ;
echo Gello < ?:5=? : if it is false. :ecause an e.tra \n does no har!" we de!and it.
*+amples of How SM ,arses 5nput
f you want to watch SM thinking about these e.a!ples" the co!!and 2,:451, $ will !ake it
print out in detail each token as it reads it" and each !acro or variable as it e.pands it. Jo turn
this oU" use 2,:451, . or 2,:451, ". Jo really see the parser at work" try a negative value of
verbosity. #is will report every step that the parser takes" providing that it was co!piled with
,C:7= de&ned. ' second negative value will turn the infor!ation oU again.
?:5=? [
?:5=? is an e.ternal token" so ?:5=? is passed to the gra!!ar which recognises the
rule ?:5=? J5:+" and sets the pro!pt to be YLD. 9hen it has &nished" control is passed
back to the input routine.
=83:5 p ; ?:5=? <
#is is a si!ple !acro de&ning p to be ?:5=?
p [
#e le. analyser doesnDt recognise p as a keyword" so it returns J5:+ and as the gra!!ar
has no other interpretation of a J5:+ in this conte.t" it passes p to the !acro interpreter"
which replaces it by ?:5=? (i.e. pushes ?:5=? onto the input stack). SM now thinks
that you have 4ust typed ?:5=? [" and behaves as described in the &rst e.a!ple.
=83:5 pp " ; ?:5=? H" <
#e !acro pp is declared to have one argu!ent" which is referred to as E<. ')er pp is
invoked it reads the ne.t (whitespace deli!ited) word fro! the input strea!" and replaces
H" by that word.
pp [
Vust like the &rst e.a!ple" the pro!pt is set to [.
pp
Iou are pro!pted for the !issing argu!ent to ?:5=?.
?:=?
's ?:=? isnDt an e.ternal token" it is a J5:+" so SM tries to e.ecute it as a !acro and
co!plains if it isnDt de&ned.
+,S09, Gi Gello
#e variable Gi is de&ned to have the value Gello.
J:0, 189+8:+ HGi Aentle Lser
9hen it has read HGi SM pushes the value of the variable Gi onto the stack and then reads
it" popping it oU again when it has &nished. #e J:0, 189+8:+ co!!and writes
Gello Aentle :eader (i.e. up to the end of the line) to the ter!inal.
J:0, 189+8:+ HGi Aentle Lser Mn pp N1=TN
's above" the rest of the line is writen to the ter!inal (up to the carriage return Y\nD)" then
the pro!pt is changed yet again.
4he Stdgraph ;raphics 7ernel
SM can use a single set of subroutine calls to plot on al!ost any ter!inal" and on !any printers.
#e routines that it uses" called stdgraph" were originally taken fro! the R'Q =* package
writen at 3it Peak by ,oug Jody(-F) and converted to ( and partially re%writen to be integrated
into SM. ,espite our e.tensive rewrite" these routines should probably still be considered to be in
the public do!ain.
=raphcap Qile$ #e =raphcap Qile
:inary Cncoder$ StdgraphDs :inary Cncoder
=raphcap C.a!ples$ C.a!ples of =raphcap Cntries
=raphcap (ursors$ 7sing (ursors with =raphcap
=raphcap (olours$ 7sing (olours with =raphcap
Modi&ed Cntry$ Bow to Modify a =raphcap Cntry
@ew Cntry$ 9riting a @ew =raphcap Cntry
Raster$ Support for Raster ,evices
(o!piling$ (o!piling =raphcap
=raphcap nde.$ nde. to =raphcap (apabilities
4he ;raphcap 'ile
Stdgraph uses a &le called a graphcap &le to specify the properties of ter!inals" in a way that is
si!ilar to the ter!cap facility of 7ni.. Iou donDt have to know anything about ter!cap to read
this sectionO you donDt have to read this section unless you want to change the graphcap &le to
add a new device" to &. a bug" or to change the way that SM treats your ploting device. #e na!e
of the graphcap &le is given by the variable graphcap in the environ!ent &le.
' list of &les to be searched in order !ay be given instead of a single graphcap &le (up to a
current !a.i!u! of three). #e usual way to acco!plish this is to add an entry
Ographcap /u/rhl/sm/graphcap
above any other graphcap entries in your `.sm' &le" which instructs SM to put
`/u/rhl/sm/graphcap' &rst in the list of &les" followed by any others that !ight appear"
either in your &le or in so!e other that the syste! provides (ask the person who installed SM
where the default `.sm' &le isO usually so!ething like `/usr/local/lib/.sm').
' graphcap &le is a way of describing a ter!inal in a concise way" so a progra!!e can discover
which idiosyncrasies a ter!inal has without having to be reco!piled. ' graphcap &le consists of a
nu!ber of entries" one for each device supported" and to add a new ter!inal all that one has to do
is to add another entry. t is also possible to de&ne variables in graphcap &les" which are used in
1@ entries. Iou can co!pile selected entries in the graphcap &le" so as to i!prove access ti!e for
popular ter!inals. f this has been done" changing the graphcap &le for one of these ter!inals will
have no eUect until it is reco!piled" see section (o!piling =raphcap for details.
Qor a list of all the capabilities that SM uses see the inde. to graphcap at the end of this appendi..
So!e devices are not supported through stdgraph (graphics drawn to a Sun8iew window would
be an e.a!ple)" but they still appear in graphcap with a special entry (+2) giving the na!e of the
appropriate hard%coded device driver.
Cach entry consists of a na!e for the device" followed by a list of aliases" followed by a list of
&elds" separated by colons. ' \ !ay be used to continue an entry onto the ne.t line" and lines
starting with a 7 are co!!ents (co!!ent lines are per!ited both between and within entries).
's a rather co!ple. e.a!ple" the graphcap entry for a Jektroni. >?<- reads$
te/$.".Ute/$."#U,E$.".U,E$."#Ue/troni! $."./#:M
:ch7..#'$:cw7.."#*:co7%.:li7&*:!r7".#$:yr7%..:M
:=3BI=:3-BIYI-:397):A+BI6:A,BIY"IQ:M
:=-BIYD"H.)`DH")aDH#)cDH&)dDH$)bDHH:ltB."#&$:M
:5JBIQI_::3BIYIF:13BD>W&> ^ C> ^OW"> ^ C> ^OW#:M
:4BIQ_tI_:21BIQ:M
:!r7".#$:6@B_t:yr7(%.:
#is is one of the longest entries in the graphcap &le % all of the ter!inals which are Jektroni.
e!ulators e.plicitly include this entry" so they only need provide the capabilities that are diUerent
fro! the Jektroni.. 's an e.a!ple" the entry for a Perico! reads
pericomU?ericom:M
:A,BIQ:4BIQD#7(-W#)_tI_:M
:tcBte/$."#:
#e U separate the aliases" and the &nal &eld tcBte/$."# tells stdgraph to take all other &elds
fro! the entry for te/$."#" given above. f you have speci&ed a list of graphcap &les" each will
be searched in order for each :tcB continuation. f you donDt want the search to begin again use
3" e.g.
graphonUAraphon which claims to support lw:M
:-JB:3Bgraphon:
if you had used :tcBgraphon: this would have been recursive and illegal" but as 3 doesnDt
restart the search it !erely has the eUect of adding (or in general" replacing) an capability in a
pree.isting graphcap entry.
(ontrol characters are entered as ['" [:" and so on (those are two characters" Y[D and Y'D).
YCscapeD !ay be represented as [g" \C" or in octal as \?55. :ecause the nor!al way of handling
strings in ( treats M. as !eaning Yend of stringD you canDt si!ply put a M... into a graphcap
entry" instead write M&(( and SMDll interpret it as M.. (f you need a real M&(( enter M
&((M&((). f a delay of so !any !illiseconds is re/uired before the trans!ission of a string" it is
given &rst (followed by a C if it is to be applied to each line aUected). #is leads to proble!s with
graphcap entries that start with nu!bers" you !ust precede the! with a space or (if the string is
run through the encoder) insert a no%op e.g. :3?BD)"...:. @u!erical values are preceded by a
^" so :co7%.: !eans that co (the nu!ber of colu!ns displayed) is W?" while :=3BI=: !eans
that M( (the cursor deli!iter) consists of the character [M. #is could 4ust as well have been
writen :=3BM.".:. f the &rst character of a capability is YLD" it speci&es that that capability is
not present for that ter!inal (e.g. :lt[B"#&$: speci&es that lt is not de&ned). ' &eld !ay
si!ply not be provided if it is irrelevant" although in this case it !ay be supplied by a tc or 3
continuation. ' co!!on set of graphcap entries to Yco!!ent outD are 4 and ," which deal
with hardware character sets. f you donDt want your ploter to use itDs internal fonts si!ply insert
YLD before the Y`D. :y inserting their private &le before the syste! one in the list of graphcap &les"
users can tailor the entries to their liking.
9e use a subset of the graphcap capabilities de&ned by the R'Q group" and the distinction
between upper and lower case para!eters co!es fro! the!. n a few cases our usage is diUerent
fro! theirs" in these cases we have speci&ed our own capabilities (3+ =3" ++ 1@" - =-" and 1
4. 9e have also added the lt" 4?" 4:" 35" 31" 3" +3" +" +2" ,?" ,:" and 3. capabilities.).
Qirst the lower case" which specify !ostly di!ensions$
ch
Beight of a character" relative to the screen height being <.?.
co
@u!ber of colu!ns displayable" with characters of width cw.
cw
9idth of a character" relative to the screen width being <.?.
li
@u!ber of lines displayable" with characters of height ch.
lt
9hich linetypes are supported in hardware.
pc
Pad character for delays (use @7L if not supplied).
!r
. di!ension of ploting device. #is !ay be speci&ed as an argu!ent fro! the +,203, line.
C.g. for +,203, e!ample "#.. "$.." :!rBH":yrBH#: is e/uivalent to
:!r7"#..:yr7"$..:
yr
y di!ension of ploting device. See the previous entry for an e.a!ple.
*f these" co and li are not currently used.
#e capitalised capabilities !ostly tell the stdgraph routines how to plot lines" clear the screen
and so forth. So!e of these are no !ore than character strings to send to the ter!inal" (e.g. 3- to
clear a screen)" but so!e use the graphcap entries to progra!!e a sort of RP@ calculator" which
co!putes the bit%paterns that the ter!inals de!and. #is calculator is usually referred to as the
YencoderD. 9eDll &rst list all the capabilities in a reasonably ordered way" then describe the encoder
and what it can do" and then go through a nu!ber of e.a!ples.
Qirst the &elds which are si!ple character strings to be writen to the ter!inal. #e second
colu!n is an ate!pt to e.plain the ety!ology of the two character na!e.
3- D3-ear)
(lear the screen" possibly also the te.t screen.
3J D3lose Jor/station)
(lose ter!inal" e.pect no !ore graphics.
+1 D+raw 1tart)
Prepare the ter!inal to draw a line.
+, D+raw ,nd)
Qinish a line.
S+ DSill +raw)
,raw a side of a &lled polygon.
S, DSill ,nd)
Qinish drawing a &lled region.
S1 DSill 1tart)
Start drawing a &lled region.
A+ DAraphics +isable)
Return the ter!inal to a character !ode.
A, DAraphics ,nable)
Set the ter!inal to graphics !ode.
0S D0nitialisation Sile)
7sed to supple!ent *9 if se/uence is too long.
-: D-oad :egisters)
(7sed by the RP@ encoder" see Ybinary encodingD).
=, D=ar/ ,nd)
Qinish a series of dots !ove!ents.
=1 D=ar/ 1tart)
Start a se/uence of dots !ove!ents.
5J D5pen Jor/station)
Prepare a ter!inal to produce plots.
56 D5pen wor/station)
(a continuation of *9).
5@ D5pen wor/station)
(a continuation of *;).
5F D5pen wor/station)
(a continuation of *I).
?A D?aAe)
Start a new page.
2, DV ,nd)
Qinish a series of pen (bea!) !ove!ents.
21 DV 1tart)
Start a se/uence of pen !ove!ents.
Qor hardcopy devices ?A should start a new page. #e A+ and A, are used by ter!inals which
spend so!e of their ti!e being graphics ter!inals" and so!e being regular te.t ter!inals. #e
various 6... Start6 and 6... Cnd6 capabilities assu!e that the points in /uestion are speci&ed by the
6@ entry (e.cept for S1+S, where S+ is used instead). Jypically" the YstartD is used to put the
device into (e.g.) line%drawing !ode" then the line is drawn with a se/uence of 6@Ds" then it is
taken out of (e.g.) line !ode with the YendD. #e support for &lling areas assu!es that a region is
speci&ed by drawing a line around itO if this isnDt so" youDll have to o!it area &ll fro! graphcap"
and rely on SM e!ulating it for you. 'n e.a!ple would be a =raphon =*%-G?" which has an area
&ll where you &ll rectangular areas by specifying opposing cornersO this is not acceptable to SM.
So!e operations re/uire an argu!ent" for instance seting the hardware line type" specifying
which cursor to read(-W)" or specifying coordinates. n the following properties" the e.pected
para!eters are listed a)er the &eld na!es" the &rst to go into register <" the second into register -"
and so on. f you havenDt skipped forward to the section on the encoder this will see! obscure"
but all will beco!e clearer.
35Dr>g>b) D35lour)
Set ne.t colour to (r"g"b).
31Dn) D3olour 1tart)
Start de&ning n colours.
3Di) D3olour ype)
Set a colour.
+3 D+efault 3olour)
Set default colour.
-JDf) D-ine Jeight)
Set the lineweight to f.
=3Di>!>y) Ds= 3ursor)
,ecode a cursor response.
=-Di) Ds= -ine)
Set the linetype to i.
:3Dc) D:ead 3ursor)
Read the cursor. YcD is for co!patibility.
13 D1can 3ursor)
,ecode the cursor reply following a R(.
4D!>y) De!t 4egin)
Start writing te.t at (."y).
, De!t ,nd)
Stop interpreting characters as te.t.
6@D!>y) D6 @)
Cncode the coordinate pair (."y).
So!e of the above co!!ents are a litle cryptic" but we return to the various graphcap
para!eters that take argu!ents as e.a!ples a)er describing the encoder. @ote that it isnDt
su2cient to change the =- entry %% for a linetype to be supported in hardware it !ust also be
included in the lt list" e.g. ltB."#&$. Si!ilarly" for hardware fonts you !ust include ch and
cw" and 4 !ust be present even if it does nothing. @ote that -J is passed a Koating point
nu!ber" and that the special case ? is special" !eaning choose the !ost e2cient line thickness for
the device.
#e following capabilities have to do with rasterising and are discussed in their own section near
the boto! of this appendi.$
4? D4it ?attern)
:it paterns for rastered data.
4:Di) D4egin :ow)
:egin row of rastered data.
,? D,mpty ?attern)
:it patern for rastered e!pty pi.el.
,: D,nd :ow)
Cnd of a row in rastered data.
ll Dl09, l,9AG)
Length of a row for +:Bhe!.
=: D=any :ows)
@u!ber of rows output at once.
nb DnL= b@,1)
@u!ber of bytes to process at once for MR.
:8 D:8ster)
(R' is no longer supported %% see ,8).
:+ D:aster +evice)
Jype of device if not generic.
Raster devices also !ake use of !r" yr" 3J" 5J" 56" 5@" 5F" 5S" and 1@ which are also used by
stdgraph itself.
Qinally there are so!e capabilities that are designed for driving hardcopy devices and devices that
!ay not use stdgraph at all$
+ D+evice ype)
Jype of device in use.
+2 D+ri2er)
@a!e of hard%coded driver.
5S D5ut Sile)
#e &le to direct output to.
: D:ecord erminator)
(RJ is no longer supported).
1@ D1@stem)
#e action to be taken upon closing the *Q &le.
#e 5S &le !ay be speci&ed with the last characters being Y;;;;;;D" in this case the ;s are
replaced by a rando! characters" to !ake a uni/ue &lena!e. f the variable temp_dir is de&ned
in the environ!ent &le" then 5S is created in that directory" otherwise it is put in the current
directory. #e + string" if present" speci&es the type of device in use. (urrently the values are
only used under 8MS" where they are used to decide how to open &les. #e recognised values are
6/!s6 and 6i!agen6. n general ,J should be o!ited" as it re/uires progra!!ing support" but it
can help stdgraph to deal with hostile operating syste!s. Qor a discussion of the +2 entry" See
section @ew ,evices and @ew Machines.
#e 1@ string is passed to the operating syste! a)er graphcap variables have been e.panded
(they are si!ilar to !acros in 7ni.Ds ma/e). ' variable is de&ned with a line like$
name B value
where name !ust start in the &rst colu!n. 'ny white space surrounding the e/uals sign is
re!oved" as are any trailing blanks. f value starts with a E it is taken to be a regular SM
variable. 8ariables !ay be de&ned in any of the graphcap &les in the search path" and if a na!e
appears !ore than once the &rst value found will be used (if you change graphcap without
leaving SM the variables are re%read). #ere is no guarantee that all the graphcap &les in the path
will be read but this is unlikely to be a proble!. #e !a4or use for graphcap variables is probably
for encoding rasteriseDs full na!e$
409 B /usr/local/bin
deviceUsome device:M
:+2Braster:5SBtst_666666:M
...
:1@BH;409</rasterise -r H. HS H":
8ariables are writen as H;name< not Hname" which !eans that they will not (usually) conKict
with the operating syste!Ds uses for dollar signs. #e graphcap variable S is special" as it always
e.pands to the &lena!e speci&ed as 5S. 's a concession to history it !ay be writen as HS
instead of H;S<. 'lso special are HNpromptN" which is replaced by a string read fro! the
keyboard (you are pro!pted with prompt)" and Hn which is replaced by the nDth argu!ent to the
+,203, co!!and. Qor e.a!ple" if the ,C8(C co!!and were +,203, qms lca. Gello
(or +,203, " qms lca. Gello)" then the device na!e qms would be E?" lca. would be E<
and Gello E-. f a YED is found under other circu!stances it is si!ply treated as a dollar sign" but
if you wish you can escape it with a \ (but re!e!ber that the \ !ust itself be escaped so to
e.plicitly escape a dollar in an 1@ string you !ust type MMH). #is !eans that (under 7ni.) you
can access environ!ent variables fro! 1@ strings" e.g. :1@Bmv H;S< HG5=,:. f a variable is
referenced but no value is provided when the device is opened a warning !essage is printedO this
!essage can be suppressed by referring to the variable as (e.g.) H_". #e SI string is only used if
an *Q &le has been speci&ed. #ere is no guarantee that SI is supported by all operating syste!s"
but it is certainly available under 7ni. and 8MS (SI re/uires the ( call Ysyste!()D" as de&ned for
7ni.. 9e have provided one for 8MS" and any serious SM i!ple!entation would have to have
one too.) ' trivial e.a!ple of SI in use on an 7ni. syste! would be$
:1@Bcat HS ] rm HS:5SBout_666666:
(cat prints a &le" ] separates !ultiple co!!ands on a line" rm deletes a &le). :ecause not all
operating syste!s can support !ultiple co!!ands on one line" you can use \n within a SI string
to separate co!!ands. Qor e.a!ple" under 8MS that 1@ string could have been writen
:1@Btype HS. Mn delete HS..C:5SBout_666666:
(Jype adds a Y.lisD unless e.plicitly given a closing Y.D" delete re/uires a version nu!ber" hence the
HS. and HS..C.) 'n e.a!ple of the use of HNN would be
:1@Bmv HS HN5utput filenameV N:
which rena!es the 5S &le to whatever you want.
#e : capability has been deleted in version -.?" in favour of using +O #e :8 capability has
been replaced in version -.< by :+2Braster:.
Stdgraph2s %inary *ncoder
,iUerent ter!inals have very diUerent ways of doing the sa!e thing. Qor e.a!ple to !ove the
bea! to (-??"-??)" a vt->? in RC=S !ode needs to be told Yg-??"-GHhD" while a Jektroni. >?<?
needs YkhkBD. n order to cope with this !uch diversity" stdgraph has a binary encoder with a G?
ele!ent stack" <? registers and about a doSen operators. #e encoder co!!unicates with the rest
of the world through its registers % for e.a!ple in encoding a coordinate pair it e.pects to &nd .
in register <" and y in register -. 9hen reading a graphcap string" initially stdgraph si!ply copies
the input characters to an output string" which is then writen to the ter!inal. #is is e.actly
what it does when it interprets the *9 string for a Jektroni." 5JBIQI_. Bowever" in addition to
characters such as I being special" it also recognises the following as being special$
'
escape special !eaning of ne.t character
_
:egin a for!at string
D
Switch fro! copy into encode !ode.
9hen in YencodeD !ode" the following operators are available$
'
Cscape ne.t character (recognised everywhere)
_
Qor!ated output" e.g. dd" dg" or dt
)
Revert to copy !ode
7nnn
Push signed deci!al nu!ber nnn onto the stack
H
Part of a switch state!ent
.
Pop a nu!ber fro! the stack" and put it in the output string
>
=et ne.t nu!ber fro! input string" and push it onto the stack
`str`
Pro!pt with str" then read a character and push it onto the stack
^
Modulus operator (si!ilar to an '@, of the low order bits)
O
'dd (si!ilar to *R)
-
Subtract (si!ilar to '@,)
C
Multiply (a le) shi) if nu!ber is a power of -)
/
,ivide (a right shi) if nu!ber is a power of -)
R
Less than (?$false" <$true)
T
=reater than (?$false" <$true)
B
C/uals (?$false" <$true)
]
:ranch" MbooleanNMoUsetNO (O is at ? oUset)
.-'
Push register ?%H onto the stack
W9
Pop the top of the stack into register @.
WW
Pop the stack" and delay that !any !illiseconds.
U
(onvert the top of the stack fro! Koat to int (it is rounded rather than truncated).
7nless otherwise speci&ed the stack is taken to be integer%valued" although in fact it can support
either integer or Koating point values. #ere is no type checking %% if you ask the encoder to print
the top of the stack as a Koat" but you stored an int" you can e.pect trouble. f it is needed we
!ight add !ore Koating point supportO apart fro! printing the top of the stack" the only Koating
point operation supported is YiD which rounds the top of the stack (taken to be a Koat)" converting
it to an integer (so" for e.a!ple" "U"W converts the contents of register < fro! Koat to int).
'll the binary operators operate on the top - ele!ents of the stack" and push the answer onto the
top. 'ny other character is interpreted as an integer" and pushed onto the stack % for instance" YLD
is the sa!e as Y^X>D" octal <??. ' blank is the octal constant ?>?.
#e _ co!!and !eans" Yfor!at the top of the stack" and write it to the output stringD. #e for!at
string !ay be any printf for!at speci&er (printf is the ( for!ated i+o function. n practice" the
only for!ats that you are likely to need are _c" _d" _g and _t %% and _t isnDt even in (a _c
!eans Ywrite the integer as a characterD" _d !eans Yfor!at the nu!ber as a deci!al integerD" _)d
!eans Yand !ake it &ll X charactersD" and _g !eans for!at a Koating point nu!ber. f you should
need to know !ore" look at any book on (.) #e special for!at _t !eans Ytake . and y fro!
registers < and -" and for!at the! for a Jektroni.D. 's we shall see below" you can progra!!e the
encoder to do this" but Jektroni. e!ulators are so co!!on that _t is provided for e2ciencyDs
sake. n fact there are two Jektronics for!ats" _t for <? bit addresses" and _ for <- bit addresses.
#e switch and branch instructions are discussed below" while e.a!ining speci!en =- and 13
strings.
*+amples of ;raphcap *ntries
's a si!ple e.a!ple" the '@S co!!and to set a non%graphics cursor to a given line and colu!n
is
IYY line ] column G
'ssu!ing that the . and y coordinates are in registers < and - respectively" the corresponding
graphcap string would be
NIYYD#)_d]D")_dGN
(where the /uotes are not part of the for!at.) 9hat if line and colu!n coordinates start at <" but
the ter!inal wants the! starting at ?T then the for!at would be
NIYYD#7"-)_d]D"7"-)_dGN
Iou could write those 7"Ds as I8 which would be slightly faster" but why botherT
's pro!ised above" it is also possible to encode Jektroni.%type coordinates. #e desired bit for!at
for a <?%bit address is
. " ya y' y% y( y)
" " y* y$ y& y# y"
. " !a !' !% !( !)
" . !* !$ !& !# !"
where .< is the least signi&cant bit in ." and ya is the tenth bit in y. f . and y are in registers <
and -" the si!plest ;I (!ove+draw to (."y)) string is
N_tN
but if this werenDt available the following string would work$
ND# / O.# ^`O." / O." ^[O.N
(as before" the double /uotes donDt belong to the for!at). Jo understand this" Qirst look up the
octal values of Y D (?>?)" 6D (?<>?)" and YLD (?<??). #en the &rst `D' puts the encoder into encode
!ode. `# /' pushes the I value onto the stack" and right shi)s it by G bits (Y D is <????? in
binary). #e ne.t ` O.' adds the resulting bit patern Y? ? ya yH yW yF yXD to ?<????? and
transfers it to the output string" and we have produced the desired &rst byte. #e other bytes are
produced in a si!ilar fashion.
's another e.a!ple consider an 'C,G<-" which is reputed to desire the bit se/uence
!a !' !% yb ya y' y%
!( !) !* !$ !& !# !"
y( y) y* y$ y& y# y"
#e graphcap string
ND7"#%W'"'/I9C#'/O."'^.#'^.N
will acco!plish this. 9e could further opti!ise this by loading the value Y^<-WD into register H
once and for all with the LR capability" so a part of the graphcap entry would appear as
N:-:B7"#%W':6@BD"'/I9C#'/O."'^.#'^.:N
Dve never seen an 'C,G<-" but this should work anyway.
#e switch instruction has the for!
Hi ... HX-/ ... Hl ... H+ ... HH
where i" X" /" and l are integers. #e encoder pops the top value oU the stack adds Y?D to !ake it
a character" and scans forward looking for a H followed by that character. H#-* would !atch the
characters Y-D" Y5D" Y>D" or YGD. 9hen it has !et its !atch" it e.ecutes the instructions that it !eets
until it reaches the ne.t H in e.ecute !ode. #e encoder then skips forward until 4ust a)er the HH"
and resu!es scanning. f the character fro! the stack is not !atched by any of the cases" the
encoder will use the H+ (i.e. default) case" if present.
's an e.a!ple" consider how stdgraph sets the type of line to draw. SM e.pects linetype ? to be
solid" < to be doted" and so on. 9e e.pect a linetype in register < and have to do so!ething with
it.
Qor a Jektroni." the linetypes are set by an ML entry$
=-BIYD"H.)`DH")aDH#)cDH&)dDH$)bDHH
9hat does this doT #e IY is si!ple" it is e.ecuted in copy !ode" and writes the character IY to
the output string. #e D" enters encode !ode" and places the contents of register <" the desired
linetype" on the stack. #en begins the switch. f the linetype is ?" then the encoder scans past the
H. and starts reading the string again with )`. #e ) takes the encoder back to copy !ode" so it
copies ` to the output string" and encounters a DH which puts it back into encode !ode. *nce in
encode !ode it recognises the H as the end%of%case" and scans forward until it reaches HH" where
it stops. 9e deduce that the set%linetype%? escape se/uence is IY`. f register < had contained a -"
a)er entering the switch the encoder would have scanned forward to H# (ignoring all characters
as it went)" and copied c to the output string.
f you want to support erasing of individual lines (-@?, ,:81, or -@?, ".) youDll have to
include a HM: case in your switch (as : follows ' in the ascii character set" and an un%escaped :
would end the graphcap entry). IouDll have to escape the : in the lt list as well. 9hen leaving
erase !ode" by specifying any other line type" the device will &rst be set to -@?, "" (i.e. =-Dll
get a ]) before itDs set to the desired -@?,O this gives the driver a chance to reset itself. tDs wise
to also turn oU erase !ode when closing the device. 'n e.a!ple of an entry supporting erasing
lines is a graphon" which includes
:ltB."#&$M:]:3JBIY"IQIYI8IY#M
:=-BI_IYD"H.)`DH")aDH#)cDH&)dDH$)bDHM:)`IYI?DH])IYI8DHH:
as IYI? puts a graphon into erase !ode" and IYI8 takes it out. @ote that in erase !ode the
linetype is set to solid (IY`)" so as to erase all types of lines.
#ere is also a branch instruction" which has synta.
RbooleanTRoffsetT]
f the boolean is true (non%Sero)" then skip (oUset % <) characters in the progra!!e string. #e
oUset !ay be either positive or negative" and the YOD is at oUset ?. Qor e.a!ple"
D.7"*])AoodbyeD7"7%])GelloD)Mn
will print Y=oodbye\nD if register ? contains Sero" or YBello\nD otherwise. 's an e.a!ple of the use
of YOD" consider using the encoder to decode a string. Re!e!ber that Y"D !eant Yread a character
onto the stackD" and that there was a graphcap capability S( to decode cursor responses. Suppose
that we are dealing with a vt->? in RC=S !ode" then a cursor read will return a string of the
for! Ykgnnn"!!!hD where YkD is the character you hit" and (nnn"!!!) is the cursor position. 9e
want to put k into register 5" and (."y) into registers < and -. #is is a litle !essy" as weDll have to
convert the ascii positions into integers. #e desired graphcap entry is
13BD7.W"7.W#>W&>7.W%>7$%-W''H.-'"7".C'OW"7"W%HH%7"B7-&']M
.W%>7$%-W''H.-'#7".C'OW#7"W%HH%7"B7-&'])#-W#):
#e &rst part is si!ple enough" store ? in registers < and -" store the &rst character in register 5"
read a character (the g)" and store ? in register W. #en we co!e to >7$%-W''H.-'"7".C'OW
"7"W%HH%7"B7-&']. #e >7$%- reads a character and converts it to an digit (>W is the deci!al
code for Y?D)" then stores it in register H. #e switch then checks if we do have a digit" if so we
!ultiply register < by <? and add the new digit. 9e then set register W to < and &nish the switch
which is here being used as an if state!ent. #e %7"B7-&'] tests register W against < (i.e. checks
if we found a digit)" and if we did it 4u!ps back 5H characters" to read the ne.t character(-H). So
we are accu!ulating the integer nnn in register <" 4ust as we needed to. #e rest of the string
deals with decoding the y coordinate.
So!eti!es you donDt want to read fro! the input string" but fro! the keyboard instead. n this
case use `str`" e.g. D`GelloM: `7$%-H.)SalseDH+)rueDHH)Mn: will pro!pt you
with Gello: " then read a character fro! the keyboard. f you enter a Y?D itDll print Salse"
otherwise itDll print rue. *f course" in reality youDd want to do so!ething !ore useful (such as
erasing the screen).
<sing "ursors with ;raphcap
9e have 4ust been through a long e.planation of how to decode a cursor string" but how did
stdgraph know what to read in the &rst placeT ')er receiving the R( string" the ter!inal will
send back a se/uence of bytes" and the for!at of these bytes !ust be speci&ed in graphcap.(5?)
#ere are two ways to do this" either by specifying a se/uence of characters which `end' the
response string along with a !ini!u! nu!ber of characters to read" or by specifying a patern
that the ter!inal response is to !atch. ' typical e.a!ple of the for!er is a Jektroni. whose
cursor response !ay be chosen to be control-= (this is called the =@ response" and can
usually be set in the ter!inal setup). 9e know that the ter!inal will also send G other bytes (the
key struck and the encoded ."y coordinates so we would specify
:=3BI=:39B):
*n the other hand" a RC=S ter!inal sends Ykgnnn"!!!hD. #is can be speci&ed as
:=3BVY7C>7CQ:39B-):
where the negative value of (@ !eans that we are providing a patern not 4ust a ter!inator (as
before" the absolute value of (@ is the !ini!u! nu!ber of bytes in a cursor response). n M(
strings" but nowhere else" the characters V" 7" and C are special (although their special !eanings
!ay be escaped with a M). V will !atch any character" 7 any digit" and C !eans Y!atch Sero or
!ore of the preceding charactersD. So a M( string of a7CVba will !atch Yaaa<<<<bbaaD at the
third character. (ncidently" a7CVa would !atch at the &rst). :ecause this special character
synta. is diUerent fro! that used in standard graphcap &les for R'Q" the na!e of this graphcap
para!eter has been changed fro! 3+ to =3.
f your cursor is atached to a !ouse" if possible the butons should be set up to generate YeD" YpD"
and Y/D fro! le) to right (if you have that !any butons). f you have only one buton" YpD is
probably the best choice.
<sing "olours with ;raphcap
#e nu!ber passed to 3 are the sa!e as those speci&ed with the 3@?, 09,A,: co!!and"
so initially they specify default" white" black" blue" red" green" !agenta" yellow" and cyan (white is
<). #ese are the colours corresponding to turning one" Sero" two" or three of the pri!ary colours
on. #e default colour to use for a device is speci&ed by the +3 capability" e.g. :+3BNredN:.
#e 31 and 35 capabilities are used to support the 3@?, B e!pr co!!and. Qirst 31 is used
to tell the device how !any colours to e.pect" then 35 is used for each nu!ber" with red" green"
and blue as its argu!ents. n this case 3 passes an inde. into the set of 35 values. f you want to
get an inde." but donDt need 31 and 35" you !ust still provide the!O 4ust provide a no%op such as
:31BD):.
How to Modify a ;raphcap *ntry
Iou !ight think that all that you have to do to !odify a graphcap entry is to start up your
favourite editor" and start typing. Iou could do that" !any people have" but it isnDt reco!!ended
because youDll have to do it again when a new release of SM co!es along. tDs beter to use SMDs
graphcap search path (see section #e =raphcap Qile) as follows$
Let us assu!e that you want to !odify the .ter! entry to print so!ething every%ti!e that is
changes fro! graphics to alpha !ode or vice versa (whyT so as to &. a proble! with e.cessive
screen switching). Qirst set up the syste! `.sm' &le to look like$
Ographcap /my/private/graphcap
graphcap /usr/local/lib/sm/graphcap
which tells SM to &rst search `/my/private/graphcap' then
`/usr/local/lib/sm/graphcap' (the graphcap &le that we provide) for graphcap entries.
#en edit `/my/private/graphcap' and add the entry
!termUan !term with noisy mode flipping:M
:A,BMn,MnIYYV&%h:A+BIYI3Mn+Mn:3B!term:
@ote the use of :3B!term: which says that SM should skip this &le when looking for the
de&nition of !term" thus avoiding an in&nite loop.
9hen a new version of SM is released your new de&nition will continue to work (unless we
change the de&nition of !term in which case youDll have so!e work to do anyway). Iou can use
this techni/ue to change entries or add your own new ones without !odifying the syste! &leO all
of your changes are in `/my/private/graphcap'.
Writing a $ew ;raphcap *ntry
So" if youDre faced with a new piece of hardware what should you doT Qirst of all" donDt panic %%
writing entries is /uite si!ple. Second" see if your device is basically the sa!e as one that already
e.ists in graphcap" for e.a!ple the entry for YgraphonD uses the YselanarD entry" and it in turn uses
Ytek>?<?D. Iou !ight be able to get away with using tc to satisfy !ost of your deviceDs needs.
:efore writing your new entry please read the previous section to learn the reco!!ended
strategy for !odifying graphcap &les.
LetDs assu!e that you are faced with a totally new type of device and really do have to start fro!
scratch. Qirst &nd out how large your device is" and &ll in the !r and yr entries. f you are going
to use hardware character sets you also need ch and cw. @e.t decide on the string to initialise the
device %% does it need to be set into so!e weird !ode %% and put it into 5J. Put the string to reset
it into 3J. @ow" if the initialised device needs to be put into a special graphics !ode put it into A,
and its inverse into A+. @e.t" you need to tell SM how to draw a line and !ove the plot pointer.
So enter the +1" 6@" +," 21" and 2, capabilities. *f course" if one isnDt re/uired" donDt put it in. f
you have so!e sort of printer you probably want to store all the co!!ands in a &le (5SB)" and to
plot the! (1@B). Iou should now be ready to !ake your &rst test" so plot a bo.. f it doesnDt look
right" &. it. *r you !ight like to try printing the cover (load cover cover).
9hen all is well" you can begin looking into options that !ight !ake your graphcap entry !ore
e2cient. Look through this appendi. to see what is available. ,oes your device support line
typesT 'dd =- and lt. Beavy linesT -J. (oloured lines or a cursorT See section 7sing (olours
with =raphcap. Qilled polygonsT S1" S+" and S,. ,otsT =1 =,. Bardware charactersT 1 ,. f
your device produces hardcopy you should arrange to start a new page with ?A (the ?8A,
co!!and). 9hen you have &nished please send us your new entry.
Support for Raster #evices
Stdgraph can only handle devices that can plot vectors speci&ed by their endpointsO unfortunately
so!e devices (such as !ost line printers) can only plot graphs when they have been reduced to
rows of YonD and YoUD pi.els. SM supports such devices through +,203, raster and a separate
progra!!e called rasterise. Iou specify that a device in a graphcap &le is a raster device by
using +2$ :+2Braster: (#e old for! ::8: is no longer supported). t co!!unicates with the
rasteriser through graphcap" so the whole process is user transparent. ' separate rasterising
progra!!e was writen so as to allow the plot to be produced in the background while you do
!ore productive things" and to allow the rasterising to be done on a re!ote !achine.
+,203, raster produces a &le" whose na!e is speci&ed as usual by the 5S &eld in graphcap"
containing the vectors to be ploted (as groups of four short integers) in device coordinates" where
the siSe of the device is taken fro! !r and yr. 9hen the device is closed" the co!!and speci&ed
by 1@ are e.ecuted" and these will usually be of the for! rasterise -r H. HS
outfileMn print_it outfileMn delete outfile where print_it is the proper
way of actually geting a plot. 7nder 7ni." the co!!and !ight well be so!ething like
Drasterise -r H. HS - U lpr -v -r -?H")^ dispensing with the te!porary
outfile.
9hat do these rasterise co!!ands doT #e co!!and synta. is rasterise Y-flagsQ
device infile outfile" where the in&le !ay be speci&ed as Y%D to use standard input
(sysEinput to 8MS)" where the out&le !ay be speci&ed as Y%D to use standard output (sysEoutput to
8MS). Possible Kags are r to re!ove the in&le a)er use" : to rotate the plot through H? degrees"
and v for !ore verbose operation. :asterise then reads the data in the in&le" and produces a
rasterised version" row by row" on the out&le. n order to do this" it looks in graphcap for an entry
for device" and uses the !r" yr" 5J (and 5Y6@FQ)" and 3J &elds as usual.(5<)
LetDs &rst consider a si!ple" one%line%at%a%ti!e device such as a line printer. :efore writing each
row to outfile" rasterise encodes the 4: (:egin Row) capability" using the current row nu!ber
as an argu!ent" and encodes ,: (Cnd Row) at the end of the line. :y default" it assu!es that the
raster device si!ply wants bits turned on where a dot is re/uired" but this can be overridden
using the 4? and ,? capabilities. ,? (C!pty Pi.el) speci&es the bit patern for a character to
represent white space. n the si!ple case !entioned a !o!ent ago" this would be si!ply @7L"
with no bits on" but so!eti!es this doesnDt su2ce (see e.a!ples below). 4? (:it Patern) is a
string" giving the bit paterns re/uired to turn on the various pi.els. n the default case" 4? could
be speci&ed as 4?BM.."M..#M..$M.".M.#.M.$.M"..M#.." so M.." would turn on the
&rst (right!ost) dot. :ecause there are eight characters given in the string" raster assu!es that
it can &t eight pi.els into a single character. f you donDt specify a 4? this is what will be used.
So!e devices desire or re/uire that the data be sent as he.adeci!al nu!bers rather than as
binaryO see the :+Bhe! graphcap entry.
So!e other devices (e.g. Cpson printers) choose to print several lines at a ti!e" so a single byte
trans!ited to the device !ight print W lines" but only the &rst pi.el of each line. Such devices are
described to graphcap by being given the =: (Many Rows) capability and a nu!ber nb which
describes how !any bytes deep the printing band is (if o!ited nb defaults to <). n this case" 4?
is used to describe which bits are turned on vertically rather than horiSontally but everything is
otherwise the sa!e as for the si!ple case.
's an e.a!ple" consider the BP laser4et. IouDd specify it as +,203, laserXet" and its 7ni.
graphcap entry reads$
laserXetUG? laserXet Dhigh resolution):M
:+2Braster:!r7"#%.:yr7)$.:3JBIYCr4:5JBIYCr"#%.IYCr8:4:BIYCb").J:M
:5SBhp_666666:M
:1@B/usr/local/sm/rasterise -r H. HS - T /dev/hp^:
*n opening the device" it gets the string IYCr"#%.IYCr8" seting the resolution and raster
!ode. #en" at the beginning of each rastered line it gets IYCb").J specifying that <X? bytes are
co!ing its way" then &nally IYCr4 to restore it to alpha !ode. (t doesnDt need to know which
row it is on" so the 4: string doesnDt tell it" and the default 4? and ,? are &ne). ')er the input &le
is read it is deleted" and the output &le is sent to the standard output" whence it is redirected to
the proper device" in this case directly rather than through a spooler.
' !ore co!ple. e.a!ple is a printroni. printer" which encodes X pi.els in each byte" and re/uires
that bit F be turned on. t also needs an escape se/uence at the end of each line. #e
corresponding graphcap entry is
printroni!U+,3 printroni! printer:M
:+2Braster:!r7('#:yr7('#:3JBI-:5JBI-:4:B,:BI,IZ:M
:4?BM.."M..#M..$M.".M.#.M.$.:,?BM"..:M
:5SBpr_666666:M
:1@BD/usr/local/sm/rasterise -r H. HS - U rsh wombat lpr)^:
9e use ,? to turn on the seventh bit everywhere" as re/uired" and specify only X values for 4?" so
only X dots will be packed into each character. #e 4: entry is e!pty" and ,: provides the needed
escape se/uences at ends of lines. n this case 1@ sends the plot over a network to !achine
wombat.
So!e devices are not able to si!ply accept a string of bytes with an occasional escape se/uence.
Qor e.a!ple" a versatec needs to have the bit order changed" or a si!ple screen ploter !ight want
to write a C if a bit is set and a space otherwise. f this is the e.tent of your pathology" you can
deal with it via the provided capabilities. (Qortunately adding a C onto a space !akes a C" so you
can use :,?B :4?BC: for the later.) f you have a really bad device" it is possible to add new
coded device drivers to rasterise. Qor the convenience of such devices there is a graphcap
capability :+ which speci&es the na!e of a type of raster device. f rasterise recognises the
device it it calls a diUerent set of routines to deal with the rows of data. *therwise it proceeds as
discussed in the previous paragraph. #is behaviour is si!ilar to that of the +,203, co!!and in
using stdgraph if it doesnDt recognise a device na!e.
f you &nd that you do need to write routines for so!e device" donDt be too disheartened.
:asterise will still do the book%keeping and rasterising for you" your work will be li!ited to a
couple of output routines. f you need to know !ore" see the source for rasterise. #e only ti!e
that used this capability ca!e about two years a)er rasterise was writen" and was :+Bhe!
which speci&es that lines be writen as he.adeci!al nu!bers rather than as W%bit characters (e.g.
write the two characters SS instead of the single character Y\5FFD). #e line length is given as ll.
"ompiling ;raphcap
(#is section is really for so!eone !aintaining SM.) Rather than have stdgraph read the graphcap
every ti!e that it opens a devices" it is possible to co!pile the capabilities of the !ore popular
devices into the e.ecutable. #is is done by preparing an include &le which initialises the
appropriate arrays" using the progra!!e Yco!pile]gD in the !ain directory. ')er this &le (called
cacheg.dat) has been prepared" &les depending on it !ust be reco!piled and SM !ust be relinked.
#e use of co!pile]g is prety !uch self%e.planatory" you give it a list of the devices you want
and it produces the cacheg.dat &le. Proble!s arise" however" if you donDt have a valid cacheg.dat
&le" as then you canDt co!pile co!pile]g in the &rst case. Qortunately" it is possible to bootstrap a
cacheg.dat &le (by de&ning :**JSJR'P to the (%preprocessor)" and proceed fro! there.
9hen stdgraph ate!pts to use the co!piled capabilities" it checks that the current graphcap &le
has e.actly the sa!e na!e as the one that cacheg.dat was co!piled fro!" if it isnDt then it reads
the graphcap &le anyway. #is provides a !echanis! for those without ( co!pilers to change the
graphcap entries of pre%co!piled devices. f you have a list of graphcap &les" the na!e of the &rst
is checked against the na!e in the `cacheg.dat' &le.
5nde+ to ;raphcap "apabilities
b
:P (:it Patern)
:R (:egin Row)
c
ch ((haracter Beight)
(L ((Lear)
(* ((*lour)
co (nu!ber of (*lu!ns)
(S ((olour Start)
(J ((olour Jype)
cw ((haracter 9idth)
(9 ((lose 9orkstation)
d
,( (,efault (olour)
,C (,raw Cnd)
,S (,raw Start)
,J (,evice Jype)
,8 (,ri8er)
e
CP (C!pty Patern)
CR (Cnd Row)
f
Q, (Qill ,raw)
QC (Qill Cnd)
QS (Qill Start)
g
=, (=raphics ,isable)
=C (=raphics Cnable)
i
Q (nitialisation Qile)
l
li (nu!ber of Lnes)
ll (l@C lC@=JB)
lt (Line Jype)
L9 (Line 9eight)
m
M( (sM (ursor)
MC (Mark Cnd)
ML (sM Line)
MR (Many Rows)
MS (Mark Start)
n
nb (n7M bIJCS)
o
*Q (*ut Qile)
*9 (*pen 9orkstation)
*; (*pen workstation)
*I (*pen workstation)
*P (*pen workstation)
p
pc (Pad (haracter)
P= (Pa=e)
r
R' (R'ster)
R( (Read (ursor)
R, (Raster ,evice)
RJ (Record Jer!inator)
s
S( (Scan (ursor)
SI (SIste!)
t
J: (Je.t :egin)
JC (Je.t Cnd)
v
8C (T Cnd)
8S (T Start)
+
.r (;%Resolution)
;I (; I)
y
yr (I%Resolution)
"alling SM from ,rogrammes
(allable ntro$ ntroduction to (allable SM
C.a!ple$ C.a!ple of (alling SM Qunctions
Qunctions (<%,)$ Qunction ,e&nitions$ <%,
Qunctions (-%,)$ Qunction ,e&nitions$ -%,
(allable Parser$ (alling the SM interactive Parser fro! Progra!!es
9hy call s!]alphaT$ 9hy do have to call sm_alpha etc.T
Qortran @a!es$ Bow to (on&gure Qunction @a!es for Qortran
5ntroduction to "allable SM
#e SM callable interface is diUerent fro! that of Mongo and corresponds directly to the
interactive version. 'l!ost all of the co!!ands available in SM can be called fro! either fortran
or (" the e.ceptions being those concerned with the !acro processor" variables" history" and
vector !anipulations. 9e assu!e that if you want to call graphics routines directly" then you are
prepared to take responsibility for such things. n ( (and probably pascal" !odula" or ',')" the
calls have the sa!e na!es as the co!!ands with the pre&. sm_" so to set the li!its say
sm_limitsD...>"..>...>"..)]. *n 8MS" and with so!e uni. syste!s (notably BP7;
and ';)" if you are writing fortran" you !ust prepend an YfD to the co!!and % call
fsm_limitsD...>"..>...>"..). f you forget this YfD" your progra!!es will co!pile" but
they `won't' work. (#eyDll give seg!entation violations" !ost likely. 9hyT :ecause you will
be calling the ( functions directly" not the Qortran interface functions" and the languages have
diUerent ways of passing argu!ents" so e.g. you will pass the address of the variable fro! your
Qortran progra! to a ( function that e.pects to get the value of the variable. #is translation is
precisely what the interface functions are set up to do for you).(5-) f your fortran co!piler
cannot &nd the function na!es" you !ight have to read the section on how SM chooses function
na!es (see section Bow to (hoose the @a!e for Qortran Subroutines).
So how are you supposed to know what to call the functionsT 9ell" our best suggestion is to ask
the person who build SM on your syste!O the second best suggestion is to look in
`libplotsub.a' (or `libplotsub.olb' on 8MS syste!s)" and see what the na!es of the
functions are. *n 8MS" try this$
lib/list/names libplotsub/lib
and look at the na!es it lists under !odule 09,:S83,. *n a uni. syste! you can use nm (or" if
desperate strings). #e output is /uite long" so Dd &lter the output" e.g.$
nm libplotsub.a U grep errorbar
f you see things in the output like fsm_errorbar" then you know this is one of those
!achines where you have to prepend the YfD for the fortran interface functions.
f you used an '@S co!piler to link SM (or your guru did) then you should provide prototypes
for the SM functions that you call if you use the ( interface (Qortran knows nothing of such
things). #is can be done by including the &le `sm_declare.h'.
n what follows" we will assu!e that you are not writing fortran under 8MS" so we will o!it the
leading eUs.
Jo use SM functions" you !ust link with appropriate libraries. Iou will always need to link with
the three SM libraries" libplotsub" libdevices" and libutils in that order. Speci&cally"
under 7ni." youDll need to include the &les `libplotsub.a'" `libdevices.a'" and
`libutils.a' when you link (itDs probably easier to use -lplotsub -ldevices
-lutils" along with a --dir if needed). and under 8MS youDll need
`libplotsub.olb/lib'" `libdevices.olb/lib'" and `libutils.olb/lib'.
canDt tell you where theyDll be on your syste!. n addition" you !ay need to link (a)er utils)
any libraries used by the devices that have been co!piled into your version of SM. Qor e.a!ple" if
you use the ;%windows driver" youDll need to link with the ;%library (-l6). (onsult a local guru
in case of any trouble % the person who installed SM has had to work this out already.
*+ample of "alling SM 'unctions
' list of functions giving the calling se/uence for all the available functions follows" but &rst an
e.a!ple. @ote especially the use of graphics and alpha to set the ter!inal to graphics !ode"
and return to a nor!al ter!inal a)erwards. 9e would reco!!end always calling these" if they do
nothing (e.g. on a laser printer) theyDll do no har!. ' related function is gflushD) which will
update graphics on the screen" for instance with stdgraph where output is usually buUered.
So!e devices (such as =L on an S=" or ;%windows on !achines without backing store such as
RS+X???Ds) need so!e help fro! you to redraw the screen. Iou do this by calling redraw
whenever you are waiting for input" passing it Y?D (the &le descriptor of standard input" for those
of you fa!iliar with (). 9hen input is ready" redraw will return and your application can
proceed. t should do no har! on syste!s where it does no good.
f you donDt want to be bothered with calling sm_alpha" sm_graphics" sm_gflush" and
sm_redraw" see section 9hy do have to call sm_alpha " sm_graphics " sm_gflush " and
sm_redraw T.
#ere are e.a!ples of progra!!es (in both ( and fortran) calling SM in the directory
sm/callableO you !ight want to look at the! before starting your own pro4ect.
integer 96@
parameter D96@B#.)
integer sm_device
integer i
real !D96@)>yD96@)
c
do " iB">96@
!Di) B i
yDi) B iCi
" continue
c
ifDsm_deviceD'hire\') .lt. .) then
print C>'3anNt open hire\'
stop
endif
call sm_graphics
call sm_defvarDNe6_stringsN>N"N)
call sm_limitsD-".>##.>..>*...)
call sm_ctypeD'red')
call sm_bo!D">#>.>.)
call sm_ptypeD$..>")
call sm_pointsD!>y>96@)
call sm_!labelD'6 a!is')
call sm_ylabelD'9ot ! a!is')
call sm_alpha
print C>'hit any /ey to e!it'
call sm_redrawD.)
readD*>C) i
end
Re!e!ber" if you were running 8MS" BP7;" or '; then all those calls would start YfD % call
fsm_graphics and so forth. @ote that sm_bo! takes all of its four possible argu!ents" and
that co!!ands such as sm_points add an argu!ent to specify the nu!ber of points to plot.
Iou !ust" of course" ensure that you use the correct type of variables" passing integers or reals as
re/uired (and as listed below). f you are using (" you !ust carefully distinguish between passing
by value" and passing by address (which we only use when an array is e.pected" and for returning
a cursor position).
'unction #efinitions! /-#
#e functions are as follows. Qor fuller de&nitions of the argu!ents look at the !ain description
of the co!!and. #e only ones that are diUerent are sm_curs" sm_defvar" and sm_plotsym
because they donDt /uite correspond to any interactive co!!ands. ' co!!on source of trouble is
not noticing that the sm_ptype call is the vector for! of the co!!and" so to set a ptype of Y> <D
you !ust say sm_ptypeD$"..>").
#e argu!ents are declared in fortran in this list. real !Dn) !eans that ! is an array of siSe n.
YRealD !eans single precision. (So in (" character char CO integer intO real floatO
realD) float C. 9e deal with converting the calling conventions fro! one language to
another" but note co!!ents at the boto! of this table.)
sm_alpha
Set ter!inal back to a nor!al state
sm_angleDa)
Set angle to a (real a)
sm_a!isDa">a#>as>ab>a!>ay>al>il>ic)
,raw an a.is. (real a<"a-"as"abO integer a."ay"al"il"ic)
sm_bo!D!">y">!#>y#)
,raw a bo. % note > args. (integer .<"y-".-"y-)
sm_connectD!>y>n)
(onnect a line. (real .(n)"y(n)O integer n)
sm_connD!>y>n)
C/uivalent to s!]connect
sm_ctypeDc)
Set colour to c (character c)
sm_ctype_iDi)
Set colour to i (integer i)
sm_cursD!>y>/)
Return position of cursor (real ."yO integer k)
sm_defvarDstr">str#)
Select variable str< to str- (character str<" str-)
sm_deviceDstr)
Select device str (character str)O return integer
sm_dot
,raw a dot
sm_drawD!>y)
,raw to (."y) in user coords (real ."y)
sm_erase
Crase screen
sm_errorbarD!>y>e>/>n)
,raw error bars (real .(n)"y(n)"e(n)O integer k"n)
sm_e!pandDe)
Set e.pand to e (real e)
sm_formatD!f>yf)
Set for!at strings to .f and yf (character .f"yf)
sm_get_variableDname) Dcharacter name)
Return the value of the variable na!e" if itDs a special variable
sm_gflush
Qlush graphics output
sm_graphics
Set ter!inal into ploting !ode
sm_grelocateD!>y)
Relocate in screen coordinates (integer ."y)
sm_gridDi)
,raw a grid (integer i)
sm_hardcopy
(lose current device" if appropriate !ake hardcopy
sm_histogramD!>y>n)
,raw a histogra! (real .(n)"y(n)O integer n)
sm_identificationDstr)
denti&cation string (character str)
sm_labelDstr)
,raw a string (character str)
sm_limitsD!">!#>y">y#)
Set li!its (real .<".-"y<"y-)
sm_locationD!">!#>y">y#)
Set location (integer .<".-"y<"y-)
sm_ltypeDlt)
Set ltype (integer lt)
sm_lweightDlw)
Set lweight (real lw)
sm_notationD!l>!h>yl>yh)
Set a.is for!at defaults (real .l".h"yl"yh)
sm_pageD)
C/uivalent to P'=C interactively
sm_plotsymD!>y>n>sym>ns)
,raw user points (real .(n)"y(n)O integer n"sy!(50ns)"ns)
sm_pointsD!>y>n)
,raw points (real .(n)"y(n)O integer n)
sm_ptypeDpp>n)
Set point type % vector for! (real pp(n)O integer n)
sm_putlabelDi>str)
Position a label (integer iO character str)
sm_redrawDi)
9ait for input on &le descriptor i (integer i).
sm_relocateD!>y)
Relocate in user coords (real ."y)
sm_set_ctypesDcols>n)
Set SMDs per!ited colours to cols (real colsO integer n)
sm_shadeDdelta>!>y>n>type)
Shade a region (integer deltaO real .(n)"y(n)O integer n"type)
sm_tic/si\eD!s>!b>ys>yb)
Set ticksiSe (real .s".b"ys"yb)
sm_windowDn!>ny>!>y>!#>y#)
Select a window (integer n."ny"."y".-"y-)
sm_toscreenDu!>uy>s!>sy)
(onvert to screen coordinates (real u."uy" integer s."sy)
sm_!labelDstr)
,raw .%a.is label (character str)
sm_ylabelDstr)
,raw y%a.is label (character str)
sm_device returns ? if it opens the re/uested device" or j< if it fails. Iou !ust declare
sm_device as returning integer" of course. sm_curs returns a)er you hit any key" returning
the coordinates of the point" and the key struck as an integer (e.g. YaD as HF in ascii). n (" all three
argu!ents are pointers" two to Koat and one to int. sm_defvar de&nes a variable" it is identical
to the interactive co!!and +,S09, name value. t is only used to certain de&ne variables
that are signi&cant to SM" currently file_type" graphcap" e6_strings" !_gutter" and
y_gutter. Qortran users !ight or !ight not need to double Ms in Je; labels" depending on the
foibles of your co!pilers (you are !ore likely to need the doubled MM under uni.).
sm_plotsym is like &rst using the ?@?, ; ... < co!!and to de&ne sym" and then
?5091 to plot . against y. #e sym array consists of triples of integers" Dmove ! y) where
!ove is < to !ove the plot pointer" ? otherwise. #is is not /uite the sa!e as the interactive
co!!and" but doesnDt involve any characters. #e move integer !ay not be o!ited. #e Y&le
descriptorD that sm_redraw de!ands will al!ost always be . (standard input) on uni. bo.esO if
it is needed by 8MS or other operating syste!s will add a note here when write the device
driver.
sm_shade shades the inside of the curve speci&ed by . and y if type is <" or the area below a
histogra! speci&ed by ! and y if type is - (or j- if the histogra! is rotated by H? degrees). #e
line spacing in screen coordinates is delta. #e second and third argu!ents (!> y) should be
pointers to :,8- if called fro! (.
Iou can use sm_toscreen to convert fro! user to screen coordinates (which run fro! ? to
5-FXF" and are used by sm_grelocate). #e second pair of argu!ents should be pointers to int
if called fro! (.
sm_window takes an e.tra two argu!ents over the interactive versionO they are the values that
youDd specify using the 7:7 for! of window speci&cationO for e.a!ple" J09+5J $ * " #:&
corresponds to the call sm_windowD$>*>">#>">&).
#e colour functions are sm_ctype and sm_ctype_i" e/uivalent to 3@?, name and 3@?,
integer respectively" and sm_set_ctypes" e/uivalent to the nu!erical for! of 3@?, B
e!pr.
Iou can get at !ost of SMDs YspecialD variables (e.g. e.pand) directly by looking at ( globals (these
!ay look like co!!on blocks to fortran" it depends on your co!piler)O look in the &le
`src/plotsub/set.c' for details. 'lternatively (and less involved in SMDs insides" if a bit
slower)" you can use sm_get_variable" which will return values as Koating point nu!bers.
#e functions to !anipulate -%di!ensional data are described in the ne.t section.
'unction #efinitions! 2-#
#e use of the -%, functions !ay re/uire a litle !ore e.planation. f you want to use SM to read
your data" producing contour plots is very si!ilar to doing so interactively" with the diUerence
that instead of de&ning the variable file_type" you !ust call the function sm_filetype
with the desired value as the argu!ent before reading the data. #is is e/uivalent to calling
sm_defvar to de&ne the variable file_type" and is only supported for backwards
co!patibility. 's an alternative" you can &ll your own data array" and pass it to SM to be
contoured with sm_defimage.
Please note$ the i!age data that you provide to SM should be >%byte Koats even if you are built
SM to use W%byte (double) Koating point nu!bers.
#e function calls follow (again in fortran)" followed by so!e e.planation.
sm_contour
(ontour current -%, i!age
sm_defimageDarr>!">!#>y">y#>n!>ny)
,e&ne an i!age (real arr(n."ny)".<".-"y<"y-O integer n."ny)
sm_delimage
delete current -%, i!age
sm_filetypeDtype)
Set -%, &letype (character type)
sm_levelsDl>n)
Set levels for contour (real l(n)O integer n)
sm_minma!D!>y)
=et !ini!u! and !a.i!u! of i!age (real ."y)
sm_readimageDfile>!">!#>y">y#)
Read a -%, i!age (character &leO real .<".-"y<"y-)
#e translation to other languages is not /uite as si!ple as above. n (" sm_minma! e.pects to
be passed pointers to Koats" and the &rst argu!ent to sm_defimage is not a -%, array" but an
array of pointers to the rows of the i!age. !"> !#> y"> y# specify the li!its as in the
interactive 0=8A, co!!andO if they are set to be ?.? then the di!ensions of the array will be
used. 's an e.a!ple" again in non%8MS fortran$
integer 96@
parameter D96@B#.)
integer sm_device
integer i>X
real \D96@>96@)>levD96@)
c
do # iB">96@
do " iB">96@
!Di>X) B Di-96@/#)CC# O DX-")CC#
" continue
# continue
c
ifDsm_deviceD'postscript latypus') .ne. .) then
print C>'3anNt open printer'
stop
endif
call sm_graphics
call sm_limitsD-".>#".>-".>#".)
call sm_bo!D">#>.>.)
call sm_defimageD\>..>#..>..>#..>96@>96@)
call sm_minma!Damin>ama!)
do iB">96@
levDi)Bamin O Di - ".)/D96@ - ")CDama! - amin)
& continue
call sm_levelsDlev>96@)
call sm_contour
call sm_hardcopy
call sm_alpha
end
"alling the SM interactive ,arser from ,rogrammes
t is also possible to call the SM parser directly fro! your own progra!!es. #is is usually done
by people who have large data arrays that they want to plot" so we have also provided a call to
de&ne your arrays as SM vectors. Jo use this" your SM guru !ust build an e.tra library" (called
`libparser.a' on uni. syste!s). #is is done with the co!!and
ma/e ?arser
in the top level SM source directory. f this has been done" you can link the parser into your code
by including the Kag -lparser before the other SM libraries (but a)er any -- Kags). #e
progra!!es `interp' and `finterp' in the `callable' directory provide e.a!ples of
calling SMDs parserO `finterp.f' looks like$
real aD".)
integer i
do " iB">".
aDi) B i
" continue
call sm_array_to_vectorDa>".>'!y\')
print C>'3alling 1= parser...'
call sm_parserD'-q')
print C>',!ited parser'
end
Bere the array a (with <? ele!ents) is to be called !y\ in SM" and SM is to be invoked with the
co!!and line options -q. Iou can of course de&ne as !any vectors as you feel like" but using
+,-,, to delete the! fro! the parser is a serious error (i.e. donDta).
sm_array_to_vectorDarr>n>name)
,e&ne an SM vector called na!e to have the values of the array arr. (real arr(n)O int nO
character na!e).
sm_parserDargs)
Start up the SM co!!and parser as if you had started SM interactively with co!!and line
argu!ents args" but with so!e vectors prede&ned (those that you de&ned using
array_to_vector) (character args).
Why do 5 have to call sm_alpha 9 sm_graphics 9 sm_gflush 9 and
sm_redraw ?
#e /uestion so!eti!es co!es up" Y9hy do have to bother with these calls sm_alpha"
sm_graphics" sm_gflush" and sm_redrawT ')er all" other graphics libraries donDt re/uire
the!.D
#e answer is that it all depends on how sophisticated and device dependent you want to be.
f you are using so!ething like an .ter! to plot to" then yes" you do need to e.plicitly switch
between graphics and alpha screens %% or else youDll get gibberish on the te.t screen (so!ething
like `V_Ns7=NsTGNs7=7b7=Ws7SWs7S.NsH6N) and no graphics on the graphics screen" or
else your graphs and your input co!!ands (and so!e gibberish to handle the screen editor)
!i.ed together on the graphics screen. *f course the SM routines could have done the switches
for you" but if the !ode were changed everyti!e that it might need switching" youDd get an
i!!ense a!ount of !ode switching. 9hy would that !aterT Jry running the code on a ter!inal
like a vt->? that physically has only one screen.
f you didnDt care about devices like !term and were deter!ined to only use devices like !"" or
sgi or postscript you wouldnDt have to worry about any of this.
@e.t to gflush. Qor e2ciency" SM doesnDt guarantee that every write re/uest is actually writen
to the screen when received" so at the end of a function call there could be lines or points that
havenDt yet reached the screen. gflush deals with this by Kushing the graphics buUers" thus
ensuring that all pending writes to the screen are co!pleted. f you donDt care about possible
!issing points" donDt worry about it.
Qinally redraw. *n a traditional ter!inal such as an [-S or a tektronics >?<?" there was no need
to worry about other windows appearing on top of your beautiful graphics window and erasing
what was thereO for so!e devices such as !term there is no proble! as the ter!inal e!ulator is
always looking at the screen" like a faithful dog" waiting for you to type so!ething or for one of
its screens to get corrupted. n the old days of sunview" Sun had hacked the lowest level syste!
calls (read etc.) to allow an application progra!!e to call the e/uivalent of redraw
auto!atically (well" under a reasonably co!!on set of conditions). :ut if you are running on
so!ething like an ;<< display or a =L display on an S=" there is no9one looking out for events
that erase your window" and you have to do it yourself. f you donDt care about refreshing the
screen when raised to the top of the window stack" thereDs no need to worry about redraw.
So all these co!plications with alpha" redraw" and friends are due to SM being designed to
handle all the possible nasty cases. f you use SM interactively" it is all done for you" but if you
want to call SM functions you have to decide how !uch responsibility you want to take.
*f course" you can write a trivial wrapper about each SM pri!itive that calls sm_graphics
before calling (e.g.) sm_points> then sm_gflush and sm_alpha 4ust before returning. n a
si!ilar way" you could write a general i+o function that calls sm_gflush then sm_alpha" then
pro!pts you" then calls sm_redraw" then reads the reply" then calls sm_graphics. :ut donDt
think that the SM pri!itives should do it for you.
How to "hoose the $ame for 'ortran Subroutines
's discussed above" the na!es used for SM callable functions fro! fortran are" in general"
diUerent fro! those used in (al!ostT) all other languages" as fortranDs calling conventions are
diUerent" so we have to provide interface code (in the &le
`sm/src/plotsub/interface.c'). #e SM function sm_func !ay be called as
888sm_func444 where 888 and 444 are the values of the (%preprocessor !acros
S5::89_?:,?,9+ and S5::89_8??,9+ respectivelyO their default values are nothing and
_. f you want to change this" edit sm/src/options.h and de&ne the values that you desire.
@ote$ with ( co!pilers that donDt adhere to the (WH ansi standard" you are restricted to the values
f and _ for ?:,- and 8??,9+.
')er changing options.h (or options.s/l if you want your changes to survive the running
of `set_opts')" rebuild SM and you should be in business.
4he SM ;rammar
Previous editions of this !anual included a printed copy of the SM gra!!ar" prepared directly
fro! the source code using the get_grammar utility. #is was helpful in understanding
otherwise biSarre ob4ections to your favoured co!!and" as it speci&ed e.actly what SM would
accept" but used a lot of paper. 9e have therefore o!ited it fro! this edition" but you are
welco!e to !ake yourself a copy.
4wo-#imensional ;raphics
#ere is li!ited support for -%di!ensional graphics in SM" and we do not e.pect to !ake !any
e.tensions in this area. (urrently it is possible to read an unfor!ated i!age" to draw contours" to
generate a Qloyd%Steinberg dithered i!age" to e.tract values fro! the i!age into vectors" and to
obtain i!age values with a cursor. Previous editions of this !anual (prior to version -.5) have
traditionally said$ Y9e e.pect to support half%tone i!aging in the nearish futureDO as of this release
there is a !acro (called greyscale and writen by =abor Joth here at Princeton) that draws
reasonably e2cient grey scale i!ages on any supported output device.
#e proble! of specifying data for!ats for i!ages is di2cult" and we have adopted an approach
of using a Y&lecapD &le to describe the unfor!ated &les. #is allows the user to write the &le using
( or Qortran (or" presu!ably" lisp) and then use SM to read the data. #e na!e of the entry in the
filecap &le is given by the variable file_type" which !ay be given in your `.sm' &le if
you use the standard startup !acro. #e for!at of data on disk is &rst the .% and y% di!ensions
of the i!age" then the data in row%ascending order. #e e.act state!ents used to write the data
!ay depend on the chosen value of file_type (or vice%versa). ' description of the filecap
&elds co!es at the end of this appendi.O !ost users should never have to change this &le.
t is also possible to read data fro! a for!ated &le and create an i!age inside SM" for e.a!ple if
! and y are integers in the range ?%H$
0=8A, D".>".) 7 declare a ".C". array
:,8+ ; ! " y # vals & < 7 read some data
1, 0=8A,D!>y) B vals 7 and put it into the image
#e co!!and used to read an i!age is M'=C" and you !ay optionally specify the . and y range
covered by the data (e.g. M'=C datafile !min !ma! ymin yma!O this also works with
declarations like the one in the previous paragraph). *nly the region of the i!age lying within the
current li!its is ploted when contouring % 4ust like any other graphics operation in SM. !ages
!ay be deleted with the ,CLCJC M'=C co!!and. Jo e.tract values fro! an i!age" use the
special e.pression 0=8A,Dvec_!>vec_y) which has the value of the i!age at the points
(vec]."vec]y).
Iou can e.tract variables fro! the i!ageDs header using the co!!and +,S09, name 0=8A,.
See the discussion of &lecap if you need to know what variables can be retrieved this way.
f you want to use non%interactive SM (i.e. write your own co!!and interpreter)" there is a call
(defimage) to de&ne your data array to the contouring package" but this is of course not
available interactively.
'ilecap
Qilecap is si!ilar in graphcap or the 7ni. ter!cap" and in fact the Y&lecapD entries !ay be
physically in the sa!e &le as graphcap (i.e. added as if they were graphcap entriesO of course an
ate!pt to say device fits will lead to confusionf). Qilecap can be speci&ed as a list of &les to
be searched in order. #e &elds in &lecap are used to specify the data type of the &le" the record
for!at of the &le (record%length" inter%record gaps" etc.) and the header used (length of header"
oUset of desired ite!s). @ote that these are Yunfor!atedD &les" as writen by ( write() or fortran
write(nu!) state!ents.
#e current &lecap is as follows$
7
7 Silecap describes unformatted file formats to 1=. he synta! is
7 identical to termcap or graphcap files.
7
cU3U3 files:M
:G17%:n!7.:ny7$:
chU3GU3 files with headers:M
:G17#$:n!7.:ny7$:!.7%:!"7"#:y.7"):y"7#.:
fitsUcfitsUS01U3S01U3 S01 files:M
:+8Bfits::-B#%%.:
no_headerUSiles with no header> will prompt for n!> ny:M
:G17.:
uni!UL906USortran unformatted files under Lni! on a 2a!:M
:G17-":n!7.:ny7$::17$::-7-"::,7$:
uni!_intUL906_09U-i/e uni!> but integerC$:M
:+8Bint:tcBuni!:
uni!_shortUL906_1G5:U-i/e uni!> but integerC#:M
:+8Bshort:tcBuni!:
vms_varU2=1_28:USortran unformatted under 2=1> recordtypeBvariable:M
:G17%:n!7.:ny7$:
vms_fi!edU2=1_S06,+USortran unformatted under 2=1> recordtypeBfi!ed:M
:G17-"::17.::-7-"::,n!7.:ny7$:
7 his seems to be correct> based on one e!ample
vms_direct:2=1_+0:,3USortran unformatted> direct access> under vms:M
:G17%::17.::,7.:n!7.:n!7$:
(o!!ent lines start with a ^" continuation lines start with white space (a tab or a space) and \
!ay be used to continue an entry on to the ne.t line. #e &rst few &elds in an entry are separated
by U" and are alternative na!es for the sa!e entry. Qor e.a!ple" fortran unfor!ated &les under
7ni. !ay be referred to as uni! or L906. Qields are separated by colons" and are of the for!
:337nnn: for nu!bers" and :11Bstr: for strings. *!ited &elds !ay be speci&ed as
:33[nnn:" or si!ply o!ited. Qilecap capabilities currently used are$
+8 D+8ta type)
Jype of data in &le (string)
S1 DSile 1tart)
7nwanted bytes at start of &le
G1 DGeader 1i\e)
SiSe of header
:, D:ecord ,nd)
7nwanted bytes at end of record
91 D9o 1wap)
,onDt swap bytes for QJS &les
:- D:ecord -ength)
@u!ber of useful bytes per record
:1 D:ecord 1tart)
7nwanted bytes at start of record
1J D1Jap)
:yte swap - by integer data" and byte%and%word swap > by integers.
n! D9umber 6)
*Uset in &le of ; siSe of data
ny D9umber @)
*Uset in &le of I siSe of data
!. D6 .)
(oordinate at start of ; a.is
!" D6 ")
(oordinate at end of ; a.is
y. D@ .)
(oordinate at start of I a.is
y" D@ ")
(oordinate at end of I a.is
n addition" GG is supported as an archaic for! of G1.
n ter!s of these /uantities a &le will look like this$ 's !entioned below" G1 can be negative and
is then taken as the record length of the header :-_G" in which case the &le will be like$ @ote that
the &rst real data record begins with an :1 %% this !eans that if you are writing fortran you must
write the header in a diUerent write state!ent than the one that you use to write the data (i.e.
writeDfd) n!>ny>arr will not work).
Most para!eters are optional" and will default to ?. f RC or RS is speci&ed" you !ust give RL as
well. f you specify it as negative" then weDll look for it fro! the operating syste!. Iou !ust
provide a value for BS (or BB if youDre old fashioned)" if it is negative weDll assu!e that even the
header has a record structure" with RS and RC 4ust like any other record. ts record length will be
taken to be RL" if RL is positive" otherwise weDll &nd it fro! the operating syste!. f BS and RL
are both negative there is no reason why the record length of the header should be the sa!e as
that of the data.
f neither n. nor ny are present in the graphcap entry you will be pro!pted(55) for the . and y
di!ensions of the &le" otherwise they !ust both be present. f they are negative they are taken to
be the negation of the true di!ension (so a &lecap entry :ny7-): speci&es that the y%di!ension
of the data is X)" but usually they are taken as the oUsets of the values of the . and y di!ensions
in the &le" relative to the start of the header (if you set BS to be Sero you can specify n. and ny on
the co!!and line" but they !ust be on a separate line" either a real separate line" or following a
\n). @ote that BS e.cludes QS" so BS will usually be -0siSeof(int) irrespective of the value of QS"
and n. will usually be ?. f BS is negative" then the n. and ny oUsets also ignore RS" i.e. n. is still
usually ?.
's an alternative to specifying the actual &le siSes as negative integer values of n. or ny (e.g.
:n!7-".:) you can si!ply specify the! as positive string values$ :n!B".:. @ote how this
diUers fro! :n!7):.
Possibilities for +8 are char" float (default)" int" long" and short" all as in (" and also
fits for QJS for!at data. (f you donDt know what QJS for!at is" donDt worry about it. tDs a
style of header and record structure used for data transport in astrono!y(5>). f you do know
about QJS" then we assu!e that each record is -WW? by long" although possibly with RS and RC
non%Sero. #e header is processed for the siSe of the &le and the value of :JP;. f the &le is not
SMPLC" it is taken to be > by Koating point data. (RP;" (R8'L" and (,CLJ are interpreted
correctly" as are :PCR* and :S('LC. ;?" .<" y?" and y< are speci&ed as the keywords ;?" ;<" I?"
and I< respectively" and take preference over (RP; etc. QJS &les on a !achine with va. byte
order are supposed to be byte swapped" but you can override this by specifying the 91 capability
which stops SM fro! doing any byte swapping). f you specify 1J it takes preference over any
other instructions about byte swapping and forces byte%swapping for - byte (short) data" and
byte%and%word swapping for > byte (int) data. f !. and !"" or y. and y" are o!ited" the range
of values on the appropriate a.is is taken to be ? to n.%< (or ny%<). Iou can override these values
with the 0=8A, co!!and. #e values of 6. (and so on) can be obtained directly using +,S09,
6. 0=8A,O *ther values can be speci&ed in `filecap'" for e.a!ple a &lecap entry :aa7#$:
speci&es that +,S09, aa 0=8A, should recover the (Koating%point) nu!ber stored at byte
oUset ->. :ecause of the way that &lecap &les work" you are restricted to two%character na!es. f
you are using QJS &les" all the keywords fro! the header are available" but you should re!e!ber
that SM is case sensitive.
Qor e.a!ple" suppose wrote a &le using the 7ni. fFF co!piler" with so!e code that looked like$
integer C$ n!>ny>arrD".>#.)
c
n! B ".
ny B #.
writeD%) n!>ny
writeD%) arr
(*!iting opening unit W as an unfor!ated &le" and &lling the array with data). #en could read
it in SM by de&ning file_type to be uni.]int. #e &lecap entry indicates that the length of the
header is to be obtained fro! uni. (in fact fro! the &le" itDll be the record length of the header)" as
is the record length. :oth the start%of%record (RS) and end%of%record (RC) gaps are > by long (they
in fact contain the record length" but you neednDt know that). #e nu!ber of .%records is at Sero
oUset in the &le" and y%records is at oUset >. n other words" allowing for QS being ? and RS being
>" n. occupies bytes >%F in the &le" and ny W%<<. #e data is taken to be >%byte integers (integer0>
to fortran). n fact" the &rst record consists of only the values of n. and ny" so the record length of
the &rst record is W by" and part of an e/uivalent &lecap entry would be
:S17$:G17"#:
where have interpreted RS as QS" and added the RC onto the end of the header length BS. f had
writen the data out line%by%line in a do loop" the &le type would still be uni.]int" but the record
length actually used by SM in reading the &le would be diUerent (see section !age).
's another e.a!ple" use an i!age processing syste! called 9olf that used to use &les with the
arcane structure of -?? bytes of header" then the .% and y%siSe of the &le" given as ints" then !ore
header up to a total oUset of <?-> bytes fro! the start of the &le" then the data writen as short
integers. could write a header with code that looked so!ewhat like (o!iting all error checking)$
int fd>i]
int !s B #.>ys B ".]
short arrY".QY#.Q]
...
lsee/Dfd>#..->.)]
writeDfd>Dchar C)^!s>si\eofDint)]
writeDfd>Dchar C)^ys>si\eofDint)]
lsee/Dfd>".#$->.)]
forDi B .]i R ys]iOO) writeDfd>Dchar C)arrYiQ>!sCsi\eofDshort))]
#e corresponding &lecap entry is
wolfUJolf-0f8 files:M
:G17".#$:n!7#..:ny7#.$:+8Bshort:
which is prety si!ple really.
Reading and writing tables
SM is able to read a variety of table for!ats" but the only one of practical interest appears to be
QJS binary tables. f you disagree with this state!ent and either have proble!s or a section to
contribute to this appendi." please send RBL !ail.
#e relevant co!!ands are given in the sections on the 84-, (see section Jable) and J:0,
(see section 9rite) co!!ands.
Reading Jables$ Bow to read tables
9riting Jables$ Bow to read tables
How to read tables
f you want to read variables fro! the header" you can use the define var image co!!andO
so to read both data and variables youDd say so!ething like$
table . table-file.fit
read table ; ! y <
table $
local define :+- image
echo :+- B H:+- DHDdimenD!)) point)
#is reads ! and y fro! the pri!ary data unit (P,7O thatDs what the ? !eans)" and then the
variable R,L fro! the fourth data unit. f you o!it the . itDll be assu!ed" unless the P,7 is
e!pty in which case SMDll read the &rst real table instead.
How to write tables
9riting tables is basically prety si!ple" e.g.
local define tab Ntable.fitsN
local set ! B ">". local set yBsinD!)
Wrm -f Htab
write table Htab ; ! y <
set ! B ! concat "* O ! set y B y concat -y
local set \ B ".C!
write table O Htab ; ! y \ <
f you donDt de&ne the variable noclobber" you donDt need to e.plicitly delete the &le before
writing your &rst sert of data.
f you want to put variables into the headers" and care about which data unit they go in" things
look !ore co!plicated (but they really arenDt too bad)$
local define tab Ntable.fitsN
local set ! B ">". local set yBsinD!)
table delete
define :+- local
image define :+- N:owanN
Wrm -f Htab
write table Htab ;<
table delete
write table O Htab ; ! y <
table delete
set ! B ! concat "* O ! set y B y concat -y
local set \ B ".C!
define -=- local
image define -=- N=ummyN
write table O Htab ; ! y \ <
Bere the table delete co!!ands are being used to unde&ne 0=8A, variables. @ote that
e.plicitly wrote an e!pty pri!ary data unit (P,7)" whose only interesting content is the variable
:+-
4ermcap -- A 4erminal #atabase
Jer!cap is a 7ni. idea" that !akes it possible to write so)ware that runs on a wide range of
diUerent ter!inals. #e i!ple!entation that SM uses contains no 7ni. source code. #e idea is
si!ilar to graphcap or &lecap %% each property of the ter!inal is given as a &eld in a &le. Qor
e.a!ple" the string to clear to end of line is called ce" and for ansi ter!inals is given as
ceBcontrol-YYE. #e for!at for ter!cap &les is described under YgraphcapD" which is
identical. *ur ter!cap is identical to the 7ni. one" so for details see section G of the 7ni. !anual.
#e &le to use as a ter!cap &le is speci&ed as termcap in your `.sm' &le" or as the
environ!ent variable ,:=38? (logical variable to 8MS). f SM canDt open ,:=38? as a &le" it
is taken to be the value of the entry for your ter!inal. f it doesnDt begin with a colon" it is treated
like a ter!cap &le" and searched for the desired ter!inal. f it does begin with a colon" it is si!ply
taken to be the ter!cap entry to use. ' ,:=38? variable takes precedence over an entry in your
`.sm' &le. 's for graphcap" a list of ter!cap &les can be speci&ed" to be searched in order.
' full ter!cap entry can be prety long" but fortunately SM only uses a s!all subset. (#e rest are
needed by full scale screen editors" but we havenDt writen one.) n particular we use$
ce D3lear ,nd)
,elete to end of line
ch D3ursor Gori\ontal)
Move cursor within line
cm D3ursor =ovement)
Move cursor around screen
cn D3olum9s)
@u!ber of colu!ns on screen
dc D+elete 3haracter)
,elete character under cursor
is D0nitiali1e)
nitialise ter!inal
/s DEeypad 1tart)
nitialise 3eypad
/s DEeypad ,nd)
7ndo 3eypad nitialisation
/d DEursor +own)
Move cursor down one character
/l DEursor -eft)
Move cursor le) one character
/r DEursor :ight)
Move cursor right one character
/u DEursor Lp)
Move cursor up one character
/" DEey ")
3ey se/uence e!ited by PQ< key (also /#" /&" and /$)
li D-ines)
@u!ber of lines on screen
pc D?ad 3haracter)
Pad character" if not @L
'll of these are strings e.cept co and li which e.pect nu!bers" and pc which e.pects a single
character. #e editor uses all of these e.cept co" although the / ones are only provided as a
convenience to you" !apping the arrow keys. n fact" these arrow keys !ay supersede desired
bindings such as control-E to delete to end of line (e.g. on a televideo H<-). f this happens" use
the ,+0 or :,8+ ,+0 co!!ands to &. things up.
#e cursor addressing strings ch and cm use a variant of the ( printf d. (onsider the string as a
function" with a stack on which are pushed &rst the desired colu!n" and then the desired line (so
the line is on top). #e possible d for!ats operate on the stack" and pop it a)er output.
d
's in printf" Sero origin
#
Like d-d
&
Like d5d
.
Like dc
O!
'dd . to value" then Yd.D
T!y
f value N . add y (no output)
r
nterchange line and colu!n (no output)
i
ncre!ent line and colu!n by < (no output)
_
*utput a single d
9e do not support _n" _4" or _+ out of pure laSiness. ' couple of e.a!ples !ight help. Jo go to
(G"X?) a vt<?? e.pects to receive the string control-YY*]).G" so the ter!cap entry reads
:cmBM,Y_i_d]_dG:. 9e need the _i to go to one%inde.ed coordinates" and the escape is
writen M,. #e :Ds deli!it the ter!cap entry. ' Jelevideo H<- e.pects to be given &rst
control-YB" then the coordinates as characters" where Y D is ?" YaD is <" and so forth through the
ascii character set. Jo convert a given nu!ber to this for! we add Y D" so the ter!cap entry is
:cmBM,B_O _O :.
f an entry begins with a nu!ber" it gives the nu!ber of !illiseconds of padding that the ter!inal
re/uires (it is optionally followed by an 0" which we can and do ignore). f the ter!inal re/uires a
pad character that is not si!ply ascii 90- it should be given as pc" so to use YaD as a pad character
specify :pc7'(:. #e baudrate is taken to be HX??" unless you specify it as the ttybaud
variable in your `.sm' &le. 9e have never yet seen SM have any trouble with padding" so we
wouldnDt worry about any of this if we were you.
Iou !ight wonder why we need both ch and cm. #e si!ple answer is that we donDt" but that we
do want one of the!. :ecause cm !oves the cursor to a speci&c line" its use re/uires that SM
re!e!ber which line you are on which can be tough what with switching to and fro! graphics
!ode. 9e therefore assu!e that you are on the last line of the ter!inal" as set by li or e.plicitly
by the ,:=@?, co!!and. f you provided ch this proble! wouldnDt arise but !any ter!inals
donDt support such a capability and we have to code around this de&ciency. Jo su!!arise$ use ch
if you can" failing that use cm.
#ere is a proble! with using the last line of the screen as the SM co!!and line" and this is that
so!e ter!inals use the sa!e screen for graphics as for te.t" and your graph will !errily scroll
away as you type. #e graphcap A+ (=raphics ,isable) co!!and can be set to take you to the top
of the screen" but cm wonDt keep you there. Iour only chance is to disable cursor !otion" either by
seting ch to YdisabledD" or by specifying a negative screen siSe to ,:=@?, which has the sa!e
eUect. Iou can still use the editor" but itDll be slower. f you still have trouble" try ,:=@?,
dumb" which really is a bit brain da!aged" or ,:=@?, none which disables the editor
entirely.
$ew #evices and $ew Machines
Adding $ew #evices
's we have discussed e.tensively (see section #e Stdgraph =raphics 3ernel)" !ost ploting
devices can be acco!!odated within the fra!ework of stdgraph+graphcap without writing a line
of (O raster devices can use the raster device driver. So!eti!es" however" this is not possible and
you !ust write a real driver. 'n e.a!ple would be !aking SM run native under ;<<O running
under a ter!inal e!ulator can be done with graphcap.
f you do !ake any changes" write any new drivers" or !odify graphcap (e.cept trivially) please
send us copies of your !odi&cations.
Let us assu!e that you really do need a new driver" how do you go about itT SM co!!unicates
with devices solely through a graphcap entry" so!e e.ternal variables (de&ned in s!.h) and a
structure called +,203,1 which is de&ned in devices.h and declared in
plotsub/devices.c.
9hen you issue a +,203, devname args co!!and" the stdgraph driver is called with the
string devname args" and it opens the graphcap entry for devname. f it &nds an entry of the
for! :+2Bdriver: it tries to &nd a hardcoded device driver called NdriverN (youDll see in a
!o!ent where the na!es co!e fro!). f it can &nd such a driver it calls its setup function (to be
de&ned in a !o!ent) with args as an argu!ent. (5G) Iour device driver is now in charge" and no
!ore stdgraph routines are called until your device is closedO a)er you return fro! your close
function stdgraphDs close function is called to close the graphcap descriptor. 9hat do you have to
re!e!ber fro! this paragraphT #at you need a graphcap entry" if only a trivial one along the
lines of
my_deviceUall_mine:+2Bmy_driver:
which associates the driver my_driver with the device referred to as either my_device or
all_mine. :ecause stdgraphDs stg_open and stg_close functions are called around your
device code the standard graphcap support for 5J" 0S" +3" 5S" 1@" and 3J is auto!atically
provided if you want itO see the i!agen driver and graphcap entries for an e.a!ple. Iou !ight
also want to re!e!ber that you can directly access any graphcap entry for your device fro!
within your driver" using the functions ttygets" ttygetr" ttygeti" and ttygetb.
#e current de&nition of +,203,1 looks like this$
typedef struct ; /C output device dependent functions C/
char d_nameY$.Q] /C name of device C/
int DCdev_setup)D)] /C initialisation C/
void DCdev_enable)D)> /C enable graphics C/
void DCdev_line)D)> /C draw a line from !"> y" to !#> y# C/
void DCdev_reloc)D)> /C relocate current position C/
void DCdev_draw)D)> /C draw a line from current pos to !>y C/
int DCdev_char)D)> /C hardware characters C/
int DCdev_ltype)D)> /C hardware line type C/
int DCdev_lweight)D)> /C hardware line weight C/
void DCdev_erase)D)> /C erase graphics screen C/
void DCdev_idle)D)> /C switch from graph to alpha mode C/
int DCdev_cursor)D)> /C cursor display C/
void DCdev_close)D)> /C close device C/
int DCdev_dot)D)> /C draw a single pi!el dot C/
int DCdev_fill_pt)D)> /C draw a filled point C/
int DCdev_fill_polygon)D)> /C draw a filled polygon C/
void DCdev_ctype)D)> /C set colour of line C/
int DCdev_set_ctype)D)> /C set possible colours of lines C/
void DCdev_gflush)D)] /C flush graphics C/
void DCdev_page)D)] /C start a new page C/
void DCdev_redraw)D)] /C redraw the screen> if need be C/
< +,203,1]
ote that this is the 80$/10S structure at the time o" writingD be sure to see that it is still correct
when you write your driverB Jo add a new device to SM" all you have to do is to write functions to
&ll as !any of the slots in +,203,1 as possible" add their de&nitions to `sm_declare.h'"
then add an ele!ent to the array devicesgh in devices.c. ')er reco!piling" SM will recognise your
device by the na!e d_name that you gave it in devicesgh. Jraditionally the functions have the
sa!e na!e as those given above with the dev replaced by so!e !ne!onic for your new device.
Iou should surround both your driver and the entry in devicesgh with ^ifdefDs so that all have to
do to totally lose your device is to not ^de&ne it to the co!piler. n writing your device you !ay
want to use graphcap to give it various pieces of infor!ation. #is can be doneO see the i!agen
driver for an e.a!ple.
Iou should include the &le `sm_declare.h' (which auto!atically includes `options.h')
which provides declarations for all SM functions (including prototypes if the co!piler supports
the!)" and you should add your own declarations to this &le.
f you donDt provide so!e of the functions" SM will try to e!ulate the! in its so)ware. Qor
e.a!ple" of your ltype function returns j<" then we will chop your lines for you. #ere are a set of
functions for nodevice that have the correct types" you can use the! for functions that you
donDt want to provide (e.g. if you donDt support dev_ltype you can use no_ltype). So!e of
the routines" e.g. dev]char are so!eti!es passed @7LL argu!ents to in/uire if they can provide
particular capabilities. n the following paragraphs we discuss all the functions" their argu!ents"
what they do" and what they return.
'll coordinates are given in screen units" where the device is 5-FXW pi.els along a side.
dev_setupDstr) Dchar Cstr])
*pen the ploting device. Str contains the rest of the co!!and line" so if the +,203,
co!!and was +,203, newdev abcde \y!wvut" setup will be passed abcde
\y!wvut. f the device canDt be opened for so!e reason setup should return j<" otherwise
?. Setup has a nu!ber of book%keeping responsibilities$ seting the value of ter!out to < if
the device is a ter!inal" otherwise ?O seting the value of ldef to the !a.i!u! spacing
between lines if they are to appear as one thick line rather than a set of parallel ones" (used
if we have to e!ulate -J,0AG)O seting the variables .screen]to]pi. and yscreen]to]pi.
to give the conversion fro! S(RCC@ to device coordinatesO calling default]ctype with the
na!e of the default colour for lines (e.g. default_ctypeDNwhiteN)). #ere is no need
to look in the `.sm' &le for a foreground entry" this is done for you (by set]dev()) a)er
dev]setup returns" but you should deal with any bac/ground entry if you feel so inclined.
#ere is a function parse]color that converts a colour na!e into r" g" and b values (see the
sunwindows setup function for an e.a!ple of its use) that !ay help. @ote that you should
not call stg_setup %% this was done for you auto!atically before your setup function was
called. @o return value.
dev_enableD)
Cnable ploting on the device. Qor a graphics ter!inal this !eans switching fro! alpha to
graphics !ode" but !ay well not be re/uired for other devices. @o argu!ents" no return
value.
dev_lineD!">y">!#>y#) Dint !"> y"> !#> y#])
,raw a line fro! (.<"y<) to (.-"y-). @o return value.
dev_relocD!>y) Dint !>y])
Move the plot !arker to (."y). @o return value.
dev_drawD!>y) Dint !>y])
,raw a line fro! the current plot !arker to (."y) which beco!es the new plot !arker. @o
return value.
dev_charDstr>!>y) Dchar Cstr] int !>y])
9rite the string at the position (."y). #e position given is 4ust to the le) of the &rst
character" at about the height of the centre of a capital leter. Return ? if you support
hardware characters" otherwise j< in which case weDll use the so)ware character set
instead. f str is @7LL" this is 4ust an en/uiry as to whether the device supports a hardware
character set. (har is also called (with @7LL) whenever the value of e.pand or angle is
changed" to allow you to ad4ust the siSes of cheight and cwidth (the height and width of a
character in S(RCC@ units) for a hardware character set" as the siSes of hardware sets can
be very diUerent fro! the SM fonts. Iou should only change cheight and cwidth if we are
really going to use your hardware characters (e.pand `` <" angle `` ?).
dev_ltypeDi) Dint i])
Set the -@?, to be i" as in the interactive co!!and. Return ? if you support the ltype
asked for" otherwise j<. f you canDt support a linetype" !ake sure that you are drawing
solid lines" so that SM can e!ulate it for you. -@?, <? is special" it is generated by the
-@?, ,:81, co!!and" and asks you to delete lines as they are drawn" -@?, "" is
used to indicate the end of -@?, ,:81, !ode.
dev_lweightDlw) Dreal lw])
Set the -J,0AG to be lw" as in the interactive co!!and. Lines with lweight ? should be
the natural thickness of a line on your device" higher lweight lines are usually drawn
with a thickness of -+,SClweight in S(RCC@ coordinates. Return ? if you support the
lweight asked for" otherwise j<.
dev_eraseD)
Crase the screen. @o return value.
dev_idleD)
Return to alpha !ode" the opposite of dev]enable(). @o return value.
dev_cursorD!>y) Dint C!>Cy)
Qind the current position of the cursor" if there is one. f there is" the return value is the
character struck by the user" otherwise return j<. f your device has a !ouse" you should try
to !ake the butons correspond to YeD" YpD" and Y/D fro! le) to right. f you only have one
buton" YpD is probably the best choice.
dev_closeD)
(lose the device" the opposite of dev]open(). @ote that you should not call stg_close %%
this is done for you auto!atically. @o return value.
dev_dotD!>y) Dint !>y)
,raw a dot at (."y)" (i.e. a real dot" not like the +5 co!!and). IouDll have to do the !ove to
(."y) yourself. Return ? if you can draw dots" otherwise j<.
dev_fill_ptDn) Dint n])
,raw a &lled point at the current position. #is is the routine that draws ?@?, n &
points. Re!e!ber to allow for ,6?89+ and 89A-,. Return ? if you can draw the point"
otherwise j<O
dev_fill_polygonDn) Dint style] float C!> Cy] int n])
,raw a &lled polygon de&ned by ! and y (a total of n) points) in the style style (?$ &lledO
all other values are currently unde&ned). Return ? if you can &ll polygons in the desired
style" otherwise j<. Iou !ay get /ueries with on style with n BB ..
dev_ctypeDr>g>b) Dint r>g>b])
Set the current line colour. #e interpretation of (r"g"b) depends on whether you have a
dev]set]ctype function. f you donDt" then r" g" and b are the red" green" and blue intensities
in the range ?%-GG. f you do" then r is an inde. into the array de&ned by set]ctype and g
and b are irrelevant. @o return value.
dev_set_ctypeDcol>n) D35-5: Ccol] int n])
,e&ne a set of colours to be accessed by set]ctype. (ol is an array of n ele!ents" each of
which consists of 5 unsigned chars ((*L*R is de&ned in s!.h) corresponding to red" green"
and blue in the range ?%-GG. (type will be used to access this array to change colours.
Return ? if you do support set]ctype" otherwise j<. f col is @7LL this is 4ust an en/uiry. f
you are asked for !ore colours than you are prepared to support" you should scale the
re/uest in a user transparent way (e.g. if she wants -GX colours" and you are only giving her
<-W" you should arrange that dev]ctype divides her re/uests by - so it looks as if she got all
-GX).
dev_gflushD)
Qlush graphics" update graphics on screen. @o return value.
dev_pageD)
Start a new page. f your device produces hardcopy you should print the current page and
start a new oneO if you are writing a window syste! driver you probably should si!ply
raise the window so that it is visible. @o return value.
dev_redrawDfildes) Dint fd)
Redraw the screen" but only if it needs it. #is function is called by get"charD) before it
tries to read a character fro! SMDs standard input (&le descriptor fd). t is intended for the
use of drivers that need to keep an eye on YtheirD window. Qor e.a!ple" the Silicon =raphics
driver needs to redraw a window every ti!e that it is !oved. Such device drivers will
probably want to poll fildes (e.g. using selectD)) to see that there really is input
before returningO look at the sgi or !"" driver if you want an e.a!ple. @o return value.
f you are still confused" look at so!e of the hardware drivers that are already available.
,orting to $ew Machines
Porting to new 7ni. !achines should be relatively si!ple. f the !achine runs :S, 7ni. the only
changes that should be necessary are to the e.ception handler routines in !ain.c" to reKect the
error conditions signalled by your new !achine. Qor a Sys 8 7ni." youDll have to edit
`options.h' to de&ne 1@1_2. *therwise" your only proble!s should be hidden bugs which
Kourish in new architectures.
*therwise there isnDt all that !uch that can tell you. SM runs on 7ni. (:S, and Sys8) and 8MS
!achines" and the places where the code is ^ifdefDd for those operating syste!s is your best bet
for places where there are !achine dependencies. #at said" there are a few obvious proble!
areas.
Qirst consider get<char" which is the routine that reads ter!inal input. t has to be able to get one
character a ti!e fro! the ter!inal" and not interpret control characters. #is is obviously
operating syste! dependent ((:RC'3 under >.5:S," P'SS'LL under 8MS" ...). =et<char e.pects
to be passed control-8 to start operations" and C*Q to end the!. 'nything else !eans Yreturn
a character pleaseD. #e ter!inal output functions used by stdgraph are also !achine dependent"
for e.a!ple they use A* calls under 8MS.
's !entioned above" the e.ception handlers try to interpret the e.ceptions that they receive and
this !ay re/uire a litle !odi&cation in !ain.c.
Bardcopy devices need the syste!() syste! call to send co!!ands to the operating syste!" and if
you donDt have one you are in trouble.
n a few places SM needs to !ake assu!ptions about how &le na!es are put together" and these
will need changing. *n a si!ilar note" so!e operating syste!s (e.g. 8MS) are very picky about
opening &les and you !ay have to be careful. @ote the use of the + graphcap capability to signal
particular re/uire!ents to the progra!!e.
' !achine that didnDt use ascii would be rather a nuisance as !akeyyl assu!es that the
characters for '%P are contiguous" and although this could be easily &.ed a! not sure that other
proble!s wouldnDt arise.
' &nal rather horrifying thought is that :ison !ight not co!pile on a !achine that doesnDt have
I'(( as an alternative. donDt know how to &. that" youDd 4ust have to hope for the best" or else
run :ison+I'(( on a diUerent !achine and copy over control.c.
4he System Macro &ibraries
#is appendi. describes the collection of useful !acros" writen by a variety of people" that are to
be found in the default !acro directory" i.e. the directory pointed to by the macro entry in your
`.sm' &le. f ever you write a useful (or si!ply clever) !acro" why not send it to us for inclusion
in the ne.t version of SMT
#e !acros are arranged in a nu!ber of &les which !ay be read using the load !acro. Qor
e.a!ple" to load the &le fonts type load fonts. Jo forget a set of de&nitions" use unload.
7nder 7ni." there is a !acro lsm that can be used to list the contents of !acro libraries" e.g. lsm
utils. t is !ore%or%less co!plete depending on the value of 2,:451," 4ust like -01 =83:5.
#e list that follows gives the na!e and a one%line synopsis of all the !acros in the default &les as
of the date of this !anual. #e full te.t of any !acro !ay be e.a!ined via the help
RmacronameT co!!and in SMO the default &les !ay be printed for those who desire a
hardcopy.
&le `abbrev' in directory `macro' (#is is a &le of all una!biguous abbreviations of
keywords. t is created using the shell script `abbrev' in the !ain SM directory. ts use !ay
interfere with cunning !acros" and is not reco!!ended).
&le `cover' in directory `macro'
cover 7 draw the cover
&le `default' in directory `macro'
batch 77 run the history buffer> but don't delete from history list
bell 77 ring terminal bell
calc 77 evaluate an e!pression
cd 77 change directories
compatible 77 define macros to be compatible with =ongo
declare 77 declare a vector H": declare name si\e
del 77 delete last command from history list
del" 77 don't put command on history list
echo 77 write to terminal
ed 77 edit a macro> or the previous one if no argument
edit_all 77 edit history buffer
emacs_all 77 edit the history list using an e!ternal editor.
emacs_hist 77 edit the history list using an e!ternal editor.
error_handler 77 Gandle control-3 interrupts
e!ecute 7 read and e!ecute an 1= file of commands D" per line)
e!tend_history 7 ,!tend history buffer to be of si\e H"
for 77 :epeat a macro while a condition is true> li/e 3's forD]]). 1ee
also while
gripe 77 complain to :obert DLni! only)
h 77 get help
head 77 print the top of the current data Dor other) file
hm 77 help with the last macro edited
hv 77 help with variable
insert 77 insert te!t after line H"
load 77 load macros in default directory
load# 77 load macros in Dsecond) default directory
ls 77 list macros
lsm 77 list macros in a file in default macro directory
lsv 77 list variables
q 77 chec/> then quit
re 77 macro read
reset_ctype 7 :eset the default ctypes De!cept NdefaultN)
sav 77 save to a file H"> don't save from files `Hmfiles'
show 77 show current values of various things
startup 77 macro invo/ed upon startup
undef 77 undefine a variable
undo 77 undo YmacroQ : undo Di.e. erase lines drawn by) macro H"
unload 77 forget macros from a file
unset 7 delete a vector
v 77 set verbosity
wr 77 macro write
!tcolours 7adds e!tra colors to the default set
&le `demos' in directory `macro'
square 7 sum the Sourier series for a square wave> using H" terms
colours 7 draw a circle in a number of colours until I3 stops it
crings 7 draw a set of coloured circles
crings# 7 draw a set of coloured circles using #*) shades of yellow
gauss_convolve 7 convolve # Aaussians with sigmas H" and H#
grey_sincos 7 draw a grey scale image of a sinD!)cosDy) surface
scribble 7 use cursor to draw a line> and then shade the interior
shading 7 draw an ammonite
sundial 7 draw a sundial> allowing for the analemma
&le `fonts' in directory `macro'
fonts 7 draw the font table
e6_defs 7 draw the Ne6N definitions
ma/e_char 7 help create a new character
&le `fourier' in directory `macro'
7
7 =acros to ma/e dealing with comple! numbers for SS's easier
7 8ssumes that comple! vector `name' is represented by two vectors
7 called name_r and name_i
7
fft 7 +irect SS: fft name name
ifft 7 0nverse SS: ifft name name
cadd 7 8dd comple! numbers: H" B H# O H&
cdiv 7 +ivide comple! numbers: H" B H#/H&
cmod 7 =odulus: H" B UH#U
cmult 7 =ultiply comple! numbers: H" B H#CH&
csub 7 1ubtract comple! numbers: H" B H# - H&
imag 7 0maginary part: H" B 0mDH#)
real 7 :eal part: H" B :eDH#)
vcentre 7 shift a vector so that its .th element appears in the middle
vcenter 7 an alias for vcentre
&le `images' in directory `macro'
entropy 7 Sind entropy of an image
hist_equalise 7 Gistogram equalise an image
gamma 7 Aamma correct an image
&le `irregular' in directory `macro' #ese !acros were writen by =abor Joth" to who!
!any thanks. #ey enable you to de&ne an SM M'=C fro! 5 vectors" (."y) and the value S
irregular_image 7 1et 0=8A, from & vectors D!>y) and \
trigrid 7 0nterpolate to the regular grid
trigridtry 7 +emonstrate the use of trigrid
&le `math' in directory `macro'
7
7 Jritten by +aniel ?fenniger D?S,990A,:[obs.unige.ch)
7 `8^1' is 8bramowit\ ^ 1tegun
7
Z. 7 4essel func. Z.DU!U)> 8^1> '.$.">.&
@. 7 4essel func. @.DU!U)> U!UT.> 8^1> '.$.#-&
Z" 7 4essel func. Z"DU!U)> 8^1> '.$.$>.)
@" 7 4essel func. @"DU!U)> U!UT.> 8^1> '.$.*-)
0. 7 =odified 4essel func. 0.DU!U)> 8^1> '.%."-#
0" 7 =odified 4essel func. 0"DU!U)> 8^1> '.%.&-$
E. 7 =odified 4essel func. E.DU!U)> U!UT.> 8^1> '.%.*-)
E" 7 =odified 4essel func. E"DU!U)> U!UT.> 8^1> '.%.(-%
E 7 3omplete elliptic integral EDm)> .RBmR"> 8^1 "(.&.&$
, 7 3omplete elliptic integral ,Dm)> .RBmRB"> 8^1 "(.&.&)
fresnel 7 3alculate the Sresnel integrals 3> 1> and S
&le `matri!' in directory `macro'
matri! 7 0ntroduction to matri! utilities
mdeclare 7 declare H" to be a H#!H# square matri!
mdimen 7 print matri! H"'s dimension
mprint 7 print the matri! H" Dgiven as H"_. H"_" etc -- see minv)
madd 7 set matri! H" equal to H#OH&
minv 7 Kuic/ matri! inversion> done in place.
mset 7 set matri! H" equal to H#
mmult 7 set matri! H" equal to H#CH&
mmult_c 7 set matri! H" equal to H#CH& where H& is a scalar
mmult_v 7 set vector H" equal to H#CH& where H& is a vector
mmult_v 7 set vector H" equal to H#ICH& where H# is a vector
mtrans 7 set matri! H" equal to H#I
mprint 7 print the vector H"
&le `mongo' in directory `macro' (o!iting those that are si!ply abbreviations" like ang)
da 77 set data file
dev 77 set device
dra 77 draw> accepting e!pressions
ecolumn 77 define vector error_col as error vector
end 77 quit> not on history
era 77 erase screen> not on history
lis 77 list history> not on history
hard 77 ma/e a hardcopy of what you type Dor get by history)
hardcopy 77 close the old device and set dev type to .
hcopy 77 hcopy YprinterQ Yl"Q Yl#Q: =a/e hardcopy of playbac/ buffer
hmacro 77 hmacro YmacroQ YprinterQ: ma/e hardcopy of `macro' on `printer'
identification 77 write an id to the top right hand corner of screen
input 77 e!ecute an =ongo file
mongo 7 ma/e 1= resemble =ongo as closely as possible
pcolumn 77 set point column D=ongo)
playbac/ 77 define NallN from buffer> and run it
read_all 77 read a macro file> putting `all' onto the history buffer
read_hist 77 read history from a file
read_old 77 read an =ongo file onto the history buffer
rel 77 relocate> accepting e!pressions
save_all 77 write the playbac/ list to a file Duse sav instead)
terminal 77 device
toplabel 77 put label at top of plot
!column 77 read a column into vector ! D=ongo)
!logarithm 77 ta/e log of vector ! D=ongo)
ycolumn 77 read a column into y
ylogarithm 77 ta/e log of y
&le `proXect' in directory `macro' Miscellaneous pro4ections (e.g. e/ual area). (ontributed
by Michael Strauss.
aitoff 7convert l and b to ! y in 8itoff coordinates
aitoff" 7 3onvert l and b to ! y in reverse 8itoff coordinates
aitoffdec 7 +raw a line of constant declination in an 8itoff plot
aitoffdec" 7 +raw a line of constant declination in a reverse 8itoff plot
aitoffgrid 7 ?ut up equal area grid in 8itoff
aitoffgrid" 7 ?uts up equal area grid in 8itoff. :everse sense
calc_lb 7 3alculates r> l and b given !> y> and \
circle_e!clude 7 8fter circleplot> draws regions e!cluded in latitude
circlelabel 7 +raw a!es for a redshift circleplot
circleplot 7 ?lot redshift points] requires circlelabel
eqgal 7 Lsage: ra dec l b] 3onvert Dra> dec) to Dl>b).
galeq 7 Lsage: galeq l b ra dec. 3onvert Dl>b) to Dra> dec)
galgrid 7 ?uts up equal area grid
galplot 7 Lsage: galplot ra dec l b
galpoints 7 ?lot points on an equal area grid] galpoints l b
gstrans 7 3onvert supergalactic to galactic coordinates
hemiconvert 7 3onvert from l b to ! y for hemisphere plotting
hemidec 7 +raw a line of constant declination on a pair of
hemiplot 7 1/y plot in two hemispheres> equal area
invaitoff 7 3onvert ! y in 8itoff coordinates to l> b
pielabel 7 +raw a!es for a redshift pieplot
pieplot 7 ?lot redshift points] requires pielabel
radtic/ 7 ?ut tic/ mar/s on a radial a!is
sgtrans 7 3onvert galactic to supergalactic coordinates
&le `stats' in directory `macro'
cgauss 7 evaluate a cumulated Aaussian distribution : 9DHmean>Hsig)
cuniform 7 evaluate a cumulated uniform distribution> Hmean>Hsig
chisq 7 :eturn chiI# distribution of vector H" with H# dof
draw_E1 7 +raw a cumulated curve> for loo/ing at E1 statistics
erfc 7 calculate complementary error function erfcDH")
factorial 7 Lse 1tirling's formula to calculate a factorial DH")W
gauss 7 evaluate a Aaussian : 9DHmean>Hsig)
gaussdev 7 return a 9D.>") random vector
linfit 7 linear least squares fit for any number of parameters
log_fac 7 Lse 1tirling's formula to calculate a log factorial.
lsq 7 do a least squares fit to a set of vectors
lsq# 7 do a least squares fit to a set of vectors> errors in ! and y
prob_chisq 7 probability of getting a given value of chiI#
prob_E1 7 probability of getting a given value of the E-1 statistic
prob_wilc 7 return probability in HH# that ! e!ceeds H" from Jilco!on
r!y 7 find ?earson 3orrelation 3oefficient for two vectors
smirnov" 7 calculate " sided Eolmogorov-1mirnov statistic for vector
smirnov# 7 calculate # sided Eolmogorov-1mirnov statistic for vectors
spear 7 calculate 1pearman ran/ correlation coefficient for # vectors
stats 7 stats vector mean sigma /urtosis : calculate Hmean Hsigma etc
stats# 7 stats vector weights mean sigma /urtosis
stats_med 7 stats_med vector median 10K: : calc Hmedian H10K: from vector
wilco!on 7 calculate Jilco!on statistic for # vectors
wlsq 7 do a weighted least squares fit to a set of vectors
&le `trigd' in directory `macro' C/uivalents for all SM trig functions" taking degree
argu!ents. @a!es add an e.tra YdD (e.g. sind)
&le `utils' in directory `macro'
alpha_poi 7 alpha_poi ! y \. -i/e poi ! y> but use \ as labels for points
arc 7 the arclength along the curve DH">H#)> e.g. set vBarcD!>y)
arrow 7 use the cursor to define an arrow.
barhist 7 draw a bar histogram
bo!it 7 use the cursor to define a bo!> and draw it
circle 7 draw a circle> centre DH">H#) radius H&
cumulate 7 find the cumulative distribution of H" in H#
draw_arrow 7 draw an arrow from DH">H#) to DH&>H$)
draw_bo! 7 draw a bo!> defined by two corners
error_! 7 draw !-error bars: error ! y si\e
error_y 7 draw y-error bars: error ! y si\e
get_hist 7 get_hist input output-! output-y base top width
gauss 7 evaluate a Aaussian : 9DHmean>Hsig)
get 7 synta!: get i X. :ead a column from a file
glevels 7 1et grey levels. Lsage: glevels e!pr
greyscale 7 +raw a grey-scale image.
7 Lsage: greyscale Ynp! npy ma!weight dmarginQ
info 7 Aet help about a command from 1='s info files
interp 7 -inearily interpolate H& into DH">H#)> giving H$
interp# 7 -inearily interpolate H& into DH">H#)> giving H$
is_file 7 :eturn true if file H" e!ists
is_macro 7 :eturn true if H" is a macro
is_set 7 define variable HH" if the H&'rd bit is set in H#
is_vector 7 :eturn true if H" is a vector
logerr 7 synta!: logerr ! y error> where y is logged> and error isn't
mconcat 7 3oncatenate # macros> optionally renaming result
number 7 convert a string vector to an arithmetic one
pairs 7 pairs !" y" !# y#. connect D!">y") to D!#>y#)
polar 7 draw a circle as an `a!is' for polar coordinates
pmatri! 7 print the matri! H"
puts 7 +raw a line of te!t> then move to the start of the ne!t line
qminv 7 Kuic/ matri! inversion> done in place
repeated 7 :eturn an array that is true for repeated elements in H"
reverse 7 reverse the order of a vector
save_vec 7 put the definition of a vector onto the history list
set_window 7 cycle through all available windows
shade_bo! 7 shade a bo!> spacing H"> defined by two corners
shed 7 shade region between ! y and !# y# with n lines
simp 7 1impson's rule integration: simp answer ! y
smooth 7 bo!car smooth a vector
smooth# 7 smooth a vector with a given filter
smooth& 7 smooth a vector with a given filter omitting points
#dhistogram 7 convert the current image to a #-d histogram
thin 7 create a NthinnedN version of a vector for plotting points
thin# 7 NthinN the end of a vector
thin& 7 NthinN the central portion of a vector
uniq 7 :emove duplicate elements of H"> e.g. u B uniqD!)
upper 7 define a variable giving an `upper limit' symbol
vecminma! 7 find the minimum and ma!imum of a vector
vfield 7 plot a vector field: vfield ! y len angle
vfield# 7 plot a vector field> vfield ! y len angle Dlen in !-a!is units)
vfield& 7 plot a vector field: vfield ! y len angle Dlen in y-a!is units)
vfield$ 7 2ector field at points !> y] components v! vy
vfield* 7 2ector field at points !> y] components v! vy scaled by f
4ips for Mongo <sers
#ifferences from Mongo
SM diUers in a nu!ber of ways fro! Mongo" and these fall into three groups$ those which are
enhance!ents" those which are generalisations" and those which are si!ply inco!patibilities. 9e
do not feel that there is a fourth group for degradations. Qor those users of Mongo inti!idated by
change" we note that in !ost cases it is possible to ignore the enhance!ents by using a !acro
presented in the ne.t section. #is !acro rede&nes co!!ands to reproduce the old synta.O for
e.a!ple limits is de&ned to !ean -0=01 ! y. t is also possible to read Mongo &les using
the :,8+ 5-+ co!!and" and the !acros input and read_old based upon it. #e following
list of enhance!ents in not co!pleteO See the distribution notes fro! the current release of SM.
Cnhance!ents$
8ny number of vectors may be defined.
2ectors may be manipulated arithmetically.
2ectors are named.
2ectors may be defined from the /eyboard using +5 loops or e!pressions.
2ectors may be defined using the cursor.
8ny vector may be used for plotting.
8ny vector may be used for the ?@?, or ,::5:48: commands.
8 history feature is implemented.
he playbac/ buffer may be edited.
=acros may be defined from the /eyboard> and edited.
8 +5 construct is available.
8 S5:,83G construct is available.
3haracter strings may be read from a file and used freely as labels or names.
+ata may be read from rows as well as columns in files.
5nly those parts of a vector satisfying a logical condition need be plotted.
2ectors may be sorted or fit with splines.
=acros e!ist for doing least square fit to sets of points>constructing
cumulative distributions and histograms> drawing circles> and shading regions.
8ll devices have the same range of device coordinates> .-&#()(.
he entire 1= environment may be saved for later resumption with 182,
and :,15:,.
he special variable Hdate e!pands to the current date and time.
@ou can define private point types.
#ere are also a few inco!patibilities$
+,S09, is used to define variables] macros are defined
using =83:5.
=acro arguments must be declared> and are referred to as Hn>
not ^n.
he form -0=01 is not supported Dit's meaningless)] use
-0=01 ! y> or the macro lim> mentioned above.
D4ut note that :,8+ 5-+ allows for these> and ma/es suitable changes.)
J09+5J now ta/es $ arguments.
4he R*A# 8&# command
:,8+ 5-+ reads a Mongo &le" converts its contents to a for! acceptable to SM" and de&nes the!
as a !acro. 'ny !acro de&nition (i.e. fro! a line beginning def to a line beginning end) is
converted to the SM for! (i.e. `Hs' not `^s') and de&ned. #e co!!ands (*@@C(J"
BSJ*=R'M" LMJS" and P*@JS are converted to LMJS . y" and so forth. CRR*R:'R"
C(*L7M@" and 9@,*9S are also converted. RC', *L, will fail if the Mongo &le contains
abbreviations such as .c for ;(*L7M@" then your only hope is to de&ne the sa!e abbreviations.
n !any cases this will have already been done" for instance !c e.pands to read ! . (o!!ents
(beginning a) are optionally converted to standard SM ^ co!!ents (depending on how the &le
`read_old.c' was co!piled.)
@ote that it is advisable to convert these old Mongo !acro &les to SM !acros" to enable you to
take advantage of SMDs features. Iou can do this by si!ply using RC', *L, to read the! into
SM" and then M'(R* 9RJC or S'8C to write the converted !acro out to disk.
#ere is also a !acro e/uivalent of the old 09?L co!!and.
input " 77 read and e!ecute a =ongo Dnot 1=) file
:,8+ 5-+ _temp H"
_temp
=83:5 _temp +,-,,
4he compatibility macro
#is version of co!patibility is !ore co!plete than in pre%version - SM" it also conKicts !ore
strongly with nor!al SM operations.
#e !acro compatibility de&nes !i!ics for the Mongo co!!ands which assu!e that the
only vectors are ! and y. 9e strongly reco!!end that you do not use this !acroa f you want to
use it anyway" co!!ands like limits alpha beta will give synta. errors. Iou can turn
co!patibility !ode oU again with compatibility .. #e !acro itself is a litle co!plicated" it
turns oU the special !eaning of (e.g.) limits" and replaces it with a !acro that reproduces the
old behaviour" in this case -0=01 ! y. #e new de&nitions are in the &le `compatible' in
the default !acro directory" as speci&ed in your `.sm' &le. 't the ti!e of writing" the co!!ands
connect" errorbar" histogram" limits" list" points" read" and window are
rede&ned to reproduce the old synta.. n addition" help is de&ned to not appear on your history
buUer" and define is de&ned to create !acros interactively. Iou !ight also be interested in
other rede&nitions of co!!ands (e.g. list to !ean list the playback buUer)" if so look at
YoverloadingD in the inde.. t should be clear that this set of de&nitions could thoroughly confuse
SM if you try to take advantage of its featuresO in the real! of co!patibility !ode" it is strictly
caveat emptor.
compatible "" 77 define macros to be compatible with =ongo
7 0f the argument is non-\ero or omitted>
7 compatibility mode is turned on.
7 note that some of these ma/e it hard to use regular 1=W
ifDHV" BB .) ;
compatible "
:,L:9
<
ifDH" BB .) ;
=83:5 +,-,, NHWmacroNcompatible
<
S5:,83G w ; connect define errorbar help histogram limits M
list points read window write < ;
52,:-58+ Hw H"
<
ifDH") ;
=83:5 :,8+ NHWmacroNcompatible
<
7 1o newline will end 0S statement
SM2s 'onts
#ese are a sub%set of the well%known Bershey fonts(5X) and the available characters are listed in
the following table" which were generated fro! within SM by saying load fonts fonts.
Qor details on SMDs i!ple!entation of Je; and the YtraditionalD style see the section in the !ain
body of this !anual (see section ,rawing Labels and SMDs Je; C!ulation).
#e characters in a font are speci&ed using a progra!!e read_fonts which you can use to
!ake binary font &les fro! the list of Bershey characters" using an inde. &le to specify what
character should go where. #e binary fonts &le also speci&es which Je; Yde&nitionsD are
available (e.g. Malpha). #e &rst > bytes of the &le are an integer (in binary) that speci&es the
for!at of the &leO when the for!at is changed in an inco!patible way this nu!ber if changed and
you will have to rebuild your font &les (Y!ake fontsD).
#e default font table is illustrated at the end of this appendi.. 9hich font &le you want to use is
speci&ed as the fonts entry in your `.sm' &le.(5F). #e fonts.bin fonts have been cleaned
up a bit for version -.? of SM" although the order of characters in the greek and ro!an fonts is
unchanged. #ere is a new font" Y*ld CnglishD or \o or \oe" and a good nu!ber of new characters
are provided. @either of these fonts supports the YprivateD fonts" that is there in case users
desperately need so!ething" when they can !ake their own binary font &le. Qor e.a!ple" there is
a set of Bershey oriental fonts that can be used to help SM write Vapanese (see section 7sing SM
to write Vapanese).
#e co!plete list of (occidental) Bershey characters is given in a &le called hershey_oc.dat"
and is in the public do!ain. Cach character is speci&ed by a nu!ber in the &rst G colu!ns" then a
nu!ber of strokes in the ne.t 5" then pairs of leters in the re!aining colu!ns up to F-" and in as
!any F- character lines as are needed. ('nnoyingly" if a line consists of e.actly F- characters" the
ne.t !ust be le) blank). Cach pair of characters consists of a coordinate" with the origin at (R"R)"
and the y a.is pointing down. ' Y D indicates that the ne.t point is a !ove" otherwise 4ust connect
the dots. #e very &rst pair is diUerent" as it speci&es the le) and right spacing for the character. f
this isnDt clear" try drawing a few characters on graph paper" character -??< (ro!an ') for
e.a!ple. #ere are a few characters that have traditionally been available in Mongo that are not
in the Bershey set" these have been added to the end of the `hershey_oc.dat' &le" plus a few
that we thought deserved adding.
f you want to create your own characters" the !acro ma/e_char in `fonts' (i.e. load
fonts ma/e_char) !ight help. t uses the cursor to !ake a string that is (nearly) in the
correct for! for inclusion in `hershey_oc.dat'
#e progra!!e read_fonts reads this &le" an Yinde.D &le that speci&es the characters to be put
into the fonts" and a list of Je; de&nitions. #e inde. &le consists of character nu!bers" or ranges
consisting of two nu!bers separated by a !inus sign. (o!!ents go fro! the character ^ to end
of line. Cach font consists of HX characters in ascii order" and fonts appear in the inde. in the order
r!" gr" sc" ti" oe" and then the various private fonts (private'" private:" ..." private=.). Iou can also
use cat_fonts to concatenate binary font &les prepared with read_fonts.
#e for!at of the Je; de&nition &le is that each de&nition has a line to itself" lines starting with a
^ are co!!ents. ' line consists of a na!e" so!e whitespace" the nu!ber of argu!ents (optional"
defaults to Sero)" the na!e of the font to use" a single white%space character" and the value of the
de&nition to the end of the lineO you can continue onto another line by puting a M at the end of
the line. Iou can use any of the nor!al font speci&cations" or cu which !eans use the current
font.
Qor e.a!ple
alpha gr a
alsoalpha . cu Mgr a
alphatoo " gr M7"a
de&nes Malpha the conventional way as the character a in the greek font" then de&nes
alsoalpha in a less e2cient way (by specifying the current font" then e.plicitly switching to
greek)" then de&nes alphatoo as a large " used as Malphatoo*. #ereDs no reason why your
de&nitions canDt be reasonably co!plicated" see for e.a!ple the de&nition of Me6.
f the nu!ber of argu!ents is given as j< the Je; sy!bol will be interpreted as an alias for the
speci&ed font" for e.a!ple the Je; de&nition &le begins
/ata/ana -" private8
hiragana -" private4
to !ake M/ata/ana change to the private8 font.
#e !ain Make&le prepares your binary font &le for you. #ere is also a progra!!e cat_fonts
that can be used to concatenate two or !ore binary fonts &lesO an e.a!ple is given in the section
on Vapanese fonts (section 7sing SM to write Vapanese).
t is also possible to build SM fonts for other languages$
Vapanese$ 7sing SM to write Vapanese
<sing SM to write ?apanese
SM is currently able to use either katakana or hiragana fonts" but no kan4i are yet supported. #e
order of characters in the fonts is likely to change" based on the desires of the users. Please let !e
know what you want.
's distributed" the Vapanese font tables arenDt built. Jo !ake the!" say ma/e Xfonts.bin in
the toplevel SM directory" and ensure that your `.sm' &le sets fonts correctly. #e Vapanese
characters are available as Mhiragana and M/ata/ana. Iou can list the characters available
with load fonts Xe6_fonts.
*ne /uestion is whether M/ata/ana # should print an 'rabic (western) or a Vapanese twoO a!
open to suggestions.
#ere are a variety of kan4i characters present" but no easy way to select the!. f so!eone would
like to donate a table of the correspondence between so!e accepted ascii encoding and the
available characters" will ensure that the character encoded as 84 os available as (say)
M/anXi84" and provide a progra!!e to generate such codes fro! the output of at least one
popular word processor" e.pecting the user to cut%and%paste the result. *f course" itDd be /uicker if
you did it for !ea
;eneral 5nde+
#ere is a separate inde. for graphcap capabilities" see section nde. to =raphcap (apabilities.
-
.s!
.s! concatenating values with 1
.s! o!iting your b+.s!
.s! search path
.s! stopping search for a variable with L
.s! using so!eone elseDs
.s!" background
.s!" default]font" .s!" default]font
.s!" de&ning variables
.s!" &le]type
.s!" fonts" .s!" fonts
.s!" foreground
.s!" graphcap
.s!" help
.s!" history
.s!" history &le
.s!" history]char
.s!" !acros
.s!" na!e
.s!" overload
.s!" PR@JCR
.s!" printer
.s!" pro!pt
.s!" pro!pt-
.s!" raise]on]erase
.s!" re!e!ber]history]line
.s!" save]&le
.s!" SBCLL
.s!" speci&ed on co!!and line
.s!" tabsiSe" .s!" tabsiSe
.s!" ter!
.s!" Je;]strings
.s!" traceback
.s!" tybaud
2
-%di!ensional graphics
-%di!ensional graphics" contour
-%di!ensional graphics" contour levels
-%di!ensional graphics" cross section
-%di!ensional graphics" dither
-%di!ensional graphics" &le for!at
-%di!ensional graphics" &le]type
-%di!ensional graphics" i!age
-%di!ensional graphics" !anipulating
-dhistogra!" -%d histogra! fro! i!age
@
5:< device driver
a
abort" catching errors
aborting a co!!and
aborting a plot
aitoU" convert l"b to 'itoU ."y
aitoU<" convert l"b to reverse 'itoU ."y
aitoUdec" ,raw line of constant dec
aitoUdec<" draw line of constant dec
aitoUgrid" 'itoU e/ual area grid
aitoUgrid<" rev. 'itoU e/ual area grid
alphanu!eric" see ter!inal
apropos" e.a!ples
arc" arclength along curve
arith!etic operators
arrow" draw arrow with cursor
ascii labels
a.es" drawing" a.es" drawing
a.es" font used
a.es" grid
a.es" label for!at
a.es" logarith!ic
a.es" tick spacing
b
barhist" draw bar histogra!
batch" run the history buUer
batch" running SM in
bell" ring bell
bindings" na!es of operators
binning" see histogra!
bisonDs copyright notice
borland graphics
bo.it" draw bo. with cursor
break" e.iting while loops
c
( interface to SM
caching the read pointer" caching the read pointer
calc" evaluate an e.pression
calc]lb" &nd r" l" b given ." y" S
calling SM
calling SM" -%, e.a!ple
calling SM" -%, function de&nitions
calling SM" e.a!ple
calling SM" function de&nitions
calling SM" Libraries
case sensitivity
cat]fonts
cd" change directories
cgauss" cu!ulated =aussian
changing directory" changing directory
changing key bindings
changing !eanings of co!!ands
character siSe
chis/" return chi[- distribution of vector
circle" draw a circle
circle]e.clude" draw e.cluded regions
circlelabel" ,raw a.es for a circleplot
circleplot" redshi) points in circleplot
classifying strings
color" graphcap entry
color" see also ctype
color" used in ploting
colors" add !ore na!es
colour" graphcap entry
colour" see also ctype
colour" used in ploting
colours" add !ore na!es
co!!and history
co!!and line" %f and %u options ignored
co!!and line" co!!ands
co!!and line" environ!ent &le
co!!and line" log&le
co!!and line" !acro &les
co!!and line" no startup !acro
co!!and line" other user
co!!and line" /uiet
co!!and line" specifying .s! &le
co!!and line" stupid
co!!and line" suppress echo
co!!and line" verbose
co!!and line" version nu!ber
co!!ents in data &les
co!!ents in !acros
co!!ents" in !acro &les
co!patibility with Mongo
co!patible" !acros co!patible with Mongo
concatenate" concatenate
continuing long lines
cover" draw the cover
ctype" e.a!ple of seting -GX colours
ctype" geting values and na!es
cu!ulate" &nd cu!ulative distribution
cunifor!" cu!ulated unifor! distribution
current directory" current directory
cursor" graphcap
custo!ising SM
d
da" set data &le
declare" declare a vector E<
default argu!ents for ,C8(C
default]font
del" delete last co!!and
del<" donDt save on history
delete" !acros
dev" set device
device" adding new ones" device" adding new ones
device" borland
device" nodevice
device" postscript
device" saving output to a &le
device" sgi
device" stdgraph
device" sunview
device" sunwindows
device" 7ni. P(
device" ;windows
diagnostics" verbose
do loops
do" avoiding do loops
do" foreach" and if" i!ple!entation
double precision
double /uote
draw]arrow" draw an arrow
draw]bo." draw a bo.
draw]3S" ,raw a cu!ulated curve
drawing ticks outside the bo.
e
C" (o!plete elliptic integral
echo" write to ter!inal
ecolu!n" !ake error]col error vector
ed" edit a !acro
edit" bindings" edit" bindings" edit" bindings
edit" co!!ands
edit" cursor being weird
edit" editing a !acro
edit" escaping
edit" history
edit" na!es of operators
edit" padding
edit" siSe of screen
edit" ter!type" edit" ter!type
edit]all" edit history buUer
e!acs]all" edit history w. syste! editor.
end" /uit
entropy" &nd entropy of an i!age
environ!ent &le" see .s!
e/gal" convert (ra" dec) to (l"b).
e/uality
era" erase screen
erase" erasing lines
erase" raises window
erfc" calculate erfc
error]handler" Bandle interrupts
error]." draw .%error bars
error]y" draw y%error bars
errors" handler for
e.a!ple" calling -%, SM
e.a!ple" calling SM
e.a!ples" apropos
e.a!ples" basic
e.a!ples" &lecap
e.a!ples" !acros" e.a!ples" !acros
e.a!ples" parabola
e.ecute" read and e.ecute co!!ands
e.iting SM" /uit
e.pand" line style
e.tend]history" C.tend history buUer
e.tending history buUer
f
factorial" calculate a factorial
l" see !acro &le fourier
&le]type
&lecap" de&nition
&nd !ean sig!a ...
QJS" &le]type
Koats as words
fonts" .s!" fonts" .s!
fonts" available characters
fonts" choice
fonts" draw the font table
fonts" hardware character sets
for" (Ds for(OO) (see also while)
foreach loops
foreach" ele!ent in a vector
fortran interface to SM
fresnel" Qresnel integrals
g
gale/" (onvert (l"b) to (ra" dec)
galgrid" Puts up e/ual area grid
galplot" 7sage$ galplot ra dec l b
galpoints" points on an e/ual area grid
ga!!a" ga!!a correct an i!age
gauss" evaluate a =aussian
gauss" evaluate =aussian
gauss]convolve" convolve - =aussians
gaussdev" !ake @(?"<) variate
get" Read colu!n fro! &le
=@ ter!inators" =@ ter!inators
glevels" Set grey levels
glossary
good advice
good ideas
gra!!ar tokens
gra!!ar" e.a!ples
gra!!ar" variables
gra!!ar" verbose debugging
graphcap" .s!
graphcap" adding a local device
graphcap" co!piling
graphcap" description
graphcap" entering nul
graphcap" inde.
graphcap" !odifying an entry
graphcap" overriding on co!!and line
graphcap" overriding with private &le
graphcap" raster devices
graphcap" search path
graphcap" writing a new entry
grey]sincos" draw a grey scale i!age
greyscale" ,raw grey%scale i!age.
gripe" co!plain to Robert
gstrans" supergalactic to galactic coords
guters between windows
h
handler" see errors
hardcopy
hardcopy" close old device
hardcopy" e.a!ple
hardcopy" using a !eta&le
hcopy" hardcopy of playback buUer
head" print the top of a &le
help
help (see also apropos)
help" .s!
help" !acros
help" variable
help" vector
he!iconvert" l b to . y for he!isphere
he!idec" line of dec on he!ispheres
he!iplot" e/ual area plot" two he!ispheres
hist]e/ualise" histogra! e/ualise an i!age
histogra!" binned fro! vector" histogra!" binned fro! vector
history" changing character
history" converting to a !acro
history" deleting co!!ands
history" editor
history" e.tending buUer
history" introduction
history" listing
history" listing backwards
history" nu!ber re!e!bered
history" re%using co!!ands
history" reading fro! a !acro
h!" help with edited !acro
h!acro" hardcopy of !acro
hv" help with variable
i
+* co!!ands" data
?" Modi&ed :essel function
<" Modi&ed :essel function
identi&cation" write id to plot
if state!ents
i!age variables" listing
M'=C" converting too and fro! vectors
M'=C" de&ning header values
M'=C" headers
M'=C" !anipulating
M'=C" writing out
i!ages" !ade fro! vectors.
info" help fro! info
initialisation" see startup
input character processing
input" e.ecute an Mongo &le
insert" insert te.t a)er line
integer vectors" reading
internal variable" label]oUset
internal variables" accessing
internal variables" angle
internal variables" aspect
internal variables" ctype
internal variables" date
internal variables" e.it]status
internal variables" e.pand
internal variables" f.<" f.-" fy<" fy-
internal variables" g.<" g.-" gy<" gy-
internal variables" listing
internal variables" ltype
internal variables" lweight
internal variables" n.
internal variables" ny
internal variables" ptype
internal variables" sdepth sheight slength
internal variables" u.p"uyp
internal variables" verbose
internal variables" .p"yp
interp" linearily interpolate
interp-" linearily interpolate
interrupts
invaitoU" convert 'itoU ." y to l" b
irregular]i!age" Set M'=C fro! ."y and S
is]&le" does &le e.istT
is]!acro" is a na!e a !acroT
is]set" is a bit setT
is]vector" is a na!e a vectorT
A
V?" :essel function
V<" :essel function
(
3" (o!plete elliptic integral
3?" Modi&ed :essel function
3<" Modi&ed :essel function
key bindings" changing
key" de&ning keyboard !acro
l
labels partly in diUerent fonts
labels" aspect ratio
labels" identi&cation
labels" partly in diUerent fonts
landscape plots
line drawing on a new device
line drawing" colours
line drawing" line style
line drawing" line weight
lin&t" least s/uares &t for n para!eters
lis" list history
listing variables
listing" key bindings
listing" !acros
listing" vectors
load" load !acros
load-" load user !acros
local" variables
local" variables and vectors
local" vectors
log]fac" calculate a log factorial
logarith!ic" a.es
logarith!ic" geting nice a.es
logerr" logarith!ic error bars
logical and
logical or
long lines" continuing
loops
lost co!!ands" lost co!!ands
ls" list !acros
ls!" list !acros in a default &le
ls/" least s/uares &t
ls/-" least s/uares &t
lsv" list variables
m
!acro" variable nu!ber of argu!ents
!acros" .s!
!acros" argu!ents
!acros" co!!ents
!acros" de&ning
!acros" deletion
!acros" disk for!at
!acros" editing
!acros" error handler
!acros" error]handler
!acros" e.a!ples" !acros" e.a!ples
!acros" fro! history list
!acros" help" !acros" help
!acros" i!ple!entation
!acros" introduction
!acros" libraries
!acros" listing" !acros" listing" !acros" listing
!acros" not found
!acros" not listing
!acros" read rest of line
!acros" reading fro! disk
!acros" returning fro!
!acros" saving
!acros" saving to disk
!acros" tail recursion
!acros" to history list
!acros" traceback
!acros" unde&ning sets
!acros" usage
!acros" useful
!acros" variable nu!ber of argu!ents
!acros" writing to disk
!add" add !atrices
!ake]char" help create new char
!atri." ntroduction to !atri. utilities
!concat" (oncatenate - !acros
!declare" declare a s/uare !atri.
!di!en" print a !atri.Ds di!ension
Meta&les
!eta&les" playing back.
!inv" invert a !atri.
!!ult" !ultiply a !atri. by a !atri.
!!ult]c" !ultiply a !atri. by a constant
!!ult]v" !ultiply a !atri. by a vector
!!ult]vJ" !ultiply vector[J by a !atri.
!odifying a graphcap entry
!ongo" !ake SM rese!ble Mongo
!ouse butons
!print" print a !atri.
!set" set a !atri. e/ual to another
!trans" transpose a !atri.
n
@a@
noclobber" and tables
nu!ber" as a string
nu!ber" convert strings to nu!bers
nu!bers as words
o
overload
p
paging through lists
pairs" connect (.<"y<) to (.-"y-)
panic save &le
parenthesised e.pression
peculiarities of the gra!!ar
pielabel" ,raw a.es for a redshi) pieplot
pieplot" Plot redshi)s in pieplot
plot !acros
plot !acros" writing to history list
plot siSe" how to change
plot siSe" plot window
plot" aborting
ploting devices" see device
p!atri." print the !atri. E<
points" ploting
points" siSe
polar" draw Ya.isD for polar coords
porting to new !achines
portrait plots
postscript graphics
precedence of arith!etical operators
precedence of string operators
precedence" logical operators
private initialisation
prob]chis/" probabilities for chi[-
prob]3S" probabilities for 3%S
prob]wilc" probability for 9ilco.on
pro!pt" suppressing
puts" ,raw a line of te.t

/" check" then /uit

/!inv" Rick !atri. inversion
/uit
/uoting" 6double /uotes6
/uoting" Dsingle /uotesD
/uoting" Mangle bracketsN
/uoting" _curly bracketsZ
r
radtick" put tick !arks on a radial a.is
raising windows
Rando! nu!bers" seting seed
raster" adding new devices
raster" graphcap support
raster" writing data in he.
rasterise" description
R,`he.
read" !acro
read" table
read]all" read &le including history
read]fonts
read]hist" read history fro! &le
read]old" read an Mongo &le
reading na!ed vectors
reading vectors fro! !any colu!ns
repeated" &nd repeated ele!ents
Reporting :ugs
Re/uesting Qeatures
reset]ctype" Reset the default ctypes
restore
reverse" reverse a vector
r.y" Pearson (orrelation (oe2cient
s
sav" save to a &le E<
save
save]all" write history to &le
save]read]ptr" save]read]ptr
save]vec" save a vector on history
saving device output to a &le
scaling" line style
scope" restriction for variables
scope" restriction for vectors" scope" restriction for vectors
screen" see ter!inal
scrolling" graph disappears oU screen
set]window" cycle through all 9@,*9s
sgi graphics
sgtrans" galactic to supergalactic coords
shade surprises
shade]bo." shade a bo.
shading regions
shell escape
show" show current values
si!p" Si!pson integration
single /uote
s!irnov<" < sided 3%S statistic
s!irnov-" - sided 3%S statistic
s!ooth" bo.car s!ooth
s!ooth-" s!ooth a vector
s!ooth5" s!ooth a vector (o!iting points)
SMP'JB variable
spacing between windows
spear" Spear!an correlation coe2cient
special characters" a
special characters" 6
special characters" ^" special characters" ^
special characters" E
special characters" D
special characters" gh
special characters" \
special characters" [
special characters" arith!etic
special sy!bols" ploting
startup !acros
startup" co!!and line
startup" default !acro
startup" history &le
startup" !acros
startup" private !acros
startup" startup !acro
startup" syste! initialisation !acro
startup-" private startup !acro
stats" calculate !ean sig!a ...
stats]!ed" &nd !edian SAR
string operators
string vectors into variables
string vectors" declaring
string vectors" if tests
string vectors" ptypes
string vectors" reading
string vectors" seting ele!ents
strings" preserving /uotes
strings" printing
strings" printing for!ated
sun cursor
sun" device drivers
sundial" draw a sundial
sunview graphics
sunwindows graphics
synta. error
synta. error" deliberate
synta. error" tracking down
t
table" for!ats
table" @a@s
tables" reading
tables" writing
ter!cap" description of &le
ter!cap" used by ter!type
ter!inals" description for SM
ter!inals" graph scrolling oU screen
ter!inals" seting ter!inal type
ter!inals" specifying screen siSe
ter!type
Je;" caveats
Je;" de&nitions
Je;" e.tensions
Je;" using in labels
Je;]defs" draw 6Je;6 defs
te.t ploting" aspect ratio
thin" !ake sparse version of a vector
thin-" 6thin6 the end of a vector
thin5" 6thin6 central portion of a vector
toplabel" put label at top of plot
traceback on error
trigrid" nterpolate to the regular grid
trigridtry" ,e!onstrate the use of trigrid
u
undef" unde&ne a variable
unde&ning variables
undo" erase lines
uni/" re!ove duplicates fro! a vector
7ni.%P( device driver
unload" forget !acros
unset" delete a vector
upc device driver
upper" get Yupper li!itD sy!bol
uppercase" !aking SM understand
user abort" catching
v
variables fro! keyboard
variables" accessing internal" variables" accessing internal
variables" are not vectors
variables" concatenation
variables" de&ning
variables" deletion
variables" forcing e.pansion
variables" fro! .s!
variables" fro! data &les
variables" fro! internal values
variables" help
variables" introduction
variables" listing" variables" listing
variables" local" variables" local
variables" !list
variables" saving to disk
variables" special values
variables" synta.
variables" te!porary
variables" testing if de&ned
variables" use
variables" within double /uotes
vec!in!a." !in. and !a.. of vector
vector &eld
vectors" are not variables
vectors" arith!etic
vectors" assign!ent
vectors" concatenating
vectors" conditional assign!ent
vectors" converting string to arith!etic
vectors" declaring
vectors" de&ning
vectors" e.a!ples
vectors" e.tract histogra!
vectors" help" vectors" help
vectors" introduction
vectors" listing
vectors" local" vectors" local
vectors" !acro as function
vectors" operators
vectors" printing
vectors" saving to disk
vectors" sorting
vectors" specifying types
vectors" spline &ting
vectors" string
verbose" variables
v&eld" plot a vector &eld
v&eld-" plot a vector &eld (.%units)
v&eld5" plot a vector &eld (y%units)
v&eld>" 8ector &eld v. vy at ." y
v&eldG" Scaled 8ector &eld v. vy at ." y
8MS" ,(L escape
8MS" foreign co!!and
8MS" keybindings" 8MS" keybindings
8MS" na!es of callable functions
8MS" /uotas
8MS" spawned processes
vprint" print a vector (like !print)
w
weird" alpha cursor being" weird" alpha cursor being
weird" behaviour of alpha cursor
weird" behaviour of keys" weird" behaviour of keys
weird" (anDt enter superscripts
weird" canDt get pro!pt" weird" canDt get pro!pt
weird" co!!ands !isbehave
weird" co!!ands rede&ned
weird" delete in foreach
weird" graphcap eats a \5FF
weird" local vector doesnDt e.ist" weird" local vector doesnDt e.ist
weird" losing ends of !acros
weird" losing hardcopies
weird" lost argu!ents to !acros
weird" lost co!!ands
weird" variable nu!ber of !acro argu!ents
weird" wonDt plot log a.es
weird" wrong local variable
weird" wrong local vector" weird" wrong local vector
weird" wrong !acro in !essage
while loops" while loops
while loops" e.iting
wilco.on" 9ilco.on statistic
wls/" weighted least s/uares
write" !acro
write" table
write" to a &le
write" to the ter!inal
writing vectors to a &le
writing vectors to the screen
+
;<?" device driver
;<<" device driver
.colu!n" read a colu!n into .
.logarith!" take log of .
;windows device drivers
.windows device drivers
;windows graphics
y
I?" :essel function
I<" :essel function
ycolu!n" read a colu!n into y
ylogarith!" take log of vector y
"ommand 5nde+
?
T$
a
'bort
'bs
'cos
'nd
'ngle
'propos
'rith!etic
'sin
'spect
'tan
'tan-
'tof
'.is
b
:o.
:reak
c
(hdir
(oncat
(onnect
(ontour
(os
(type
(ursor
d
,ata
de&ne
,elete
,evice
,i!en
,ither
,o
,ot
,raw
e
Cdit
Cnviron!ent 8ariables
Crase
Crrorbar
C.p
C.pand
f
QQJ
Qloat
Qoreach
Qor!at
g
=a!!a
=rid
h
Belp
Bistogra!" Bistogra!
Bistory
i
denti&cation
f
!age" !age
nde.
nt
(
3ey
l
Label
Label for!at
Length
Levels
Lg
Lines
Listing
Ln
local
Location
Logical operators
Ltype
Lweight
m
Macro
Meta
Min!a.
o
*r
*verload
p
Page
Plot li!its
Point style
Points
Print
Pro!pt
Putlabel

Rit
r
Rando!
Range
Read
Reading fro! a &le
Relocate
Return
s
Save
Set
Shade
Show
Sin
Sort" Sort
Spline
Sprintf
S/rt
String" String
Strlen
Substr
Su!
Surface
t
Jable
Jan
Jer!type
Je; strings
JicksiSe
u
7ser
v
8erbose
8ersion
8iewpoint
w
9hatis
9hile
9indow
9rite
+
;label
y
Ilabel
'ootnotes
1/3
#ere is a !acro era de&ned as +,-,, G015:@ ,:81, that wouldnDt have appeared on the
list in the &rst place" si!ilarly lis is like G015:@ but wonDt appear on the list of co!!ands. 's
an alternative" you can use the !acro set_overload to !ake lowercase erase the sa!e as
+,-,, G015:@ erase" along with a nu!ber of other changes. #is could be confusing for
neophytesa See 6overloading6
123
t is usually easier to use SMDs editor to create !acros" try ed square or read on.
1@3
or q which is a !acro de&ned as +,-,, G015:@ KL0. #is will e.it SM 4ust the sa!e" but
the quit wonDt appear on your history list" waiting to be playedback accidently. 'ctually" q will
/uery you before /uiting
1.3
f you are using 8MS" you !ay prefer to use control-@ as your interrupt character. ' suitable
set of key de&nitions is in a &le called maps_vms.dat in the top SM directory. t !ay be read
with the :,8+ ,+0 co!!and (see section (hanging 3ey%:indings)" and this !ay be done
auto!atically in your startup !acro by the variable edit in your `.sm' &le.
1B3
n fact you can rebind any character to replace I" see section (o!!and Bistory
103
7nder 8MS" SM !ust have been installed as a foreign co!!and for this to work" and it !ust not
have been linked with the debugger
1C3
*ccasionally a M(RN is re/uired by SM" so puting two co!!ands on one line will give a synta.
error. #e cause is the way that the gra!!ar is writen (see section #e (o!!and nterpreter)"
the &. is either to use two lines" or else to put an e.plicit carriage return at the appropriate point
with a \n
1D3
II and IH really do get back the last co!!and typed" even if it isnDt on the history list. f you
want the last re!e!bered co!!and" use up%arrow or I?
1E3
#e &rst of these co!!ands in a SM session !ay be rather slow under 8MS" as we have to spawn
a subprocess.
1/F3
7nfortunately" this is currently not available to 8MS users
1//3
unless you have been playing with 52,:-58+
1/23
More accurately" by specifying two or !ore digitsO see section Macro for !ore details and
e.a!ples
1/@3
usuallyO this !ay not be available on 7ni. Syste! 8 and 8MS syste!s.
1/.3
you !ight prefer to use the !acro ed which is e/uivalent to =83:5 ,+0" but doesnDt appear
on the history list and" if invoked without a !acro na!e" will edit the sa!e !acro as last ti!e. n
addition" you can list the current !acro with hm.
1/B3
#is was the only way before the days of 9BLC loops (see section 9hile)" and as the techni/ue
is interesting" weDve kept this section in the !anual
1/03
well" to be honest the L*('L co!!andDs a recent addition to SM so there are lots of !acros out
there that donDt do this
1/C3
'ctually" if the environ!ent (8MS$ logical) `.sm' variable ?:09,: is de&ned the !acros
pretend that it was the &rst argu!ent" so you can si!ply type hcopy.
1/D3
#e _Z turn oU all e.pansions" so hi is de&ned to be RNHWD'Gello')N JorldT. #e state!ent
de&ning hello then beco!es +,S09, hello RNHWD'Gello')N JorldT" and the YaD
ensures that the e.pression 'Gello' is evaluated and substitutedO 'Gello' is a string valued
vector" ad!itedly with only one ele!ent" so it evaluates to the &ve characters YBelloD and the
state!ent beco!es +,S09, hello RGello JorldT which !eans that hello is de&ned as
Gello Jorld. 'part fro! being a red herring" the colons are only there to !ake it easy to see
which variable e.pands to what.
1/E3
,ue to a 8MS RJL bug" this co!!and is not available on all 8MS syste!s.
12F3
#is isnDt actually the preferred way to create a postscript &leO itDs beter to use a specialised device
such as postfile (see section ,evice)" or at least to say device postscript N:1@Bmv
HS foo.ps:N (see section ,evice).
12/3
See discussion of double /uotes in see section 9hat Rotes 9hat 9hen if you want to know
why.
1223
Iou are not allowed to use co!!as in such a list" so set !B;"> #> &> $ < !akes ! a string
vectorO but set !BatofD!) soon &.es that (or say set !BatofD;"> #> &> $ <) in the
&rst place). Iou can use inde! and substr to achieve the sa!e result for truly string%valued
vectors.
12@3
you can o)en do beter with a V: or 1, J5:+Ye!prQ B e!pr co!!and
12.3
#e gra!!ar is actually speci&ed using I'((" see S.(. Vohnson =311( =et 3nother 1ompiler
1ompiler" (o!puting Science Jechnical Report @o. 5-" <HFG" 'JkJ :ell laboratories" Murray Bill"
@V?FHF>. #is report is reprinted in section -b of the 7@; !anual" and is rather di2cult reading
at &rst. 9e do not in fact use the 'JkJ code" which is proprietary" but rather a public do!ain
co!piler%co!piler called :ison writen by the Qree So)ware Qoundation.
12B3
Specifying -s on the co!!and line bypasses all of this" and !akes SM read input one line at a
ti!e.
1203
i.e. tokens that have been recognised" typically keywords
12C3
=raphics +* ,esign" ,oug Jody" March <HWG. @*'* (3it Peak)
12D3
'ctually" SM always uses cursor <
12E3
n counting characters for 4u!ps" the O is at character ? and co!binations such as [@ count as one
character
1@F3
f the R( string is given as prompt" then you will be pro!pted for the key you would have hit"
and the (."y) position the cursor would have been at" if the ter!inal that you were using could
support a cursor.
1@/3
n looking for the graphcap &le" any environ!ent &le or search path speci&ed on the SM
co!!and line with a -f or -u Kag is ignored.
1@23
7nder 7ni. the loader can o)en distinguish fortran fro! (" so you !ay not need the YfD %% call
sm_limitsD...>"..>...>"..)
1@@3
in fact they will be read fro! a !acro or the co!!and line without pro!pting if they are
availableO try define file_type no_header image file Mn ". #.
1@.3
#e usual reference is 9ells" ,.(." et al. 'stron. 'stroph. Suppl" %% 5X5 (<HW<)" although QJS is in
fact beco!ing a national standard in the 7S
1@B3
f the +2 entry contains an e!bedded space" only the &rst word is used to choose a deviceO the
rest is treated as if it was typed as part of a ,C8(C co!!and. Qor e.a!ple" if the graphcap &le
contains the entry svga$Usvgalib> mode $:+2Bsvgalib -m $:" the co!!and
+,203, svga$ is e/uivalent to +,203, svga -m $.
1@03
created by ,r. '. 8. Bershey at the 7. S. @ational :ureau of Standards and illustrated in @ational
:ureau of Standards publication @:S SP%->. #e for!at used in the hershey]oc.dat &le was
originally due to Va!es Burt at (ognition" nc." H?? Jechnology Park ,rive" :illerica" M' ?<W-<. t
!ay be converted to any for!at e)cept the for!at distributed by the 7. S. @JS (whatever it !ay
be). 9e have to tell you all this for copyright reasons" but as distributed the fonts are in the public
do!ain.
1@C3
tDs possible to resurrect the font table used by pre%-.? versions of SM" using the inde. &le
`old_font_inde!'
#is docu!ent was generated on W Septe!ber -?<< using the dMd translator version dd.
4he SM 4utorial
by Robert Lupton and Patricia Monger
4able of "ontents
9hat is SMT
Bow should get data into SMT
Bow do generate a basic plot for data in a &leT
9hat do have to do to start up SMT
Bow do de&ne variables" and how can use the!T
9hat is a plot !acro" and how do !ake oneT
Bow do save !acrosT
Bow do get a hardcopy of a plotT
9hat about -%di!ensional dataT
9hat are the other co!!on co!!andsT
9hat are (o!!on Crrors" and 9hat Should ,oT
9here do go fro! hereT
What is SM?
SM is an interactive ploting package for drawing graphs. t does have so!e capability to handle
i!age data" but !ostly works with vectors. #e !ain features of the package are that one can
generate a nice looking plot with a !ini!u! nu!ber of si!ple co!!ands" that one can view the
plot on the screen and then with a very si!ple set of co!!ands send the sa!e plot to a hardcopy
device" that one can build and save ones own plot subroutines to be invoked with a single
user%de&ned co!!and" that the progra! keeps a history of ones plot co!!ands" which can be
edited and de&ned as a plot subroutine" to be reused" and that one can de&ne the data to be ploted
fro! within the progra!" or read it fro! a si!ple &le.
Iou !ight ask" 69hy do need SMT6" but a! not going to answer you. f you read through this
tutorial" and use the package for a while" and still canDt see why you need it" then you probably
donDt need it.
How should 5 get data into SM?
Plot vectors !ay be generated in several ways$
a.
Iou !ay read the vectors fro! a &le using the read co!!and #e &le is e.pected to be an
'S( &le of colu!ns of nu!bers (separated by spaces" tabs" or co!!as). Iou de&ne the &le
to SM using the data co!!and" and associate a colu!n or row of nu!bers with a SM
vector using the read co!!and. C.a!ple$ Say have a &le na!ed test.dat with the
following data in it$
" # & *.) ".
& ) % #.& ""
* % # (.( "#
( ' $ '.& "&
' & " $.% "$
#en the co!!ands to issue to SM to get the data into the progra! are$
data test.dat
read ! "
read y #
(or read ; ! " y # <). n the last - co!!ands have told SM to read the values in
colu!n < of the &le test.dat" and assign the! to a vector na!ed ." and read the values in
colu!n - of the &le and assign the! to a vector na!ed y. could read any of the other
colu!ns in as well" of course" and assign the! to vectors. 'nd can na!e the vectors
whatever like" as long as the na!e consists of the characters a%S"'%P"?%H" and ]
(underscore). can also read a row fro! the &le" instead of a colu!n" by saying
read row ! "
@ote that the vector is de&ned by the read co!!and. :ut can rede&ne it whenever wish"
and change the siSe. #e only point to re!e!ber is that when you rede&ne the vector" the
old values are overwriten. ' &nal point to note about de&ning vectors fro! &les is that you
can skip over lines in the &le with the lines co!!and. lines de&nes which lines in the
&le you want to read. ' li!itation of lines is that you !ay only de&ne one set of lines to
readO that is" if you had a 5? line &le" and wanted to read lines 5%H and <G%5?" you couldnDt
(well" you could" but youDd have to !ake clever use of the !ethod of de&ning vectors which
is discussed in the ne.t subsection" or !ake lines <?%<> each begin with a ^).
b.
Iou !ay de&ne the vectors within SM using the set co!!and. #is co!!and has a
nu!ber of for!s$
f you 4ust want to de&ne the vector with a list of values" the co!!and is
set numlist B ; # & $ * ) ( % ' #( <
you can also de&ne a vector in ter!s of arith!etic operations on a previously
de&ned vector. Qor e.a!ple" having de&ned nu!list as above"
set ylist B sqrtDnumlist) O numlist/&."
the allowed arith!etic operators are sin> cos> tan> acos> asin> atan>
atan#> abs> int> lg> e!p> ln> sqrt> concat> CC> O> -> C>
and /" where lg is " ln is " int takes the integer part" and concat concatenates
two vectors.
you can de&ne vectors with i!plied do%loops$
set ! B .>?0>?0/")
set y B .>".>.."
(P is a constant de&ned for you by SM" but you can also de&ne your own scalar
variables" as will be described in a later section of this tutorial)
c.
Iou can rede&ne an e)isting vector ele!ent by ele!ent with a do loop$
set y B ">*.
...
do iB.>$' ; set yYHiQ B HiCC# <
(ote Eell that vector ele!ents are nu!bered starting fro! !)
d.
Iou !ay create a vector with the spline co!!and. #is &ts a spline function to a
previously de&ned pair of vectors" and evaluates it at the points given in a third vector" to
produce a fourth vector for you.
set ! B .> # C ?0> ?0/$
set y B sinD!)
set !! B .> # C ?0> ?0/&#
spline ! y !! yy
#is will &t a spline to the curve y vs ." at the points ?" P+5-" P+<X" 5 0 P+5-"... (i.e. the
points in the .. vector)" and the spline values will be stored in the vector yy.
e.
Iou !ay de&ne a vector with the graphics cursor using the cursor co!!and. f you type
the co!!and
cursor a b
then a cursor will be displayed on the screen" and to the spline co!!and. #is will take a
horiSontal slice through the i!age. f you do not give a &lena!e" the vectors are printed to
the ter!inal.
f.
f you want vectors that look properly scienti&c to play with" you !ight &nd that
set !BrandomD"..)
is 4ust what you want.
How do 5 generate a basic plot for data in a
file?
#e procedures listed above describe how to get your data in to SM. #en the steps to ploting it
are as follows$
,e&ne the plot device you want to use with the device co!!and. #e synta. and list of
available devices are described in the !anual (see section Y,eviceD in Te SM Manual).
,eclare the data &le with the data co!!and" see section Bow should get data into SMT"
or you could see section Y,ataD in Te SM Manual. Iou !ight want to use the !acro da
instead" which stops SM worrying about things like H or / in the &lena!e.
Read in the data vectors with the read co!!and" also described previously and in the
!anual.
,e&ne the a.is li!its with the limits co!!and.
,raw the a.es with the bo! co!!and
Plot the data points using the connect co!!and to plot the points as a connected curve"
or the points co!!and to plot the! as points. f you are using connect you can also
de&ne the line type with the ltype co!!and (see section YLtypeD in Te SM Manual). f
you want to plot points" you should &rst de&ne the point style with the ptype co!!and.
ptype allows you to de&ne the point as a type of polygon" with any nu!ber of sides" and
> basic for!s (see section YPtypeD in Te SM Manual). Ptype also allows you to de&ne your
own private sy!bols" or use strings that youDve read fro! a &le.
f you want to label the a.es" use the !label and ylabel co!!ands. SM is able to plot
=reek leters" superscripts and subscripts" !any sorts of sy!bols" and a couple of other
special fonts. #e available fonts are listed in the !anual (see section YQontsD in Te SM
Manual).
Qor e.a!ple" you !ight type$
device !""
echo reading test.dat
data test.dat
read ; ! " y # \ $ <
limits ! y
bo!
connect ! y
ptype ) &
points ! \
!label his is the 6 a!is
ylable his is data plotted against 6
#ere are a nu!ber of other co!!ands that elaborate on this basic set to allow logarith!ic a.es"
labelling curves" puting an , on the plot" reading positions fro! the plot with a cursor"
!anipulating -%, data" and !uch !ore. So!e of these co!!ands are described in this tutorial
(see section 9hat are the other co!!on co!!andsT)O the de&nitive source" however" is in the
real !anual" where all the co!!ands plus their synta. are described.
What do 5 have to do to start up SM?
9ith any luck" your syste! !anager has set up SM so that you can run it by typing a single
co!!and. She should have created a syste! wide &le called an Y`.sm' &leD. Vust in case she was
negligent" or in case you want to overrule so!e of her choices" you can have in addition your own
`.sm' in your ho!e directory. #is &le is used by SM to tell it a nu!ber of things. ' prototype
.sm &le for a 8MS syste! is reproduced below$
device hire\
edit Hdis/:Ysm_dirQmaps.dat
filecap Hdis/:Ysm_dirQfilecap
file_type vms_var
fonts Hdis/:Ysm_dirQfonts.bin
help Hdis/:Ysm_dir.helpQ
history %.
history_file .smhist
graphcap Hdis/:Ysm_dirQgraphcap
macro Hdis/:Ysm_dir.macroQ
macro# Hdis/:Ylupton.smQ
name my_friend
printer qms
temp_dir sysHscratch:
term hire\
termcap Hdis/:Ysm_dirQtermcap
@ow" what is all thisT
device
allows SM to initialiSe a default ploting device for you. f it &nds an entry of this type in
your .sm &le" it will do the call to the device co!!and for you.
edit
is used by SM to &nd out how to !ap the key se/uences used by the !acro and co!!and
line editor. #e only reason you need to change this line is if you decide you want to de&ne
the key se/uences diUerently. Qor e.a!ple" if you invoke the !acro editor ( See section
9hat is a plot !acro" and how do !ake oneT" to &nd out what that !eans)" and want to
edit your !acro and" say" insert a line" to do that you type control-= (hold down the
(JRL key and then press the ! key" or si!ply hit 3arriage :eturn). @ow" if you donDt
like that particular choice of keys" you can set up your own key de&nitions in your own edit
&le" and tell SM to use that instead of the default ones by rede&ning the edit line of the
.sm &le.
filecap
is a &le that tells SM how to read -%di!ensional &les. 's !entioned in section <<" binary
&les vary enor!ously fro! operating syste! to operating syste!" and also depend on the
language of the progra! you wrote to generate the!" so we de&ned a few si!ple &le
for!ats you can use to read binary data into SM" and SM interprets the! via the filecap
&le. Read the !anual if you want to plot -%, data.
file_type
is also for -%, data. #is sets the default &le type for the binary &les. #e types are described
in the !anual (see section YQilecapD in Te SM Manual). #e filecap &le tells SM how to
read data of the given file_type
fonts
#is tells SM where to &nd the font de&nition &le. Iou will al!ost certainly never change
this" but if you have !ade a new font &le you would cause SM to use it instead of the one
we supply by changing this line in your .sm &le.
help
#is tells SM where to &nd the co!!and help &les.
history
#e nu!ber of history co!!ands to re!e!ber (see the ne.t entry).
history_file
SM keeps of history of the co!!ands you used in your SM session in a &le. t reads in the
last history &le when you start it up again" and you can reuse those co!!ands as you wish
(e.g. scroll through the! like with the 8MS co!!and line editor" e.tract a group of
co!!ands into a !acro (see section 9hat is a plot !acro" and how do !ake oneT)" ...). f
you donDt want a history" leave this line blank. *therwise" specify a &lena!e.
graphcap
#is is the &le SM uses to &gure out what !agic co!!ands to send to your plot device to
cause it to go into graphics !ode. 9e have de&ned !any device types" so hopefully the one
you need is already in the default &le. f not" you !ay want a private graphcap.
macro
SM loads a set of default plot !acros for you when you start it up. #is line gives the
location of the default !acro &le.
macro#
Iou can load - default &les if you wish" and this is where you de&ne the second one. Lite!
!acro- is the na!e of a directory where SM e.pects to &nd a &le na!e `default'" in
which are contained SM !acros. Iou should load our default one &rst" for reasons which are
e.plained in the !anual. #e !acro startup# in &le `default' will be e.ecuted.
name
#is is the na!e by which SM will address you when you use it.
printer
#ere is a !acro called `hcopy' that replays the co!!ands used to generate a plot on
your screen and changes the device to a printer to allow you to easily get a hardcopy of
your screen plot. #is line tells SM what printer you want to use. Iou can also get hardcopy
plots !anually (see section Bow do get a hardcopy of a plotT).
temp_dir
Bardcopy plots are writen to a disk &le" and then sub!ited to a print /ueue and deleted.
#is tells SM what directory you want it to write the disk &les to. #ey can be large" so if
you have disk /uota proble!s" temp_dir ought to point to a scratch disk or so!ething
term
SM knows about ter!inals" and uses that knowledge to allow you to do co!!and line
editing. Bere is where you specify what kind of ter!inal you have. @ote this is for `te!t'
onlyO the graphics description is given in the device line at the start of this &le. #e
available ter!inal types are described in the termcap entry.
termcap
#is &le describes ter!inals.
So to run SM" you should have a &le like this in your ho!e directory" with the directory na!es"
etc changed to point to your co!puter and you" and then 4ust run the progra!. f all goes well"
when you invoke the progra!" you will wait a while" and then get the following !essage
Gello> RnameT> please give me a command
where RnameT is as de&ned in the .sm &le name line" and you will get a pro!pt. f this isnDt
what happens" you need to contact the people who installed SM on your syste!.
How do 5 define variables9 and how can 5 use
them?
Scalar variables are de&ned with the define co!!and. 's !entioned above" vectors are de&ned
with the set co!!and. ' variable !ay be a nu!ber" or a character string. Iou !ay use the! in
any SM co!!and" by preceding the na!e of the variable with a E. Qor e.a!ple$
define two_pi ).#%& 7 or define two_pi HD#Cpi)
set !B">"..
do i B .> ..''> .." ;
set !Y"..CHiQ B Hi C Htwo_pi
<
set iB.> ..'' > .."
set !BHtwo_piCi
set y B sinD!)
limits ! y
bo!
define !lab ;my signal<
!label H!lab
ylabel sine
What is a plot macro9 and how do 5 ma(e one?
' plot !acro is a set of co!!ands that you can e.ecute together by invoking the na!e of the
!acroO in eUect" it is a plot subroutine. Qor e.a!ple" suppose you had a set of plots that you
wanted to generate" using the sa!e type of a.is bo. and labels. Rather than laboriously typing the
bo. and label and li!its co!!ands for each set of data" you could de&ne a !acro as follows$
drawbo! 7 this is a comment
limits . #. . "..
bo!
!label !data
ylabel ydata
where the !acro na!e in this e.a!ple is drawbo!. #en" when you access your data" you could
do as follows$
data file".dat
read ; ! " y # <
drawbo!
connect ! y
erase
data file#.dat
read ! &
read y (
drawbo!
connect ! y
(#e read ; ! " y # < is the sa!e as read ! " read y #" but faster). #is is a
si!ple%!inded e.a!ple" and you can i!!ediately see ways to i!prove the !acro have created
to save even !ore typing. Macros !ay consist of any SM co!!ands" and !ay have argu!ents.
Iou specify the nu!ber of argu!ents in the !acro de&nition" and refer to the! by nu!ber"
preceded by E. n the e.a!ple gave above" suppose we wanted to !ake the a.is labels into
variables. #en the !acro de&nition would look like this$
drawbo! # 7 this is also a comment> but not a very useful one
limits . #. . "..
bo!
!label H"
ylabel H#
#en to invoke the !acro" type
drawbo! !data ydata
Iou can !ake a !acro in > ways$
a.
Iou can create it with your favorite editor outside of SM. #e rule to re!e!ber if you do
this is that the na!e of the !acro !ust be the &rst thing on a line of the &le" and should be
followed by SM co!!ands. 'll the co!!ands !ust start in a colu!n in the &le other than
the &rst colu!n. Jo read this !acro into SM" use the macro read co!!and
macro read macro.file
will read all the !acros in the &le macro.file.
b.
Iou can de&ne the !acro within SM by e.tracting a set of co!!ands fro! the history
buUer
macro mname " #.
will e.tract lines < through -? fro! the history buUer" and create the !acro mname which
consists of those -? lines.
c.
Iou can de&ne the !acro within SM with the macro co!!and
macro mname ;
will start the de&nition of the !acro na!ed mname. Iou then enter SM co!!ands" and
ter!inate the !acro de&nition with a closing <.
d.
Iou can de&ne the !acro within SM with the macro edit co!!and
macro edit mname
will invoke the !acro editor" and you can then enter SM co!!ands to de&ne the !acro. #e
editor is described in detail in the SM !anualO the !ain co!!ands to re!e!ber are as
follows$ n the following descriptions control-6 !eans hold down the (JRL key and
then press the 6 key
the editor is a line editor" not a screen editor. Iou can advance to the ne.t line with
the down arrow on the keyboard" and up to the previous line with the up arrow.
Si!ilarly" the right and le) arrows advance the cursor one character right and le)"
respectively.
within a line" keys will work 4ust like the history editor
to insert a line above the current line" type control-5
to insert a line 4ust a)er the cursor" type control-=
to erase to the start of the current line" type control-L
to advance to the end of the current line" type control-,
when you type into an e.isting line" this acts in insert !ode" not overwrite !ode. Jo
overwrite an e.isting character" position the cursor 4ust a)er the character you want
to overwrite" use the delete key to erase the character" and then type in the new
character (or put the cursor on the character and type control-+" or lookup how
to set overwrite !ode in the real !anual)
to e.it the !acro editor" and save the changes" type control-6.
How do 5 save macros?
*nce you have de&ned the !acro" the co!!and
macro write macro" macro_file.dat
will write the !acro na!ed !acro< to the &le !acro]&le.dat #e macro write co!!and
re!e!bers the na!e of the last &le it wrote a !acro to" and if the &lena!e is the sa!e in the ne.t
co!!and" it will append the new !acro to the &le" otherwise it will delete it &rst (you can get
round this %% see section YMacroD in Te SM Manual). n this way" related !acros can be writen to
the sa!e &le.
'nother (!aybe easierT) way is to use the save co!!and. the co!!and
save save_file
will save everything to a &le %% !acros" variables and vectors. Jo get the! all back" say
restore save_file
Iou can even logout" go to dinner" co!e back" restart SM" use restore" and be back where you le)
oU.
How do 5 get a hardcopy of a plot?
Iou can si!ply de&ne the hardcopy device with the device co!!and" then issue the plot
co!!ands" and then type
hardcopy
which sends the plot to the hardcopy device.
*r" in the !ore co!!on scenario" you have put the plot on the screen" and &ddled with it until
you were happy with it" and then want to plot it to a hardcopy device. n this case" you !ake use
of the fact that SM saves your ploting co!!ands in a buUer" and you can !anipulate that
co!!and list. #e co!!and
history
will print out the list of co!!ands" in reverse chronological order (or chronological order with
history -). Iou can then delete all the co!!ands in that buUer that you donDt want with the
+,-,, co!!and.
+,-,, " ".
will delete lines < through <? fro! the history list. *nce you have deleted all the lines fro! the
history list e.cept the ones you used to !ake the plot on the screen" you can change devices to
the hardcopy device using the device co!!and" and then type
playbac/
hardcopy
#is will e.ecute the co!!ands in the history list" and then print the hardcopy plot. n fact" there
is a !acro hcopy de&ned to do this for you. hcopy sets the device to the hardcopy device (as
de&ned in your .sm &le on the printer line)" then does a playbac/" then sends the plot to
the hardcopy device" and then resets the device type to be whatever it was when you invoked the
hcopy !acro. Iou donDt have to playback all the linesO both hcopy and playbac/ have
optional argu!ents to specify the range of lines that you want.
Iou could also de&ne the co!!ands fro! the history list into a !acro" as discussed in section X"
and invoke the !acro to e.ecute the plot co!!ands$
macro hcplot " #.
device qms lca.
hcplot
hardcopy
#is will e.ecute the plot co!!ands fro! the history buUer lines < through -?" and then send the
plot to the hardcopy device for printing.
'n i!portant point to note about the hardcopy devices is that you have to reissue the device
co!!and each ti!e you do a hardcopy co!!and. #is is because the hardcopy plot vectors are
actually writen to a &le" and this &le is closed" sent to the ploter" and deleted when you issue the
hardcopy co!!and. @o new &le is opened for you auto!atically" so you !ust issue the
device co!!and to open a new plot &le if you want another hardcopy plot" or to rede&ne the
device to a ter!inal" if that is what you want. Iou !ay be able to use the ?8A, co!!and to start
a new page without starting a whole new plot.
What about 2-dimensional data?
SM has so!e capability for handling i!age data. Iou can de&ne an i!age with the image
co!!and" which is analogous to the data co!!and for vectors. 's described in the !anual" you
!ust &rst tell SM what sort of i!age &le it is. :inary data is rather tricky to de&ne in a general
way" and certainly diUers fro! one operating syste! to the ne.t" so the few standard types of
binary &les we have de&ned will hopefully cover !ost cases" and if not" you can always write a
progra! to convert your data into one of those types" or try to teach SM about your data for!at
a)er reading the &lecap appendi. to the !anual (see section YQilecapD in Te SM Manual).
*nce you have read in the i!age" you can contour it with the contour co!!and (&rst de&ne
the contour levels with the levels co!!and)" you can take a slice through it with the set !
B imageD!>y) co!!and" you can draw it as a surface plot (see section YSurfaceD in Te SM
Manual)" or you can draw a greyscale version of the data (this is a !acro. Say G,-?
greyscale for details" or load demos grey_sincos for a de!onstration).
t is possible that !ore capabilities will be added so!eday" but SM is not intended to be an i!age
processing syste!.
What are the other common commands?
Iou can leave SM by saying quit.
Perhaps the ne.t !ost i!portant thing to note in this conte.t is that SM has a co!!and
line editor" which allows you to recall previously typed co!!ands (use the up arrow to
scroll back through the!) and either re%e.ecute the!" or edit the!. Qor those of you
fa!iliar with 8MS" the co!!and line editor is very si!ilar to the one provided with that
syste!.
#e ne.t !ost i!portant thing is that there is a control-3 trap in SM" so if you start a
co!!and and regret it" you should be able to abort it by typing control-3.
f you donDt like the a.es drawn for you with the bo! co!!and" you can tailor the! a bit
!ore with the a!is co!!and.
cursor invokes the device cursor (for devices that have one). Iou can then read positions
fro! the screen by positioning the cursor" then typing any key e.cept e or q. #ose later
- keys are used to e.it the cursor routine.
end or quit causes SM to e.it.
e!pand changes the siSe of the points and characters drawn on the screen" as well as the
siSe of a.is tick!arks.
format allows you to specify the for!at of the nu!bers that are ploted along the a.es.
help is a very i!portant co!!and. Iou can also specify help on a particular co!!and
with help Rcommand_nameT
identification plots an identi&cation line at the top of the graph" giving the date and
so!e other infor!ation" of your choice.
label allows you to plot a label on the graph" at the current location. Iou can specify
diUerent fonts and sy!bols" as described in the !anual (see section YLabelD in Te SM
Manual).
Iou can change the siSe of the plot window with the location co!!and. :ut in general"
if you want to plot !ore than one graph on the screen (or page) at once" you will probably
use the window co!!and (see section Y9indowD in Te SM Manual).
lweight allows you to change the line thickness. #is will also apply to characters that
are ploted.
:y default" if the nu!bers you ploting on the a.is are between ?.???e < and <????" SM will
write these nu!bers out in deci!al for!at. #e notation co!!and allows you to
specify the range of nu!bers that you want writen out in this way" as opposed to being
writen out in e.ponential notation.
relocate relocates the current plot position to wherever you specify when you issue the
relocate co!!and.
tic/si\e is used to control the spacing of tick!arks on the a.es. ts !ost co!!on use
is to de&ne a logarith!ic a.is. Jo do this" the &rst and third argu!ent to the ticksiSe
co!!and should be negative.
window is used to draw !ore than one graph on a single screen (or piece of paper). 's the
na!e i!plies" it divides the default plot window into n by ! subwindows. Iou can !ake
the windows touch" if that is what you want to do.
'll the syste! !acros (well" all the interesting ones) are listed in an appendi. to the !ain
!anual. tDs worth ski!!ing through the list so!eti!e.
#ere are !any !ore co!!ands" which are described at the back of the !anual. Iou will regret
not reading about the!.
What are "ommon *rrors9 and What Should 5
#o?
f you try to run the progra!" and it says it canDt &nd graphcap" or font" or edit &les" you
probably donDt have a .sm &le. f you do have one" it !ust be in your !ain directory. f it is
there" it !ust have been edited to look for the &les in the correct place" and not be trying
to read the! fro! :alti!ore. f the directory speci&cations are correct" the &les probably
have not got the correct access per!issions set" so whoever installed SM should &. that.
f you try to plot a vector that you read fro! a &le" and it says the vector is not de&ned" it
probably !eans that the &le has so!e non nu!eric stuU in it" that you didnDt skip over
with the lines co!!and. f not" we have found proble!s in so!e cases with SM trying
to read a &le writen by a 8MS Qortran progra!. f yours is such a &le" 4ust use the 8MS
editor to !ake a new copy of the &le" and it should be ok. #e thing to look for is whether
the &le has Qortran carriage control atributes (do a dir/full co!!and on the &le" and
it will tell you). 9hen you edit it and !ake a new copy" those atributes will be replaced
with nor!al ones. t does read !ost Qortran &les" and we are not sure how the ones it canDt
read were writen.
f you !ake a synta. error" SM will tell you so" and reprint the line with a litle arrow
indicating the point in the co!!and at which it got confused. *ne place that a synta.
error is apt to arise is if you !ake use of the ability of SM to accept !ore than one
co!!and on a line. (ertain co!!ands cannot be used in this way" because it is a!biguous
to the parser what you !eant. #is is described in the !anual (see section YBow #e
(o!!and nterpreter 9orksD in Te SM Manual).
Where do 5 go from here?
Jo the real !anual" of course" wherein you will &nd all the co!!ands described" a list of all
currently de&ned !acros and what they do" plus a description of the progra! structure as well as
infor!ation about the graphics back end that will enable you to add drivers for other devices. See
section YntroductionD in Te SM Manual.
#is docu!ent was generated on W Septe!ber -?<< using the dMd translator version dd.
Manual de
S&per Mongo
Super Mongo es un progra!a para hacer grm&cos !uy sencillo de utiiSar"
con gran variedad de posibilidades" y !uy utiliSado en astrono!na para
realiSar &guras y cmlculos sencillos. Per!ite leer" escribir y representar
colu!nas de datos con su!a facilidad. Para los ob4etivos de las asignaturas
de Jocnicas 'strofnsicas y es !ms /ue su&ciente.
Pmgina creada y !antenida por$ 'lfred Rosenberg.
plti!a 'ctualiSaciqn$ < de 'bril del -??<
'nstalaci(n
#rrancando...
Salir
Macros
Otros tr&cos
Man&ales y #y&das
'nstalaci(n) '/un tienes algunas instrucciones para /ue SuperMongo (SM) funcione en los P(s del
(entro de (mlculo de 'strofnsica (((').
,ebes copiar en tu directorio raiS el archivo .sm /ue estm en +usr+local+lib+s!+
((q!o$ haciendo cp *&sr*local*li!*sm*.sm .)
Cl archivo contiene la siguiente infor!aciqn$

fonts
history]&le
history
te!p]dir
1graphcap
&lecap
graphcap
help
!acro
+
usr+local+lib+s!+fon
ts.bin
.s!hist
W?
+t!p+
+usr+local+lib+s!+gr
aphcap.local
+usr+local+lib+s!+&l
ecap
+usr+local+lib+s!+gr
aphcap
+usr+local+lib+s!+he
%N ,irectorio de las
fuentes.
%N Je creara este archivo
para recordar los
co!andos
%N @u!ero de co!andos
/ue recordarm
%N ,irectorio Je!poral
%N *tros directorios
!msf..
lp+
+usr+local+lib+s!+!
acro+
7na veS en tu directorio" puedes editarlo e introducir las siguientes lnneas /ue te
pueden ser rtiles
(obvia!ente" sustituir al" por tu &sername)$

!acro-
printer
Je;]strin
gs
pro!pt
na!e
e.pand
+
ho!e+alf+!acr
os]s!+
postscript
<
L$
'lf
<.???e??<
%N '/ui es donde te conviene
escribir tus !acrosf
%N Qi4a!os el tipo de i!presora.
%N Csto es para /ue puedas
utiliSar LaJe; en tus !acros.
%N Cste serm tu pro!pt (eli4e el
/ue /uieras).
%N Cste es el no!bre con el /ue
SM se re&ere a ti.
%N Csto es para /ue no de usen
los fonts por defecto (!ms
bonito..)
' continuaciqn" deberms crearte el directorio !acros]s! en tu home ((q!o$
haciendo m+dir macros_sm).
Cn este directorio puedes colocar todas tus !acros. 7n archivo especial!ente rtil
es el deno!inado default /ue serm leido desde el principio. Jodas las !acros /ue
tengas en ol se leermn y guardarmn en !e!oria" y podrms e4ecutarlas en cual/uier
!o!ento. Por e4e!plo$

startup-



!r <
.<<b
.<<w
echo Bola 'lfred .
:ienvenido. s
echo
echo Re /uieres
hacer hoy t
echo
!acro read E<.!ac
device .<< %g
X??.X??1<1< %bg
black %fg white
device .<< %g
X??.X??1<1< %bg
white %fg black
Csta pri!era !acro se
e4ecuta el entrar en SM.
'parecerm en la ;JCRM lo
/ue se indica.


!r es una !acro rtil para
leer los &cheros de las
!acros.
:asta hacer !r
nombreFdelFfchero (sin .!ac)
Si /uere!os un ter!inal
grm&co de fondo negro" de
X??.X??"
basta e4ecutar ;<<b (sie!pre
/ue tenga!os esta !acro en
default)
de! para un ter!inal
grm&co de fondo blancof
(on estos pasos deberna estar todo listo para funcionar.
#rrancando) C4ecutar SM una veS tengas listas estas con&guraciones es !uy sencillo. Cn un ;JCRM
escribes s! (y ya estm). Je debe salir algo co!o lo de la siguiente &gura.

Csto es lo /ue sale al e4ecutar s! en el ter!inal ;.
Baciendo dev .<<" q .<<b (si lo has de&nido en default
(e)plicado mGs arriba) se abre la siguiente ventana.
Csta es una ventana grm&ca tipo ;<<.
Salir
:asta hacer ,&it
Macros
(opia el archivo ngc<WW.dat del directorio +ho!e+alf+!acros]s!+ ((q!o$
haciendo cp home*al-*macros_sm*ngc.//.dat .) y prueba esta !acro en
tu directorio. Puedes usarla de !odelo para futuras !acrosf

c!d]ngc<WW erase
data ngc<WW.dat
lines > <?????
read _. - y 5 v > i XZ
set vi`v%i
li!its j?.5 <.F <W X
ctype yellow
e.pand <.X
bo.
.label 8%
ylabel 8
toplabel @=( <WW
ptype 5? ?
ctype red
e.pand ?.X
points vi v
Jrataro de e.plicar co!ando por co!ando lo /ue hace esta !acro.
erase
data ngc<WW.dat
lines > <?????
read _. - y 5 v > i XZ
set vi`v%i
li!its j?.5 <.F <W X
ctype yellow
e.pand <.X
bo.
.label 8%
ylabel 8
toplabel @=( <WW
ptype 5? ?
ctype red
e.pand ?.X
points vi v
:orra todo lo /ue pudiese haber en la pantalla grm&ca (;<<)
nfor!a del no!bre del archivo /ue procedere!os a leer
Lee a partir de la lnnea > y hasta la <????? (co!o !m.i!o)
Lee la colu!na - y la guarda en el vector .O la 5 y la guarda co!o
yO etcf
,e&ne el vector vi co!o la resta de los vectores v e i
Qi4a los ln!ites de la &gura$ de j?.5 a <.F rn el e4e ; y desde <W a X
en el I
Pasa al color a!arillo
C.pande todo lo /ue se haga a partir de ahora en un factor <.X
,ibu4a el borde (e4es) de la grm&ca
Pone el tntulo al e4e ;$ 8%
Pone el tntulo al e4e I$ 8
Pone el titulo a la &gura$ @=( <WW
Qi4a el tipo de puntos co!o circulos vacios
Pasa al color ro4o
Re%escala en un factor ?.X
Pinta los puntos vi frente a v
Para e4ecutarla" desde el ter!inal escribes$ read !acro c!d]ngc<WW.!ac" y luego$
c!d]ngc<WW. 'sn se lee y e4ecuta la !acro.
Man&ales y #y&das)

Manual BJML (Manual PostScript)
Jutorial BJML (Jutorial Postscript)
(Recuerda$ para desco!pri!ir$ g&n0ip fie.gz" y para e.traer$ tar xv-
fie.tar)
1OT#$ Cn caso de dudas o proble!as" no dudes en lla!ar!e al '( EXT)234 o !andar!e
un !ail al-5ll.iac.es . Si puedes" captura o escribe el proble!a de la for!a !ms e.plncita
posible" para /ue !e sea !ms fmcil resolverlo.
htp$++foru!.astro.keele.ac.uk$W?W?+!rs+python%graphs+super!ongo%pys!ongo+installing%seting%
up%s!%super!ongo
SuperMongoGpysmongo
Subir un nivel
'nstallation and general in-ormation -or plotting graphs 6ith SM via python
SuperMongo1pys!ongo
nstalling k seting%up SM (SuperMongo)
set%up &le$ .s!
set%up &le$ default
set%up &le$ !aps.dat
set%up &le$ graphcap.obsge
7sing SM
SM e.a!ple !acro
sa!ple output plot with SM
nstalling pys!ongo
using SM via python (pys!ongo)
test script for pys!ongo$ color.py
!odi&ed colour table rainbow> for darker colours
output of color.py$ color.ps
set%up &le$ ter!cap
;5RA''* #ata Reduction
;5RA''* #ata Reduction Software
:rought to you by$ si!ondgilles
#escription
=R'QQC :ase Line ,ata Reduction So)ware is a set of python scripts and !odules
and a ( library to reduce QJS i!ages produced by the 8ery Large Jelescope (8LJ)
QL'MCS instru!ent.
=R'QQC ,ata Reduction 9eb Site
"ategories
'strono!y
=iraUe 1 Pys!ongo$
Looking for the latest versionT ,ownload girbldrs%<.<5.<.tar.gS (G.> M:)
Bo!e + pys!ongo + pys!ongo%<.-
@a!e Modi&ed SiSe ,ownloads + 9eek Status
Parent folder
Jotals$ < te! <>X.- k: <
SuperMongoGpysmongo
Subir un nivel
nstallation and general infor!ation for ploting graphs with SM via python
nstalling k seting%up SM (SuperMongo)
tricks and tips on installing and seting%up SM
set%up &le$ .s!
to be copied in ho!e directory
set%up &le$ default
Qirst create directory s! in your ho!e and then copy this default &le into it. do not use
this default &le until now. a! not sure whether it is co!pulsory.
set%up &le$ !aps.dat
con&g &le to be copied to +usr+local+lib+s!+
set%up &le$ graphcap.obsge
to be copied into +usr+local+lib+s!+
7sing SM
starting with SM
SM e.a!ple !acro
#e ai! of this si!ple !acro is to test whether you can use SM (!acro test) and also print
on a black and white printers the diUerent colours ploted in test.ps in gray scale rather than
in black. Jo produce the plot test.ps" use !acro test-
sa!ple output plot with SM
produced by test.s! (!acro test-)
nstalling pys!ongo

using SM via python (pys!ongo)

test script for pys!ongo$ color.py
using !odi&ed color table rainbow>
!odi&ed colour table rainbow> for darker colours

output of color.py$ color.ps

set%up &le$ ter!cap

5nstalling H setting-up SM 1SuperMongo3
tricks and tips on installing and seting%up SM
% =et a copy of SM install directory.
%*'8R* 5$S4A&&A458$!
% nstall or check that the following are installed$
<) install lib.org%.<<%devel%X.F.?%>.5.<?<!dk or si!ilar rp! packages
including ;util.h" ...
(heck that you have ;util.h on your !achine by e.g. using
locate 6util.h
-) install gcc co!piler
5) install !ake
5$S4A&&A458$!
')
./set_opts
choose double precision" ]d" yes for parser" ...
% Iou then need to re!ove the &rst F lines of src+options.h but you will be see this in the error
!essage if you forget.
% Iou !ight need to change the Make&le if your ;<< location is diUerent fro! the preset one$
vi src+Make&le
;L:<< ` %l;<<
has to be changed to
;L:<< ` %L+usr+;<<RX+lib %l;<<
:)
ma/e
()
ma/e install
S*4-<,
&les to be added to your SM distribution or syste!$
copy in ho!e dir$
% .s! (and edit path)
create s!+default
and edited links
copy ter!cap and graphcap.obsge (!aybe !aps.dat) to
+usr+local+lib+s!+
set%up &le$ .s!
set%up &le$ default
set%up &le$ !aps.dat
set%up &le$ graphcap.obsge
set%up &le$ ter!cap
set-up file! -sm
to be copied in ho!e directory
Pulse a/un para obtener el archivo
Ja!auo < k: % Jipo de 'rchivo application+octet%strea!
set-up file! default
Qirst create directory s! in your ho!e and then copy this default &le into it. do not use this
default &le until now. a! not sure whether it is co!pulsory.
Pulse a/un para obtener el archivo
Ja!auo < k: % Jipo de 'rchivo application+octet%strea!
set-up file! maps-dat
con&g &le to be copied to +usr+local+lib+s!+
Pulse a/un para obtener el archivo
Ja!auo < k: % Jipo de 'rchivo che!ical+.%!opac%input
set-up file! graphcap-obsge
to be copied into +usr+local+lib+s!+
Pulse a/un para obtener el archivo
Ja!auo <<.H k: % Jipo de 'rchivo application+octet%strea!
<sing SM
starting with SM
in a shell window" type$
sm
then you can either type line co!!ands or use !acros. Jo use !acros" save the co!!ands in a
&le like test.s! and then in SM" type$
macro read test.sm
to read in the &le and then type the na!e of the !acro to e.ecute it$
test Dor test#)
#atDs it
SM e.a!ple !acro
sa!ple output plot with SM
SM e+ample macro
#e ai! of this si!ple !acro is to test whether you can use SM (!acro test) and also print on a
black and white printers the diUerent colours ploted in test.ps in gray scale rather than in black.
Jo produce the plot test.ps" use !acro test-
Pulse a/un para obtener el archivo
Ja!auo < k: % Jipo de 'rchivo application+octet%strea!
sample output plot with SM
produced by test.s! (!acro test-)
Pulse a/un para obtener el archivo
Ja!auo 5.G k: % Jipo de 'rchivo application+postscript
5nstalling pysmongo
=et the pys!ongo package fro!$
htp$++sourceforge.net+pro4ect+show&les.phpT
group]id`F>--Gkpackage]id`<<H5><krelease]id`5FXGWH
(latest version <.-.- -??G%<-%?F)
:CQ*RC @SJ'LL'J*@$
you probably need !ost of these packages$
nu!array
@u!eric
(lib)python%...develf
check which are already installed in the site%packages folder of your python distribution$
ls +usr+lib+python-.G+site%packages+
5$S4A&&A458$!
unpack the package
go inside the directory$
python setup.py install
9hile co!piling the following libraries !ay not be found$
% DplotsubD"DdevicesD"DutilsD
if you have added the su2. 6]d6 in the SM con&guration steps. Iou can either change the
setup.py &le in order to look for these &les with the 6]d6 su2. or create links in the +usr+lib
directory
%lSM %l(C
n !y new linu. distribution libraries end with 6.X6 or 6.X.?...6
have created these two links$
ln -s /usr/lib/lib1=.so.).... /usr/lib/lib1=.so
ln -s lib03,.so.).&.. lib03,.so
'nd the setup.py went through.
using SM via python 1pysmongo3
*nce SuperMongo k pys!ongo have been installed you are ready to write python scripts writing
SM plots.
color.py is a si!ple e.a!ple displaying the colours contained in the rainbow> palete that you
have to put in (assu!ing you are using python-.G)$
/usr/lib/python#.*/site-pac/ages/1=/rgb_tables
to replace the original to obtain the sa!e color.ps plot as the one in this directory.
test script for pys!ongo$ color.py
!odi&ed colour table rainbow> for darker colours
output of color.py$ color.ps
test script for pysmongo! color-py
using !odi&ed color table rainbow>
Pulse a/un para obtener el archivo
Ja!auo < k: % Jipo de 'rchivo te.t+python%source
"ontenido del Archivo
7W/usr/bin/python
import 1=
import 9umeric
g B 1=.plotDNpost_encap color.psN)
7g B 1=.plotD)
7g.paletteD'rainbow$_orig')
7g.paletteD'isophot')
g.paletteD'rainbow$')
g.limitsD.>#**>.>"#()
g.bo!D)
g.ptypeD".>&)
g.e!pandD".*)
for i in range D.>#**):
for X in range D.>".):
!B9umeric.arrayDYiQ>9umeric.Sloat)
yB9umeric.arrayDYXQ>9umeric.Sloat)
g.ctypeDi)
g.pointsD!>y)
g.writeD)
7g.showD)
modified colour table rainbow. for dar(er
colours
Pulse a/un para obtener el archivo
Ja!auo 5.? k: % Jipo de 'rchivo application+octet%strea!
output of color-py! color-ps
Pulse a/un para obtener el archivo
Ja!auo 5X?.? k: % Jipo de 'rchivo application+postscript
set-up file! termcap
Pulse a/un para obtener el archivo
Ja!auo W.5 k: % Jipo de 'rchivo application+octet%strea!