Google
 

Trailing-Edge - PDP-10 Archives - bb-m836d-bm - tools/sed/sed.rno
There are 13 other files named sed.rno in the archive. Click here to see a list.
.PS 57 68 .AUTOP
.VAR OLDTAB A B
.VAR NEWRUN A B
.IF NEWRUN
.HEADER BOTTOM
.ENDIF NEWRUN

.C;INSTALLATION MANUAL
.C;HOW TO ADAPT A TERMINAL TO THE SED SCREEN EDITOR
.C;BY A CHRISTOPHER HALL
.C;July 1983
.S1
.C;ADAPTING SED TO A TERMINAL

This is a step-by-step description of how to build the tables for SED,
for your terminal.

First, look at SEDTTY.MAC and see if your terminal is one of the ones which
already has tables defined. If so, read Appendix B. Then set the right FXXXXX
to 1 (for example, for the VT100, set FVT100==1), and compile and load SED by
typing the following commands:

.S1 .LIT
on TOPS-10:                    on TOPS-20:
    .LOAD SEDSYM,SEDTTY,SED        @LOAD SEDSYM,SEDTTY,SED
    .SS SED                        @SA SED
.EL

Beware of using terminal tables which were written for a terminal which is
similar to, but not the same as, your own. Terminals are sickeningly
different, and it's likely that the tables will not quite be right. However,
if you keep this warning in mind, you can use an existing set of terminal
tables as a starting point.

If any of your terminal types are not defined in SEDTTY.MAC you will need to
write the terminal tables to support them. There are two tables: one tells SED
what to output to the terminal to get certain things to happen (such as
clearing the screen or moving the cursor); the other tells which control
characters and sequences invoke which editor commands. There also must be two
subroutines which move the cursor, and maybe other routines to do
terminal-dependent things, like special stuff on entry to and exit from SED.

The materials you will need to write these tables and routines are the file
SEDX.MAC, which serves as the framework to build upon, and the terminal
manual which describes which character sequences move the cursor, clear the
screen, and do the other terminal functions. Also, you can use the program
SEDECO (as in SED ECHO) to make the terminal echo back the characters that
are output by its special keys, or to see how the terminal behaves when
certain sequences are typed in. See Appendix A for information on how to
run SEDECO.

If you have more than one type of terminal you will probably want to put your
new terminal modules in SEDTTY.MAC, since it contains code to read the type
from the monitor and set up the right tables. See Appendix B and the
information at the start of SEDTTY.MAC, in addition to the rest of this manual.

You can also use the other terminal definitions in SEDTTY.MAC to provide
a lot of guidance as to how your tables should look.

.PG
.C;THE TERMINAL OUTPUT TABLE

After the initial stuff in SEDX.MAC is the terminal output table. It contains
the sequences which SED must send to the terminal in order to get things to
happen. The bare table looks like this:

.S1 .LIT
ONAME:  BYTE (7) 0              ;CURSOR UP
        BYTE (7) 0              ; DOWN
        BYTE (7) 0              ; RIGHT
        BYTE (7) 0              ; LEFT
        BYTE (7) 0              ; HOME
        BYTE (7) 0              ;CLEAR TO END OF PAGE
        BYTE (7) 0              ;CLEAR TO END OF LINE
        BYTE (7) 0              ;ROLL UP AND CLEAR LINE
        BYTE (7) 0              ;ROLL DOWN AND CLEAR LINE
        BYTE (7) 0              ;PROTECT ON (CPOPJ IF NONE)
        BYTE (7) 0              ;PROTECT OFF (CPOPJ IF NONE)
        BYTE (7) 0              ;INSERT LINE (0 IF NONE)
        BYTE (7) 0              ;INSERT SPACE (0 IF NONE)
        BYTE (7) 0              ;DELETE LINE (0 IF NONE)
        BYTE (7) 0              ;DELETE SPACE (0 IF NONE)
        BYTE (7) 0              ;MOVE TO BOTTOM
        BYTE (7) 0              ;HOME AND CLEAR ENTIRE PAGE
        CPOPJ                   ;ROUTINE TO POSITION TO CHARACTER
        CPOPJ                   ;ROUTINE TO POSITION TO START OF LINE
        ^D24                    ;LINES PER PAGE
        ^D80                    ;CHARACTERS PER LINE
        0                       ;TERMINAL-DEPENDENT FLAGS
        CPOPJ                   ;ROUTINE TO CALL ON ENTRY
        CPOPJ                   ;ROUTINE TO CALL ON EXIT
        0,,0                    ;NUMBER OF NULLS TO OUTPUT,,NULL CHARACTER
        ITABLE                  ;ADDRESS OF INPUT CHARACTER TABLE
IFN FTIMD,<
        0                       ;START INSERT MODE
        0                       ;END INSERT MODE
>
        0                       ;MARK TO DISPLAY ON ENTER (OMIT IF MRK NOT SET)
.EL .S1

There's not much there, since filling it in is what this cookbook is all
about.

.S2 .I0
CURSOR MOVEMENT

First, look in the terminal manual to find which character sequences move
the cursor up, down, right, left, and home (the upper left corner).
Put each sequence is the appropriate slot of the table.

If the sequence is five characters or less, put the sequence itself in the
table. For example if CURSOR-UP were "ESCAPE A" the first word of the table
should contain

.S1 .LIT
        ONAME: BYTE (7) 33,"A"
.EL

