RISC DISC 1/RISC_DISC_1.iso/pd_share/utilities/zap/!Zap/Docs/ReadMe

Text File | 1994-01-23 | 7.5 KB | 170 lines

*************************************************************************
* >ReadMe    Introduction to Zap documentation.            *
*************************************************************************

This file is an 'index' to all the other documentation files in the Docs
directory. All other documentation files begin with the prefix "E-".

This file is split into 3 sections:

    Section A:    How Zap works.

    Section B:    Writing extension modes.

    Section C:    Adding new commands to Zap.

Please read them in this order.

The following abbreviations/notations will be used in the documentation
files:

'\E'    =    The entry conditions for this subroutine are ...
'\X'    =    The exit conditions for this subroutine are ...

The following register conventions will be used:

R8    =    Window block pointer. (See E-Windows for defn)
R9    =    File block pointer. (See E-File for defn)
R10    =    Cursor block pointer. (See E-Cursors for defn)
R11    =    Extension mode's workspace.
R12    =    Zap module's workspace.
R13    =    Full descending stack (1K), bottom = &8000

Thus for example if I write:

\E R8/R9

Then I mean that on entry, the subroutine has R8 pointing to the window
block, and R9 pointing to a file block on some file (the file the call deals
with). See also the files E-Zapcalls and E-Entry for the standard entry/exit
conditions of most Zap calls.

Two BASIC programs are provided for you in the Docs directory. The first,
E-Library defines all the Zap variable names you will need. The second,
E-Template gives a template program for producing new modes/adding command
tables. It creates a mode called 'Test' with mode number 15 based on text
mode, and adds a command table with the command 'BEEPBEEP'.

*************************************************************************
* Section A:    How Zap works.                        *
*************************************************************************

When Zap starts up it initialises a 1K stack, claims fixed size buffers and
initialises an operating system heap. File buffers are stacked on top of the
heap and shifted about as the heap or other files changes size. Thus Zap's
memory map can be summarised as:

        TOP    Wimpslot end
            File n
            ...
            File 1
            Heap
            Fixed size buffers
        &8000    Processor stack (R13) full descending.

To find out how to call Zap please see the file E-Zapcalls. All Zap calls
will be described by their name beginning "Zap_". The calls Zap_Claim,
Zap_Free, Zap_Ensure should be used to claim blocks from the heap. The call
Zap_SplitBuffer should be used to change the buffer size of a file.

Each file has a corresponding file block giving information about that file.
By convention R9 is used to hold a file block pointer. New file buffers can
be created via Zap_CreateFile, Zap_CreateFileBlk, Zap_InstallFile and can be
deleted via Zap_DeleteFile, Zap_DiscardFile. Files are stored in split buffer
form. Please see E-File for details.

Similarly, each window has a corresponding information block. By convention a
window block pointer is held in R8. Each window block determines uniquely a
file block, giving the file showing in the window. Please see the file
E-windows for details. New editing windows can be created by Zap_CreateFile,
Zap_CreateWindBlk, Zap_InstallFile, Zap_NewView and can be deleted by
Zap_DeleteWindow, Zap_DiscardWindow.

Cursor information blocks are described in the file E-Cursors. Cursor block
pointers are conventionally held in R10. Zap's internal variables can be read
by the call Zap_ReadVar and written by Zap_WriteVar. See the file E-Vars for
details. By using this call you may read the block pointers of the standard
cursor blocks.

Inserting/deleting/replacing data in files is accomplished via the calls
Zap_Command and Zap_DoCommand. The former calls the extension mode to perform
the required action and the latter is the low level call which performs the
action directly. Thus in practice, Zap_Command calls the extension mode which
then calls Zap_DoCommand. In this way the extension mode may alter the action
of all inserts or deletes. For example, text mode uses this to accomplish
wordwrap on all operations. See the file E-Zapcalls and E-Entry for more
details.

Please use the Zap_StartOp/Zap_StopOp structure to concatenate insertions/
deletions. This will give smooth update and will ensure that the operation is
undone with only one press of the undo key.

*************************************************************************
* Section B:    Writing extension modes.                *
*************************************************************************

Zap extension modes are numbered 0-255. Currently I have only reserved space
for 16 of these (numbered 0-15). A mode consists of a table of entry points
and flags. This should be held in a module so that the code is always 'mapped
in to memory'. Currently defined modes are listed below. Please note that
mode names are CASE SENSITIVE throughout Zap.

    0    Text
    1    Byte
    2    Word
    3    Ascii
    4    Code
    5    BASIC
    6    BASTXT
    7    CMode
    8-10    -
    11    Throwback
    12    Taskwindow
    13-15    -

Before you start writing an extension mode, you should be familiar with
writing modules (preferably in assembler). In most cases, you will simply
wish to 'doctor' the input/output of one of the currently defined mode entry
points. For example, you may wish to change the typed characters entry point
of the TEXT mode to change `` to a left double quote. This is fairly simple
to do. If, however, you wish to write a full blown mode with, for example,
it's own display format, then you are strongly advised to contact me first.
I will be able to give you more support than these text files, and will be
able to add the new zap calls and entry points that you may require.

To install a new mode you should write a module, which on initialisation
calls Zap_AddMode with a pointer to the mode table. This module should then
be RMLOAD'ed from the !Run file. It should be loaded AFTER the Zap module has
been loaded but BEFORE Zap starts up via the *Zap_Desktop call (see !Run
file). When Zap starts up, it will examine the mode entry point table and
copy it into its workspace, converting module offsets to actual addresses
in the process. The call Zap_ReadMode can be used to find the address of both
these tables for any given mode. Hence you can manually alter the mode entry
point of any mode.

The entry point table format is described in the file E-Entry. Please note
that you only have to fill in the first 8 words. In the fourth entry you
specify a BASE MODE. This mode is called instead of yours for all the mode
entry points you don't want to support/change. Hence in most cases you will
set a base mode of 0 (ie TEXT), and set all of the entry points except those
you wish to change to 0.

*************************************************************************
* Section C:    Adding new tables of commands                *
*************************************************************************

Zap currently has space reserved for up to 16 command tables, though I can
easily increase this. The Zap,ZapBasic modules each use one, leaving 14 for
other uses. A command table consists of a pointer to a table of commands as
described in the file E-Commands. The command table should be stored in a
module and registered with Zap when the module initialises by calling the Zap
entry point Zap_AddCommands. As with adding a mode, the module should be
loaded by altering Zap's !Run file, so that the module is loaded after Zap,
but before the Zap_Desktop command.

The main use of adding new commands is to add additional keymaps to Zap. For
example, the extra commands needed by the EMACS keymap for Zap are store in
the ZapBasic module.

See the file E-Command for fuller details.