 % -*- Mode:TeX -*-
\chapter{The screen editor}\label{editor}

As a preliminary to working on your own set of \cam\
experiments you should familiarize yourself with the Forth screen editor,
since you'll be continually using it.

\section{Editing commands}\label{editing}

As you enter the editor,\footnote
        {From the \cp, with \keye\ or \keyE\ (Section \ref{enter-editor}),
or from Forth, via {\tt EDIT} and related words (Sections \ref{util-edit}).}
        the contents of the selected screen are displayed in an editing window, with
the cursor somewhere on the screen.  You can now move the cursor to any point on the
screen; you can change, insert, delete, or move text; and then either move to another
screen or exit the editor.

Above the editing window is a {\sl status} line telling you the screen
number, the file name, and how far you are into the file (screen 0 is
0\%, last screen is 100\%).  The keyboard is no longer\index{Keyboard/control-panel mode} a \cp\ for \cam;
rather, it has been turned into a smart typewriter\index{Keyboard/typewriter mode}.  Typing ordinary
printing characters places them on the screen at the current cursor
position; the other keys are interpreted as special editing commands;
for example, \keyrubout\ will backspace and rub out the character it
backspaced over.

The editor has two modes, namely {\sl Insert} and {\sl Noninsert}
(``overwrite'');\index{Editor/insert mode} you can go from one mode to the other
with the toggle command \keyins.  The current mode is indicated at the end of the
status line.\footnote
    {See Section \ref{personalize} for selecting which mode should be the default one.}
When you are in {\sl Insert} mode, typing a character will push the
rest of the line rightwards, and characters at the end of the line will
be lost; similarly, typing \keyrubout\ will pull the rest of the line
leftwards, injecting blank characters at the end of the line.


\medskip

While a screen is being edited, the changes are only made on a copy of
it kept in a memory buffer.  When one moves to another screen or leaves
the editor, the modified screen is {\sl saved} to disk---the previous
contents of that screen in the disk file are overwritten.  Up until the
moment a screen is saved one can bring back the unmodified
version from disk by hitting \ied\ctrlx\ (``Cancel all changes'').

{\sl It is important to always exit from the editor (using \ied\keyesc)\
before removing the diskette you are working on. This will ensure
that all changes have been saved---and saved on the {\rm right} diskette.}\footnote
        {If there are fresh modifications in the screen buffer and you
swap diskettes before leaving the editor, the editor will save the screen
buffer on the wrong diskette, possibly contaminating its directory
and destroying valuable data.}

\medskip

The following lists describe the editing commands.  For the benefit of
touch typists, most commands that use a special key also have an
alternate ``control'' version that can be typed without moving the
fingers far from the home position. We have striven to retain
the {\sl Emacs} mnemonics\footnote
        {{\sc Emacs} is a text editor, originally written by Richard
Stallman at MIT, that is widely used in the scientific community.}
        for most control keys;
for example, the function of the
arrow keys \keyup, \keydown, \keyleft, and \keyright\ is duplicated by
the control characters \ctrlp, \ctrln, \ctrlb, and \ctrlf\ ({\sl Previous line},
{\sl Next line}, {\sl Back}, and {\sl Forward}).

\medskip

{\small 
The intended purpose of the screen editor is to handle screens, i.e.,
blocks containing text (see Section \ref{program files}).  However, the
editor can be useful on occasion for inspecting blocks\index{Forth/block} containing
non-text material (for instance, to check that something was actually
written to a certain block of a data file by a program under test).  In
this case, the editor screen may show all sorts of odd symbols; however,
to each of the 256 possible byte values there corresponds a {\em unique}
representation---in the form of a single text or graphic character---on
the editor's screen.

If such nonstandard use of the editor is desired, the {\sl
auto-extend/auto-shrink}\index{Editor/auto-extend}\index{Editor/auto-shrink} feature implied by \keypgdn,
\keypgup\ may be disabled by typing \iprog{AUTO-X}\id|OFF| (see
glossary).\par}


\newpage

 $$
 \begin{tabular}{|l|l|p{9.5cm}|} \hline
    \multicolumn{2}{|c|}{Keys} & \multicolumn{1}{c|}{Function performed}