If the character sequence is longer than 5 characters, use the following
format:

.S1 .LIT
        ONAME: 37777,,[BYTE (7) 33,"A","B","C","D","E","F"]
.EL

If the sequence depended on something variable, like, say, the current cursor
position, you would need to write a subroutine to handle the operation. Then
put the label of the routine in the appropriate slot of the table, thusly:

.S1 .LIT
        ONAME: MOVRGT
.EL

Usually the cursor positioning sequences are short enough to be done the
first way. The terminal may not be able to move the cursor home (the upper
left corner) in a single command; in that case put the sequence to
position to (0,0) or (1,1) in the CURSOR-HOME slot of the table.

.S2 .I0
CLEAR TO END OF PAGE

The next table entry is the sequence which clears the screen from the cursor
position to the end of the page. Note: this is NOT the sequence to clear the
entire screen. Not all terminals can clear to end of screen. If yours does,
enter the sequence in the table in one of the three formats described
above. If your terminal can't clear to end of screen, put a zero in the
table position. The zero tells SED to find some other way of clearing, and
nothing else is required from you.

.S2 .I0
CLEAR TO END OF LINE

Next comes the sequence which clears from the cursor position to the end of
the line. Set this up as above. If your terminal can't do it put a zero in
the table (which tells SED to simulate the clear by outputting spaces. Hope
your baud rate is high).

.S2 .I0
ROLL SCREEN UP AND CLEAR LINE

This is the sequence which will cause the terminal to move every line on the
screen up one, make the top line disappear, and clear out the bottom line.
You can assume that the cursor is at the bottom left of the screen when this
sequence is output.

For most terminals, this operation is done by outputting a linefeed (Octal
12). Some terminals can do it other ways, too, but if linefeed works use it.
Put the linefeed or the sequence in the table in the usual way.

Beware: on some terminals the bottom line is not cleared, but is actually the
old top line wrapped around. If this happens, you will need to put in the
sequence to clear to end of line after the sequence to roll. If that's more
than 5 characters use the long (second) format described in the cursor
movement section.

If your terminal can't roll up (and some can't), put a zero in the table.
Then if SED wants to roll it will rewrite the screen.

.S2 .I0
ROLL SCREEN DOWN AND CLEAR LINE

This is similar to the above, except movement is in the opposite direction.
You can assume that the cursor is home when this sequence is output. Handle
this the same way as the ROLL UP sequence. Put in a zero if you ain't got it.

Many terminals can roll up but cannot roll down, so it's common to see a
zero here and a sequence in the ROLL-UP position. Then SED will roll up but
rewrite the screen if it has to roll down, which is the best it can do
under the circumstances.

.S2 .I0
TURN HIGHLIGHTING ON AND OFF

Highlighting is anything which makes some characters on the screen stand
out from the rest. Reverse video, blinking, and half brightness are the
most common examples. Not many terminals can highlight, so I'll take the
negative case first.

If all you can get are normal vanilla characters, put a zero in each of these
two table positions. Then write down two things to do later: set the MRK flag
when you come to the flag word, and define a mark in the last word of the
terminal table. Both of these will be taken up below.

SED uses highlighting in the following manner: it outputs the sequence to
turn highlighting on, then the highlighted characters (which will always be
on the same line), then the sequence to turn highlighting off. Check to
make sure your terminal's highlighting works that way; most do; some don't.
If yours doesn't work that way, don't highlight.

Put the sequences which turn on and turn off highlighting in the two table
positions. The choice of what kind of highlighting is done is up to you.
Reverse video is usually the most noticeable and least irritating.

.S2 .I0
INSERT AND DELETE LINES AND SPACES

The next four functions, INSERT-LINE, INSERT-SPACE, DELETE-LINE, and
DELETE-SPACE, are found only on fairly sophisticated terminals, but they
save SED a lot of work when they exist. If they don't exist put zeros in
the table positions (it's quite permissible to have zeros in some positions
and sequences in others).

INSERT-LINE puts a blank line above the line where the cursor is, moves the
rest of the screen down one line, and the bottom line goes off the screen.
DELETE-LINE removes the entire line where the cursor is and moves
everything beneath up a line. The new bottom line is blank.

INSERT-SPACE puts a space where the cursor is and moves the rest of the line
one space to the right. Characters which go off the right of the screen must
go away, not wrap around to the next line. DELETE-SPACE removes the character
(not necessarily a space) beneath the cursor and moves the rest of the line
one space to the left. The new rightmost character on the line is a space.

If your terminal has any of these, enter the appropriate sequence or
subroutine label in the table. Beware: the four functions must behave as
described above. Almost all do, but some don't.

Terminals work in wondrous ways. The VT100, for example, cannot do any of
these things, but it can limit it's scrolling region. It turns out that that
capability can be used to simulate a hardware INSERT- and DELETE-LINES. See
the file SEDV10.MAC to see how it's done. The moral is that there's more than
one way to skin a cat; be creative.

Also, some terminals can insert a space and some have insert mode (which
you turn on, output the characters you want to insert, and then turn off).
If your terminal has the only latter, simulate the former by putting in
that slot "START-INSERT-MODE, SPACE, END-INSERT-MODE".

A final note: Some terminals can insert or delete any number of lines or
spaces in one sequence. You

.S2 .I0
MOVE TO THE BOTTOM OF THE SCREEN

