intro.29

-*-Text-*-
This is the file INFO;INTRO >, which contains information that
is, one hopes, useful to the beginning user.  It is an attempt to 
answer questions that are very common to the naive user.  It is 
not intended as 'full' documentation.

File: INTRO,  Node: Top,  Up: (DIR),  Next: Terminals

This piece of documentation is designed for use of the new ITS
user, to give him or her a broad overview of the resources available
on the system.

If you need help in using INFO, "?" will get you a brief refresher
listing all the commands, and "H" will show you a primer.  If this is
your first use of INFO, you should definitely type "H".  To exit INFO
type "Q".

* Menu:

* Terminals::		How to get your terminal set properly.
* Files::		All about the ITS file system.
* DDT::			How to create and manipulate jobs with DDT.
* Users::		How to find and communicate with other users.
* Documentation::	Where to get written documentation.

File: INTRO,  Node: Terminals,  Up: Top,  Next: Files

This node contains very basic information about how to get help
setting your terminal type properly.

To tell this machine about the type of terminal you are on, use the
:TCTYP command.  Typing ":TCTYP ?" at DDT (followed by a carriage
return) will give info about the setting TCTYP can have.  It will
also point you to more complete documentation if you desire it.  One
of your first concerns on this machine should be telling the
computer what type of terminal you have so that it can do the most
effective possible job of using your terminal's features to its
advantage.

TCTYP knows about many standard types of terminal.  For instance, if
you are on a VT52, you should just type

  :TCTYP VT52

and all programs on the system will be able to do appropriate things
with your output to take advantage of your terminal type.  (":TCTYP ?"
will, of course, give you all this info.)

If you find that TCTYP does not support your terminal, or the right
options to make it do reasonable things with your terminal, you
should also look in the INFO program under a topic called 'CRTSTY'
for a description of this program.  CRTSTY knows about special
terminals that the operating system doesn't, and it can be of great
help in making them livable.  ADM, Datapoint and Datamedia, VT100,
and others are in this category.

If you are getting a double-echo when you type characters, it is
because either you or your host computer is in half-duplex mode.  ITS
expects to be echoing your characters for you as you type.  To
correct the problem, make sure the button marked FULL/HALF DUPLEX on
your terminal is in the "FULL" position.  If it already is, then try
to get your host computer to stop echoing.  If this fails, be sure to
specify "HALF" in the list of options to TCTYP.  That will tell it
that you are using a half-duplex terminal and not to echo your
input.  All programs on ITS assume full duplex, and some are more
flexible than others about the need for full duplex, but you
shouldn't expect wonders from any programs that do fancy display if
you are set in half-duplex mode.

(See also the TCTYP node under INFO for more complete documentation.)

File: INTRO,  Node: Files,  Up: Top,  Next: Dirs

This node contains information about the ITS file system.

* Menu:

* Dirs::		What a directory is and how to see it.
* Names::		How to make sense out of ITS file names.
* Manipulation::	How to manipulate files with DDT.

File: INTRO,  Node: Dirs,  Up: Files,  Next: Names

This node contains information about the structure of file
directories on ITS.

ITS file directories are not hierarchical in nature.  There are a
finite number of directories, all at one level, and no subdirectories.

To see the files in a directory, use:

	:LISTF directory-name

File: INTRO,  Node: Names,  Previous: Dirs,  Up: Files,  Next: Manipulation

This node is designed to teach a new user how to read and
understand the various formats in which file specifications
can appear.

* Menu:

* Basic::		The four fields of a file name and what they mean.
* Abbrevs::		Abbreviations for and alternate forms of file names.
* Convention::		Special file-naming conventions.

File: INTRO,  Node: Basic,  Up: Names,  Next: Abbrevs

Each file name in an ITS file specification has four fields, not all of
which need to be specified (some may default), but all of which will at
some time be used.  This section will deal with the meaning of each
field.

A file specification will normally look something like this:

	DSK: MYDIR; MYPROG NEW

and is organized into four fields.  The structure of the above file
specification is as follows:

        <device>: <directory>; <file-name1> <file-name2>

where <device> = DSK, <directory> = MYDIR, <file-name1> = MYPROG, and
<file-name2> = NEW.

What follows is a description of the four fields of a file name:

<device> - the hardware/software device on which the file lives.
	   For the naive user this should always be DSK, which is the
	   normal disk packs.  The device is DSK by default, so, if you
	   pretend it isn't there, and if you leave it out of every
	   file name that you ever deal with, then the whole world
	   should continue to function properly.

<directory> - the name of the directory (if applicable).  Most devices
	      (like DSK for example) do use directories of some sort.

<file-name1> - the first 1-6 characters of the file name.

<file-name2> - the second 1-6 characters of the file name. 

To specify files to DDT (the top-level job that you are running) --
and to almost any other job, since all try to adhere to the convention
-- you should type:

<device>:<directory>;<file-name1> <file-name2>

File: INTRO,  Node: Abbrevs,  Previous: Basic,  Up: Names,  Next: Convention

If you wish to omit <device> or <directory> -- or rearrange their
order -- that's OK.  DDT recognizes the device because it ends
with a ":" and the directory because it ends with a ";".
<File-name1> and <file-name2> must be separated by a space.

Example: The disk file on directory "JOE" with File-name1="MY" and
	 File-name2="FILE" would look like:

		DSK: JOE; MY FILE

Spaces may be included between any of the four items.  They are
necessary at the end of file-name1 and the beginning of file-name2, of
course.  Other valid ways of naming the same file are:

	DSK: JOE; MY FILE
	JOE; DSK: MY FILE
	DSK:JOE;MY FILE
	DSK:MY FILE JOE;
	MY JOE; FILE DSK:

and probably anything else that is similar -- except, of course, that
file-name2 may not precede file-name1.

File: INTRO, Node: Convention, Previous: Abbrevs, Up: Names, Next: Manipulation

There are a few special file-naming conventions on ITS.  Some are just
traditions; but some are specially recognized by the operating system, and
interesting things are done with them.

* Menu:

* Greater-Than::	The ">" convention.
* Fn1/Fn2::		Unusual first and second file names.

File: INTRO,  Node: Greater-Than,  Up: Convention,  Next: Fn1/Fn2

There is one other important feature, or convention, for file names
on this system.  It is called the greater-than convention.  This node
will deal with that convention.

When the operating system sees the symbol ">" as a second
file name in a file specification, it will not think you mean a file
whose second file name is that character.  This is a special
convention which is very useful in creating numbered file names.

Why would anyone want a numbered file name?  Well, let's suppose you are
working on a program that involves considerable debugging.  It is
likely that you will want to create the program, test it, correct
the file, and re-test.  The most convenient way to do this on ITS
is to create a file originally with a first file name the same as the name
of the program, and a second file name which is a number.

So, let's say you've created a file called "MYPROG 1", and you
discover it has a bug.  What you would like to do is read it back
into your editor (see other documentation on editors) and make
corrections, writing the new revision out to "MYPROG 2".  That way
you can keep track of which is the newest revision, because it has
the highest revision number.

To do this efficiently, there is the 'greater-than' convention.  It
says that if you try to read in (or print, or open for input in some
other way) a file named "something >", what you really mean is to
read in the file whose second name is the highest-numbered file with
that first file name.  And when you write out a file named "something >"
-- you NEVER want to clobber an existing file, so it will have a
second file name one higher than any existing second file name for
that group of files.

You can then go and delete the old revisions of the file by naming
them explicitly.

Note that if you DELETE the ">" file, you delete the largest-numbered
file in existence.

File: INTRO,  Node: Fn1/Fn2,  Previous: Greater-Than,  Up: Names,  Next: 

DDT treats files specially that have a first file name of TS. 
When a user types

	:<job-name>

DDT will look for a file named "TS <job-name>" in the directories in
the user's search rules.  If DDT finds such a file, the file is
expected to be in a runnable binary format.

Traditionally, many second file names of files have been treated
specially.  The following is a list of some of those file names.