\\ \hline \hline
    \ied\keyesc &   & {\sl Exit}. Save the modified screen to the file and exit the editor \\ \hline
    \ied\keyins &  & {\sl Insert}. Toggle {\sl Insert} mode on or off \\ \hline
    \ied\keyup & \ied\ctrlp & {\sl Previous line}. Move cursor one line up. \\ \hline
    \ied\keydown & \ied\ctrln & {\sl Next line}. Move cursor one line down. \\ \hline
    \ied\keyleft & \ied\ctrlb & {\sl Back}. Move cursor one position left \\\hline
    \ied\keyright & \ied\ctrlf &  {\sl Forward}. Move cursor one position right. \\ \hline
    \ied\keyend & \ied\ctrle & {\sl End}. Move cursor past the last nonblank
character of the current line \\ \hline
                & \ied\ctrla & {\sl Beginning} Move cursor to the beginning of the current line. \\\hline
    \ied\keyreturn & \ied\ctrlm & {\sl New line}. Move cursor to the beginning of the next line \\ \hline
    \ied\keytab & \ied\ctrli & {\sl Tab}. Move cursor to the beginning of the next word. \\ \hline
    \ied\keybacktab & & {\sl Backtab}. Move cursor to the end of the previous word. \\ \hline
    \ied\keyhome &  & {\sl Home}. Move the cursor to the upper-left corner of
the screen. \\ \hline
    \ied\keypgup & \ied\ctrlu & {\sl Up one screen}. Move to previous screen, saving current screen to file.
If the current screen is the last of the file and is all blank, it is removed from the file before you move.\\\hline
    \ied\keypgdn & \ied\ctrlv & {\sl Down one screen}.  Move to next
screen, saving current screen to file.  An attempt to move past the last
screen of a file (indicated by 100\% in the status line) automatically
adds one blank screen to the file. \\ \hline
    \ied\keydel & \ied\ctrld & {\sl Delete}. Delete character under cursor and move the
rest of the line one position to the left \\ \hline
    \ied\keyrubout & \ied\ctrlh & {\sl Rub out}. Delete character before the cursor,
and move cursor back one position. In insert mode, the rest of
the line is moved left one position. \\ \hline
                   & \ied\ctrlz & {\sl Zap}.  Erase from cursor to end of line. The kill buffer
(see below) is not affected. \\ \hline
 \end{tabular}
 $$

 $$
 \begin{tabular}{|l|l|p{11cm}|} \hline 
    \ied\keyfn1 & \ied\ctrll & {\sl Left align}. The cursor is thought of as dividing
the line into two ``halves.'' The right half is shifted leftwards until
a nonblank character appears under the cursor; the left half is not affected.
Useful for aligning definitions or comments.  \\ \hline
    \ied\keyfn2 & \ied\ctrlr & {\sl Right align}. The opposite of {\sl Left align}.
The right ``half'' of the current line is shifted rightwards until a nonblank
character touches the right edge of the screen. \\ \hline
    \ied\keyfn3 & \ied\ctrlj & {\sl Join}. The opposite of {\sl Open}.
Join the left ``half'' of the current line (i.e., from the left margin
to the cursor position) with the right half of the
next line. The right half of the current line and the left half of the
next line are lost. All following lines are pulled up. \\ \hline
    \ied\keyfn4 & \ied\ctrlo & {\sl Open}. Break the current line 
into two ``halves'' at the cursor position. The right
half will make up a new line. All following lines are pushed down. \\ \hline
    \ied\keyfn5 & \ied\ctrlk & {\sl Kill line}.  Remove the
current line from the screen; all following lines are pulled up.  Lines
deleted by consecutive uses of {\sl Kill} are accumulated in a buffer,
from which they can be retrieved by {\sl Yank\/}; the maximum capacity of
this buffer is 16 lines (one screenful). The contents of the kill buffer remains
available to be yanked until the start of a new
series of (one or more) consecutive {\sl Kill}s.\\\hline
    \ied\keyfn6 & \ied\ctrlx & {\sl Cancel all changes}. Cancel any changes made on the current
screen since last entering it; the screen is re-read from disk. \\ \hline
    \ied\keyfn7 & \ied\ctrlw & {\sl Wipe}. Fill the kill buffer with the current screen,
without destroying the screen's contents. \\\hline
    \ied\keyfn8 & \ied\ctrly & {\sl Yank}.  Insert at the current