The next function is something which terminals usually can't do in one
operation, but which SED finds useful. You can move to the bottom left of
the screen in a number of ways: for example, move HOME and UP (if the
cursor does not stick to the margins of the screen), or position the cursor
absolutely.

Whatever way you choose to reach the bottom of the screen, put that
sequence in the table. You must have something in this table position, a
short or long character sequence or a subroutine label. Not a zero.

.S2 .I0
HOME AND CLEAR ENTIRE PAGE

Almost every terminal can clear its entire screen. That sequence goes here.
Sometimes the cursor is moved HOME automatically when the clear occurs,
sometimes it is left wherever it is. In that latter case, you must include
the sequence to move the cursor home, before or after the clear.

This table position can't contain a zero either.

.S2 .I0
CURSOR POSITIONING ROUTINES

The next two table positions contain the addresses of subroutines which move
the cursor to absolute positions on the screen. The first routine moves to
the row contained in accumulator RW and the column contained in CM. The
second moves the cursor to the start of the row contained in AC T4.

The cursor positioning subroutines themselves are part of the terminal
module you are writing. Unfortunately there are nearly as many cursor
movement algorithms as there are terminals, so I can't help you much here.
Find out from your handy terminal manual how to move the cursor around, and
write the routines.

The file SED.POS contains sample cursor movement subroutines, ones which
are used in SEDTTY.MAC If your algorithm is included among them, just copy
the routines into your terminal module. Otherwise you're on your own, but
you can use the routines in SED.POS as guides.

.S2 .I0
LINES PER PAGE AND CHARACTERS PER LINE

The next two table positions contain values: the number of lines on the
screen and the number of characters per line.

.S2 .I0
TERMINAL-DEPENDENT FLAGS

There are a number of flags which alter SED'S performance. Most deal with
terminal characteristics, and must be set in the right way for SED to work
right.

The flags are:

.S1 .LIT
        TBS    HARDWARE TABS EXIST (AND ARE PRE-SET)
        WRP    LONG LINES WRAP AROUND TO NEXT LINE OF SCREEN
        MRK    NO PROTECTED FIELDS; THUS, MARK NEEDED ON ENTER
        NEL    DON'T BOTHER RE-WRITING LAST LINE OF SCREEN
        SLW    SLOW TERMINAL: WRITE ERROR MSGS ON BOTTOM LINE
        NLP    SEND NULLS AFTER ABSOLUTE CURSOR POSITIONING
        NPG    DON'T SET TTY NO PAGE (^S AND ^Q REMAIN XOFF AND XON)
.EL .S1
Explanations:

(TBS) If hardware tabs do not exist they must be simulated using
CURSOR-RIGHT's. Beware: a lot of terminals have hardware tabs, but they must
be set up by someone. If SED expects tabs but they are not set up it will go
bananas, so don't set the TBS flag for these terminals (or enable the tabs in
the terminal-specific entry subroutine, described below).

(WRP) Lines in the file which are too long for the screen will either lock
on the right margin or wrap around to the next line, depending on the
terminal. SED's display routine needs to know which one the terminal does,
or else long lines will not display properly. Note: some terminals, such as
the VT100 (in wrap mode) will wrap before the 81st character is typed,
rather than after the 80th. Do not set the WRP flag for those terminals and
they will work o.k.

(MRK) A protected field is one which SED wants to highlight. For example,
when you type ENTER, SED will highlight the character at the cursor position
(by making it reverse video, for example). It's useful to mark that cursor
location, so if the terminal does not have any highlighting features, the MRK
flag indicates that a certain mark should be put at the cursor location when
ENTER is typed. The character code for that mark is contained in the last
word of this table (if MRK is not set that mark word can be omitted).

(NEL) Make SED not care about keeping the bottom line of the screen up to
date. If your terminal runs at a slow speed, but has enough lines on the
screen that it can afford to give one away, then some re-write time can be
saved by setting the NEL flag.

(SLW) Causes error messages to be written on the bottom line of the screen.
The remainder of the screen is not affected (normally the whole screen is
erased and re-done). You can save SED a lot of rewriting by setting the SLW
flag; set it if your terminal is slow. In fact, set SLW anyway; it's error
display is more fun than the default way.

(NLP) If your terminal needs to idle a while after positioning the cursor, set
the NLP flag, and set the NUL word of the table to the number of nulls to
send and the character to use.

(NPG) Some terminals that run at 9600 baud (and others) will send CONTROL-S
(XOFF) to the computer to tell it to stop transmitting and CONTROL-Q (XON)
to tell the computer to resume. SED cannot distinguish XOFF and XON from
DELETE-SPACES and ROLL-BACK-PAGES, so if the terminal persists in sending
XON's and XOFF's set the NPG flag and don't use CONTROL-S and CONTROL-Q as
editor commands.

Some terminal modules in SEDTTY.MAC have a switch which contains the word
"FAST", and then duplicate table definitions (in some cases, entire
duplicate tables) which implement SED with XON-XOFF either on or off.
The VT100 family tables are an example.
This was usually done because if the terminal is run at slow speeds (less
than 4800), CONTROL-S and CONTROL-Q can be used as editor commands, but if
they are run at 4800 or 9600 then those characters must be used as
XON-XOFF.

.S2 .I0
ENTRY AND EXIT ROUTINES

