



                   o----------------------------------------o
                   |                                        |
                   |  A short primer for the new Zap user   |
                   |                                        |
                   |              Version 1.10              |
                   |                                        |
                   o----------------------------------------o




        Introduction
        ============
    This is not a 'manual' for Zap. It is intended as a short instruction
    file for users who do not have experience of programmer's editors and
    who find the rather technical instructions supplied with Zap confusing.
    It will not teach you all about Zap, it won't even mention most of the
    more advanced features. The aim is to get the inexperienced user over
    the first hurdle so that you can begin to use Zap at the most basic
    level. Once you have started to use it in preference to Edit you will
    then be able to go on to discover how to change it to make it operate
    the way you want. You will also be able to explore some of its more
    sophisticated editing functions for yourself.

    I assume that you are already familiar with Edit and will describe how
    you can set up Zap to work in a similar way.

    If you want to print this file (and if you need it I suggest you do)
    then the easiest way to do so is to load it into Zap and just press the
    Print key.  Alternatively you can double-click on the !Print file in
    this same directory which will simply copy the file to your printer.

    If you are an experienced computer user who is familiar with editors on
    the Archimedes and other computers then don't bother to read this, it
    isn't intended for you.



        Copyright
        =========
    This text and the files associated with it are (C) David Holden 1993.
    They may be freely copied and distributed by any PRIVATE INDIVIDUAL. You
    must ONLY copy the complete package including the example Keys, Keystrip
    and !Config file. You must NOT distribute it separate from the complete
    Zap package to which it applies (currently version 1.10). You must NOT
    substitute the Keys file for the one in the Zap application or put the
    !Config file into the !Zap application directory. They must be
    distributed separately to ensure that the original default files are
    always included with Zap.

    It may NOT be distributed by any PD or Shareware Library or BBS or any
    other not-private media without permission. It may not be changed,
    edited, or in any way altered but you may include additional material if
    you wish. If you do want to distribute this with Zap please let me know
    so that I can supply you with an updates as new versions of Zap appear.

    These restrictions have not been imposed because I wish to stop it being
    distributed by other libraries. On the contrary I want it to have a wide
    circulation so that as many people as possible can be introduced to Zap.
    However Zap is constantly being updated and improved and anything I
    write or any examples I provide may not apply to other versions.

    It is therefore VERY important that these files should only be
    distributed as part of the package to which they particularly refer. If
    you are running a Library or BBS then write to me at the address below
    (send a disc with a copy of your catalogue please) and I will send you
    the latest versions of this file and the latest version of Zap. If you
    have been sent a copy by either myself or Dominic Symes or if you have
    acquired it as part of the COMPLETE !Zap package from any 'authorised'
    distributor then  you automatically have permission to distribute it but
    ONLY with the version of Zap with which it was included.



                    David Holden
                    Archimedes Public Domain Library
                    39 Knighton Park Road
                    Sydenham
                    London SE26 5RN


                            _______
                       ____|__     |               (R)
                    --|       |    |-------------------
                      |   ____|__  |  Association of
                      |  |       |_|  Shareware
                      |__|   o   |    Professionals
                    -----|   |   |---------------------
                         |___|___|    MEMBER




        Text Editors
        ============
    There are two types of programs used for writing text on a computer,
    Wordprocessors and Text Editors. It might seem that they perform similar
    functions but in fact that is not the case. A wordprocessor is used for
    producing text which will eventually be turned into a printed document.
    This could be anything from a single page letter up to a book. More
    exotic wordprocessors can handle fancy fonts and graphics and when they
    reach this degree of sophistication they are called Desktop Publishing
    programs. Wordprocessor files are not intended to be 'transportable'.
    They contain embedded control codes and formatting commands which are
    unintelligible to other programs.

    Text Editors can be used to prepare text which will be printed but that
    is not their main purpose. The files they produce will normally contain
    only the 'standard' characters. These are called Plain Text or ASCII
    files. In fact different types of computer have different ideas of
    'plain text' since the character set will vary between countries. The
    character which marks the end of a line is also not standard.

    The Archimedes uses the ascii character code 10 at the end of each line,
    the BBC computer used code 13 and the PC and Apple Mac use both
    together. However in general a plain text file written on one computer
    can be read on most other computers once these minor differences have
    been put right. This is made easier if you confine yourself to the main
    characters which appear on the computer keyboard and avoid special
    symbols such as accented and currency characters.

    Most text editors have a few simple aids to text formatting such as
    variable line length and wordwrap. You will probably be familiar with
    these from Edit.

    Another use of text editors is for writing Source Code for compilers and
    assemblers. Because programmers have special requirements a particular
    type of text editor known as a Programmer's Editor has appeared.


        Programmer's Editors
        ====================
    The biggest difference between a programmer's editor and a 'simple' text
    editor like Edit is that it is, as its name suggest, designed to be used
    by programmers. It therefore needs to be able to create and edit source
    code for compilers such as 'C' or Pascal. As Basic is such a powerful
    and widely used language on the Archimedes ideally it should also be
    able to edit Basic programs. The RiscOS 3 version of Edit can do this
    although earlier versions could not. It will need powerful Search and
    Replace functions and should not be upset by files containing Control
    Characters. It will not need complex text formatting or printing
    controls because program source code would normally only be printed out
    as a 'listing' for the programmer to examine so nothing fancy is needed.
    It must be capable of basic text formatting and wordwrap because the
    programmer will probably want to use his favourite editor for writing
    short 'help' files for his program. Above all is must be FAST.


    There is one requirement which separates the 'professional' programmers
    editor from simple ones like Edit. Programmers are, by nature, perverse,
    individualistic and self opinionated. Wherever three programmers are
    gathered together there will be a minimum of four strongly held opinions
    on any subject connected with computers. It follows that an editor
    designed to be used by such people must be capable of being customised
    to suit his/her requirements and temperament. All good programmer's
    editors have some means whereby the keys used for the various functions
    can be set by the user. They also permit things like screen colours and
    as many other factors as possible to be altered.

    This is one reason why many new users of Zap become confused and give up
    before they realise how superior to Edit it is. The Author of Zap spends
    much of his time with computers running UNIX. He has therefore designed
    the standard keyboard layout to conform to the UNIX editors with which
    he is most familiar. You do not need to be bothered by this. Remember
    that almost everything about Zap can be set the way you want it.


        The vanishing cursor
        ====================
    Zap has a 'proper' cursor instead of the (often almost invisible) caret
    and this is much easier to find, especially as you can define its colour
    and make it flash if you wish. Earlier versions of Zap had a 'feature'
    (translation:- bug) which can be a bit disconcerting to the new user.

    What happened was that when you used the mouse to scroll a window,
    either the main scroll bars or the up and down arrow icons, the cursor
    didn't move as the window scrolled. For example, if you loaded a long
    file and used the mouse and scroll bars to move part way through it all
    appeared to work normally. However if you pressed the Down Arrow key to
    scroll down just one more line something very unexpected happened. You
    suddenly discovered that were are back at the start of the file with the
    cursor on the second line!

    This was completely different from the way that Edit and most other text
    editors work. With these the cursor always remains within the window.
    With this version of Zap the cursor can also be confined in this way and
    the example !Config file supplied actually does this.

    Some users have now become accustomed to the 'old' method, myself
    included, and have discovered that it does have it's uses. If you want
    to 'browse' through the file you are editing then you can do so using
    the scroll bars, but to return quickly to your original position (the
    position of the cursor) all you need to do is tap one of the 'arrow'
    keys and Zap will take you back there. This is another example of how
    useful it is to be able to customise Zap, you aren't constrained by what
    the Author decides is best but can change it to suit yourself.



        Configuring Zap
        ===============
    Zap uses two files for configuration. These are found in the !Zap
    application directory. One is a Data file called !Config. This will not
    be present when you first get your copy of Zap, it is created when you
    select 'Save Options' from the 'Options' sub-menu. It sets colours, wrap
    widths, cursor type, and most of the other 'visual' layout parameters.

    The most important is a text file called 'Keys'. This contains the
    things that define how Zap will operate, including the all important key
    binding table which tells Zap which keys should perform which functions.

    With this instruction file you should find two files which are intended
    to replace the standard configurations. There should also be a Drawfile
    of a keystrip. This 'keys' file is designed to mimic Edit to enable you
    to become accustomed to Zap as easily as possible. Many of the more
    powerful functions of Zap cannot be directly accessed via keystrokes
    because they don't have keys assigned with this file. As you become more
    experienced with Zap you will wish to alter the keys file so you can
    access these functions but for the present they would only be confusing.
    The full list of functions which can be bound to keys can be found in
    the file 'Commands' in the 'Docs' sub-directory of the !Zap application
    directory. This also contains instructions for creating your Keys file
    and with the aid of this, the original Keys file supplied with Zap and a
    bit of experimentation you should be able to work out how to make Zap
    operate in the way that you require.

    To use these configuration files first make a working copy of Zap. If
    you have a hard disc then copy zap onto your hard disc, if you are using
    floppies then copy it to a new disc. Now delete the 'keys' file from the
    application directory of this working copy and replace it with the file
    of the same name supplied with this file. You should also copy the
    !Config file into the application directory.

    When you start up this version of Zap it will use the keys shown on the
    next page which are roughly equivalent to Edit. There are a few extra
    ones which have no direct equivalent but are so useful that I didn't
    want to leave them out. These are not the keys that I normally use and
    no doubt you won't use them for long before you begin to make changes.

    As yet Zap has no equivalent to Edit's the 'expand tabs' and 'change
    LF<->CR' functions. LF<->CR can be mimicked by 'search and replace'. For
    example, to change all CR's to LF's enter in the 'Search' icon -

        \13

    and in the 'replace' icon -

        \10

    or to delete al CR's from a LF-CR terminated text file from a PC in the
    search icon -

        \13

    and leave the 'replace' icon blank.



        F1          Execute 'learnt' key sequence (no equivalent)
        F3          Save
        F4          Find and Replace
        F5          Goto line or address
        F6          Mark beginning or end of block
        F7          Copy marked block to cursor
        F8          Renumber (BASIC mode only)
        F9          Redo last action
        F10         Undo last action

        Sh-F1       Toggle Insert/Overtype modes
        Sh-F3       Immediate Save (no dialogue box)
        Sh-F4       Find (no equivalent)
        Sh-F6       Clear marked block
        Sh-F7       Move marked block to cursor
        Sh-F8       Delete marked block

        Ctrl-F2     Close current window
        Ctrl-F5     Toggle wordwrap on/off
        Ctrl-F6     Format paragraph

        Ctrl-B      Split line at cursor position (for BASIC mode, B=Break)
        Ctrl-C      Copy marked block to cursor
        Ctrl-L      Learn key sequence (no equivalent)
        Ctrl-J      Join two lines (for BASIC mode)
        Ctrl-N      Next match when Searching (no equivalent)
        Ctrl-P      Previous match when Searching (no equivalent)
        Ctrl-S      Swap case of character at cursor (no equivalent)
        Ctrl-V      Move marked block to cursor
        Ctrl-W      Next window. If there is more than one window open this
                    will move the cursor to the next one (no equivalent)
        Ctrl-X      Delete marked block
        Ctrl-Z      Clear marked block

        Delete      Delete backwards
        Copy        Delete forwards
        Ctrl-Copy   Delete entire line
        Sh-Copy     Delete from cursor to end of line (no equivalent)
        Sh-Delete   Delete from cursor to start of line (no equivalent)
        Print       Print file (no equivalent)

        Sh-Ctrl F0 to F7  Change to Zap mode 0-7 (more about these next)





        Zap Modes
        =========
    Unlike Edit Zap has a series of different 'modes'. The mode you will
    probably use most, and the one that is similar to Edit, is Text Mode.
    The reason for the different modes is to enable you to edit data in a
    variety of ways. When you load a file into Zap it decides which is the
    most appropriate mode to use, although like most features this can also
    be defined in the keys file. Each mode can have various options, such as
    the wrap width, set by the user.

    For the present I shall concentrate Text (mode 0) and BASTXT (mode 6)
    because these are almost directly equivalent to the way that Edit works,
    and BASIC (mode 5) because you may prefer this to BASTXT for editing
    Basic programs. However you may wish to experiment with others. The two
    others you will probably find most useful are Byte (mode 1) and Code
    (mode 4).

    Byte mode edits a file in a window that looks like a disc sector editor.
    It is particularly useful for editing Data files or other files which
    don't contain normal text.

    Code mode shows a machine code or compiled program in in disassembled
    format. In fact it makes Zap into a simple disassembler. There are
    various functions which can be used when in this mode, such as following
    Branches, assembling instructions, etc.

    BASTXT mode is the mode that most people prefer for editing Basic
    programs. This converts a tokenised program to text when it is loaded
    and back to Basic when you save it. It enables all the 'normal' editing
    functions to be used just as if you were working on a text file. This is
    the way that the RiscOS 3 version of Edit handles Basic programs and for
    this reason I have used it as the default for this primer.

    If you think that Acorns Basic Editor is wonderful (!) then you may
    prefer to use BASIC mode (mode 5). This operates in a similar manner to
    Acorns (now obsolete) Basic Editor. If you want to use Zap in BASIC mode
    (see below) then you will need to use the 'split line' and 'join line'
    keys, otherwise these can be ignored.

    In the past I regarded the 'standard' Basic mode as so inferior to
    BASTXT mode that I advised people not to use it. This is because when
    Zap is in BASIC (as compared with BASTXT) mode it operates as a Line
    Editor and works on the file in its tokenised form. This means that only
    complete lines can be copied or moved, you have to worry about things
    like renumbering, using a special key to split or join a line etc.
    Previously the only 'good' thing about BASIC mode is that it will handle
    GOTO's properly and automatically (but then you wouldn't put a GOTO
    anywhere in your programs, would you?).


    However from version 1.1 Zap has a feature which makes BASIC mode more
    attractive. It can display the constituent parts of a program in
    different colours. Keywords, line numbers, REM's and string constants
    can all have there own colours defined which makes it much easier to
    'read' a program and see how it is made up. Inexperienced programmers
    often find this invaluable. Personally I still prefer the superior
    editing ability of BASTXT mode but try them both and choose the one that
    you like best.

    To change the mode that Zap uses by default load Zap and go to the
    sub-menu 'Options' on the main menu. Click on 'Edit Keys'. This makes
    Zap load the current Keys file from it's own application directory ready
    for you to edit it. Press F5 to bring up the 'Goto' window, enter line
    number 200 and press RETURN. Zap will now display the lines in this
    region and you will find that about here are defined the modes that Zap
    uses for each type of file. You should see a line -

        Basic          &1FFB    BASTXT

    Change this to

        Basic          &1FFB    BASIC

    Press SHIFT-F3 to 'quicksave' the Keys file (ie. it will be Saved
    without any further prompting) and close the file window. Now click on
    'Reload Keys' from the Options sub menu and Zap will re-interpret the
    Keys file so the next time you load a basic program it will be in BASIC
    mode instead of BASTXT. If you find you prefer the alternative method
    just change the Keys file back again.



        Setting the Options
        ===================
    Each Zap mode can have many options set independently of the general
    options, other items are common to all modes. I shall describe briefly
    how you make these changes and then let you experiment for yourself.

    The 'Options' sub menu is where most of this customising is carried out.
    As this leads to a series of sub-menu's you will probably find it best
    to open this menu and drag it to the left of the screen because
    otherwise as you open the other sub-menus they will obscure each other.
    Keep the mouse pointer within the menus as you do this otherwise they'll
    all close and you'll have to start again.

    I shall concentrate on only two items, Colours and Width. The first
    thing you need to understand (or you'll soon become very confused) is
    that when you change an option like Width it changes ONLY for the mode
    that is currently selected.

    Go to the Options-> Mode sub menu and click on 'Text'. (Click on it with
    ADJUST otherwise all the menus will close and you'll have to start
    again. Now open the Options-> Display-> Width sub menu and look at the
    width shown. If you are using the !Config file supplied with this text
    it will be 112. Now go back to Config-> Mode and click on 'BASIC'. Look
    at the Width after this and you will see it has changed to 76. What this
    shows is that Zap has a different Width for each mode, and so if you
    want to change it the change you make will apply ONLY to the currently
    selected mode.

    Precisely the same situation applies to colours. The only difference
    here is that to avoid having to change every colour in every mode you
    can select 'All' on the Options-> Display-> Colours menu and the
    colour(s) you select will be made in every mode. If you want one mode to
    have different colours from another then de-select 'All' and select that
    mode and the colours will apply to that mode only.

    There is a slight departure from this when you select BASIC mode. You
    will find three more items appear on the Options-> Display-> Colours
    menu. These set the colours used for REM's, Basic keywords and string
    constants. Obviously these only apply in BASIC mode which is why they
    don't appear if any other mode is selected.

    When you are satisfied with your choices click on 'Save Options' on the
    Options menu.

    You will probably spend a bit of time exploring the various options and
    discovering the effects of the changes. Most are fairly self evident and
    the more obscure ones probably will not concern you at this stage.



        Using Search and Replace
        ========================
    Unlike Edit Zap has two Search windows. One simply 'finds' what you are
    looking for, the other enables you to replace it with something else.
    The advantage of this over Edits single window is that if you just want
    to find something you can't accidentally press the wrong key and replace
    it with a 'null string' (ie. delete it).

    The way that Zap's search function works is completely different from
    Edit and it will probably take you a while to get used to it. However it
    is MUCH more powerful and flexible.

    You have a choice of where you want the search to start from. You can
    begin from the cursor position or from the start of the file. You also
    have a choice of whether you want the search to be forwards or
    backwards. Another feature is that you can choose the 'output' for the
    search. This enables you to do more than just 'find' something. If you
    select 'Cursor' then the cursor will simply move to wherever the search
    string is found, just like Edit. If you choose 'To buffer' then when Zap
    finds a match it will create a new file and copy each line where a match
    is found to this new file. A window will open containing a list of all
    the lines containing a match and you can save or edit this as usual. If
    you want to go in your original file to any of the matches displayed in
    the new window then just 'click' on the line in this window and Zap will
    move the cursor to that line in your original file. Alternatively just
    use the 'go to line' function since each match will have it's 'line
    number' shown.

    Like Edit certain special characters can be used. These are all defined
    by being preceded by the '\' character. A full list of these can be
    found in the !Help file but a few examples are shown.

        \10         Matches ascii character number 10, eg the normal
                    end-of-line character. \12 would find character 12 etc.
        \|          Matches one string OR another. For example John\|Fred
                    would match John or Fred.
        \A          CTRL-A, \B would be CTRL-B etc.
        \#          Any character
        \*          Any number of the previous string. eg A\* would match A,
                    AA, AAA etc.
        \<          Finds the string only at the start of a line. eg. \<fred
                    only finds 'fred' if it's the first word on a line.

    The biggest change from the way that Edit's Search function operates is
    that Zap can use Search Macro's. If you click on 'Show Macros' in either
    Search window the Macro Window will open. This shows the current macros.
    When you enter a Search string if any of the characters you enter has a
    macro defined for it then that macro will be substituted during the
    search. I am not going into great detail about these. You will need to
    experiment to find out exactly how they work and which macros you wish
    to use. Like most other things they are all defined in the Keys file and
    you will be able to see the current ones near the end.



        Learn
        =====
    This is another very powerful function which exists in all 'proper'
    programmers editors but not in Edit. The idea is that Zap can 'learn' a
    series of keystrokes and play them back on command. When editing or
    modifying a file you may need to carry out the same operation many
    times. Instead of being forced to manually repeat it you can teach Zap
    what you want it to do and save yourself all the repetitive work.

    For example, if you had a text file which consisted of a a series of
    lines made up of a code number, a name, and a description, like this;

    189554       Screw, Widget         The screw that fits the Widget
    295677       Bolt, Mangel          The bolt that attaches the Mangel

    Now assume that you want to reduce the gaps between the three items so
    that you can add to the descriptions like this;

    189554   Screw, Widget    The screw that fits the Widget
    295677   Bolt, Mangel     The bolt that attaches the Mangel

    This is the same thing but with four spaces deleted between each section
    which let's you add eight characters to your description with the same
    line length. The way this is done 'manually' is to place the cursor
    after the number and press COPY four times (or whatever key you have
    chosen as Delete Forward), move it just after the first section and
    press it four times again, then move down to the next line and repeat,
    etc, etc. Instead of doing all this you can use Learn to do it for you.

    Move the cursor to the start of the first line. Press Ctrl-L to tell Zap
    to start learning your keystrokes. Press the Right Arrow key six times.
    This will move the cursor just after the number. Each time you press the
    key the computer will 'beep' to remind you that Zap is recording what
    you do. Now press the Copy key four times to delete the four spaces,
    press Right Arrow eighteen times to move to the second 'gap' and Copy
    four times once again. Now press Ctrl-Left Arrow to move to the start of
    the line and Down Arrow to move down one line. When you have done this
    the cursor should be at the start of the next line (ready to carry out
    the next operation) and the line should be 'closed up' like the second
    example. As you have finished the 'learning' process press Ctrl-L again
    to tell Zap to stop recording what you do.

    All you need to do now is press F1 which makes Zap Execute the learnt
    keystrokes and by 'playing back' the learnt sequence Zap will carry out
    exactly the same operation on the second line that you did manually on
    the first. You will then find that the cursor has been moved to the
    third line, just as you moved it to the second, so just press F1 again
    to do the third line and so on to the end of the file.

    Of course it might have been simpler in this case to use 'Search and
    Replace' but this does show how the Learn function can can save a lot of
    typing and, because each sequence will be carried out precisely as the
    first, there is less chance of mistakes.