line the contents of the kill buffer.  The contents of the current line and all
following ones are pushed down to make room.  The kill buffer can
be {\sl Yank}ed as many times as desired, possibly to different screens,
or even different files (by leaving the editor
and then starting editing a new file).\\\hline
    \ied\keyfn9  & \ied\ctrls & {\sl Search for string}.  Given a text string, start from
the cursor position and search forward through consecutive blocks until
the string is found.  The string argument is typed in right after \ctrls;
hitting \keyreturn\ instead makes this command reuse the previous
string.  \\ \hline
    \ied\keyfn{10} & \ied\ctrlc & {\sl Copy file}. Copy current file to a new
file. You'll be asked to type in the name of the new file; the default extension
is the same as that of the current file. Once the copy is made, {\sl the editor
will automatically take you to the new file!}\\\hline
 \end{tabular}
 $$

For convenience, we display below the layout of the 
editing commands that are attached to the function keys
 $$
  \begin{tabular}{|l|l||l|l|} \hline
    \ied\keyfn1 & {\sl Left align} & \ied\keyfn2 & {\sl Right align} \\\hline
    \ied\keyfn3 & {\sl Join}       & \ied\keyfn4 & {\sl Open}        \\\hline
    \ied\keyfn5 & {\sl Kill}       & \ied\keyfn6 & {\sl Cancel all changes} \\\hline
    \ied\keyfn7 & {\sl Wipe}       & \ied\keyfn8 & {\sl Yank} \\ \hline
    \ied\keyfn9 & {\sl Search}     & \ied\keyfn{10} & {\sl Copy file} \\ \hline
  \end{tabular}
 $$
Some users have found it convenient to photocopy this layout and tape it to
their keyboard.

\section{Date stamp}\label{stamp}

If you look at the first line of any of the present system's  source screens,
you'll notice that it contains a ``stamp''\index{Editor/date stamp} such as
        \begin{verbatim}
    04Jan87NHM\end{verbatim}
        indicating {\sl when} the screen was last written or modified,
and by {\sl whom}.  This stamp is automatically updated whenever one
leaves the screen (by moving to another screen or by leaving the editor)
after having made any changes to it.  Of course, the system needs to
know the date and the identity of the user---as explained in Section
\ref{personalize}. The default name used in date stamps will be \prog{cam}
until you change it.

The date stamp is added to a screen only if the first line
begins with a backslash (in particular, if the screen begins
with one of the ``comment'' words \id|\| or \id|\S|).

\section{Shadow screens}\label{shadow}

The F83 Forth implementation provides support for {\em shadow screens}\index{Shadow
screen}---a rudimentary mechanism for using the second half of a file as screen-by-screen
documentation for the first half.

Suppose you have a Forth program file (Section \ref{program files}) consisting of 10
screens, numbered 0--9.  Add to this file ten more screens, numbered 10--19, with the
understanding that screen 10 will contain comments or other text documentation
for screen 0, screen 11 for screen 1, and so forth---that is, each screen in the
second half of the file is treated as a ``comment shadow'' for the corresponding
screen in the first half.  When you want to {\em load} the file, you will still load only
screens 1 through 9 (as explained in Section \ref{program files}, screen 0 cannot be
accessed by the loader) and ignore the second half of the file; but when you want to
{\em examine} the file, you'll find on screen 13 extra documentation for screen 3.

Most of the source files for the \cam\ system are in the above format.

\medskip

Two editor commands, \ctrlt\ and \ctrlg, are meant to provide support for this kind
of file organization.  
 $$
 \begin{tabular}{|l|p{12cm}|} \hline 
    \ied\ctrlt & {\sl Toggle shadow}. Toggle between a source screen and its
shadow. \\ \hline
    \ied\ctrlg & {\sl Get shadow line}.  Copy to the current line of your screen the
corresponding line from the screens's ``twin'' (the shadow screen if this is a
program screen, and vice versa).  Provides a convenient way of copying source screen
information into shadow screens, to be edited into documentation.\\\hline
 \end{tabular}
 $$

\noindent Note that these commands have no way of knowing whether your file actually
contains shadow screens; they just work on that assumption, treat the file as divided
into two equal halves, and match corresponding screens in the two halves.