If your terminal needs to be initialized (TABS set up, for example), write
a subroutine to do whatever is necessary and put its address in the
appropriate table position. That routine will be called just before SED
reads in the file you want to edit. Similarly, if you need to reset things
before exiting from SED, write a subroutine and put its address in the next
table position. That routine is called just before SED exits.

If nothing special needs to be done put a CPOPJ in these positions.

.PG .I0
NUMBER AND TYPE OF NULLS TO OUTPUT

There are a number of situations where SED needs to delay and let the
terminal finish what it is doing. The most reliable delay tactic is to send
some nulls to the terminal. A null is any character which causes no action
from the terminal. 000 is the classic null, but beware: some terminals or
communication lines ignore 000's, and the desired delay does not occur.
Suggestions: RUBOUT (177) or CONTROL-F (006). Anyway, the situations which
need a delay are set up in the terminal characteristics flags, described
elsewhere, and the number of nulls to output for each delay and the null
character are defined in the NUL word of the terminal output table. If no
delay is ever required (the "usual" case) set the NUL word to 0 and don't set
any of the NL? characteristics flags.

.S2 .I0
ADDRESS OF THE TERMINAL INPUT TABLE

The terminal input table tells which sequence of characters coming from the
terminal invoke which commands. The next section of this manual describes how
to write the input table.

Put the address of the input table in this position.

.S2 .I0
START OR END INSERT MODE

These two table slots are under a feature test switch, FTIMD, which is
defined in SEDSYM.MAC. Its default value is on (==1). Start/end insert mode
are new entries in the terminal output table, and the FTIMD switch is
included for compatibility with older versions of SED. If you are
installing SED for the first time, leave FTIMD set and include these two
table slots, even if your terminal doesn't have insert mode. If you are
re-installing SED, please modify your terminal modules to include the
insert mode slots, and leave FTIMD on.

If your terminal has insert mode SED can output START-INSERT-MODE. Then
any characters (on the same line) be "inserted" into the line - existing
characters will be pushed to the right; not overwritten. Outputting
END-INSERT-MODE will return the terminal to normal replace mode. If your
terminal does not have insert mode, put zeroes in both slots.

If the sequences for START-INSERT-MODE and END-INSERT-MODE are the same, no
sweat. Put the same sequence in both table slots. SED will understand.

.S2 .I0
MARK TO DISPLAY ON ENTER

If you do not have the MRK flag set, skip this. You don't even need to
include this word in the table, and it will be ignored if it is there.

If you have MRK set (usually because your terminal cannot highlight
characters), put in this table position the single character which you would
like to be displayed as a place marker in your file. Any character will do,
but a little experimentation may be needed to decide on one which is easy to
locate on the screen.

.PG
.C;THE TERMINAL INPUT TABLE

The terminal input table tells what you type at the terminal to invoke
which commands. Building this table takes a little more work than building
the output table, because you can set up the editor commands on the keyboard
just about any way you want.

.S2 .I0
ARRANGING THE COMMANDS

The first step is to find out what things on your terminal keyboard can
be used to invoke commands. Control characters should be used for most of
the commands, as they are the easiest to type. Any special keys can also be
used as commands; look in your terminal manual to find out what sequences
of characters those keys transmit.

There are 55 commands. If you don't have enough control characters and special
keys to take care of them all you can set up the remainder as control
sequences (a control character followed by one or more characters). For
example, you might define the <WINDOW> command as ESCAPE#W, <MARK> as
ESCAPE#M, and <CASE> as ESCAPE#C. The SED user would be expected to type
those two-character sequences in order to invoke those commands (so set up
the less frequently used commands this way).

Note that if you use a control character as the start of a sequence it cannot
also be used by itself to invoke a command. If CONTROL-A#L is <SLIDE-LEFT>,
then CONTROL-A alone cannot be a command.

When you have a list of the available control characters and sequences,
link them up with ther editor commands. Use the worksheet on the next page,
if you like.
.PG
.C;WORKSHEET (PAGE 1)
.C;WHICH COMMANDS ARE INVOKED BY WHICH TERMINAL SEQUENCES

.S2 .LIT
   COMMAND           NORMAL  YOUR          COMMAND           NORMAL  YOUR
NAME AND TITLE     SEQUENCE  SEQUENCE   NAME AND TITLE     SEQUENCE  SEQUENCE

         Cursor Movement                     Inserting and Deleting

$CURUP CURSOR-UP             ______     $INSSP INSERT-SPACES      ^A ______

$CURDN CURSOR-DOWN           ______     $DELSP DELETE-SPACES      ^S ______

$CURLF CURSOR-LEFT           ______     $INSLN INSERT-LINES       ^D ______

$CURRT CURSOR-RIGHT          ______     $DELLN DELETE-LINES       ^F ______

$CURHM CURSOR-HOME           ______     $PICK  PICK               ^V ______

$RETRN CARRIAGE-RETURN    ^M ______     $PUT   PUT                ^G ______

$TAB   TAB                ^I ______     $MARK  MARK                  ______

$BKTAB BACKTAB            ^U ______     $DELCH DELETE-CHARACTER   ^H ______

$BLINE BEGIN-LINE            ______     $ERSWD ERASE-WORD            ______

$ELINE END-LINE              ______     $ERSLN ERASE-LINE         ^J ______

$UPTAB UP-TAB                ______                 Searching

$DNTAB DOWN-TAB              ______     $SRCFW SEARCH-FORWARD     ^R ______

         Screen Motion                  $SRCBK SEARCH-BACKWARD    ^E ______

