From c0cea682186b2dd1cec719fec182366227d10a2f Mon Sep 17 00:00:00 2001 From: Lars Brinkhoff Date: Tue, 8 Nov 2016 09:28:48 +0100 Subject: [PATCH] Add ITS intro manual. --- doc/README.md | 3 +- doc/info/intro.29 | 958 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 960 insertions(+), 1 deletion(-) create mode 100755 doc/info/intro.29 diff --git a/doc/README.md b/doc/README.md index e3422089..bcb3ff05 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,6 +1,7 @@ ## Documentation -- ITS: [primer](_info_/its.primer), [building](kshack/build.doc) +- ITS: [intro](info/intro.29), [primer](_info_/its.primer), + [building](kshack/build.doc), [Getting Started Computing at the AI Lab](ai_wp_235.pdf) - DDT: [manual](info/ddt.33), [commands](_info_/ddtord.1462), [colon commands](_info_/ddt.:cmnds) diff --git a/doc/info/intro.29 b/doc/info/intro.29 new file mode 100755 index 00000000..50ebb0c7 --- /dev/null +++ b/doc/info/intro.29 @@ -0,0 +1,958 @@ +-*-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: + + : ; + +where = DSK, = MYDIR, = MYPROG, and + = NEW. + +What follows is a description of the four fields of a file name: + + - 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. + + - the name of the directory (if applicable). Most devices + (like DSK for example) do use directories of some sort. + + - the first 1-6 characters of the file name. + + - 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: + +:; + +File: INTRO, Node: Abbrevs, Previous: Basic, Up: Names, Next: Convention + +If you wish to omit or -- or rearrange their +order -- that's OK. DDT recognizes the device because it ends +with a ":" and the directory because it ends with a ";". + and 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 + + : + +DDT will look for a file named "TS " 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) => LOGIN + .DDT_ (INIT) => LOGOUT + .EMACS (INIT) => EMACS + .TECO. (INIT) => TECO + .LISP. (INIT) => LISP + MACSYM (INIT) => 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 + +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 , + This will change the name of to -- + providing they are both on the same directory. + +:COPY , + This will copy a file named anywhere, including + between directories, to the location specified by . + Be careful that you have no existing , because it + will be destroyed by this operation. + +:MOVE , + This is just like :COPY but deletes if the copying + to is successful. + +:DELETE + This makes 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 , 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 + +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 "^". + +, , 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 , type the key marked or + or on your terminal. It will echo as a . + Very few programs mean $ (dollar sign) when they echo the + dollarsign - most mean . 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 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 + +where 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 + lists personal description of 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 ^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 at