deer manual
(deer project, 2006-2008, Antonio Maschio @ )
Last updated: December 05, 2008
Index
-----
1. Introduction
2. The Dartmouth Operating System emulator
2.1 deer options
2.2 First run
2.3 Customizable variables
2.4 System commands
2.5 Tips on manipulating files
3. Conclusions
4. References
1. INTRODUCTION
------------
deer is an acronym for Dartmouth Environment Elementary Renderer; though
there are already emulators of the Dartmouth OS (on which the original BASIC
language environment ran), more complete and capable of running BASIC and ALGOL
(see [1]), I wanted to build my own, and I wanted to do it in two languages:
- deer, the "operating system", in bash, due do its extreme ability to deal
with strings (while lacking floating numbers);
- dib, the BASIC interpreter, in C, for its speed and its math functions.
This was particularly interesting because I had to dive into a more complete
bash and C theory before coding, and I was very pleased by that.
I spent one year (or so) in building deer, partly because of my need to study,
and partly because I have a family that occupies my head and time, and leaves
me nights bits for coding. Finally the OS was ready, but my BASIC was far to be
completed. It's not that easy to program an algebraic language (my experience
was limited to stack languages, which are very easy to build). You can read
the rest about this story in the file 'dib manual.txt'.
2. THE DARTMOUTH OPERATING SYSTEM EMULATOR
---------------------------------------
deer is not a complete replica of the original Sixties OS. It's rather a
subsystem, but as such it can create, edit, run, delete BASIC programs, and
has some other features, along with minor differences compared to the
original OS.
I discarded all the connection commands (network, kermit, and so on) and all
the documentation files (which couldn't be applied to my work); besides,
documentation takes its time to be written and read, so I limited it to a HELP
screen. There are no games, no web browsers, no mail readers. Nonetheless, you
will be able to build your own BASIC programs.
To tell the truth, I'm conscious that this emulator goes beyond the real
capabilities of the original OS; in all, deer is probably a subset of an
Eighties OS version, rather than a Sixties on. In any case, I set it to make
it work, to be rather useful; all the commands contained into [2] have been
implemented, along with a bunch of others to ease the programmer's task.
2.1 deer OPTIONS
------------
Usage: deer
Options are:
-h --help Give this help and exit
-l --lower-allowed Disable conversion of input characters to upper case
-t n Set auto shutoff to n seconds (n=0 disable shut-off)
-v --version Show version and exit
-x --extended-features Enable extended BASIC features (pass -x to dib)
Option -x is passed 'as-is' to dib (if you use another interpreter, don't set
it in deer because it may have a different usage).
By default, auto shutoff is set to three minutes (180 seconds).
2.2 FIRST RUN
---------
The first time you run deer, it will create a hidden directory into your $HOME,
named '.deer/' .
After you log in, a subdirectory will be created with the first 6 characters of
the user number turned to upper (e.g., if you type myra8697 at the prompt, the
directory .deer/MYRA86 will be created); all subsequent logins with MYRA86 will
use the same directory, and different users will have different directories. So
you can have many projects, each under a particular user. Please note that the
original DTSS accepted a login username made of six numbers or one letter and
five any characters; deer is less restrictive, in this regard, and will accept
any series of characters, cutting them to six and turning them to capitals.
If you want, you can copy the content of folder 'USER/' (contained into the
package) to you user home: you will have a complete set of examples and a
working environment ready to go; type
$ cp -r USER/* ~/.deer/MYRA86).
from within the deer unpacked installation directory.
When you run deer, yor will see the screen cleared, and a few data will be
displayed on the upper left corner:
DARTMOUTH COLLEGE TIME SHARING, T1
04 OCT. 2008, AT 13:36, 011 USERS.
(You will see different time values and different logged users.) T1 means
Tonibin 1, and is the machine simulated by deer (the original was D1, but
I believe I had to change it).
At this point only three commands are available:
- HELLO to start a sequence to establish a connection to the system;
- HELP to print a couple of help screens with all the available deer commands,
all aimed to help you in writing, maintaining, saving, retrieving, printing
and running your files and programs.
- BYE (also GOODBYE) to log off (there's an automatic log off if you don't
type nothing for 3 minutes - see options below for changing this behavior);
2.3 CUSTOMIZABLE VARIABLES
----------------------
Before running deer, you can change some default variables values contained in
the first lines of the script. They are:
deered
------
It contains the deer editor name, enclosed into double quotes. Default editor
is vim, but you can use the one you prefer (emacs, vile, nano etc.), even a
graphical one, if you want to.
deerless
--------
It contains the deer viewer name, enclosed into double quotes.The viewer is
used to examine a file without changing its contents, so you may use a pure
viewer, here, or you can even set it to an editor.
INTERVAL
--------
It contains the number of seconds for the autologoff procedure. Any value
greater than 0 sets the option for that number of seconds (default is 180,
which is about three minutes). If you put here 0, the timing feature is
disabled.
noTiming
--------
It contains the flag for disabling ($TRUE) or enabling ($FALSE) the timing
feature. A value of 0 for INTERVAL sets automatically noTiming to TRUE, but
you can disable the feature without changing INTERVAL (for a temporary usage,
for instance). Default is $FALSE (Timing enabled).
DELAY
-----
It contains the delay factor for an empty cycle to be performed to slow down
the listing of a BUILD or a BASIC file. On my emac G4 1.42 GHz, a value of
1000 corresponds to about 2 lines per second (a speed comparable to the one
of the old dear 8086). Default is (aha!) 1000.
basic
-----
(Important) It contains the name of the executable of a basic compiler or
interpreter of your choice. Of course, by default, deer comes with dib.
EF
--
For dib: it contains all the options you want to pass to it, and in particular
the Extended Features option "-x"; by default it's void, so that deer will
execute only standard BASIC (version III) programs.
For other compilers/interpreters: you can put any meaningful option you want
to pass to your BASIC.
Important: don't change anything else, unless you know what you're doing.
2.4 SYSTEM COMMANDS
---------------
Notes "before"
--------------
1) in the following:
- a PROGRAM file is a BASIC listing (with each line starting with a number);
this kind of file may be executed.
- a BUILD file is a text file in free format; this kind of file cannot be
executed; it's useful for writing documentation files.
- CURRENT is the current file (PROGRAM or BUILD).
- ARG is the (sometimes optional) argument of a command.
Commands belong to three classes:
- Class 1 commands require a value, so if you don't give an argument,
you will be requested to give one;
- Class 2 commands act on CURRENT file if no argument is given, or on
the file whose name match the argument;
- Class 3 commands act on CURRENT file only, or are general purpose
commands requiring no arguments
The class is exposed into square brackets before the command name.
2) any command (except HELP, HELLO and LIST--) is recognized by means of the
first three letters (so CAT and CATALYTIC will all act as CATALOG). But
beware: you have to type HELLO, HELP and LIST-- in full, though, to make
them work.
3) the string WHAT? is printed if you type a command which is not recognized.
4) the same condensed information (or so) can be obtained with HELP.
5) some information about I/O transfers and CRU (Computer Resources Usage)
have been grabbed by iostat. The iostat program I use comes from Mac OS X,
the system on which I work, thus it's a BSD version. Linux users and other
UNIX implementations may have a different (sometimes very different) version
of the program, capable of giving very diverse data, but not compatible
with the settings in deer. In any case don't worry: These data wont'
interfere with BASIC.
***
Here's the command list (text enclosed into {} is typed by you).
[3]ACCOUNT
Give some accounting information
Note: original data were CRU, SECS, I/O, CORE, written on one line.
I don't know exactly what's the meaning of these data, but I cannot
replicate them in bash on a UNIX machine. So I changed them to reflect
more practical needs for the deer user, and they will be reported in
two lines, the first with headers, the second with values.
Data will be:
- CRU (here Computer Resources Usage): it uses iostat for retrieving
idle percentage of the system, subtracting it from 100 and yielding
the global system resources usage.
- I/O (not knowing the original meaning of that): it expresses,
through iostat and in terms of MB/s, the amount of exchanged memory.
- LOGTIME: it expresses the total account session time.
- RUNS: it expresses the total of RUNs (assuming this has some meaning
for moderns systems)
SECS and CORE, two original data of the ACCOUNT command, have been
'forgotten', since I have no idea what they were and how to parallel
them with those on my UNIX machine.
[1]APPEND
Add file {name} to the end of CURRENT file. Usage:
{APPEND}
APPENDING FILE NAME--{name}
or
{APPEND name}
Note: If you APPEND a BUILD file to another, their content won't
overlap. If you APPEND a PROGRAM to another, the appended file will
overwrite all lines whose number appears in both files. If you APPEND
a PROGRAM to a BUILD file it will appear with its line numbers as a
listing queued to the BUILD file. You cannot APPEND a BUILD file to a
PROGRAM. A warning appears when you try to do so.
[3]BUILD
Allow entering free text on CURRENT file. To terminate input press
RETURN three consecutive times.
CAUTION!
If you type BUILD with an existing PROGRAM as CURRENT, its state will
turn to BUILD, and a subsequent REPLACE will overwrite the PROGRAM
file. So, before BUILD, be sure to open or create a BUILD file.
[3]BYE/GOODBYE
Terminate current session. If CURRENT has not been save to disk yet,
the system will invite you to use SAVE or REPLACE; this advice will
appear once only; if you save the file or not, when you retype BYE
you'll be allowed to exit anyhow.
[3]CATALOG
Give information about user saved files in the CURRENT catalog
[1]CREATE
Create new catalog under CURRENT with name {name}. Usage:
{CREATE}
CATALOG NAME--{name}
or
{CREATE name}
[3]EDIT
Edit CURRENT saved file with user editor (see variable 'deered')
[1]ENTER
Changes CURRENT catalog to catalog {name}. Usage:
{ENTER}
CATALOG NAME--{name}
or
{ENTER name}
[3]HELLO
Start a sequence of questions for logging in. Here's an example of
output:
{HELLO}
0.38 CRU
USER NUMBER--{MYRA86}
SYSTEM--{BASIC}
NEW OR OLD--{OLD}
OLD PROBLEM NAME--{LINEAR}
READY.
[3]HELP/EXPLAIN
Print a help screen (in future versions, EXPLAIN may expanded to show
help for each command)
[3]HOME
Shortcut for enter *MYCAT; re-enters main catalog
[3]IGNORE
Retrieve saved file, losing all changes made
[3]LENGTH
Give length of CURRENT file
[3]LIST
List CURRENT file (BUILD or PROGRAM)
[3]LIST--XXXXX
List CURRENT BASIC file starting from line XXXXX. Mind the two dashes
following LIST.
[1]NEW
Create a new empty file and set it CURRENT with name {name} and
state PROGRAM (you can safely type BUILD after NEW, because the file
is empty). Usage:
{NEW}
NEW PROBLEM NAME--{name}
or
{NEW name}
[1]OLD
Retrieve an existing file with name {name} and set it CURRENT; the
state will be PROGRAM if the first character of the file is a number,
otherwise it will be a BUILD file. Usage:
{OLD}
OLD PROBLEM NAME--{name}
or
{OLD name}
[2]PUNCH
Send CURRENT file to printer. Usage:
{PUNCH}
Send file {name} (which may be different from CURRENT) to printer.
Usage:
{PUNCH name}
[1]RENAME
Change name of CURRENT file to {name}, retaining the state (PROGRAM
or BUILD). Usage:
{RENAME}
RENAME PROBLEM NAME--{name}
or
{RENAME name}
[3]REPLACE
Save CURRENT file replacing previous contents.
[3]RUN
Execute CURRENT PROGRAM file; an implicit SAVE/REPLACE is done, so
you don't need to type SAVE or REPLACE, before running a program; this
is because sources to run must be taken from the disk file, and they
must be the more recent too! The same was applied in the 1964 OS (see
the October 1964 BASIC manual for examples in which a program typing
is directly followed bu a RUN).
[3]SAVE
Store CURRENT file to disk if file does not exist (if file exists,
a warning will appear; in this case use REPLACE).
[3]SCRATCH
Empty CURRENT file, retaining the state (PROGRAM or BUILD).
[3]SORT
Sort contents of CURRENT BUILD file; a PROGRAM is always sorted
automatically in memory and during saving.
[1]SYSTEM
Change system language (fake) to {name} (actually, only BASIC is
accepted). Usage:
{SYSTEM}
SYSTEM NAME--{name}
or
{SYSTEM name}
[2]UNSAVE
Delete CURRENT file from disk. Usage:
{UNSAVE}
Delete a file or a catalog from disk. Usage:
{UNSAVE name}
CAUTION!
1) Don't use this command thoughtlessly! Remember that, if you type
UNSAVE, deer **won't** ask you for a file name; rather, IT WILL DELETE
CURRENT FILE! If you want to delete a different file, you **have** to
type its name after UNSAVE!
2) If used with catalogs (directories), UNSAVE will delete the catalog
***AND ALL ITS FILES***! Nothing is asked, nothing is written.
In all, use it with GREAT CARE!
[3]USERS
Give number of currently logged users (fake)
It's a random number to give the impression the system is not used
by you only!
[2]VIEW
Show CURRENT file without editing it (using user viewer). Usage:
{VIEW}
Show file {name} with user viewer. Usage:
{VIEW name}
[3]WHAT
Give information about current session in the form:
CURRENT FILE MOTION
COMPUTER T1 (deer system)
USER NUMBER 242424
SYSTEM BASIC
SEARCH PATH :242424
***
Notes "after"
-------------
1) After any command performance, successful or not, a READY will be printed
so that you may type next command
2) Please, pay attention to the UNSAVE command: if you happen to type UNSAVE
inadvertently, you can recover the file (because it's still in memory)
typing SAVE immediately after it. File will be rewritten.
3) The command EXTEND (which is off-topic) has some meaning only for dib, the
BASIC interpreter. It may be used to activate dib's extended features from
console, if you have forgotten to start deer with option -x.
4) The SAVE and REPLACE commands play a similar role: the first must be used
the first time you write a file to disk; the second must be used when you
want to replace what's stored on disk with what's on memory, updating
file's contents.
5) The command EXIT has been given to offer a helping hand to shell users. It
behaves in the very same way of BYE.
2.5 TIPS ON MANIPULATING FILES
-------------------------
In the following, I assume that:
is the directory where we are
is the destination directory
is the name of current file
is a new name for current file or a name of an existing file
other than current
SAVE and REPLACE must be used with the following cautions:
- SAVE if the file doesn't exist
- REPLACE if the file exists
Anywhere I write SAVE you must read SAVE or REPLACE, depending on the file
existence.
2.5.1 How to move CURRENT file to another directory
--------------------------------------------
UNSAVE
ENTER
SAVE
This procedure is not safe, because if something happens to your system
between UNSAVE and SAVE the file is lost, though it's very unlikely since it's
a question of a few seconds; in any case, if you want a safer (and longer)
procedure:
ENTER
SAVE
ENTER
UNSAVE
2.5.2 How to rename an existing file
------------------------------
UNSAVE
RENAME
SAVE
A safer procedure:
RENAME
SAVE
OLD
UNSAVE
2.5.3 How to move and rename a file to another directory
--------------------------------------------------
UNSAVE
ENTER
RENAME
SAVE
A safer procedure:
ENTER
RENAME
SAVE
ENTER
OLD
UNSAVE
2.5.4 How to copy a file in the same directory (renaming it)
------------------------------------------------------
RENAME
SAVE
2.5.5 How to copy a file in another directory with the same name
----------------------------------------------------------
ENTER
SAVE
2.5.6 How to copy a file in another directory with another name
---------------------------------------------------------
ENTER
RENAME
SAVE
2.5.7 How to delete a file
--------------------
UNSAVE
3. CONCLUSIONS
-----------
deer is an emulation, written in bash: don't expect it to be fast, precise,
robust. After all it's more like a game. And remember that dib, the BASIC
interpreter, may be used all alone, as UNIX program, and in this case deer
may be forgotten.
But, please, if you want to help me improve this program, write me tips and
snippets of code to better it or make it compatible with other UNIX systems.
I hope you like deer.
It's GPL: Enjoy!
4. REFERENCES
----------
The following documents were very useful to understand basic principles and
set up general behaviors:
[1] The dtss simulator, with many information about the system, can be found
at http://www.dtss.org/ - in the site you can also find a link to an
emulator written in java and running online (a registration is requested
in order to use it - I didn't).
[2] "Dartmouth BASIC manual" for version II, October 1964, is available as a
pdf file at http://www.bitsavers.org/pdf/dartmouth/BASIC_Oct64.pdf
[3] "Programming with BASIC", by Byron S. Gottfried, edition 1, 1975 (Italian
version, titled "Programmare in BASIC", Schaum 1982).
[4] "Dartmouth Time-sharing System - a brief description", from october 1964,
outlines the system in which the OS was implemented, and is available as a
pdf file at http://www.bitsavers.org/pdf/dartmouth/DTSS_descr_Oct64.pdf
*** ***
(written with gvim)
(
geocities.com/it/tonibin/deer) (
geocities.com/it/tonibin) (
geocities.com/it)