$ROLBP ROLL-BACK-PAGES    ^Q ______     $SUBST SUBSTITUTE            ______

$ROLFP ROLL-FORWARD-PAGES ^Y ______               File Control

$ROLBL ROLL-BACK-LINES    ^W ______     $EXIT  EXIT               ^Z ______

$ROLFL ROLL-FORWARD-LINES ^T ______     $ABORT ABORT              ^C ______

$SLDLF SLIDE-LEFT         ^K ______     $STFIL SET-FILE           ^B ______

$SLDRT SLIDE-RIGHT        ^L ______     $SAVE  SAVE-FILE             ______

$GOTO  PERCENT-GOTO       ^P ______
.EL .PG
.C;WORKSHEET (PAGE 2)
.C;WHICH COMMANDS ARE INVOKED BY WHICH TERMINAL SEQUENCES

.S2 .LIT
   COMMAND           NORMAL  YOUR
CODE AND NAME      SEQUENCE  SEQUENCE

         Parameter Control

$ENTER ENTER-PARAMETER       ______

$RESET RESET          RUBOUT ______

$RECAL RECALL                ______

           Miscellaneous

$SWTCH SWITCH             ^N ______

$ENTCC ENTER-CONTROL-CHAR ^O ______

$EXEC  EXECUTE            ^X ______

$INMOD INSERT-MODE           ______

$RLTAB REAL-TAB              ______

$CASE  CASE                  ______

$WINDO WINDOW                ______

$RWRIT RE-WRITE              ______

$HELP  HELP                  ______

$TBSET TAB-SET               ______

$JUSTI JUSTIFY               ______

$MARKR MARKER                ______

$ERROR ILLEGAL-COMMAND       ______

$PUSH  PUSH (TOPS-20 ONLY)   ______
.EL .PG

If the "normal" sequences given above seem a little chaotic it is because the
commands are arranged on the keyboard so that similar commands are nearby.
The name of the key has nothing to do with the nature of the command invoked.
Most SED users agree that this system is better than having commands linked
to keys which are mnemonic but which are located far apart (like CONTROL-F
and CONTROL-B for <SEARCH-FORWARD> and <SEARCH-BACKWARD>, for example).

The general layout is:

.S1 .LIT
          .____.____.____.____.____.____.____.____.____.____.
          !  Q    W !  E    R !  T    Y !  U    I !  O !  P !
          !      ROLLS AND SEARCHES     !         !ENTR!PERC!
          !     BACK          FORWARD   !  TABS   !CCH !GOTO!
          !_.__!____!____!____!_.__!_.__!_.__!_.__!____!_.__!
            !  A    S    D    F !  G !  H !  J !  K    L !
            !                   !    !CUR !ERAS!         !
            !   INSERT/DELETE   !PUT !LEFT!LINE! SLIDES  !
            !_.__!_.__!_.__!_.__!_.__!_.__!_.__!_.__!____!
              !  Z !  X !  C !  V !  B !  N !  M !
              !    !    !    !    !SET !    !RE- !
              !EXIT!EXCT!ABRT!PICK!FILE!SWCH!TURN!
              !____!____!____!____!____!____!____!
.EL .S1
Also, RESET is invoked by the RUBOUT (DELETE) key.

Most terminals have special keys with arrows on them which can be used
for the cursor movement commands. The terminal manual will tell you what
sequences they send. If there is no key for <CURSOR-HOME>, locate it near
the arrow keys.

.S2 .I0
SETTING UP THE TABLE

Now it's time to introduce you to the terminal input table itself.
In SEDX.MAC the table looks like:

.S1 .LIT
            EXP     $RESET                          ;RUBOUT
    IVT52:  EXP             $RECAL, $INSSP, $SETFI  ;   0, A, B
            EXP     $ABORT, $INSLN, $SRCBK, $DELLN  ;C, D, E, F
            EXP     $PUT,   $DELCH, $TAB,   $ERSLN  ;G, H, I, J
            EXP     $SLDLF, $SLDRT, $RETRN, $SWTCH  ;K, L, M, N
            EXP     $ENTCC, $GOTO,  $RLBKP, $SRCFW  ;O, P, Q, R
            EXP     $DELSP, $RLFWL, $BKTAB, $PICK   ;S, T, U, V
            EXP     $RLBKL, $EXEC,  $RLFWP, $EXIT   ;W, X, Y, Z
                    -SV52.S,,SV52.T                 ;ESCAPE
            EXP     $PUSH,  $CURRT, $SUBST, $SAVE   ;\, ], ^, _
.EL

The 5th slot in the table, for example, tells what happens when the user
types a CONTROL-E (which has Octal code 5); the 34th slot tells what
happens to a CONTROL-_\ (which might be invoked by a special or cursor
movement key); and so forth.

The command which is invoked by the RUBOUT (or DELETE) key is given by
the location just ahead of the table (in this case $RESET).

If a control character invokes a command directly the corresponding slot
in the table contains the name of that command. If CONTROL-B invokes
the <SET-FILE> command then slot 2 of the table contains $SETFI. If
CONTROL-B invoked <SEARCH-FORWARD> then slot 2 would contain $SRCFW.

Things get more complicated when it comes to control sequences. In this
example, ESCAPE (slot 33) is the start of a number of control sequences
(the example is based on a VT52 terminal, where ESCAPE is the first
character sent out by all the cursor movement and special keys). Slot 33
contains not a value but a pointer to a subtable. The right half of the
pointer is the address of the subtable and the left half is the negative of
its length.