COMPRS	This is a TECO compressed library.
:EJ     This is a TECO compiled library.  (Note that ':' is special
	to file naming and usually means the end of a device field.
	To type in a file name with a ":" in it, you must type a ^Q
	(control-Q) immediately before the colon.
	Example: "DSK:FOO;BAR :EJ"

OUTPUT	This is a temporary file output by a program.  Such files
	should be renamed to something more useful when the program
	is finished with them.  The GFR (Grim File Reaper) has been
	known to delete files with  this name without asking.

@XGP	This is a temporary file created by the ":@" command.  The @ program
	normally queues this file for output on the XGP, and later deletes
	this file automatically.
XGP	This is a file created by some text-justifying program (for
	example, TJ6) for output on the XGP.  Such files are also
	usually considered temporary.
PRESS	This is a file, also temporary, created for output on the
	Dover printer.

LAP	This is a file containing a lisp-assembly program (compiled,
	not assembled).
FASL	This is a file containing a fast-loading lisp binary program
	(compiled and assembled).

(INIT)	In the past, initialization files had funny first file names
	and '(INIT)' as a second file name.  This convention has been
	flushed, in favor of a first file name the same as the
	user's login name and a second file name the same as the
	program name.

	Thus, the following old file names now convert into the new
	file names as shown:

		.DDT.	(INIT)	=>	<uname> LOGIN
		.DDT_	(INIT)	=>	<uname> LOGOUT
		.EMACS	(INIT)	=>	<uname> EMACS
		.TECO.	(INIT)	=>	<uname> TECO
		.LISP.	(INIT)	=>	<uname> LISP
		MACSYM	(INIT)	=>	<uname> MACSYM

File: INTRO,  Node: Manipulation,  Previous: Fn1/Fn2,  Up: Files

This node describes the DDT commands for manipulating files
(for example, :PRINT, :COPY, :MOVE, :RENAME, etc.).

To print a file (don't use the term LIST - that's for directories) 
means to see its contents on the terminal you are typing on.

:PRINT <file specification>

will print a file.  For example, to print out the documentation 
on DDT, you would do:

:PRINT .INFO.;DDTORD >

Remember, the ">" asks for the highest-numbered revision (which will
be the latest documentation).

Other useful things to do with files are:

:RENAME <file-spec1>,<file-spec2>
  This will change the name of <file-spec1> to <file-spec2> --
  providing they are both on the same directory.

:COPY <file-spec1>,<file-spec2>
  This will copy a file named <file-spec1> anywhere, including 
  between directories, to the location specified by <file-spec2>.
  Be careful that you have no existing <file-spec2>, because it 
  will be destroyed by this operation.

:MOVE <file-spec1>,<file-spec2>
  This is just like :COPY but deletes <file-spec1> if the copying 
  to <file-spec2> is successful. 

:DELETE <file-specification>
  This makes <file-specification> go away.
  Be careful with this!  Type the whole file specification.  Don't
  leave any of the pieces out.  The file specified by default (if you
  just type :DELETE followed by a carriage return) is the last file
  you referred to with DDT!  There is no protection on files around
  here to keep them from being deleted.  Users are expected to be
  sensible enough not to delete files that aren't their own (unless
  they have the owner's consent, of course).

A full list of all DDT commands can be gotten by typing ":?"
at DDT.

While we're on the subject of printing, deleting, etc., it is well to
mention that most of these commands have control-character
abbreviations to aid in typing speed.  ":PRINT" can be abbreviated as
"^R" (Control-R).  Thus you can do

^R .INFO.;DDTORD >

to print DDT documentation if you don't like typing all of

:PRINT .INFO.;DDTORD >

With such power comes danger.  ^O (control-O) deletes files.  If you
are a TENEX hacker, DON'T use ^O thinking it means to stop output!!
It doesn't -- it deletes files!  (^S stops output.)  ^O followed by
a carriage return will delete the last file you printed or copied or
otherwise referred to with DDT.

The :? commands will list these abbreviations (if there are any; :MOVE
doesn't have one) in brackets at the end of the description.  For
example, the entry for :COPY is

:COPY	<old file>,<new file> copy file, preserving date & FN2 []

The abbreviation is "$^R".  One thing that should be mentioned:  When
you see a "$", it is probably NOT a dollar-sign, but an escape, so what
you should type is <escape><control-R>

File: INTRO,  Node: DDT,  Up: Top,  Next: Manipulation

When you log in you are initially typing at DDT.  DDT is your
top-level job.  Its primary responsibility is to help you in your use
of other jobs.  Things DDT can do fall into two categories: (1) DDT
commands and (2) jobs.

* Menu:

* Commands::		What are DDT commands; why are they useful?
* Programs::		What is a user program?  How does it differ from
			a DDT command?
* Ctrl-Char::		Useful control characters.
* Detached Trees::	How to get back a detached tree.

File: INTRO,  Node: Commands,  Up: DDT,  Next: Programs

This node will describe what DDT commands there are, and what
you can do with them.

	DDT itself is a job (DDT's formal name for a program), and it
takes up a job slot in the system.  The system has a fixed number of
job slots (95 for MC, which has a large amount of real memory, fewer
for the other ITS sites).  Most DDT commands do not take up job slots
(except those which are specific requests for creation of a job) --
instead, you may think of them as subroutines in the DDT job.  A full
list of all DDT commands can be gotten by doing ":?" -- any command
that you do from DDT which is not on the list you get with ":?" is not
a DDT command but a job.  (See next section: Programs.)  DDT commands
include some file manipulation commands (see section on file
manipulation), system status, and many debugging commands.

All commands and job names are only six characters or fewer.  You may type
more characters, but only the first six will be used in the creation
of a job name.

File: INTRO, Node: Programs, Previous: Commands, Up: DDT, Next: Ctrl-Char

Your process is structured in the form of a tree with its root at
the top.  DDT is at the top and it may create lower nodes which may
(on rare occasions) create lower nodes below them.  When you run a
DDT command, you stay in the node of the tree called HACTRN (the job
name of your DDT).  If you create two jobs (called FOO and BAR, for
instance), your tree would look like this:

			HACTRN
		       /      \
		    FOO	       BAR

DDT itself is a job.  Other jobs can be created by DDT.  DDT is
responsible for keeping track of which job you are in and moving you
from job to job.  Jobs are created by typing a ":" followed by a job name
followed by a carriage return.  (Note, many DDT commands use the same
syntax -- there are no jobs with the same name as DDT commands, so this
isn't a problem.)  For example, typing ":NAME" followed by a carriage
return will start a job that will tell you the names of all the people
logged into the system.

To return from a job to DDT temporarily, you can type ^Z (control-Z), which
will harmlessly leave the job in a manner that it can be re-entered later.
For example, if you are in a Macsyma and receive a message from another
user to which you would like to reply, you can type control-Z, which will
return you to DDT temporarily; then send your reply; then re-enter your
Macsyma with ":CONTINUE" (see below) without having harmed what you were 
doing in it.

The following DDT commands may be useful for manipulating jobs:

:LISTJ	- lists all of your jobs.  The current job (if you have any jobs)
	  will have a "*" beside it.

:CONTIN	- continues running the current job, as if you had never left it.

:JOB	- rotates the job tree.  (It selects the next job in the tree as the
	  current job.  It may be useful to think of your jobs as being 
	  in a circle, upon which :JOB will move you from point to point.)
	  Typing this when you have no jobs will give the response:
	  "JOB?".  This is a DDT error message equivalent to "Are you
	  implying that you think you have a job?"  It isn't asking for
	  an answer -- all DDT errors just seem to end in a "?". 

:KILL	- You will see many jobs do this on their own when they are done
	  doing their thing (:NAME for instance).  If you have control-Z'd out
	  of a job and are done with it, you should do ":KILL" to free up
	  the job slot it consumes.

:MASSAC - (short for :MASSACRE, but, due to the rule about 6 characters,
	  :MASSACHUSETTS will also work if you're fond of extra typing)
	  will kill all of your jobs in one fell swoop.  (It won't affect
	  detached trees, however -- there's an entry later on about how to
	  deal with detached trees if you've run across one and wondered
	  what to do.)

Some DDT commands and jobs require additional information in
order to do their thing.  Some may allow additional info but
not require it.  This additional is called JCL (Job Control
Language), and, unlike IBM JCL, ITS JCL is simple and does not
require years of study to master -- you just put the info the
job needs on the line after the job name and before the
carriage return.

For example, the ":JOB" command -- that we mentioned will rotate your
tree to the next job -- may be given JCL to get it to do something
different.  If you do something like

:JOB FOO

you will reselect the job FOO, no matter where it is in your job tree.
(Note: If no such job FOO exists in this case, a slot will be allocated
for it.  The job will have no program in it and will be essentially useless
to you.  If this happens, you can make the job go away with ":KILL".)

Also note that there is a DDT command called :JCL that allows you to
specify JCL for a job.  Do NOT use it for the time being.  Using it
correctly requires more advanced knowledge of DDT than you 
probably have right now if you are reading this.  It will likely have
an un-noticed effect on your jobs, but it may produce VERY odd results as
well under certain circumstances.

File: INTRO, Node: Ctrl-Char, Previous: Programs, Up: DDT, Next: Detached Trees

This node will discuss some of the useful control characters which are
recognized by DDT, and how to make use of them.

Control characters are produced by holding the control-key on your
terminal and typing the character.  (It's like a different flavor of
Shift key.)  Control characters are printed usually as up-arrow ("^")
followed by the character.  Don't type the "^" -- just hold down
"control" and type the character following the "^".

<Altmode>, , or ^[ 
		Many programs, including DDT, treat this character 
		specially.  Note that there is a character $ (dollar sign)
		on your terminal, and it probably echoes the same as  
		(Altmode).  To get <Altmode>, type the key marked <ESC> or
		<ALT> or <SEL> on your terminal.  It will echo as a .
		Very few programs mean $ (dollar sign) when they echo the 
		dollarsign - most mean <Alt>.  But be aware that there is
		a difference, so you're not completely lost.

		If you're using a very fancy TV keyboard, there may be
		two keys - one marked ESC and one marked ALT.  Use ONLY
		the key marked ALT in that case.

^D		This flushes any partial input to DDT.

^G	        This is DDT's quit character.  If you are at DDT
		level, this will echo "QUIT?" (which doesn't mean it
		wants an answer).  You are then ready to type a new
		command to DDT.

		If you are using another program, ^G will be handled
		by the program.  Most programs will handle ^G by
		quitting and going back to the main command reader.

^L		This clears the screen.  If there are pending,
		unprocessed characters (that is, you're in the
		middle of typing a command) it will redisplay those
		characters.

^S		This flushes output at DDT level.  Once a given
		output is flushed, you must type the command again
		and restart the output all over.  There is no way to
		resume a flushed output from the point it was
		stopped.  This command is not meant to stop a
		command from working.  It just stops its output.

^Z		This causes a program interrupt asking a job to
		return to its superior.  If you are running a
		program, EMACS for example, and wish to exit for a
		moment to do something else, type ^Z.  This will
		bring you back to DDT, suspending your EMACS job.
		(For more info on job selection and re-entering
		jobs, see the section on job manipulation.)

File: INTRO, Node: Detached Trees, Previous: Ctrl-Char, Up: DDT

If you have a detached (job) tree, you will be told so when you log in.
Typing <Space> to the message "--Attach your detached tree--" will work.

If you miss your chance, type the following magic incantation immediately
after you have logged in (if you want the old tree back):

		:REATTACH <your-name>

where <your-name> gets replaced by the login name you use.  For example, if
you log in as JSMITH, you do

		:REATTACH JSMITH

and your old tree will be magically reowned.  If this doesn't work, or you
are unsure, feel free to do :LUSER, which will request a system wizard 
to help you.

File: INTRO, Node: Users, Up: Top, Next: Who

ITS is a time-sharing system.  There are many other users who use the 
computer, and it can be to everyone's advantage if you are able to
know who is logged in and how to communicate with them when you need
help (as well has how to give help to others when they need it).
This node attempts to deal with some of these issues.

* Menu:

* Who::			How to find out who's logged in.
* Communication::	Communicating with other users.
			Using MAIL and SEND.
* Announcements::	How to enter items for others to read in :MSGS.
* System Load::		How to tell if the system is 'heavily loaded.'

File: INTRO, Node: Who, Up: Users, Next: Communication

There are many system programs for finding out who is using or has used
this computer, and whether they are currently logged in.  This node
gives a brief description of what each does.

The following commands will give info about who's on the system (in 
increasing levels of verbosity):

:U or :USERS
  lists the user names only of all users logged in.

:W or :WHO
  lists the user names and TTY (terminal) numbers of all logged in.

:WHOJ
  lists the user names, TTY numbers, and job names of all logged in.

:NAME, :FINGER, :F
  lists the user names, affiliations, real names, job names, idle time
  (time since the user typed on the terminal) if any, TTY number, and
  TTY location for all logged in.

:WHOIS
  lists the same as :NAME plus an incredible array of extra stuff like
  home addresses, nicknames, remarks to INQUIR, etc. for all logged in.

Some of the commands do different things with something on the same
line as the command (JCL line).  Examples:

:WHOIS <name>
  lists personal description of <name> regardless of whether he or
  she is logged in.

File: INTRO, Node: Communication, Previous: Who, Up: Users, Next: Announcements

There are two basic forms of message sending, SEND and MAIL.  This
node talks about how the :SEND and :MAIL commands are used, and 
the cases in which it is desirable to use one over the other.

SEND is something that you use to send a message to a person who is
  currently logged in and whom you want to get the message right away.
  The usage is:

:SEND <name> <message> ^C

  Note that since the message is terminated with a control-C, it may extend
  over more than one line.  So something like:

:SEND JOHN Hi. How are you.
I have a problem. I don't know how to use :SEND
^C

  is perfectly acceptable.

  When you type the control-C at the end of the send, JOHN will immediately
  receive the message on his terminal.  It will look like:

[Message from <Yourname> at <Machine>  <Time>]
Hi. How are you.
I have a problem. I don't know how to use :SEND

  He can then respond to you with a message explaining that you are 
  bothering him with untrue complaints since you had to know about 
  :SEND to send the message.  Anything a user receives that is sent 
  via :SEND will be deleted when the user logs out.  Until then, it 
  is accessible by the :PRSEND command...

:PRSEND or :PRSEND <name>

  For more info on how to use :SEND try typing ":SEND ?" immediately 
  followed by a carriage return. 

MAIL is the way to send mail to another user that you don't expect to be
  read now or that you want to be saveable.  MAIL will not be deleted
  until it is explicitly read by the recipient(s).  If they are logged in,
  DDT will print a message on their terminal(s) telling them they have
  mail, which they may choose to look at or not, depending on how busy
  they are.  If you try :SEND <name> and it immediately types "(Mail)",
  it means the user is not logged in or not accepting messages (perhaps
  they are trying to get a nice printout), and your SEND will go as
  mail.

  To print your mail, use :PRMAIL.  The usage is:

:PRMAIL or :PRMAIL <name>

  For more detailed information on MAIL, see *Note Mail:(Mail).

File: INTRO, Node: Announcements, Previous: Communication, Up: Users, Next: System Load

Announcements are messages that everyone will read with the :MSGS
command.

There are two kinds of announcements: System Messages and
Bulletin-Board Messages.  (See *Note Announcements: (SYSMSG).  You can
do that by typing "F" for footnote, followed by enough letters of the
word "Announcements" to distinguish it from the other footnotes in
this node.  Then, type "L" to come back here to continue with your
introduction.)

File: INTRO, Node: System Load, Previous: Announcements, Up: Users

This node describes how to recognize a heavily loaded system, and
the meaning of the term "fair share," and what net ports are.

It is hard to define precisely what is meant by a "loaded" system.
There are several different kinds of system resources which are
needed from time to time, and, if any of them are exhausted, the
system may be said to be heavily loaded.

If you are connected to an ITS machine from the ARPAnet (or another
ITS machine), then you are using a net connection called a "port."  If
you are using the CRTSTY program for a terminal type which ITS does
not support directly (VT100, ADM3A, etc.), you are using two net
ports.  There are a limited number of net ports.

Additionally, your CRTSTY is using a job slot.  A job slot is just what
it sounds like.  Your HACTRN (the monitor program you are running when you
aren't doing anything else) and this INFO program are examples of jobs.
Like the number of net ports, the number of job slots is limited, and
it varies from site to site.

If you want to find out about system status, you can call the LOADP
program by typing

		:LOADP

If you type ^Z and :LOADP now, you'll see something which looks like this:

     12 users idle less than 1 minute.
     5 idle 1 to 5 minutes.
     3 idle 5 to 10 minutes.
     4 free net ports.
     3 free job slots.
     :KILL INFOJ

Type "P" (or ":CONTIN ", since they do the same thing) to return to INFO.

The load described in the above example is too much for tourist
usage on any machine but MC.

SSTATUS is a DDT command which prints out some other system load
information.  The following guidelines may be helpful in interpreting the
information that :SSTATUS will give you:

[1] Fair share below 40% -- Fair share changes a lot from moment to
    moment, even with light load, but, if it is consistently below
    40% or (Heaven forbid!) 10%, then the system is pretty loaded.

[2] Over 18 users on MC, 15 on AI, 7 on ML and DM.  No matter what
    else is happening, things start to slow down and job slots start
    to get scarce when the number of users starts to climb.

[3] Fewer than 10 job slots.

Any time you get a message from a lab member (or the SYSTEM OVERSEER
or GUNNER) asking that you log out, you should do so immediately.  Even
if the above guidlines indicate that you should be able to stay logged
in, other factors which are not mentioned here may be in play.

File: INTRO, Node: Documentation, Up: Top, Next: Manuals

This node contains documentation about where to find written
documentation on and offline.

* Menu:

* Manuals::		How to order manuals.
* On-line::		On-line (non-interactive) help files.
* Helpers::		Programs that give on-line help.
* Teachers::		Programs that teach things.
* Other::		How to order other documentation (besides manuals).

File: INTRO, Node: Manuals, Up: Documentation, Next: On-line

Available from the MIT Laboratory for Computer Science publications office:

 * MacLisp Manuals ("Saturday Evening" Edition, 1983) are $8.90,
   postage included.

 * The Macsyma Manual (9th edition, maybe out of print) costs $5.00.
   A 10th edition, published in 1982, is available as a three-volume set.
   It costs more; we should look up the price and insert it here sometime.

 * There are two manuals for MDL:

   "The MDL Programming Language" ($4.00)
	describes the language itself.

   "The MDL Programming Environment" ($3.50)
	describes MDL programs that can raise a MDL programmer
	from "basic survival" to "comfortable living".

 * A list of other LCS publications is free.  These include Technical
   Reports, Technical Memoranda, and Progress Reports.

The address of the MIT Lab for Computer Science publications office is

	Publications Distribution
	MIT Laboratory for Computer Science
	545 Technology Square, room 112
	Cambridge, MA 02139

Make all checks payable to "MIT Laboratory for Computer Science."

Please add $1.00 per order for postage and handling unless otherwise
noted.

		-----     -----     -----

Available from the publications office of the MIT A.I. Laboratory:

 * The Lisp Machine Manual

 * A list of AI Lab publications is free.  These include Technical
   Reports, Memos, Working Papers, Books in Print, etc.

The address of the MIT A.I. Lab publications office is

	Publications
	MIT Artificial Intelligence Laboratory
	545 Technology Square, room 908
	Cambridge, MA 02139

Make all checks payable to "MIT Artificial Intelligence Laboratory."

File: INTRO, Node: On-line, Previous: Manuals, Up: Documentation, Next: Helpers

This node contains nodes which are the long documentation files for
some of the major user programs available.  These files are on-line
with more or less complete documentation about certain major aspects
of the system.  (These files are ones which are not currently
structured for the INFO program.)

* Menu:

* ITS Intro: (.INFO.;ITS PRIMER)*
	A more formal (and longer) introduction to the MC system

* DM Intro: (DM:.INFO.;ITS INTRO)*
	An even longer introduction to the DM system

* DDT Doc: (.INFO.;DDTORD >)*
	Full documentation of DDT
				
* DDT History: (.INFO.;DDT ARCHIV)*
	In reverse chronological order, the changes made in recent
        revisions of DDT

* MDL Doc::
	This node describes how to get documentation using programs
	and files available especially for this purpose (on DM only).

* EMACS Doc: (EMACS)Top
	EMACS is an editor which is very smart about how to edit
	files using a display terminal.  If you have a CRT capable
	of writing anywhere on the screen (that is, not just on the
	bottom line), this is probably for you.

* TECO Doc: (.TECO.;TECORD)*
	This file contains full documentation on the Teco text
	editor.  TECO is an old but reliable text editor used now
	mostly by people on printing terminals.

	Note: ITS TECO is not the same as DEC's version.  Read the
	documentation before using it (especially for any commands 
	starting with "F" or "E", which are all different on ITS). 

Other files on the .INFO. directory may also be useful.
Do ":LISTF .INFO." for a list of the files.

There is also an INFO directory, which contains files in a format
used by the :INFO program.  Don't bother to print these; run :INFO
instead, since it knows how to read those files in a nicer way!

File: INTRO, Node: MDL Doc, Previous: On-line, Up: On-line

The MUDMAN directory is the place to look for documentation on MDL.
There are two separate "manuals" on this directory.  The larger is
an on-line copy of the printed "The MDL Programming Language". It is
contained in the file DM:MUDMAN;REFERENCE MANUAL.  Its separate
chapters are in the ARChive file DM:MUDMAN;ARC MANUAL.  You can
"step through" it a chapter at a time by

   :PRINT MUDMAN;ARC:CHAP01 >

and incrementing the chapter number until you run out of them.

The :MUD program on DM may be useful in obtaining documentation on
individual primitives (SUBRs or FSUBRs) from a shorter on-line
reference manual (MUDMAN;MUDDLE ORDER).  Sample usage:

   :MUD
	This command will list all of the MDL SUBRs and FSUBRs and a short 
	(one-line) description of what they do.

   :MUD MAPF
	This command will describe the MDL SUBR MAPF.

File: INTRO, Node: Helpers, Previous: On-line, Up: Documentation, Next: Teachers

This node deals with programs running on ITS that give helpful
information or documentation about programs not described through
INFO.

The following other methods of obtaining info on this machine's
programs are available (in addition to the INFO which you are now running):

:?
  This will give a full list of DDT commands.

:LUSER
  This will send a message to any system people now logged in,
  saying that you are in trouble or greatly confused and need help.
  It will send to a large number of people if all the helpers are
  logged in, so try not to rely on it always, but these people can
  be very helpful if you are really lost.

:SEND
  (fully described in the section on SEND/MAIL commands in this
  file) can be used of course, too.  If you're wondering whom to
  ask, do :NAME and pick a system native out of the logged-in users.
  Natives to MC  will have an "M" by their names, natives to ML a
  "P" or "Z",  natives to AI an "A", and natives to DM a "D".  They
  can  probably either answer your question or suggest someone else
  who can  help.

>>> How NEVER to request info:

:SHOUT
  This is a command to send a message to all users.  It works like
  :SEND but doesn't need a name of a person to send to, since it
  sends to all logged-in users.  This is NOT for casual use, since
  it interrupts everyone.  If you are thinking of using this to find
  out the answer to a question, don't.  Use :LUSER, which will
  bother only people who have volunteered to help out in such
  situations.

  This command also DOES NOT put something in the system messages
  that you see when you log in.  The way to send a system message is
  documented elsewhere in this file.

File: INTRO, Node: Teachers, Previous: Helpers, Up: Documentation, Next: Other

There are a few programs available, which will actually attempt
to teach you how to use themselves: EMACS (a text editor) and
MACSYMA (a symbolic algebra system (running on MC only)).  This
node will tell you about how to start them up in teaching mode.

:TEACHE
  This program works only if you are on a display terminal (CRT
  which can display on other than just the bottom line of the
  screen) and ITS knows your terminal type (via :TCTYP).  This
  program will teach the EMACS editor -- by far the fanciest and
  most powerful of the editors available.

On the MC machine (ARPAnet host 236 decimal), the following are also available:

:TEACHM
  This program goes through a basic primer for the Macsyma language,
  interactively.  Macsyma doesn't run on ITS machines other than MC,
  so neither does this program.

:TEACH;LISP
  This program offers an interactive introduction to the Maclisp language.
  It is also available at MIT-OZ as <KMP.TEACH>TEACH-LISP.


File: INTRO, Node: Other, Previous: Teachers, Up: Documentation

This node contains information about ordering Macsyma documentation
via US Mail.

Documentation, which accompanies orders for Macsyma manuals
automatically, but which may be ordered separately if needed,
includes:

	"An Introduction To ITS for the Macsyma User" -- $1.00
	(available on-line as .INFO.;ITS PRIMER)

	"The Macsyma Primer" -- free
	(available on-line and interactively through :TEACHM)

   If you need a photo-copy of these, you can send mail to
MATHLAB-SECRETARY (that is, :MAIL MATHLAB-SECRETARY ...) asking for
info.  If you don't know how to send mail, there are directions
elsewhere in this piece of documentation.

   If you are not planning to use Macsyma regularly, don't ask
for the documentation unless you are seriously interested
in it and cannot obtain it another way.  Remember that you are
asking a favor of the secretary, so don't irritate her with
messages like "Send one manual immediately to ..." -- introduce
yourself and explain that you would appreciate it, etc., and you 
will have a much better chance of being taken seriously.