The subtable might look like:

.S1 .LIT
        SV52.T: $CURUP,,"A"
                $CURDN,,"B"
                $CURRT,,"C"
                $CURLF,,"D"
        -SV52.S==.-SV52.T
.EL

Here, <CURSOR-UP> is invoked by Escape-A, <CURSOR-DOWN> by Escape-B,
<CURSOR-RIGHT> by Escape-C, and <CURSOR-LEFT> by Escape-D. More details
about subtabled are given in the next section.

.PG .LM3 .P-3
.C;PROCEDURE FOR WRITING THE TERMINAL INPUT TABLE

A) Look in the terminal's manual to see which sequences are output by
cursor movement keys and any other special keys which you want SED to use.
Note that the first character of those sequences cannot be used for commands.
For example, if the cursor movement keys are Control-D A, Control-D B,
Control-D C, and Control-D D, then don't make Control-D by itself invoke a
command (on most terminals, these sequences start with Escape, but there
are lots of exceptions).

.S1 .I0
Also note special keys which send control characters. If the Cursor-Down
key sends Control-J, then Control-J on the keyboard must also mean
Cursor-Down. SED can't tell the what key was typed, just what sequence was
sent. In the standard layout, Control-J is <ERASE-LINE>, but in this case
you will have to find some other sequence for that command.

B) Fill in the command worksheets with the control characters and sequences
you want to invoke each command. Note that
Control-_\, Control-_], Control-_^, and Control-__ (Octal codes 34-37) can
all be commands (sometimes they're easy to type, sometimes not). Rubout is
legal, too. Control-Space (Octal 0) is legal on TOPS-10, but not on TOPS-20.

.S1 .I0
You're on your own as to which special keys to assign to which commands. If
your terminal doesn't have special keys, here's your chance to be really
creative. The usual cop-out is to define Escape-Character to mean a command
which is hinted at by the Character (Escape-C for <CASE>, for example).
Escape-Escape can mean <ENTER>.

C) Build the terminal tables, as follows:

1) Put command invoked by Rubout (which is normally $RESET. $DELCH
(<DELETE-CHARACTER>) is also a possibility) in location -1 of the table.

2) For every control character which invokes a single command, put in
the command's name (A==$INSSP, B==$SETFI, etc).

3) For every control character which invokes more than one command, put
in a subtable pointer entry. That entry looks like

.S1 .LIT
        -LENGTH,,TABLE-ADDRESS
.EL

.S1 .I0
There can be more than one subtable.

.S1 .I0
Do steps 2) and 3) for each of the 32 control characters.

4) Now build the subtables. Each subtable looks like:

.S1 .LIT
        SUBTB:  TABLE-ENTRY
                TABLE-ENTRY
                ...
        SUBTL==.-SUBTB
.EL .S1
the pointer in 3) to this subtable is -SUBTL,,SUBTB.

.S1 .I0
TABLE-ENTRY's in the subtable can take a number of forms:

a) If the command is 2 characters long, put in an entry like:

.S1 .LIT
        COMMAND,,CHARACTER  (example: $CASE,,"C")
.EL

b) If it's 2 long but it doesn't matter what the second character is:

.S1 .LIT
        COMMAND,,0
.EL

c) If it's longer than two characters:

.S1 .LIT
        SSTABLE-ADDRESS,,CHARACTER  (example: SSBTAB,,"[")
.EL .S1
SSTABLE is a sub-subtable. It's format is the same as that of the subtable,
with one additional thing: the last entry must be a 0 word, which tells SED
when to stop looking down the table (since it doesn't have a table length
to tell it when to stop).

.S1 .I0
There can be any number of levels of sub-subtables. The number of levels
depends on the number of characters in the sequence that invokes the
command.

.S1 .I0
For example, suppose <CURSOR-UP> is invoked by Escape-[-A (and there are
other commands which start with Escape-[). Then the 33rd location of the
input table would contain "-SUBTL,,SUBTB". There'd be a subtable labeled
SUBTB: containing the entry "SSTAB,,"[" ", and a sub-subtable labeled
SSTAB: looking, in part, like:

.S1 .LIT
        SSTAB:  $CURUP,,"A"
                ...
                0
.EL .S1
That's all there is to it.

.S2 .LIT
SUMMARY: WHAT KINDS OF BEASTS LIVE IN THE TERMINAL INPUT TABLE:

DESCRIPTION        EXAMPLE        WHATZIT

command-name       $SWTCH         name of the command invoked
-length,,address   -4,,SUBTAB     subtable pointer for sequences
                                   which begin with this control
                                   character
-big,,address      -100,,SUBTAB   ditto, if subtable ends with a
zero

BEASTS LIVING IN SUBTABLES:

name,,character    $CURHM,,"H"    code of command whose invoking
                                   sequence ends with the given
                                   character
address,,character SSUBTB,,"O"    sub-subtable pointer for given
                                   character
code,,0            24,,0          command code which will match
                                   on anything
0                  0              optional end-of-table word
.EL

.LM0 .P5
.PG
.C;APPENDIX A - SEDECO

SEDECO is a tool to tell you 1) what character sequences are sent by a
terminal's special keys, or 2) shows you what the terminal does when some
character sequence is typed in.

.S2 .I0
LOOKING AT WHAT THE TERMINAL SENDS

To check out the special keys, edit SEDECO.MAC and set CONV==1. Also, if you
are running TOPS-10, set TOPS10==1. If it's TOPS-20, set TOPS10==0. Then
assemble SEDECO (LOAD SEDECO ... SAVE).

Then run SEDECO. If you type, for example, "ESCAPE A CONTROL-A" SEDECO will
echo "CTRL-[(033)A(101)CTRL-A(001)". That's the name of the character with its
octal code in parentheses. All characters will echo this way, except that
Carriage Return will also move to a new line, and Control-C will exit from
SEDECO. When you push a special terminal key, the characters it sends will
be echoed as above. Most such keys send escape (or some other control
character) followed by a number of printing characters.

Beware: if your terminal keyboard needs to be set up in a special mode (for
example, the VT52 and VT100 needs to be set in alternate keypad mode) you
will have to set it yourself somehow. One good way is to run SEDECO in its
other mode (CONV==0, described below) and type the character sequence that sets
that mode.

.S2 .I0
SEEING WHAT HAPPENS WHEN YOU TYPE THINGS

If you want to see what the terminal does when you type certain character
sequences (for example to verify that the sequence that the terminal manual
says will clear the screen really does so), edit SEDECO.MAC and set CONV==0.
Also, if you are running TOPS-10, set TOPS10==1. If it's TOPS-20, set
TOPS10==0. Then assemble SEDECO (LOAD SEDECO ... SAVE).

Then run SEDECO. Your type-in will be sent to the terminal exactly as you type
it. Printing characters will echo. Escape- (or control character-) sequences
will probably not echo, but will do special things as described in the terminal
manual.

To exit SEDECO, type Control-C.

.PG
.C;APPENDIX B - SEDTTY

SEDTTY contains all the tables and routines for the terminals I know about. It
may interest you for three reasons: 1) if some of your terminals are defined in
SEDTTY it will save you most of the trouble of writing them yourself; 2) if
you have more than one type of terminal, SEDTTY contains code to read the
terminal type from the monitor and decide which tables to use (if you have only
one type of terminal then that code is not assembled, thus saving the wasted
space and overhead); and 3) the tables and routines in SEDTTY can serve as
guidelines for writing your own module(s).

If you have only one terminal type, and it's not included in SEDTTY, you can
either modify SEDX.MAC and load it with SED (as described in SEDX), or add your
stuff to SEDTTY, under the appropriate switch, and load SED with SEDTTY.
SEDTTY contains guidelines for defining labels and symbols in order to make
sure they are not multiply defined. However, with one terminal type, there's
not much advantage in using SEDTTY.

If any of your terminals are defined in SEDTTY, please look over their
input tables to make sure that they do the right things (the output tables
are probably O.K.). Most of the input tables are not up to date, and some
are real old. Most were sent by the people who wrote them so I could
include them in my distribution - they are for terminals I have never seen.
I have not modified them, since I have found that changing something I
can't test is very risky. If you improve an out-of-date terminal tables and
send them to me I'll update my copy of SEDTTY.

The tables for the VT52 and VT100 family of terminals are up-to-date. I use
those terminals every day.

There are two things to be careful of if you want to use the tables for some
terminal other than the VT52 or VT100 family: 1) there may be no sequences
defined to invoke SED's newest commands, and 2) the keyboard definitions
may vary greatly from the standard layout.

Here are SED's newest commands, oldest first. If one of them is missing from
the terminal module, probably the ones newer than it are also missing.

.PG .LIT
CODE    NAME       DESCRIPTION

 50     $ERSLN     Erase from cursor to end of line
 52     $UPTAB     Up-tab (up 6 lines)
 53     $DNTAB     Down-tab (down 6 lines)
 54     $REWRT     Rewrite screen
 55     $SAVE      Save file
 56     $HELP      Give on-line help
 57     $BLINE     Move to start of line
 60     $ELINE     Move to end of line
 61     $ERSWD     Erase previous word
 62     $PUSH      Push to EXEC (TOPS-20 only)
 63     $SUBST     Substitute
 51     $TBSET     Set/clear tab stops (NOTE: out of sequence)
 64     $ERROR     Illegal command (gives an error)
 65     $JUSTI     Justify text
.EL

None of these commands have any "standard" invocation, so you're on your
own as to how to implement them. The $BLINE and $ELINE commands supercede
the $LINE command, which is now obsolete.

.PG
.C;APPENDIX C - MISCELLANEOUS INFORMATION

There are a number of assembly parameters at the beginning of the editor
program:

.S1 .LIT
        STKSIZ==20       ;SIZE OF PUSH-DOWN STACK
        MAXSIZ==^D1200   ;MAXIMUM FILE SIZE (BLOCKS) THAT CAN BE EDITED
        PCBSIZ==600      ;SIZE OF PICK AND CLOSE BUFFER
        PARBLN==40       ;SIZE OF PARAMETER BUFFER
        NOBYTE==140      ;LENGTH OF LOOK-AHEAD WHEN SEARCHING FOR NULLS
        SQZVAL==100      ;NUMBER OF DELETE COMMANDS BETWEEN SQUEEZES
        XBFNUM==50       ;NUMBER OF EXECUTE BUFFERS
        XCFSIZ==XBFNUM*3 ;SIZE OF EXECUTE BUFFER FREE SPACE
        TYPSIZ==40       ;SIZE OF TYPE BUFFER
        JRNSIZ==26       ;SIZE OF JOURNAL BUFFER
.EL

None of these except MAXSIZ, XBFNUM, and NOBYTE should need to be modified
unless the spirit moves you.

.LM5 .P-5

MAXSIZ: SED will not try to edit a file which is longer than MAXSIZ. It is set
as large as it should be. Make it smaller if you want to prevent large
files from being edited.

XBFNUM: tells how many different execute buffers a user can have at the same
time. It can't be larger than 64 (octal 100). The only reason to make
XBFNUM small is is to save memory; however, it won't save much, so don't
bother unless memory is really a problem at your site (Note: XCFSIZ used to
be the size of each buffer, now it determines the size of free space area
from which buffers are allocated dynamically. Three words per buffer
may seem small, but I've found it to work out well. If a user creates
40 buffers most of them are smaller than three words, so he can afford a
couple of long ones.

NOBYTE: tells how far SED looks for nulls when it wants to open a hole in
the file. SED will first look NOBYTE non-zero bytes forward from the cursor
position to see if it can find enough nulls. If it can't find enough it
will then move everything from the cursor position to the end of the file
forward. NOBYTE should be large enough that the desired nulls will be found
often, but small enough that time is not wasted searching for nulls that
are not there. Its optimal value depends on the individual user and what he
is doing to the file. The given value works O.K., whatever O.K. means. If
you want to change NOBYTE, study the results carefully, as it can affect
SED's performance noticeably.

Quick descriptions of the other parameters:

STKSIZ: Size the the push-down stack. This only affects the number of
levels you can stack execute constructs, and 16 is plenty.

PCBSIZ: if a pick or delete is done longer than 5*PCBSIZ characters the
buffer will be written to disk. That costs overhead, so PCBSIZ should be
high. On the other hand, 2*PCBSIZ words of memory total are used for the
pick and delete buffers, so lower it if memory is a problem.

PARBLN: the longest parameter allowed is 5*PARBLN characters. The only large
parameters are search keys (which can be long but usually won't be) and
execute buffers (when read or listed with the R or L formats).

SQZVAL: every SQZVAL times a large delete is done SED passes through the
file and removes null words. Otherwise SED likes to keep nulls around so it
can use them for later inserting. But too many nulls will slow SED down,
since it has to pass over them while looking for other things.

TYPSIZ: Text is output to the terminal when necessary or when SED has
5*TYPSIZ characters to output. A large value saves overhead, a small one
makes SED easier to interrupt while it is re-displaying the screen.

JRNSIZ: If you are writing a journal, your commands are appended to the
journal every 5*JRNSIZ "characters". A command counts as three of these
characters. A small value means the journal is updated more frequently, so
less is lost on a crash; but it costs more overhead. And journaling
overhead is high.

.LM0 .P5

SEDSYM.MAC has a number of switches, some independent of operating system,
and some specific to TOPS-10 or to TOPS-20. They are described below.

.LM5 .P-5

TOPS10: set to one if your operating system is TOPS-10, to 0 if it's
TOPS-20.

FTIMD: Two words were added to the terminal output table, telling how to
enter and exit insert mode. For compatibility with older versions they are
under the FTIMD feature test. My advice is to set FTIMD and add those words
to your table(s).

NEWTAB: A very old version of SED had a slightly different arrangement of
commands. If you don't know what it was, consider yourself lucky and leave
NEWTAB set.

FTJOUR: Journaling is under this feature test switch, and is turned OFF on
the distribution tape. That's because journaling is an expensive operation
and it takes a lot of code. It can be a lifesaver, however, and worth the
cost. If you want your users to be able to journal, set FTJOUR to 1.

FTTST: This switch surrounds code which I am testing, but for some reason
do not want to release. If you're curious go ahead and set it. But don't
say I didn't warn you (I can't describe what things are under FTTST because
they are constantly changing. Look at the sources).

FTDDT: If you're debugging SED a lot, set this switch to 1. It causes the
symbols to stay around.

.LM0 .P5

The following switches are meaningful only on TOPS-10:

.LM5 .P-5

FTKA10: Set this if your processor is a KL-10. Then KI-KL-only instructions
are simulated for the KA.

FTTMPC: If set, FTTMPC causes the information about the previous two files
edited to be written to TMPCOR. If cleared, the it's written to nnnSED.TMP.
Clear it if you don't have much TMPCOR

FTSFD: If FTSFD is 0 SED will not allow sub-file directories on filespecs.
If it's 1, then set SFDLVL to the number of SFD levels that are allowed on
your system.

.LM0 .P5

The following switches are meaningful only on TOPS-20:

.LM5 .P-5

FTSTSN: If FTSTSN is 1, statistics on SED will be entered in the monitor's
subsystem tables. These are possibly useful if you want to track SED's
performance (but I find that an essential datum is missing: what the users
are doing during their editing sessions).

FTECHO: If FTECHO is 0, SED turns off echo and reads characters one by
one. SED outputs printing characters itself. If it's 1 SED allows the
monitor to echo printing characters and terminate on control characters.
When SED is reading a command sequence it puts the terminal in no-echo,
single character read mode. The ==1 method probably puts less of a strain
on the system than the older ==0 method, but it's still experimental. If
you like trying new things, set FTECHO and see how you like it. Ideally
there should be no difference in the way SED acts (in fact, there are
a couple of minor differences), but performance should be better.

.LM0 .P5