                        Zap: A Programmers' Editor
                        ==========================


Contents
--------
1  :  Introduction
1.1  :  ZAP is a text editor
1.1.1  :  About this manual
1.1.2  :  License
1.1.3  :  Getting in touch

2  :  Installation: making sure everything's in the right place
2.1  :  Getting the right files
2.2  :  Core setup
2.2.1  :  ZapUser: user configuration files
2.2.2  :  ZapFonts: the global bitmap font resource
2.3  :  Recommended extensions setup
2.4  :  Optional extensions setup

3  :  Simple operation
3.1  :  Loading and creating files
3.2  :  A Zap editing window
3.2.1  :  Titlebar options characters
3.3  :  Basic editing
3.3.1  :  Zap's cursors
3.4  :  Keyboard shortcuts
3.4.1  :  Moving around your file
3.4.2  :  Other useful keystrokes
3.4.3  :  Keystrokes in dialogue boxes
3.4.4  :  Zap's minibuffer
3.5  :  Further editing
3.5.1  :  Undo and redo: recovering from mistakes
3.5.2  :  Quoting characters
3.5.3  :  Inserting files
3.6  :  Saving and closing files
3.6.1  :  Automatic backups

4  :  Selections
4.1  :  Making a selection
4.2  :  Copying, pasting, cutting, yanking and moving
4.2.1  :  The global clipboard
4.3  :  Saving the selection
4.4  :  Processing the selection
4.4.1  :  Indent
4.4.2  :  Outdent
4.4.3  :  Swap case
4.4.4  :  Upper case
4.4.5  :  Lower case
4.4.6  :  Filters
4.4.7  :  Filter sort
4.4.8  :  Filter format
4.4.9  :  Filter untab
4.5  :  "Sending" the selection

5  :  Mouse control
5.1  :  Standard mouse actions
5.2  :  Click Send: Alt+ double click

6  :  Advanced editing
6.1  :  Auto indenting
6.2  :  Tabbing
6.2.1  :  Tab editing
6.2.2  :  Tab display
6.3  :  Wrapping and formatting your text
6.3.1  :  Window wrap
6.3.2  :  Soft wrap
6.3.3  :  Word wrap
6.3.4  :  Line wrap
6.3.5  :  Infinite wrap
6.3.6  :  Auto soft wrap
6.3.7  :  Strong soft wrap
6.4  :  Keymaps
6.5  :  Cursor behaviour
6.5.1  :  Line select
6.5.2  :  Smart movement
6.5.3  :  Confine horizontally
6.5.4  :  Confine vertically
6.5.5  :  Free click
6.6  :  Block editing: quickly editing all lines in a selection
6.7  :  Line editing
6.8  :  Other options
6.9  :  Save options

7  :  Display options
7.1  :  Display config
7.1.1  :  Display width
7.1.2  :  Line numbers
7.1.3  :  Line spacing
7.1.4  :  EOL and Tab characters
7.2  :  Fonts
7.3  :  Colours
7.3.1  :  Font substyles
7.4  :  Dumping files
7.5  :  Printing files

8  :  Searching
8.1  :  Search options
8.1.1  :  Raw search
8.1.2  :  Case sensitivity
8.1.3  :  Macros
8.1.4  :  To window searching
8.2  :  \-commands
8.3  :  Replace
8.3.1  :  Global replace
8.3.2  :  The replace expression
8.4  :  Incremental search

9  :  Advanced use
9.1  :  Setting and using marks
9.2  :  Working with read only files
9.3  :  Zap's help system
9.4  :  Zap's command language
9.4.1  :  Command syntax
9.5  :  Learning and playing back actions
9.6  :  The universal argument: repeating actions
9.7  :  Object Linking and Embedding, and External Edit

10  :  Zap's modes: helping with particular types of file
10.1  :  Zap's binary editing modes
10.1.1  :  Editing in binary modes
10.1.2  :  Display options in binary modes
10.1.3  :  Creating files directly from memory
10.1.4  :  Reading directly from memory.
10.1.5  :  Reading directly from disc
10.2  :  ASCII editing mode
10.3  :  ARM code editing mode
10.3.1  :  Code mode colours
10.3.2  :  Advanced disassembly
10.3.3  :  Module disassembly
10.3.4  :  AIF disassembly
10.4  :  BASIC editing modes
10.4.1  :  ARM Basic Editor emulation
10.5  :  C, C++ and Java editing modes
10.6  :  ARM assembler editing mode
10.7  :  Throwback mode
10.8  :  Taskwindow mode
10.9  :  Email reading and editing mode
10.10 :  HTML editing mode

11  :  Commands: Zap's command language
11.1  :  Types of command
11.2  :  Parameter evaluation
11.2.1  :  Allowed syntax
11.2.2  :  Accessing system variables
11.2.3  :  Dynamic versus static evaluation
11.3  :  Functions
11.4  :  Variables
11.4.1  :  Local variables
11.5  :  Conditional constructs
11.5.1  :  IF
11.5.2  :  CASE
11.6  :  Looping constructs
11.6.1  :  WHILE
11.6.2  :  REPEAT
11.7  :  Examples
11.7.1  :  Simple conditional
11.7.2  :  Simple loop
11.7.3  :  'For'-style loop and static evaluation
11.7.4  :  Loop and conditional

12  :  Customising and configuring Zap
12.1  :  Other complete configuration setups
12.2  :  Binary configuration options
12.2.1  :  Per-mode options
12.2.2  :  Configuring Zap's cursors
12.2.3  :  Configuring the minibuffer
12.2.4  :  Miscellaneous configuration options
12.2.5  :  Autoloading internal extensions
12.3  :  Textual configuration
12.3.1  :  Miscellaneous settings
12.3.2  :  Zap's behaviour with different file types and locations
12.3.3  :  Configuring Zap's keystrokes
12.3.4  :  Configuring Click Send
12.3.5  :  Configuring Zap's menus
12.4  :  Differences in different versions of Risc OS
12.4.1  :  Dynamic areas
12.4.2  :  Fonts
12.4.3  :  Task windows
12.4.4  :  Loading files
12.4.5  :  Help
12.4.6  :  Templates
12.4.7  :  NCOS

13  :  Extensions to Zap
13.1  :  ZapSpell: spell checking for Zap
13.2  :  ZapConfig: graphical configuration of Zap
13.3  :  Behind-the-scenes extensions to Zap
13.3.1  :  Olly Betts' Line editor
13.3.2  :  ExtBASICAsm: extended assembly and disassembly
13.3.3  :  HidePtr: hiding the mouse pointer while you work
13.3.4  :  KeyExtend: Better keyboard response
13.3.5  :  FlashCar: flashing the cursor in dialogue boxes
13.3.6  :  IClear: clear writeable icons using the mouse

14  :  Developing for Zap
14.1  :  Developer mailing lists
14.2  :  Writing extensions to Zap
14.2.1  :  Writing additional Zap commands
14.2.2  :  Writing a Zap mode
14.3  :  Working on the Zap core
14.4  :  Working on Zap's documentation

15  :  How to find out more
15.1  :  Other documentation that comes with Zap
15.2  :  The future: ideas, bugs, and obtaining upgrades
15.3  :  Credits
15.4  :  Getting in touch with Zap developers

Appendix
A  :  Default keystrokes
A.1  :  Common editing keys
A.2  :  Cursor keys
A.3  :  Miscellaneous keys
A.4  :  Keypad keys
A.5  :  Function keys
A.6  :  Control letters






Chapter 1: Introduction
-----------------------

   1.1 ZAP is a text editor

       Welcome to Zap, a text and programmers' editor for Acorn RISC OS.
       This manual will help you to learn about its various features, from
       basic text editing up to the more sophisticated needs of programming
       source code and the like. Don't panic! Just because Zap allows you
       to do lots and lots of things doesn't mean that you have to use all
       the features. If you find that the default configuration of Zap
       isn't appropriate for you, but don't want to get involved in
       configuring it yourself, there are a range of alternate
       configurations available - see section 12.1.

 1.1.1 About this manual

       Firstly, in this manual, we have assumed that you are familiar with
       standard RISC OS use and techniques; in particular we assume you
       understand how to use the /Filer/ to load applications and files,
       and the common use of the mouse and keyboard. Zap behaves like a
       normal RISC OS application in many ways - in general, if you think
       it should work it will do.

       Secondly, Zap is highly configurable: all the keypresses can be
       changed; the colours Zap uses can be changed; the menus can be
       changed; and many of the operations and functions can be customised
       to work in the way you wish. However, except for chapter 12, this
       manual describes Zap in its default behaviour - the way you get it
       when you obtain it for the first time (whether from a CD ROM,
       Bulletin Board System or via the Internet - see section 15.2). (This
       is the reason it is important that you too pass on Zap in its
       'virgin' state - see `!Zap.Docs.Copyright' for information about
       distributing Zap.)

       Zap contains both interactive help (using Acorn's /Help/
       application), and its own online help - see section 9.3 for more
       information.

 1.1.2 License

       Zap is released as free software; you can use, copy and distribute
       it free of charge. In addition, the source code to Zap is available,
       and you are encouraged to join in its development if you wish - see
       chapter 14 for more information. The license is supplied with Zap as
       `!Zap.Docs.Copyright'.

 1.1.3 Getting in touch

       If you have any comments about this manual, please get in touch; if
       you need specific help with Zap, the best places to try are the
       Acorn-related newsgroups, specifically `comp.sys.acorn.apps' - many
       of the Zap developers read them thoroughly, and in addition there
       are other experienced users who can help you. More information is
       available in section 15.4.

       --------------------------------------------------------------------

       The first section in the manual is chapter 2, which shows you how to
       install and setup up Zap so that it will work correctly. Even if you
       already have a working Zap installation, it is as well to check over
       this to make sure you haven't missed anything. This is particularly
       important if you are upgrading from an earlier version of Zap, since
       a number of things have changed.



Chapter 2: Installation: making sure everything's in the right place
--------------------------------------------------------------------

       Zap is a fairly complex application, and while you /can/ just copy
       it onto your hard disc, it is better if you set it up properly. This
       will only take a couple of minutes, and has a number of benefits
       (although you won't notice them directly - you just won't get
       irritated by some of the things that can go wrong if you /don't/ set
       it up properly).

       Unfortunately there is no upgrade path from earlier versions of Zap
       to version 1.40, because both the configuration and the layout of
       files within Zap itself has radically altered. We apologise for the
       inconvenience this causes.

   2.1 Getting the right files

       Zap comes in a number of parts. Which parts you need will depend on
       what you're intending to do.

       Firstly there is the core distribution, which contains merely those
       files /required/ to get Zap running. While this will give you a
       usable text editor, it will be missing many of the more
       sophisticated features described in this manual.

       Secondly there is a group of extensions which is /recommended/; you
       don't need these to run Zap, but they provide lots of useful
       features which you will probably want.

       Thirdly, there are some /optional/ extensions which many people
       won't need, but which some people will find useful.

       The core distribution is supplied in one archive, `zap.zip'. This is
       the first thing you should set up; this process is described below
       in section 2.2.

       The recommended extensions are also supplied in one archive,
       `zmods1.zip'. Once you've set up Zap itself, you can install these;
       see section 2.3 below.

       The following additional archives are optional:

       (*) `zfonts.zip' - a full ZapFonts distribution, containing lots and
           lots of fonts. Generally you don't need this for Zap; however
           ZapFonts is used by some other applications, so you may want the
           additional fonts for use with them. See section 2.2.2 below for
           more information.

       (*) `zmods2.zip' - several more extensions. As new extensions
           appear, they will usually be added in here rather than making
           `zmods1.zip' any bigger (unless they are considered to be
           incredibly useful). See section 2.4 below for more information.

   2.2 Core setup

       The Zap core distribution contains an Install file (this document in
       text format), and the `!Zap' application directory. Please don't
       just copy it onto your hard disc - this is extremely limiting.

       As well as the Zap application, the core distribution contains a
       stripped-down copy of ZapFonts, and a copy of ZapUser. In the
       archive, they are both /inside/ the `!Zap' application directory.
       What you should do is to copy `!Zap' into wherever you want it, and
       then move both ZapFonts (the `!ZapFonts' application directory) and
       ZapUser (the `!ZapUser' application directory) out of it. To do
       this, hold down shift and double-click on the `!Zap' icon. This will
       open a directory viewer; you can move things out by holding down
       shift and dragging the icons out to where you want them to go.

       Now let's look at where they should be going. We'll deal with
       ZapUser first.

 2.2.1 ZapUser: user configuration files

       ZapUser is designed to keep all your preferences and settings in one
       place. This means that you can copy it onto a floppy disc, take it
       to another computer, and have exactly the settings that you want
       there too.

       To make this work, we don't really want ZapUser hiding away inside
       the Zap directory, and fortunately there is a better place. If you
       have a RISCPC-style boot structure (as most people do - see below if
       you don't), then you want to put ZapUser in `Boot:Choices' (shift
       double-click on `!Boot' on your main hard disc, and then
       double-click on Choices in the directory viewer that come up; then
       you can move the `!ZapUser' application by shift-dragging).

       If you /don't/ have a RISCPC-style boot structure, then you have a
       choice. If you have a boot structure then you can try to find a
       place to put ZapUser in that, so that it will get booted /before/
       Zap (wherever you put Zap). If you can't do that, or don't know what
       it means, then it's best to keep ZapUser living inside Zap. While
       that's far from ideal, it's a lot easier than setting up a boot
       structure just to deal with ZapUser.

       You can use ZapUser to have multiple configurations on one machine.
       To change from one to another, just double-click on the ZapUser you
       want to use, and then quit and restart Zap. A range of sample
       configurations is available from wherever you obtained Zap - see
       section 15.2.

 2.2.2 ZapFonts: the global bitmap font resource

       ZapFonts is the global bitmap font resource; it is to bitmap fonts
       what !Fonts is to outline fonts. Zap uses bitmap fonts in all its
       file windows, and several other applications also use it, including
       /Messenger/ and /FreeTerm/. Consequently we want it to be somewhere
       that they can all get at it, rather than hidden away inside Zap.

       If you have a RISCPC-style boot structure, then you want to put
       ZapFonts in `Boot:Resources'. If you don't have a RISCPC-style boot
       structure, then you need to find another place to put ZapFonts so
       that it will boot before Zap. If you absolutely can't do this, then
       you should leave ZapFonts inside the `!Zap' directory, and make sure
       that Zap boots before anything else which might need ZapFonts. The
       best way to do this is to have Zap in the root directory of your
       main hard disc; however we strongly suggest that you use a boot
       structure of some sort - there are a number of free ones availabe
       which should suffice.

       Because ZapFonts supplies all the bitmap fonts for all the
       applications that want to use it, the complete distribution is
       fairly large. Consequently the version in the core Zap distribution
       is minimal, containing only a couple of fonts. The complete set is
       available from wherever you got Zap from (see section 15.2); it will
       come as a `!ZapFonts' application directory containing only the
       additional fonts - you can simply copy it over the top of your
       ZapFonts directory. You may need to restart some applications to get
       them to recognise the new fonts (this isn't true of Zap, which will
       recognise automatically that you have installed new fonts).

       For more information on using ZapFonts, please see the documentation
       supplied inside its application directory.

   2.3 Recommended extensions setup

       The `zmods1.zip' archive contains a directory `Modules' which should
       be copied over !Zap.Modules.

       Alternatively, you can install just some of the extensions. If you
       are fairly confident, you can do this yourself by simply copying the
       relevant applications /from/ the `Modules' directory of the archive
       /into/ `!Zap.Modules'. Alternatively, you can install individual
       extensions using ZapConfig - see section 13.2 for more information.

       You will then need to quit and restart Zap to complete the setup.

   2.4 Optional extensions setup

       Setup for the current optional extensions is the same as for
       recommended extensions; see section 2.3.

       --------------------------------------------------------------------

       Now you have a working version of Zap. If you currently have an
       older version of Zap running, you should quit it; now you should
       double-click on both ZapUser and ZapFonts to make sure that they are
       setup correctly in their new locations. Finally you can double-click
       on Zap to load it.

       The next section in the manual is chapter 3, which introduces you to
       the basic editing facilities of Zap. Even if you have used Zap
       before we advise that you at least skim through this section, to
       make sure you haven't missed any of the useful functions available.



Chapter 3: Simple operation
---------------------------

   3.1 Loading and creating files

       Once Zap has loaded onto the iconbar, you can create a new file by:

       (*) clicking `Select', which will create a new text file.

       (*) clicking `Adjust', which will create a new BASIC file.

       (*) clicking `Menu', opening the `New file' submenu, and selecting
           the type of file you want.

       Alternatively, you can load an existing file into Zap.

       (*) if it is a text file, double click on it (you will find that
           some other files will load straight into Zap in this way - see
           section 12.3.2 for more details.

       (*) if the file is typed, hold down the left `Shift' key and double
           click on it.

       (*) (for all files) drag it to Zap's icon on the iconbar.

       If you load a file into Zap, it will check to see if it is a DOS
       (line ends are `CRLF') or Spool (line ends are `LFCR') file as it
       does. If it is in either format, it doesn't just load the file, but
       converts it first to make editing easier. It will then automatically
       convert back when you save - see section 6.9 for more details.

       When you load a file into Zap, or create a new one, it works out the
       best /mode/ to put it in. For the moment, don't worry about this -
       if you're new to Zap, just create a text file by clicking Select on
       Zap's icon, and we'll cover modes later, in chapter 10. However it
       is worth noting that you can override what Zap thinks is the best
       mode by holding down `Control' - this will drop the file into
       whatever's set as the 'default mode' - typically either Text or
       Byte. See the note at the end of section 12.2.1 for how to configure
       this.

       If the file is already loaded into Zap and you have altered it, Zap
       will ask you whether you want to `Cancel' (don't load the file),
       `Edit' (load the file, but keep the altered file loaded as well), or
       `Overwrite' (close the altered file without giving you a chance to
       save it, and then opening the one on disc). The dialogue box Zap
       uses to ask you this also has a `To Front' button, which will bring
       all the windows on the altered file to the front of the window
       stack, so you can decide what you want to do. Several of Zap's
       dialogue boxes in similar situations have this button.

       Zap can also grab the memory of running applications, the contents
       of dynamic areas, sectors from discs, and the code or workspace of a
       module; see section 10.1.3 for more information.

   3.2 A Zap editing window

       A Zap editing window is just a normal RISC OS window, with one
       slight exception (see section 3.4.4). As you'd expect, clicking
       `Menu' on a Zap editing window will bring up a menu which has
       options to let you save the file you are working on, and a range of
       other useful operations.

       In common with many applications, Zap puts the filename in the
       window's title bar, but it also puts some other information there
       too. In any mode, the window title is of the form
       `<filename> [*] ([mode name] [options]) [view number/number of views]'

       The title is centered unless the window is small, when it is right
       aligned so that you can see the leaf name and options of the file. A
       '*' indicates that the file has been altered since last saved
       (sometimes you will get a '?' instead, which means that Zap isn't
       sure, but the file /may/ have been changed). The view number is only
       shown if you have more than one view on a file.

 3.2.1 Titlebar options characters

       The options characters are one or more of:

       (*) `R' - permanent read only (ie you can't make it non-read only).

       (*) `r' - read only, but can be made read/write (see section 9.2).

       (*) `D' - this is a DOS text file: line feeds will be converted to
           [CR][LF] on saving (see section 6.9).

       (*) `S' - this is a Spool text file: line feeds will be converted to
           [LF][CR] on saving (see section 6.9).

       (*) `p' - strip spaces on saving (see section 6.9).

       (*) `B' - Block edit mode is on (see section 6.6).

       (*) `A' - File has non-standard attributes (update using OS_GBPB).

       (*) `u' - Undo is enabled for this file.

       (*) `o' - Overwrite (typing in characters overwrites whatever's at
           the cursor - see section 6.8).

       (*) `h' - Hex entry mode (used by Byte and Word modes - see section
           10.1).

       (*) `w' - Wordwrap mode active (see section 6.3).

       (*) `L' - Line wrap mode (see section 6.3).

       (*) `l' - Line edit mode (see section 6.7).

       (*) `n' - Non-standard mode (see section 6.8).

       (*) `a' - Auto indent mode (see section 6.1).

       (*) `W' - Window wrap mode (see section 6.3).

       (*) `s' - Soft wrap mode (see section 6.3).

   3.3 Basic editing

       Now we've got a new file, we probably ought to alter it in some way.
       First we need to briefly talk about Zap's cursor.

 3.3.1 Zap's cursors

       Unlike /Edit/, which has a /point cursor/ - a single line which
       indicates where text that you type will be entered, Zap has a /block
       cursor/. When you open a new file, you will see it sitting at the
       top left of the window. Text you type will get inserted immediately
       to the left of the block cursor (unless you have overwrite turned
       on, in which case typing a character will overwrite the character
       displayed in the block cursor with the new character that you
       typed). You can position the cursor by clicking `Select' with the
       mouse (the mouse can also be used for other things - see chapter 5
       for more information).

       That said, you can now happily type some text in; the cursor keys
       work in the way you would expect.

       Zap also has another three cursors. Firstly, it has a /mark cursor/.
       This shows where the cursor /would/ be in a window that doesn't have
       the focus. To see this, open two new text files, and type some text
       into each. Resize them so you can see both - and you will see that
       the window with the focus has a block cursor, while the window
       without the focus has an empty square mark cursor to indicate where
       the cursor was when you last used that window. Clicking `Select'
       both sets the focus to the window you clicked on and moves the
       cursor; if you want to set the focus to a window, but not set the
       cursor, click `Adjust' - this will position the cursor where the
       mark cursor was. This way you can quickly move between windows with
       the mouse without having to click accurately to keep the cursor
       where you want it.

       Secondly, Zap has a pair of /copy cursors/. If you turn copy mode on
       by pressing `sCopy' (hold down `Shift' and press the `Copy' key),
       you will have two separate cursors (although they will initially be
       at the same position, so you won't be able to see this). One, a
       block cursor will remain in place, while the other, a thin line
       drawn under the character it's at, can be moved around the file. In
       copy mode, pressing `Copy' will copy the character under the line
       cursor to the position of the block cursor. Pressing `Escape' or
       `Return' will cancel copy mode. (This works in the way you'd expect
       from using the `Copy' key in BASIC or from the command line.)

       You can configure how Zap draws its different cursors - see section
       12.2.2.

   3.4 Keyboard shortcuts

       Many applications have some keyboard shortcuts to help you perform
       common operations quickly. Zap has lots of keyboard shortcuts, so
       that not only common operations but also less common ones can all be
       performed without having to move your hands from the keyboard. As
       with everything else, what each keypress does can be configured -
       see section 12.3.3 for more information; you might also like to look
       at section 6.4, which allows both for a series of keypresses to
       perform an action (eg: `scF11 cX cS' saves the file), and for
       different modes to have the same keypresses doing different things.

       Keystrokes are shown on Zap's menus, where they are displayed using
       `^' to stand for `Control', and an up arrow to stand for `Shift'
       (eg: `^F3'). In this manual we will use `s' for `Shift' and `c' for
       `Control' (eg: `cF3', `scW'). `Control' and `Shift' are /modifiers/
       - you hold them down while you press the key named afterwards. The
       keynames should all be fairly obvious; if it starts with `k' it
       means the named key on the keypad at the right of the keyboard (eg:
       `k0', `kEnter', `sk1' and so on).

       For a complete list of Zap's default keystrokes, see appendix A.

 3.4.1 Moving around your file

       You will probably already be familiar with the way cursor keys work.
       Not only can you use them to move around, one character or one line
       at a time, but you can use them to move quickly around your file.
       Their complete operation is as follows:

       (*) `Left' - Moves left one character.

       (*) `Right' - Moves right one character.

       (*) `Up' - Moves up one line.

       (*) `Down' - Moves down one line.

       (*) `sLeft' - Moves left one word (see section 6.5).

       (*) `sRight' - Moves right one word (see section 6.5).

       (*) `sUp/PageUp' - Moves up one page.

       (*) `sDown/PageDown' - Moves down one page.

       (*) `scUp' - Scrolls the window up one line without moving the
           cursor.

       (*) `scDown' - Scrolls the window down one line without moving the
           cursor.

       (*) `scLeft' - Scrolls the window left one character without moving
           the cursor.

       (*) `scRight' - Scrolls the window right one character without
           moving the cursor.

 3.4.2 Other useful keystrokes

       Zap's default configuration also contains many of the standard RISC
       OS shortcuts. For instance, the save box is opened by pressing `F3',
       and the selection keys (`cZ', `cX', `cC' and `cV') work as expected.

       Some other useful keys are (these are clearly our idea of what is
       useful!):

       (*) `F2' - Load the named file.

       (*) `cF2' - Close current window.

       (*) `sF3' - Open the save selection box.

       (*) `cF3' - Save the file without opening the save box.

       (*) `F4' - Bring up the search box (see chapter 8).

       (*) `sF4' - Bring up the replace box (see chapter 8).

       (*) `cF4' - Open a new window on this file.

       (*) `F5' - Bring up the goto line/address box.

       (*) `F6' - Drop a mark (see section 9.1).

       (*) `sF6' - Jump to last mark (see section 9.1).

       (*) `F7' - Bring up the search to buffer box (see chapter 8).

       (*) `sF7' - Next match in search (see chapter 8).

       (*) `cF7' - Previous match in search (see chapter 8).

       (*) `F8' - Undo last operation (see section 3.5.1).

       (*) `F9' - Redo last operation (see section 3.5.1).

       (*) `sF9' - Jump to next mark (see section 9.1).

       (*) `scF1-scF10' - Switch mode (see chapter 10).

       (*) `Insert' - Toggle insert/overwrite mode.

       (*) `Print' - Send file direct to printer ('quick print') - see
           section 7.5.

       (*) `sPrint' - Print file through printer driver ('fancy print') -
           see section 7.5.

       (*) `scSpace' - Remove excess spacing around the cursor.

       (*) `sDelete' - Delete next character.

       (*) `cDelete' - Delete current line.

       (*) `scDelete' - Delete to end of line.

       (*) `cCopy' - Start/end selection (see chapter 4).

       (*) `cEscape' - Enter command into minibuffer (see section 3.4.4 and
           section 9.4).

       (*) `cQ' - Quote following character (see section 3.5.2).

       (*) `cR' - Reverse search 'as you type' (or i-search) - see chapter
           8.

       (*) `cS' - Search 'as you type' (or i-search) - see chapter 8.

       (*) `cH' - Get content sensitive help using /StrongHelp/.

 3.4.3 Keystrokes in dialogue boxes

       Zap's dialogue boxes all work in a consistent manner. Firstly,
       `Return' always closes the dialogue and performs the action for that
       dialogue box. Secondly, the `Up' and `Down' keys always move between
       writeable fields, and the `Tab' key always moves onto the next
       field. These features are common with all normal RISC OS
       applications.

       An additional feature with Zap dialogue boxes is that all options in
       the dialogue box can be altered by holding down `Control' and
       pressing the first capitalised letter in the option's descriptive
       text. For instance, in the goto line/address dialogue box (`F5') the
       number you input in the writeable field can be interpreted in three
       ways: as a logical line, as (`x,y') coordinates, or as an address.
       Each option (Logical line, Coordinates, Address) has its first
       letter capitalised (in some dialogues, the first letters clash and
       some options will have later letters capitalised) - so `cL' selects
       logical line, `cC' coordinates and `cA' address. In dialogue boxes
       without writable icons, you can simply press the first capitalised
       letter (ie: you don't have to hold down `Control' first).

       Some dialogue boxes will have specific other keystrokes - for
       instance the search dialogues have commands to access the search
       history. Where it makes sense, some dialogues will use ^P to insert
       Zap's current selection into the writable icon at the caret.

 3.4.4 Zap's minibuffer

       Sometimes you will run a command in Zap which needs more information
       - for instance cW sets the width for the window you're working on,
       but you need to tell it /what/ width to use. In cases such as this,
       Zap will open a 'minibuffer' for you to type information into; this
       temporarily replaces the horizontal scrollbar.

       (You can actually configure the minibuffer to be present constantly;
       see section 12.2.3.)

       If you drag a file or directory into the minibuffer, its full
       pathname is inserted.

       Several control keys have default meanings in the minibuffer. These
       cannot be reconfigured, but are compatible with the /Emacs/
       minibuffer keys:

       (*) `cA' / `cLeft' - Move to start of line.

       (*) `cB' / `Left' - Move back a character.

       (*) `cD' / `sDelete' - Delete the next character.

       (*) `cE' / `cRight' - Move to end of line.

       (*) `cF' / `Right' - Move forward a character.

       (*) `cG' / `Escape' - Quit the minibuffer.

       (*) `cK' - Clear minibuffer's history buffer.

       (*) `cP' - Paste the current selection (in Zap) into the buffer.

       (*) `cCopy' - Delete to end of line.

       (*) `sCopy' - Delete word to right.

       (*) `cU' - Clear minibuffer.

       (*) `cW' - Paste the contents to the cursor position.

       (*) `Tab' - Complete key (eg after `F2', `Tab' will complete
           filenames).

       (*) `Return' - Execute the command.

       (*) `sLeft' / `sRight' - Move the cursor a word at a time.

       (*) `cLeft' / `cRight' - Move the cursor to the start / end of the
           line.

       If you have the Line editor module loaded (see section 13.3.1):.

       (*) `Up' / `sUp' - Recall line.

       (*) `Down' / `sDown' - Next line.

       (*) `cUp' - First line in recall buffer.

       (*) `cDown' - Last line in recall buffer.

       The last four can be redefined by commands to the Line editor
       module, but you will probably want to keep them consistent with the
       rest of the commands for the minibuffer. For information on
       configuring the Line editor, see the files in
       `!Zap.Code.Extensions.LineEditor'.

       In addition, you can access the recall buffer by clicking `Menu'
       over the minibuffer. You can also drag the minibuffer around with
       `Select', and resize it with `Adjust', although this gets reset next
       time the minibuffer is opened - it is of use primarily if you
       configure the minibuffer to be open all the time (see section
       12.2.3).

       One particular use of the minibuffer is to give commands directly to
       Zap. All Zap's menus and keystrokes are defined in terms of the
       commands, which are explored further in section 9.4. All you need to
       know for the moment is that `cEscape' opens the minibuffer and
       allows you to type a command directly. For instance, if you want to
       open the save box, type `cEscape', enter `SAVE' into the minibuffer,
       and press `Return'. The minibuffer will close automatically, and the
       save box will open - just as if you'd pressed `F3'.

   3.5 Further editing

       Now we introduce undo and redo (enabling you to recover from
       mistakes), quoting (which allows you to insert any character into
       your file), and inserting files.

 3.5.1 Undo and redo: recovering from mistakes

       Often you will make a mistake and need to recover from it; you may
       have deleted a section, or formatted a paragraph you didn't mean to.
       Pressing `F8' will undo your last action. Zap stores undo
       information right back until when you loaded or created the file, so
       you can undo several actions in a row. Of course, this can take a
       lot of memory - if you find that you are running short on memory you
       can turn undo off: it's in the File submenu.

       Of course, just having undo would be a bit limiting - so pressing
       `F9' redoes your last undo step. For instance, if you insert the
       letter `a', then press `F8' the `a' will disappear - pressing `F9'
       will bring it back again.

       Zap actually has two different forms of undo, fast and full. Fast
       takes the fastest route through the undo tree, and full follows it
       step by step - an example should make this clearer.

       Suppose you insert the letters `a' then `b', and then undo the last
       step. Now insert the letter `c' - so you have `ac'. If you undo the
       last step, you are left with just `a' again, and up to this point
       fast and full undo will behave in the same way. However if you undo
       /another/ step, there are two choices: fast undo will remove the
       `a', while full undo will insert the `b'.

       `F8' is fast undo; `scBackspace' is full undo.

 3.5.2 Quoting characters

       As we've already seen, Zap uses most `Control + key' combinations to
       perform useful actions; therefore you can't use them to enter
       'control characters' - characters which you can't type on the
       keyboard. Instead, you can 'quote' the character you want, by
       pressing `cQ' (hold down control and press `Q') and then typing the
       control character you want. For instance, `cQ cA' will insert the
       byte 1 (which is `cA'). Use `cQ cSpace' for the byte 0.

       An alternative is to change into Byte mode, type the digits in
       hexadecimal, and then switch back to whatever mode you were working
       in - see chapter 10 for more information about modes in general, and
       section 10.1 for details on Byte mode.

       Control characters are displayed by Zap in blue, as opposed to white
       - see section 7.3 for more information.

 3.5.3 Inserting files

       You can drag a file directly into a Zap window to insert its
       contents at the cursor. If you hold down `Shift', then the filename
       of the file will be inserted instead.

       You can also save from another application into Zap; this will
       always insert the file's contents.

       Another way of inserting a file is to use the `INSERTFILE' command,
       which is available from the `Misc->Insert' menu. This will open the
       minibuffer to let you type in the filename. You can also prefix the
       filename with one or more of `|' and `*' - the first will indent the
       text as if you'd typed it in, and the second will run the file
       through GSTrans first, to allow you to use system variables.

   3.6 Saving and closing files

       In order to save your changes, bring up the save box by pressing
       `F3', clicking on the `File' menu, or opening it from the menu tree
       as `File->Save->(Save box)'. While this doesn't look like a normal
       RISC OS save box, it essentially is - just with more information
       available to you. The icon at the top left is draggable as you'd
       expect, and the filename is near the bottom. In addition, the middle
       section gives you some information about the file - its current
       size, and the date and time it was last altered - and the top right
       allows you to change the filetype. You can either type in a new
       filetype (the upper icon allows you to type it in as text, while the
       lower one is numeric), or you can use the menu to get a list of
       filetypes.

       Zap will warn you if you are about to overwrite a more recent file
       (the warning can be turned off - see section 12.3.1).

       If you want to save the file quickly, without having to confirm the
       filename, you can press `cF3', or click on `File->Save' in the menu.
       This is known as a 'quick save'.

       `cF2' closes the current window; when there are no more windows open
       on a particular file that file will be removed from Zap's memory. At
       this point, if you have made any changes, Zap will ask you wheter
       you want to save the file to preserve your changes, discard it, or
       cancel (therefore not closing the last window). Similarly if you try
       to quit Zap with some modified files still hanging around, it will
       ask whether you want to lose your changes.

       (Zap has an option to allow files to stay in memory even when you've
       closed all windows. This is similar to the way /Impression/, and
       some other applications, handle things - for more information, see
       section 12.3.1.)

 3.6.1 Automatic backups

       When you save a file, Zap will usually overwrite whatever was saved
       on disc under that filename. However, in many cases - particularly
       when you're programming - you might want to keep old versions of the
       files. While you could make sure you always move the old version
       before saving, it would be easy to forget - so Zap has a method for
       doing this for you.

       When you save a file, Zap looks for a directory called `~' (just the
       tilde sign). If it exists, Zap will first move the old copy of the
       file into that directory (overwriting anything with the same name
       already there). If you want more than one old version, you can do
       that by having a number of directories called `~<number>' - eg:
       `~1', `~2', `~3' ... `~n', and Zap will then keep the last n
       versions of the file. Zap won't bother backing up a file if you've
       saved to it in the last two minutes - so if you save every time you
       type a character you won't get a series of backup files with very
       little difference between them. (The length of time Zap will wait
       between backups can be configured - see section 12.3.1.)

       --------------------------------------------------------------------

       The next section in the manual is chapter 4, which also covers
       moving blocks of text around the file, to other files, or even to
       other applications. It also covers various operations you can
       perform on blocks of text, such as sorting.

       Alternatively, you might like to move on to chapter 6, which
       tabbing, wrapping and formatting, and other advanced editing issues.



Chapter 4: Selections
---------------------

       A common need when editing files is to perform an operation on a
       particular section of the file. For instance you might want to
       reformat it to a different line length, or move on section so it
       comes before another. In Zap, as in many editors, you do this by
       /selecting/ a continuous section of the file; there are then a set
       of commands that you can perform on that section to do the jobs you
       need.

   4.1 Making a selection

       There are several ways to make a selection in Zap. The most obvious
       is to use the mouse, which we'll cover first.

       If there is no selection, then dragging `Select' will select a new
       region, and clicking/dragging `Adjust' will select between the
       clicked point and the cursor. If there is already a selection, then
       dragging `Select' will start a new selection; clicking/dragging
       `Adjust' will alter the old region. In either case, hold down the
       `Control' key to leave the cursor unaffected by the selection.

       Alternatively, there are a variety of method for selecting via the
       keyboard, which can be quicker in some cases because you don't have
       to move from keyboard to mouse and back again repeatedly. To select
       via the keyboard, either hold down `Escape' while moving the cursor
       via the cursor keys (releasing `Escape' ends the selection), or type
       `cSpace' to start the selection, move the cursor to the end, and
       type `cSpace' again.

       A third method is to use multiple clicks; double clicking selects a
       word, triple clicking a line, quadruple clicking a paragraph, and
       quintuple clicking the entire file. For more information about using
       the mouse in Zap, see chapter 5.

       You can select the entire text using `cT', and clear the selection
       by using `cZ'.

   4.2 Copying, pasting, cutting, yanking and moving

       Zap implements both the /Edit/ style copy/move of selections, and
       the /Emacs/ style paste/yank. Both of these will work happily across
       different windows, files and even from one mode to another (although
       if you copy a selection in, say, Code mode into Text mode you won't
       get the disassembled text but rather the binary data - see section
       7.4 for a solution to this).

       The /Edit/ method: to move a selection to the cursor position press
       `cV'. To copy the selection to the cursor position press `cC'.

       The /Emacs/ method: to move a selection, /cut/ it with `cX' and then
       /paste/ it with `cY' (the undo buffer must be turned on for this to
       work - see section 3.5.1). To copy a selection, grab it with `scW'
       (this is called /keeping/) and paste it with `cY'. Press `scY' to
       cycle through the previously cut selections (this is called
       /yanking/).

       Note that `cK' and `F10' produce data which can be pasted by `cY'.

       Another way to copy text is via the `Copy' key - see section 3.3 for
       more information.

 4.2.1 The global clipboard

       One very useful (but sadly little-known) feature common to several
       RISC OS applications is the /global clipboard/. Put simply, this is
       a way of using cut and paste,as described above, across different
       applications. Unlike Zap's 'kill ring' which allows yanking, as
       described above, the global clipboard can only contain one object at
       a time.

       The way it works in Zap is that when you copy or cut anything to
       Zap's clipboard (the 'local' clipboard), it also gets put into the
       global clipboard too, so that other applications can use it. When
       someone else puts something into the global clipboard, Zap will use
       that in preference to its own local clipboard when pasting using
       `cY' (the `PASTE' command).

       If there is something on the global clipboard and you want to use
       Zap's local clipboard instead, you can use the `LOCALPASTE' command
       (`cEscape' will bring up a minibuffer to type the command into - see
       chapter 11). If Zap has put something on the global clipboard which
       you don't want available to other applications any more, you can use
       the `Disown clipboard' option which is on the `Misc->Clipboard'
       submenu (the command is `CLEARGC').

   4.3 Saving the selection

       If you have a selection, you can save it by pressing `sF3' to bring
       up the save selection dialogue box. This works in exactly the same
       way as the normal save box (except that it only saves the
       selection); you can drag the file icon to a Filer window, or another
       application as you'd expect.

       Another way to quickly save the selection is to shift-drag it with
       `Select'. This will save the selection with the filename
       'Selection', but is really useful for quickly saving things into
       other applications. You can even `Shift' drag the selection into a
       Zap editing window - it will be copied to the point that you drag it
       to.

   4.4 Processing the selection

       There are a number of actions you can perform on an entire
       selection; here we will just cover the most important ones. These
       are all available from the `Selection->Process' submenu.

       A related topic here is block editing, which allows you to make
       alterations on one line in the selection which are mirrored on all
       the others - see section 6.6.

 4.4.1 Indent

       Indent simply indents the selection by whatever you type into the
       indent submenu. In other words, it adds text at the beginning of
       each line of the selection depending on what the parameter is.

       If you type in a number to the indent submenu, it will indent the
       selection by that number of spaces; otherwise it will indent it with
       whatever you type in. For instance, you might put the string `> ' in
       the indent submenu to 'quote' the selection in the manner of an
       email reply.

       Indent is also available by pressing `cJ'.

 4.4.2 Outdent

       Outdent simply un-indents the selection depending on whatever is in
       the indent submenu. If the indent parameter is currently a number,
       it will remove that many characters from the beginning of each line.
       If the indent parameter is some text, it will remove the same number
       of characters as are in the parameter (so two if the parameter is
       `> ', three if it is `> >' and so on).

 4.4.3 Swap case

       This simply swaps the case of all the characters in the selection.
       It recognises the full ISO Latin 1 character set, so accented
       characters will have their cases swapped too.

 4.4.4 Upper case

       This does the same as swap case, but leaves all characters in upper
       case.

 4.4.5 Lower case

       This does the same as swap case, but leaves all characters in lower
       case.

 4.4.6 Filters

       Zap provides a way of /filtering/ the selection (or the entire file,
       for that matter - see the documentation that comes with /ZapText/)
       through an external program. What actually happens is that the
       selection is fed through the filter program, and the output replaces
       the selection in the file. Several useful filters are supplied with
       Zap, and we introduce some of them here. For more information, see
       the files in `!Zap.Code.Filters.Docs'.

       The menu options call these filters using the default options
       (assuming the filter has options); if you want to use different
       options you'll need to call the command yourself. The Zap command
       being used here is `FILTERSEL', and the filters supplied with Zap
       are kept in a special place which you access by prefixing their
       names with `ZF:'. For instance `FILTERSEL ZF:Sort -descending -case'
       will give a case sensitive, descending ASCII sort. For more
       information, see chapter 11 and the documentation supplied both with
       /ZapText/ and the filters.

 4.4.7 Filter sort

       The sort filter sorts in straight ASCII order. The option on the
       menu does an ascending case insensitive sort - if you call the
       filter yourself you can change those options, as well as making it
       skip leading spaces and tabs on each line.

 4.4.8 Filter format

       The format filter is a simple text formatter. A paragraph is
       recognised by either starting with a space, or ending with two line
       feeds. Tab characters are treated as spaces. This filter has a fair
       number of options, and it's probably easier to read the
       documentation that comes with it than to describe only part of it
       here. You'll almost certainly want to call it directly yourself to
       be able to take advantage of all the features.

       Note that Zap has an internal command, `FORMATTEXT' (`cF6'), which
       does not work in the same way. For information on that, see section
       6.3, which explains Zap's various internal formatting and wrapping
       modes.

 4.4.9 Filter untab

       The untab filter simply replaces each tab character in a file with
       an equivalent number of spaces. It is different to the `UNTABIFY'
       command, which leaves tabs inside quotes ("") alone in program
       source modes such as C, Java and so on.

   4.5 "Sending" the selection

       Zap can send the selection straight to the keyboard buffer. You can
       start this through the `Selection->Send' menu option. Zap sends the
       selection a character at a time; you can abort at any time by
       pressing `Escape'.

       The menu option will strip out control characters; if you need to
       send them too you'll need to use the `SENDSEL' command directly.

       Only one selection at a time may be in the process of being sent.

       --------------------------------------------------------------------

       The next section in the manual is chapter 5, which gives a complete
       description of how the mouse is used in Zap.

       Alternatively, you might like to move on to chapter 6, which covers
       tabbing, wrapping and formatting, and other advanced editing issues.



Chapter 5: Mouse control
------------------------

       The mouse can be used in positioning the cursor, making and
       modifying selections, and a few other useful operations.

   5.1 Standard mouse actions

       The following is a list of the standard mouse actions. First, single
       clicks:

       (*) `Click Select' - Place cursor at the clicked position.

       (*) `Click Menu' - Bring up the window menu. This can be modified by
           holding down various keys while clicking with the mouse.
           `Control' brings up the font menu, `Shift' brings up the colour
           menu, `Alt' brings up the `Modes' menu, and `Control-Shift'
           brings up the mode menu (or the main window menu if the current
           mode has no mode menu).

       (*) `Click Adjust' - If the window doesn't have the input focus, it
           gets the input focus and the moved is moved to the last used
           position (see section 3.3); if the window contains a selection,
           the end of the selection closest to the clicked position is
           moved; if the window contains a cursor then a selection is
           formed between the cursor and the clicked position.

       Second, drags. If you hold down `Control' then the cursor will
       remain in place:

       (*) `Drag Select' - Defines a new selection.

       (*) `Drag Adjust' - Resizes the current selection.

       Thirdly, multiple clicks of `Select' or `Adjust'. If you go straight
       into a drag from these, the selection will only increase in amounts
       of whatever you selected here (for instance, double click then hold
       and drag `Select' will allow you to define a selection restricted to
       words):

       (*) `Double click' - Select a word.

       (*) `Treble click' - Select a line.

       (*) `Quadruple click' - Select a paragraph.

       (*) `Quintuple click' - Select the entire file.

       In some modes, some of these actions don't make sense - in general,
       increased numbers of clicks increase the area selected in a useful
       way.

       If you hold down `Shift' with double-clicking, the definition of
       'word' used will alter slightly. For instance, double clicking in
       `$.mydir.myfile' might only select `myfile'; `Shift' double clicking
       would select the entire filename.

   5.2 Click Send: `Alt' + double click

       If you hold down `Alt' and double click with either `Select' or
       `Adjust', the word at the cursor will be 'sent' to one of a variety
       of places, depending on what you're doing.

       For instance, `Alt' double clicking on a URL in a text mode (for
       instance Text mode or Email mode) will attempt to open that URL in a
       web browser, telnet program, or whatever as appropriate. If you
       `Alt' double click on more or less anything else, it will be looked
       up in /StrongHelp/, if that is installed on your system.

       This system is highly configurable - see section 12.3.4.

       --------------------------------------------------------------------

       The next section in the manual is chapter 6, which covers some of
       the more sophisticated editing techniques not introduced earlier. In
       particular, auto indenting, use of tabs, and how to wrap or format
       your text automatically.

       Alternatively, you could move on to chapter 7, which shows how to
       alter the way Zap displays things - the colours it uses, the font it
       displays the text in, and so on. It also looks at printing.



Chapter 6: Advanced editing
---------------------------

       Now we discuss some advanced editing options - features that you can
       turn on and off. You can set up each individual mode so that it has
       whichever of these options turned on or off that you want; see
       section 12.2.1 for more information.

   6.1 Auto indenting

       Suppose you are typing a list in which each of the entries itself
       might be a list. To make the clearer, you would probably want to
       indent each list, looking something like:

        First list, first entry 
        First list, second entry - this is a list too! 
          Second list, first entry 
          Second list, second entry 
        First list, third entry

       If the lists were long, you could spend ages pressing `Space' or
       `Tab' to indent your lists correctly - but fortunately Zap can help
       you here. With auto indent mode turned on (as it is by default in
       Text and many other modes), Zap will match the indent of the line
       above whenever you press `Return'.

       (Some modes, such as the C, C++ and Java programming modes, help you
       even more by automatically indenting to match a standard programming
       style; see section 10.5 for more information.)

       Pressing `cReturn' breaks the line without auto-indenting, even when
       auto indent mode is turned on.

   6.2 Tabbing

       Tabbing in Zap means two things: firstly, the action of the `Tab'
       key, and second how it displays tabs embedded in the file you are
       working on. We'll deal with each of these individually.

 6.2.1 Tab editing

       What happens when you press the `Tab' key is determined by the
       current tab entry mode, which is configured from the
       `Edit->Tab mode' submenu. Zap has three tab entry modes:

       (*) `Unix tab' - This inserts the current display tab character
           (usually ASCII 9 - see section 6.2.2 below).

       (*) `Column tab' - This moves the cursor to the next /tab stop/; tab
           stops occur equidistantly, and the distant between them can be
           configured from the `Edit->Tab mode->Column tab' submenu.

       (*) `As above' - This moves the cursor to the column which starts
           the next word on the above line. If the previous line doesn't
           extend far enough (ie: you're further right on the current line
           than the previous line extends in total), Zap will scan
           backwards in the file to find a suitable line. If it can't find
           one, it will use Unix tab mode.

       In the last two cases, as many tab characters are inserted as
       possible before using spaces. If you wish to use only spaces, turn
       on the `As spaces' option, in the `Edit->Tab' mode submenu.

       You can use `sTab' to switch between `Unix' and `As above' tab entry
       modes.

 6.2.2 Tab display

       The standard tab character is taken to be ASCII 9, but this can be
       changed from the `Display->Tabs->Tab char' submenu. Here you can
       also configure how the tab character is displayed. Note that unless
       you choose 'None', the tab spacing will be to the next column of
       eight characters. (This is one of the main things which isn't
       configurable, partly because it would considerably slow down Zap's
       redraw system, but also because that's what tab characters mean,
       Bill Gates notwithstanding.)

       The options are:

       (*) `None' - The tab character will be displayed 'normally', using
           the appropriate character in the current font.

       (*) `As spaces' - The tab spacing to the next column of eight
           characters will happen, but that area will be blank.

       (*) `"       |"' - As above, but the actual place in the file that
           contains the tab character will use the tab character (typically
           a small arrow pointing to the right - sometimes the letter 'I'
           when the font doesn't contain a tab character - see section
           7.2); the rest of the tab spacing will be blank.

       (*) `"-------|"' - As for 'As spaces', but the tab spacing is filled
           by a series of dashed and then the tab character.

       If you want nothing to ever act or be displayed like a tab, set the
       tab character to the same as the end of line character - see section
       7.1.

   6.3 Wrapping and formatting your text

       Zap has a number of different options for dealing with files where
       you are editing lines which are longer than the current window is
       wide. Some of these can work together (for instance window wrap and
       soft wrap together is a very useful combination); some of them are
       mutually exclusive.

       Not all of these options are available in all modes.

 6.3.1 Window wrap

       This performs the same action as the option with the same name in
       /Edit/: lines which are longer than will fit into the window are
       wrapped onto the next line. This happens dynamically as the window
       is resized, so there are never any parts of the text which are not
       visible at the sides of the screen. (Compare this with having all
       special wrap modes turned off, where lines which are longer than
       will fit inside the window /extent/ are wrapped onto the next line -
       if you resize the window, you will often obscure the ends of long
       lines and have to scroll to view and edit them.)

       Because only the visible area of the window is used, the horizontal
       scroll bar cannot be dragged, although it still indicates the true
       maximum window width. (In RISC OS 3, you can `Adjust' drag the
       horizontal scroll bar, but it will only allow you to scroll the
       window vertically.)

       Window wrap is useful in Byte and Word modes (see section 10.1),
       where it allows you to quickly set the number of bytes or words that
       are displayed to a line. It is also useful when coupled with soft
       wrap, since this gives the benefits of soft wrap (only breaking at
       word boundaries), while retaining the dynamically adjustable width.

 6.3.2 Soft wrap

       This controls how words are wrapped at line ends; when turned on,
       the display of paragraphs is reformatted dynamically as you type, in
       order to avoid words being split across lines. This works to the
       current display width - see section 7.1.1.

       Note that no physical line ends are ever inserted - soft wrap merely
       affects how Zap displays your file.

 6.3.3 Word wrap

       This acts in a very similar way to soft wrap, except that line
       breaks /are/ inserted at line ends as you type; the rest of the
       paragraph is reformatted accordingly. It can be seen as a 'hard'
       equivalent of soft wrap, because the wrapping it performs affects
       the file, and so will be preserved even if you turn off word wrap.
       Some modes may modify the behaviour of this slightly - for instance
       Email mode preserves quoting while the reformatting occurs.

       The width that Zap word wraps too is controllable from the
       `Edit->Type of wrap->Word wrap' submenu.

       A companion command to this, which reformats a single paragraph in
       the same way, is `FORMATTEXT', which is on `cF6', and also on the
       `Misc->Alter' submenu.

 6.3.4 Line wrap

       This is very similar to word wrap, except that the effect is 'local'
       - the rest of the paragraph is /not/ reformatted as you type. Line
       wrap is mutually exclusive with both word wrap and soft wrap.

 6.3.5 Infinite wrap

       Infinite wrap extends the window wrap option so that the width of
       the window can be increased indefinitely (usually it is constrained
       by whatever you set the width of the window to - see section 7.1.1).

 6.3.6 Auto soft wrap

       Auto soft wrap will turn on soft wrap automatically if it thinks you
       need it (it checks to see if you have any long lines in the file).
       However it only does this when you first load the file, or when you
       change mode, so it is generally most useful as a saved option for a
       mode - see section 12.2.1 on how to use this.

 6.3.7 Strong soft wrap

       Strong soft wrap modifies the soft wrap option to strengthen the
       illusion that the different physical lines (as displayed by Zap) are
       separate entities. With it turned off, the start and end of lines
       are taken to be the start and end of /logical/ lines, as usual
       (logical lines being lines which end in a line break); with it
       turned on, commands such as `cLeft' and `cRight' (move cursor to
       start/end of line) will move the cursor within the physical line
       only.

       This option will also affect how auto indent works (auto indent
       usually looks at the previous logical line; with this option on, it
       looks at the previous physical line, which in general will be less
       useful).

   6.4 Keymaps

       So far, you have been using the Default keymap - all the keystrokes
       have been the standard ones, chosen to be most useful for normal
       editing. However Zap has a range of keymaps available, which serve
       two purposes.

       Firstly, they allow compound keystrokes - for instance,
       `scF11 cX cS' provides a different way of saving the current file.
       This is achieved by altering the /current keymap/ - typically you
       have a keystroke which changes the keymap using the `KEYMAPN'
       command, which only remains in effect for the next keymap;
       thereafter you are dropped back to the /basemap/ (unless the second
       keypress also uses `KEYMAPN'). This is exactly what's happening in
       the example about: `scF11' executes `KEYMAPN "Emacs"', `cX' executes
       `KEYMAP 2', and `cS' executes `SAVEFILE'. Thereafter the current
       keymap returns to the basemap (normally the Default keymap).

       The difference between `KEYMAPN' and `KEYMAP' is simply that
       `KEYMAPN' allows you to use pre-defined names for the keymaps,
       rather than having to remember the numbers. Thus `KEYMAPN "Emacs"'
       is the same as `KEYMAP 1', because the /Emacs/ emulation keymap is
       alternative keymap number one. See section 12.3.3 for more
       information about this, and about how to configure new keymaps. In
       actual fact, instead of `KEYMAPN "Emacs"' or `KEYMAP 1', you can
       just use the command `EMACS' (but this is a special case). `KEYMAPN'
       is case-insensitive - so `KEYMAPN "EMACS"' and `KEYMAPN "Emacs"' are
       the same.

       Clearly, being able to chain keystrokes together is a useful thing,
       since it allows you to access many more functions quickly via the
       keyboard than would otherwise be possible. However keymaps get used
       in another way. We've already used the phrase /basemap/, but we
       haven't really explained what it means. At any one time, each window
       has a current keymap, and also a /basemap/, which is simply the
       keymap that the current keymap drops back to after each keystroke.
       Clearly there are going to be times, when you are doing a particular
       type of editing, where you might want to stay in the new keymap for
       a while, instead of being dropped back to whatever your basemap is;
       you can do this by altering the basemap, either by the `BASEMAPN' or
       `BASEMAP' commands (which work in the same way as the `KEYMAPN' and
       `KEYMAP' commands, except that the effect is more permanent), or
       from the `Edit->Keymap' submenu.

       To change the basemap back to the default, use the `DEFAULTMAP'
       command, or use the `Edit->Keymap->Default' menu option.

   6.5 Cursor behaviour

       Zap has a number of options affecting how cursor movement and
       selection works.

 6.5.1 Line select

       This controls how selections are made and insertions positioned.
       With it turned on, selections which span more than one line are
       confined so that they always selct entire lines; insertions which
       contain more than one line are always made at the start of the line
       where the cursor is, and not at the exact cursor position. This is
       much like the selection model implemented in BASIC mode - see
       section 10.4.

       Though this description may sound obscure, and the option is usually
       turned off by default, it is often very useful. In modes like
       Assembler mode, where lines are rarely very long, it cuts out a
       number of operations - selections can be made lazily, and there's no
       need to manually align the cursor before each paste, and
       consequently you can work significantly faster.

 6.5.2 Smart movement

       This affects `sLeft' and `sRight' (move forward and backward one
       word), and related functions (such as the delete word command). It
       is turned on by default; when turned off these operations stop at
       spaces and not much else. With it turned on, the action feels more
       intelligent, with the cursor stopping more frequently.

 6.5.3 Confine horizontally

       With this option turned on, the cursor cannot be moved right beyond
       the end of a line - instead it moves to the start of the next line.
       This keeps the cursor near existing editable text, and more
       accurately reverses the behaviour of cursor left.

 6.5.4 Confine vertically

       With this option on, when the cursor moves vertically into a line
       which does not extend horizontally as far as the current cursor
       position, the cursor is moved to the end of the line. However the
       preferred horizontal position is remembered, so if you then move
       vertically into a line which /does/ extend far enough horizontally,
       the cursor will move back to where you want.

 6.5.5 Free click

       If on, cursor clicks with the mouse are not confined to the end of
       the line on which they are made. Instead, the cursor can be
       positioned anywhere in the visible region. This option may be of use
       to those generating ASCII art, or editing textual spreadsheets or
       similar (typically with Overwrite mode turned on).

   6.6 Block editing: quickly editing all lines in a selection

       Block editing allows you to quickly perform the same editing actions
       on all the lines of a selection. With it turned on, editing anywhere
       within the selection will perform the edit on all lines of the
       selection simultaneously. Block editing can be turned on from the
       `Edit' submenu.

       There are two related features of Zap that you might like to
       investigate if you find that block editing isn't powerful enough for
       you. Learned sequences allow you to 'record' a set of actions and
       play them back - see section 9.5; the universal argument allows you
       to perform a single command an arbitrary number of times (see
       section 9.6).

   6.7 Line editing

       If line editing is turned on, then line breaks cannot be deleted by
       the user using `Delete'. Also, inserting a new line by pressing
       `Return' does so at the end of the line, rather than at the current
       cursor position. Instead, you can use the `JOINLINE' (join the
       current line to the following) and `SPLITLINE' (split the line at
       the current cursor position) commands, on `cF1' and `sF1'
       respectively.

       This option is used in BASIC mode to emulate the old ARM Basic
       Editor.

   6.8 Other options

       Here are the remaining editing options. Some of these have already
       been introduced earlier.

       On the `Edit->Misc' menu:

       (*) `Hex entry' - If turned on, then ASCII entry is disabled, and
           entry is in hexadecimal (or binary, if binary display is being
           used). This is used in Zap's binary editing modes - see section
           10.1.

       (*) `Non standard' - This option merely turns on an 'unusual'
           editing feature of a specific mode. Currently it is used in
           ARMBE emulation (see section 10.4.1), by Email mode (see section
           10.9) and by the Assembler programming mode (see section 10.6).

       (*) `Spell checking' - Engages spell-as-you-type operation
           (providing you have /ZapSpell/ installed - see section 13.1).

       On the Edit menu:

       (*) `Overwrite' - If turned on, then typing will replace the current
           text at the cursor rather than inserting before it.

       On the Display->Misc menu:

       (*) `Big endian' - This affects modes which deal with data sizes of
           more than a byte - currently Word and Code. In little endian
           mode (with this option turned off), a four byte word is stored,
           as you'd expect for RISC OS, with the least significant byte
           first. For instance, if the contents of the word is &12345678
           then the individual bytes will be [&78][&56][&34][&12]. In big
           endian mode, the bytes are stored in the opposite order:
           [&12][&34][&56][&78]. Some processors store numbers in big
           endian format, such as SPARC (recent ARMs can actually operate
           in either, although they can't be switched while running; little
           endian only is used for RISC OS).

   6.9 Save options

       For normal text-like modes (including most of the programming modes,
       such as C, Assembler, etc.), Zap has three options which affect how
       it saves files.

       Firstly, there is support for DOS-style and Spool files - DOS files
       have line terminators `CRLF' (rather than just `LF') and Spool files
       use `LFCR'. As mentioned earlier, if Zap detects that a file is a
       DOS file or a Spool file when it load sit, it will convert all the
       line endings and set the appropriate option, so that on saving the
       line endings are restored.

       If you have a file where you want to /keep/ the line endings as
       `LF', but where Zap has recognised it as a DOS file or Spool file,
       you can turn the options off from the File submenu. DOS file is
       indicated in the titlebar as a `B' in the options, and Spool file as
       an `S'.

       The third save option is 'strip spaces' (on the Edit menu). This
       simply strips all trailing spaces on lines before saving, and is
       particularly useful in programming modes.

       --------------------------------------------------------------------

       The next section in the manual is chapter 7, which shows how to
       alter the way Zap displays things - the colours it uses, the font it
       displays the text in, and so on. It also looks at printing.

       Alternatively, you could move on to chapter 8, which looks at Zap's
       powerful search and replace system.



Chapter 7: Display options
--------------------------

       Here we look at tailoring Zap's display characteristics so they will
       suit you. In this section, we introduce the options available to
       you, and how to use them - if you want to know how to set up Zap so
       that it will always use these options, see section 12.2.1.

   7.1 Display config

       These display options affect how Zap lays out your window - whether
       it prints line numbers, the space between each line, the display
       width - and the characters taken to mean 'end of line' and 'tab'.

 7.1.1 Display width

       You can set the display width from `Display->Width'. Note that,
       depending on your wrapping mode, this may or may not actually affect
       how the display system works (see section 6.3). Typically, however,
       it sets the window width to that number of characters.

       There is also an option to automatically determine the width you
       need. This is `Display->Misc->Auto width', and it simply finds the
       longest line in your file and sets the display width to that. (This
       won't be available in some modes - for instance, it clearly isn't
       useful in Code mode.) This option is most useful saved as a
       permanent option for a particular mode which might need it - see
       section 12.2.1.

       You can set the maximum and minimum widths that auto-width can use -
       see section 12.3.1 for more information. Note that auto width does
       not operate if soft wrap is turned on.

 7.1.2 Line numbers

       Zap can display line numbers or addresses at the left hand edge of
       the window. By default this is only on in BASIC and Code modes, but
       can be useful in others. This is configured from the `Display->Line'
       numbers submenu; you have the options of no line numbers, logical
       line numbers, physical line numbers and addresses. The first and
       last are fairly clear, but we should explain the difference between
       the middle two.

       Each row in a window in Zap is a different physical line. This means
       that if you have one long line, with no line breaks, and Zap wraps
       it so you can see it all (either because it is longer than your
       display width, or because you have one of the wrapping modes turned
       on), it will appear as several physical lines. (In the goto
       line/address dialogue box (`F5'), physical lines are paired with
       columns to get the "coordinates" option.)

       Logical lines, on the other hand, are a function of the file rather
       than of the way Zap is displaying things: a logical line is
       something which ends with a line break - then you start a new
       logical line. (In BASIC mode, a logical line is something with its
       own line number, but that effectively works in the same way.)

       That covered, you can easily choose which line numbering you want.
       If you choose physical, every single row in the window will have a
       line number; with logical, only those at the start of a logical line
       will have one.

       You can choose whether or not to have your line numbers or addresses
       displayed as hexadecimal using the `Hex nos' option; you can also
       set the width available for them at the left hand edge with the
       `Margin width' option. A value of 8 will give enough space for any
       line number or address, and if you set the width to 1, a star `*'
       will be displayed in place of a line number or address (this is
       mostly of use with logical line numbers, as it quickly shows you
       where logical lines start without taking up much space in your
       window). If the width is too small for the line number or address
       otherwise, Zap will just display the right hand segment of the
       number. You can also opt for a colon to be printed between the line
       numbers and the main text if you wish.

       The two remaining line number options cannot be configured per-mode,
       although they can be set independently for each window. These allow
       you to set the starting line and address for numbering. These can be
       used, for instance, in Code mode so that disassembly is done
       relative to the correct file base (most executables are loaded and
       run at `&8000', but sometimes they might be loaded somewhere else in
       memory, in which case you'd want to set the starting address to
       something different to guarantee correct disassembly).

 7.1.3 Line spacing

       Line spacing can be configured independently for each window, and is
       given in pixels.

       (Line spacing cannot be configured per-mode.)

 7.1.4 EOL and Tab characters

       These can be configured independently for each window, and specify
       which characters Zap considers to define the end of a line and the
       tab character. If you set these to the same thing, tabs will never
       be displayed in a normal text mode.

       (EOL and Tab characters cannot be configured per-mode.)

   7.2 Fonts

       The font used in a Zap window is determined by the `Display->Font'
       menu. There are basically four different options:

       (*) `Bitmap font' - Drawn by Zap; this is the fastest method, and is
           the default. There is currently a limit of four sub-styles when
           using this mode (see section 7.3.1 below). Zap comes with a
           small number of bitmap fonts; see section 2.2.2 for information
           on how to install more.

       (*) `System font' - Drawn by the operating system; this is rather
           drab and boring, but requires less memory. It also doesn't allow
           for sub-styles.

       (*) `Anti-aliased 'DSA' fonts' - DSA stands for Direct Screen
           Access; this is outline fonts drawn by Zap. It is still fairly
           experimental, and there is no support for font sub-styles. It
           will also only anti-alias the foreground and background colours;
           other colours will be drawn, but not anti-aliased.

       (*) `Anti-aliased 'VDU' fonts' - This is outline fonts drawn by the
           operating system. It is the slowest option, but allows eight
           sub-styles.

       For bitmap fonts, the menu tree (`Display->Font->Bitmap') is
       arranged by font size and then font name. You can plot bitmap fonts
       in one of three modes: scaled, 1dpp and 2dpp. Usually you should use
       scaled, since this will automatically scale font heights if
       necessary. Zap basically uses two types of fonts: low res ones,
       where the y size will be roughly the same as the x size, and hi res
       ones where the y size is double the x size. Low res fonts need to be
       plotted at 2dpp in hi res (square pixel) modes, but at 1dpp in low
       res (rectangular pixel) modes; hi res fonts need to be plotted at
       1dpp in hi res modes, and don't work well in low res modes - they
       always look too tall. The scaled option automatically compensates to
       get the best display possible.

       Zap has two default bitmap fonts: one for hi res modes, and one for
       low res. See section 12.3.1 for more information.

       For anti-aliased fonts, the menu tree
       (`Display->Font->Anti-aliased') is arranged by font name;
       `Display->Font->Anti-aliased size' sets the font size in points, and
       `Display->Font->Aspect ratio x100' sets the anti-aliased y:x font
       ratio in percent.

       The default fonts used cannot be configured from within Zap; you
       need to edit its textual settings file directly. See section 12.3.1
       for more information.

   7.3 Colours

       The colours Zap uses to display your file is changed using the
       `Display->Colour' submenu. The first nine colours are 'system
       colours', in that they are the same for all modes. They are:

       (*) `Background1' - The colour used for sections containing no text.

       (*) `Background2' - The background colour used for sections
           containing text.

       (*) `Foreground' - The standard foreground colour.

       (*) `Selection-B' - The background colour for the selection.

       (*) `Selection-F' - The foreground colour for the selection.

       (*) `Cursor-Bac' - The background colour for the cursor (this is the
           colour in which the cursor itself will be drawn).

       (*) `Cursor-For' - The foreground colour for the cursor (this is the
           colour in which the character at the cursor position will be
           drawn).

       (*) `Line nums' - The colour used for line numbers and addresses.

       (*) `Ctrl chars' - The colour used for control characters (ASCII
           0-31).

       If the `All modes' option at the top of the menu is set, then when
       you change a system colour, it is changed in all modes, rather than
       just the one you are using at the time. Other colours are mode
       dependent, and lie below a dotted line on the colours menu; since
       each mode uses the mode-specific colours differently, the
       `All modes' option does nothing for them.

       To learn how to save the colours you have set up so that they will
       always be used for that mode, see section 12.2.1.

 7.3.1 Font substyles

       As well as being able to define the colour, each colour Zap uses can
       have an associated group of font sub-styles; these alter the way
       that Zap draws the characters in question. Currently, the sub-styles
       are bold, italic, underline, strikethrough and inverse (which
       reverses the foreground and background colours). You won't be able
       to set font sub-styles for a colour where it would be inappropriate
       (for instance for a background colour).

       In order to use font sub-styles, the font you are using must
       actually support them. Many of the bitmap fonts don't support all of
       them, although most of the more common ones do.

   7.4 Dumping files

       By now you'll probably have looked at some of Zap's modes other than
       Text. If not, don't worry (it's all covered in chapter 10 in case
       you want to look now); however you've probably gathered that some
       modes including Zap's Code mode, which is an ARM disassembly mode,
       don't display the file you are editing as the contents of the file -
       rather they display it in a more useful form.

       This is clearly a good thing, but what is sometimes useful is the
       ability to take that display and save it off as text. This is called
       /dumping/ the file, and is achieved by pressing `scCopy'; a new text
       file is opened containing the dump. You can then save or edit that
       file as you would any other.

   7.5 Printing files

       There are three ways you can print from Zap. The first is simply to
       open the `printer:$' filing system by pressing `cPrint', and then
       saving the file into it. (You can close the `printer:$' filing
       system again by pressing `scPrint'.)

       The first of the other two methods is 'quick print'; pressing
       `Print' opens a small dialogue box which allows you to specify the
       part of the file you want to print (when it opens, it is set so that
       it will print the entire file), and to set whether or not you want a
       page header. Zap sends the display to the printer directly, with a
       `LFCR' pair at the end of each line. You can change this 'end of
       line' string (as well as strings that Zap sends at the start and end
       of the entire file) - see section 12.3.1 for more information.

       The second method is 'fancy print'; if you have a RISC OS printer
       driver loaded, pressing `sPrint' will open a dialogue box allowing
       you to configure how Zap will print the file. Zap uses the current
       outline font (set in `Display->Font->Anti-aliased'), and has an
       option to preserve syntax colouring (although if you have black as
       your background colour you'll end up using a lot of ink :-). (If the
       option to print in colour is not selected, Zap will still print
       using font sub-styles.) Note that the default setting for the option
       controlling printing in colour is taken directly from the options of
       the currently-installed printer driver.

       The display quality of this method is not yet perfect, and there may
       still be some problems when using it with Computer Concepts' Turbo
       drivers.

       --------------------------------------------------------------------

       The next section in the manual is chapter 8, which looks at Zap's
       powerful search and replace system. It is strongly advised that at
       some stage you read this section carefully, especially if you are
       only used to using /Edit/ to edit text files, since there are many
       things which you can do with Zap's search system which might not
       immediately spring to mind.



Chapter 8: Searching
--------------------

       Zap's search system is quite powerful, and is based loosely on
       /Emacs/ regular expression searching. There are a variety of ways in
       which you can use it; the main ones are search to cursor, search to
       window, replace, and incremental (or keyboard) search. These are
       started by `F4', `F7', `sF4' and `cS'/`cR' (for forward/backward
       incremental search) respectively. The first three use similar
       dialogue boxes.

       The first two are essentially the same, with one important
       difference: search to cursor will jump the cursor to the search
       match, while search to window creates a /throwback buffer/
       containing all the matches (search to window is also sometimes
       called search to buffer). See section 10.7 for more information
       about throwback buffers.

       The Zap search window is split into several sections. In the first
       column is a set of search options; the second column gives the
       direction (forward, backward, forward from the start of the file, or
       all files starting from the start of the first one); and the final
       column gives some more options. Below these columns are the search
       expression (and, for the replace dialogue box, the replace
       expression) and a button labelled `Edit macros' which we'll cover
       later. In addition there are the expected `Cancel' and `Find'
       buttons, and a button marked `couNt' with a field below it -
       clicking this (or pressing `cN', which is why the label is
       capitalised the way it is) will fill the field with the number of
       matches of the current search string.

       `cP' inserts the current selection in Zap into whichever
       search/replace field has the caret. `cK' clears the history;
       `page up' and `page down' and the cursor keys navigate the history
       (cursor keys will move from field to field in the replace dialogue),
       and `cTab' replaces the entry with the one used in the last search.

   8.1 Search options

       A number of options control how Zap's search system works. These
       are: raw search, case sensitivity, macros, \-commands and to window.

 8.1.1 Raw search

       If this option is turned on, then the whole file will be treated as
       a single line of text and searched accordingly. Thus `\<' will match
       the start of the file, and `\>' the end of the file (see section 8.2
       below). The reason it's called 'raw search' is that in this mode,
       Zap won't 'detokenise' first - so you're searching the raw data of
       the file. With this option turned off, the search is done line by
       line, but BASIC mode will detokenise the lines (so you are searching
       against what you see when Zap displays the file, rather than against
       what is stored); Code mode disassembles, and so on.

 8.1.2 Case sensitivity

       If this option is turned on, strings of letters will only match if
       their case agrees; if off, matching ignores case. Case matching is
       currently only done for letters in ASCII - ie the letters A-Z.
       Accented characters in ISO Latin 1 are /not/ understood for case
       insensitive matching.

 8.1.3 Macros

       To make your life easier, you can define up to sixteen macros. These
       are substituted in the search string before the search is actually
       performed. Macros may expand to anything - most usefully, they may
       contain \-commands, as defined below.

       There are three default macros:

       (*) `*' - `\.\*' (matches anything).

       (*) `#' - `\ #' (matches any character).

       (*) `\d' - `\[0-9]' (matches any digit).

       The 'Edit macros' button in the search windows allows you to view
       and edit these macros; note, however, that to change them
       permanently you'll have to edit Zap's textual settings file. See
       section 12.3.1 for more information.

 8.1.4 To window searching

       This option is automatically turned off when you press `F4', and
       turned on when you press `F7'. When it is turned off, the cursor
       will be moved to the first match, and subsequent matches may be got
       by pressing `sF7' (next match) and `scF7' (previous match). A beep
       will sound if there are no more matches, and the cursor will not
       move.

       If it is turned on, all matches are placed in a new throwback file.
       Double clicking entries in this file will cause the cursor to jump
       to the corresponding match - see section 10.7 for more information.

   8.2 \-commands

       The search dialogues have a switch to turn off \-commands. If you
       don't, then the character '\' introduces a /wildcard/. The wildcards
       are documented below, and are also summarised in the search windows
       (although they are initially hidden - click the toggle size icon to
       reveal the wildcard descriptions).

       In this list, `x' stands for any ASCII character unless otherwise
       mentioned:

       (*) `\x' - Matches `x' case sensitively (irrespective of the case
           sensitivity option), unless \x is mentioned below.

       (*) ``x' - Matches `x' only (without any replacement of macros).

       (*) `\(, \)' - Act as brackets for nesting expressions.

       (*) `\{, \}' - Act as bracket, but may be referred to in the replace
           string (see section 8.3 below).

       (*) `\ #' - Matches any character. eg: `'

       (*) `\.' - Matches any character except the return character.

       (*) `\*' - Matches any number of the previous expression. eg: `fo\*'
           matches `f', `fo', `foo' etc., and `\(and\)\*' matches the empty
           string, `and', `andand', etc.

       (*) `\%' - Matches any number of the previous expression. Thus
           `\[0-9]\%' matches `1' in `1pt', and the `395' in `ab395rty'.

       (*) `\|' - Matches either one expression or another. eg:
           `hello\|goodbye\|fred' matches `hello', `goodbye' or `fred'.
           `\(a\|b\)\*' matches `abababa', `abbba', etc.

       (*) `\[...]' - Matches a range of characters. eg `\[a-zA-Z%]'
           matches any letter or a `%'. If a `^' if given after the opening
           bracket, then the range given is the characters that the
           expression /won't/ match, so `\[^abc]' matches any character
           except `a', `b' or `c'. A `]' may be included in the range by
           placing it first in the list (after the `[' opening the list, or
           after the `^' if present).

       (*) `\<' - Matches the null string at the start of a line.

       (*) `\>' - Matches the null string at the end of a line. Note that
           this doesn't work properly; `phip\>' won't match `phip' at the
           end of a line. Assuming your return character is the normal one,
           `phip\n\>' will do the trick (this will be fixed at some point).

       (*) `\+' - Turns on case sensitivity for the following letters. Its
           effect stops at the next wildcard, bracket or command. It
           doesn't affect nested or bracketed statements. eg:
           `\+Fred\|Bill' will match `Fred' case sensitively, but not
           `Bill'.

       (*) `\-' - As above, but turns off case sensitivity.

       (*) `\\' - Matches a `\'.

       (*) `\ddd' - Where d is any decimal digit, matches a byte of that
           value, eg: `\0alf' matches the byte 0 followed by `alf', and
           `\233' matches the byte 233. Please note that `\999' matches
           byte 99 following by `9', since 999 > 255 (the greatest possible
           value of a byte).

       (*) `\&hh' - As above, but matches the hex byte hh when h are valid
           hex characters.

       (*) `\A' - `\Z' - Matches control A to control Z.

       (*) `\a' - Matches alert (ASCII 7).

       (*) `\b' - Matches backspace (ASCII 8).

       (*) `\f' - Matches a form feed (ASCII 12).

       (*) `\hdd..' - Where d's are hex digits, match the given word (32
           bit number).

       (*) `\n' - Matches a newline (ASCII 10).

       (*) `\o' - Matches any character except a `.' (useful for matching
           filenames).

       (*) `\r' - Matches a return (ASCII 13).

       (*) `\t' - Matches a tab (ASCII 9).

       (*) `\v' - Matches a vertical tab (ASCII 11).

       (*) `\?' - Matches a delete (ASCII 127).

       (*) `\wdd' - Where d's are decimal digits, match the given word (32
           bit number).

       (*) `\xhh' - Matches hex numbers as above (where `x' is the letter
           `x').

       Examples:

       (*) `cat\|mat' - Matches cat or mat.

       (*) `re*ment' - Matches any occurrence of `re' then `ment' on a
           line.

       (*) `SWI' - Matches any SWI (in code mode).

       (*) `LDR\|STR' - Matches any load or store instruction.

       (*) `R6' - Matches any instruction using `R6'.

       (*) `BL*&0000A95C' - Matches any call to `&0000A95C'.

       (*) `\&0A' - Matches the byte &0A.

       (*) `\<fred' - Matches fred, but only at the start of a line.

       (*) `main`(' - Matches `main('.

       (*) `\d\%' - Matches any number (where `\d' is a macro which expands
           to `\[0-9]').

       The search will be /much/ faster if you give a definite first
       character to start with. eg: `a\(nd\|pple\)' will be a lot faster
       than `and\|apple'. If the search takes longer than a third of a
       second, then an hourglass will come up displaying the position in
       the file as a percentage underneath. You may stop the search by
       pressing `Escape', and the partial results will be displayed if you
       are using `Search to window'.

   8.3 Replace

       Pressing `sF4' brings up the search and replace dialogue box. The
       first two columns of this are the same as for the search dialogue;
       the last one has a `global' option instead of `to window'. `couNt'
       works the same way as for searching (it does /not/ perform any
       replaces), as does `Edit macros'.

 8.3.1 Global replace

       With the global option turned on, replace will replace all
       occurrences of the search expression with the replace expression, in
       the direction of the search. (So if you're searching forwards, only
       matches forwards of the cursor will be replaced; if the search
       direction is `all files' then all matches in all files will be
       replaced.)

       With global turned off, each match will be highlighted in turn, and
       a `Replace ?' window will appear with a series of options. As usual,
       you can press control and the first capitalised letter of each
       button to get the desired action; in this case you can also do the
       same without holding down control. The options are:

       (*) `Replace' - Replaces that match and moves to the next.

       (*) `Skip' - /Doesn't/ replace this match, and moves to the next.

       (*) `Last' - Replaces this match and aborts the operation.

       (*) `Undo' - Undoes the last replace operation.

       (*) `reDo' - Redoes the last replace operation.

       (*) `All' - Replaces all matches from the current match onwards.

       (*) `Front' - Brings the window containing the match to the front;
           particularly useful when you are replacing across all files.

       (*) `In sel' - Replaces all matches in the selection (since the
           replace system selects the word it's considering, you'll have to
           make your own selection while the operation is in progress for
           this to be useful).

       (*) `Cancel' - Closes the window and aborts the search/replace
           operation.

 8.3.2 The replace expression

       The format of the replace expression is as for the search string,
       with the following additions:

       (*) `&n' - Replace with the n'th `\{ ... \}' expression in the
           search string. n starts at 1 and must be less than 10.

       (*) `&&' - Replace with an `&'.

       Examples:

       (*) S:`cat', R:`' - Removes all occurrences of `cat'.

       (*) S:`\{cat\}', R:`&1s' - Replaces `cat' with `cats', preserving
           case.

       (*) S:`'

       To convert spaces between columns of figures in a table into tab
       characters, use `\{\d\}  \*' as the search string, and `&1\9' as the
       replace string. Alternatively, replace `\{\d\} \%' with `&1\9'.

   8.4 Incremental search

       (This is also sometimes called keyboard or interactive search, or
       i-search.)

       Incremental search is activated by pressing `cS' (to search forward)
       or `cR' (to search backwards - reverse incremental search). When you
       do this, a minibuffer will be opened for you to type the search
       string into. As you type the string, Zap will search though the text
       placing the cursor at the end of the next match. If there is no
       match, Zap will beep and print `(fail)'. Pressing `Delete' removes
       characters from the search string; doing so will move you back to
       the first successful match of whatever is left in the search string.

       To halt the search at the current position, press `Escape' or
       `Return'. If you press an arrow or function key, then the search
       will be halted and the keypress acted upon. Alternatively, `cG'
       (`Cancel') will cause the search to be cancelled and the search
       returned to its initial position before the search.

       Pressing `cS' or `cR' whilst in search mode will move you to the
       next/previous match; if the search string was empty then the
       previous search string will be placed in the buffer.

       Macros are turned off during the search; however `\(' and all other
       \-commands will still work. The current settings of the options in
       the search window will be used (so you if you have disabled
       \-commands in searches, they won't work in incremental search
       either).

       --------------------------------------------------------------------

       The next section in the manual is chapter 9, which covers various
       advanced features of Zap, as well as Zap's internal help system.

       Alternatively, you could move on to chapter 10, which explains Zap's
       different editing/displaying modes, and looks at some of the most
       useful ones. Modes form the key to many of Zap's most useful
       features, and since they've been occasionally mentioned in the
       manual up till now you probably want to learn more about them.



Chapter 9: Advanced use
-----------------------

       Here we look at a final set of advanced functions, before moving on
       to modes. These features are all 'convenience' features, rather than
       being important things that you can't do without.

   9.1 Setting and using marks

       Often it is useful to be able to remember where you are in a file at
       a specific time, so that you can return to it later. Zap allows you
       to do this by using /marks/, which are controlled from the
       `Misc->Marking' menu or from keystrokes.

       To toggle a mark - set if there isn't one there, clear if there is -
       use `TOGGLEMARK', on `sF11'. To set a mark using `DROPMARK' on `F6'.
       To move to the next mark, use `NEXTMARK' on `sF9', and to move to
       the previous mark, use `LASTMARK' on `sF6'. For instance, if you set
       a mark, then move and set another one, `sF6' will move you back to
       the second mark, `sF6' again to the first, and then `sF9' back to
       the second mark again.

       Marks can't be seen when they are set; they can be set to any depth.

   9.2 Working with read only files

       Zap has two types of read only files: firstly there are permanent
       read only files. These tend to be internal documentation files. You
       can't set these to be writable.

       Secondly, there are temporary read only files; you can set these up
       yourself by the `File->Read only' menu option - the same option
       turns off the read only aspect again. This means that you can
       temporarily write-protect a file to stop yourself from doing
       anything stupid to it. Zap also loads any file that it won't be able
       to save changes to as temporary read only.

       If you try to edit a read only file, Zap beeps at you and prints a
       warning in the minibuffer.

   9.3 Zap's help system

       Zap can provide help on the current mode you are using, as well as
       any keystroke, command or function. Pressing c\ brings up a small
       menu in the minibuffer. You can press:

       (*) `K' - Keystroke help - press the keystroke you want help on.

       (*) `M' - Help on the current mode (see chapter 10).

       (*) `F' - Function help - type the function name (see section 11.3).

       (*) `C' - Command help - type the command name (see section 9.4).

       (*) `Z' - Help on Zap (opens `!Zap.!Help').

       To get help on a keystroke in anything other than the base keymap,
       first change into that keymap, and then run the `HELP' command
       (either through the minibuffer, or through whatever it's bound to in
       that keymap).

       Zap can also display help on its menus and dialogues in Acorn's
       /Help/; it also displays help for the relevant mode if the cursor is
       over an editing window.

       Note that the /ZapText/ extension also gives Zap the ability to look
       up help on whatever is at the cursor using /StrongHelp/. To do this,
       press `cH' (you'll need both ZapText and StrongHelp installed to do
       this - /StrongHelp/ is available from
       http://login.eunet.no/~guttorvi/strong.html).

   9.4 Zap's command language

       Pressing `cEscape' brings up the minibuffer and allows you to enter
       commands directly into Zap. This is very useful, because Zap has
       lots of commands (and you can get extensions to provide additional
       ones), and there simply aren't enough keystrokes or menu items to go
       round.

       If you don't know how to use a command, you can type `c\ c' (help on
       commands) and then type in the command name for a brief description.

 9.4.1 Command syntax

       Commands can take a parameter; there are four different types. If
       you request help on a command, the parameter type will be shown as:

       (*) `WIBBLE' - Command Wibble takes no parameter.

       (*) `WIBBLE <byte>' - Command Wibble takes a single byte.

       (*) `WIBBLE <word>' - Command Wibble takes a word (4 bytes).

       (*) `WIBBLE <string>' - Command Wibble takes a string argument.

       Byte and word parameters must be preceded by an `&' if in hex, and
       may be surrounded by brackets or quotes; string parameters must be
       either in double quotes `"' or in brackets `(' and `)'. Within a
       double-quoted string, double quotes themselves can be included by
       doubling them up (eg: `INSERT "Suddenly, Jonathon said ""Hey""."').
       For byte and word parameters, `x' is evaluated to the ASCII value of
       the character x (eg: `CHAR 'n'' inserts the letter `n').

       An error is given if the parameter you place after the command does
       not match the type of the command, except that if you omit a string
       parameter, the minibuffer will be opened for you to type the string
       into. (This is exactly what happens when you press `cEscape', in
       fact - `cEscape' executes the command `COMMAND' without any
       parameters, allowing you to specify your own command.)

       Commands can be chained together by using colon as a separator `:'
       as in BASIC. You /cannot/ chain together commands which use the
       minibuffer (ie: commands which take a string as a parameter but with
       the string unspecified).

       You can put a comment after a command by using `;' (eg:
       `COMMAND ; comment'). The comment terminates at the first `:' (so
       you can put comments between commands when you chain multiple
       commands together).

       This section has provided only a basic introduction to using simple
       commands. See chapter 11 for a complete description of Zap's command
       language, including functions, variables, and conditional and
       looping constructs.

   9.5 Learning and playing back actions

       This feature of Zap is very simple to use, and very useful. To start
       'learning' a key sequence, simply press `cL'. Type the sequence you
       wish to learn and then press `cL' again. (`EXECUTE' also stops the
       learning process.) Press `F1' to execute the learnt sequence.

       Note firstly that Zap will beep after every keypress you make to
       remind you that it is being stored. Secondly note that the `Escape'
       key will /not/ stop the learning process. Only `cL' will stop it.
       Thus you can learn sequences which use incremental search, or
       keyboard selection of regions; both these actions involve the
       `Escape' key.

       Once you have learnt a sequence, you may 'bind' that sequence to a
       key so that pressing that key in future causes the same series of
       actions to take place. To do this press `cF8' and then press the key
       you want to bind the sequence to (or `Escape' if it was a mistake -
       `Escape' won't be bound).

       Examples:

       (*) Suppose you wanted to insert a tab at the beginning of a group
           of lines. One way would be to use the indent option (see section
           4.4.1); another would be to learn the sequence `TAB,DOWN,CLEFT'
           and then to press `F1' a number of times. As a slightly more
           sophisticated example of this, it is often useful to insert an
           extra tab before the last word on the line. You can do this by
           binding `TAB,UP,CRIGHT,SLEFT' and pressing `F1' repeatedly.

       (*) Suppose you wanted to go to the next match of `cat' and switch
           the case of the letters. You could learn and then execute the
           sequence `cS cat Return Escape Left Left Left scS scS scS'
           (`scS' swaps the case of the character at the cursor).

   9.6 The universal argument: repeating actions

       The universal argument feature enables you to execute a keypress an
       arbitrary number of times. Suppose for example you wanted to insert
       100 spaces. The quick way to do this is to type `cU 100 Space'.

       In general you type `cU' then the number of times you want the key
       to be executed, then press `Return', then press the key to execute.
       The 'pressing `Return'' step can be omitted if the key you want to
       repeat is not delete or a digit or another valid key for editing the
       number you are typing (as in the example above).

       Some commands (and therefore the keystrokes they are bound to) can't
       be sensibly executed more than once (for instance `OPENPARENT',
       which opens the directory containing the current file); in these
       cases the universal argument simply won't affect the command or
       keystroke.

   9.7 Object Linking and Embedding, and External Edit

       Zap supports both OLE and EE for editing files. These are used by a
       large number of other programs that wish to have data edited for
       them, but don't know how to do it themselves. External Edit is
       primarily used for editing text, and Zap will edit all Text files
       (&FFF) for EE. Object Linking and Embedding allows non-textual files
       to be edited as well; Zap will claim both BASIC (&FFB) and Text
       (&FFF) files for OLE.

       Note that these file types, as well as those that Zap claims for
       running from the Filer, can be configured - you need to edit
       `!ZapUser.Config.!ZapBoot' and `!ZapUser.Config.!ZapRun'.
       Alternatively, you can edit them using /ZapConfig/ - see section
       13.2 for more information.

       --------------------------------------------------------------------

       The next section in the manual is chapter 10, which explains Zap's
       different editing and displaying modes, and looks at some of the
       most useful ones. Modes form the key to many of Zap's most useful
       features, and since they've been occasionally mentioned in the
       manual up till now you probably want to learn more about them.

       Alternatively, you could move on to chapter 11, which explains in
       more detail Zap's command language, including a look a functions,
       variables, and conditional and looping constructs.



Chapter 10: Zap's modes: helping with particular types of file
--------------------------------------------------------------

       Here we look at one of Zap's most powerful features; the different
       editing and displaying modes. While you might be perfectly
       comfortable using the basic mode (Text) for editing emails, program
       source, and so on, you will probably find that many of these modes
       have features which can help you do the job faster and more
       effectively. In addition, Zap has some modes which offer features
       that Text mode can't supply - such as the binary editing modes, and
       Code, which allows you to edit ARM binaries (executable programs)
       directly.

       To change mode, either use `scFn' (where `Fn' is a function key from
       `F1' to `F10'), or select the mode's name from the Mode menu. Modes
       are /dynamically loaded/, meaning that they aren't loaded until they
       are needed. If a mode hasn't been loaded yet, its name won't be on
       the Mode menu - instead it will be on the `Mode->Load' mode submenu.

       So far in this manual, we have in general only discussed the
       features of Text mode. Many of the modes described here inherit some
       or all of those features - if they aren't available, the relevant
       key press will beep or do nothing, and the menu option will be
       greyed out or will do nothing.

       Each mode can have a number of the options discussed previously set
       independently of the settings of any other mode. These are known as
       /per-mode options/; all the options introduced in chapter 6, and
       most of those in chapter 7 can be set up differently for each mode.
       For more information about this, see section 12.2.1.

       In addition, each mode can have its own, unique options. For
       instance, many modes have a number of colours which aren't available
       in any other mode (the HTML colouring mode has a colour for HTML
       'tags', which would be of no use in other modes). Except for
       specialised colours, which are at the bottom of the
       `Display->Colours' menu, all options unique to a mode will be
       presented in the mode's own menu - this is a submenu from the Modes
       menu itself - for instance, the options for Byte mode are in the
       submenu `Mode->Byte'.

       All modes come with documentation; this will be in the application
       directory of the extension when you install it. Extensions modes are
       stored in `!Zap.Modules'.

  10.1 Zap's binary editing modes

       One set of modes which Zap has which are radically different to Text
       mode are the binary editing modes. These allow you to directly edit
       files either a byte or a word at a time. The two modes are called
       Byte and Word, and they share several common features.

10.1.1 Editing in binary modes

       Firstly, they typically employ an entry system called 'hex entry'.
       With it turned on, you type the byte or word's value in hexadecimal,
       a /nibble/ (ie: a single hexadecimal digit) at a time. For instance,
       in byte mode with hex entry turned on, typing `8' will set the byte
       at the cursor to `08', but keep the cursor where it is. Completing
       the byte (since a byte has two hex digits) by typing `B' will change
       the byte to `8B' (the first nibble is rotated to make way for the
       second), and move the cursor on to the next byte. In Word mode, you
       have to type eight nibbles to complete a word. (Byte mode will also
       do normal entry - with hex entry turned off you can simply type as
       if you were in Text mode. Word mode will not do normal entry - with
       hex entry turned off, typing has no effect.)

       (Note that while the option is called 'hex entry', it doesn't always
       employ hexadecimal - see below.)

       The other editing option that the two modes share is that if you
       press `Return' the byte or word at the cursor is dropped into the
       minibuffer for you to edit; pressing `Return' in the minibuffer will
       set the edited value. This is actually done through an interface to
       the BASIC assembler - a word of value `&8000' will be placed in the
       minibuffer as `DCD &00008000'. In addition, the address of the byte
       or word will be displayed at the far left of the minibuffer. As a
       variation, in Word mode pressing `cReturn' will disassemble the word
       at the cursor - for instance the word of value 0 will be
       disassembled to `ANDEQ R0,R0,R0'. Again, the address will be
       displayed at the far left of the minibuffer.

10.1.2 Display options in binary modes

       If you have already played with the binary modes, you will have
       noticed that the display falls into three sections. On the left is
       the address (this is done using Zap's line numbering system, and so
       can be turned off or altered if you require - see section 7.1.2). In
       the middle is a line of byte or word values, and at the right is
       those values displayed as the corresponding ASCII characters. You
       can click on either of the right hand two sections to set the
       cursor.

       Zap 'display width' (see section 7.1.1) here sets the number of
       bytes or words to display per line. A useful option here is window
       wrap (see section 6.3.1), since this allows you to change the number
       per line quickly with the mouse.

       There are a number of options that control how the display is
       formatted.

       Firstly, you can make all 'control characters' (characters with
       values less than 32) be mapped to any other character. This is the
       `Suppress ctrls' option; the submenu from it sets the character to
       replace them with.

       Secondly, you can choose to 'group' the bytes or words, and the
       ASCII dump at the far right. The group size must be the same in both
       cases (the `Group size' submenu from the Byte and Word options menus
       gives the value used for both); a space is displayed between each
       group. In the default setup, Word mode groups to every fourth word,
       and Byte mode groups to every eight bytes.

       Thirdly, you can change the byte and word display in the middle of
       the window to work in binary instead. If you do this, the 'hex
       entry' system, and editing through the minibuffer by pressing
       `Return' will work in binary also. (The system is still called 'hex
       entry' for historical reasons :-)

       Finally, both modes have one mode-specific colour, ASCII chars,
       which is used for non-control characters in the ASCII dump at the
       right hand edge of the screen.

10.1.3 Creating files directly from memory

       The Byte and Word modes also come in handy with Zap's ability to
       create files directly from memory or disc. This works from the
       iconbar `Create' submenu; the options are:

       (*) `Get module' - Reads a module from memory and dumps it into Code
           mode (see section 10.3 below).

       (*) `Get workspace' - Reads a module's workspace and dumps it into
           Code mode (see section 10.3 below).

       (*) `Get dynamic area' - Grabs the contents of a dynamic area and
           displays it in Text mode (On RISC OS 3.5 and later only).

       (*) `Read memory...' - Allows you to read the memory of a Wimp
           application.

       (*) `Read disc...' - Allows you to read data directly from a disc.

10.1.4 Reading directly from memory.

       Selecting `Create->Read memory ...' from Zap's iconbar menu opens a
       small dialogue box allowing you to specify which range of memory and
       from which task you want to create a file. Dragging the Acorn icon
       at the top (Archimedes icon for RISC OS 2) to a window or icon will
       set the task name to the task that owns it. For instance, to grab
       memory from /Alarm/, drag the icon to /Alarm/'s iconbar icon. At the
       bottom you can specify the range of memory to grab - when you set
       the task, Zap will update these fields to show to maximum range
       possible; the `Grab' button at the bottom grabs the memory and makes
       a file out of it.

10.1.5 Reading directly from disc

       Selecting `Create->Read disc ...' from Zap's iconbar menu opens a
       large dialogue box allowing you to specify which bit of which disc
       you want to read. At the top you specify the filing system (eg:
       `SCSIFS', `ADFS', `RAMFS'); to the right of this Zap will report the
       number of hard drives and floppy drives for the filing system you
       have chosen. In the middle on the left will be information about the
       disc you have selected - name, size, number of tracks, number of
       heads, bytes per sector and sectors per track.

       At the right you can specify which drive, and which part of the disc
       to read, either by sector, head and cylinder or by sector address.
       Then you can click on `Read Disc', `Read Track' or `Read Sector' to
       grab the relevant part of the disc into a file.

       When a window on the file is opened, the `Navigate disc' dialogue
       will also pop up. This allows you to move the view around the disc.
       If you close this dialogue, you can bring it back up from the
       `Misc->Move' submenu (which also has entries which double the
       function of the buttons in the navigate dialogue).

       You can only have one active disc reading operation in progress at a
       time.

  10.2 ASCII editing mode

       ASCII mode allows you to edit text as an ASCII dump - the line
       length is fixed to the display width (so line endings are ignored),
       but otherwise editing is as you'd expect for Text mode.

  10.3 ARM code editing mode

       This mode displays data in disassembled format with one instruction
       per line. The format of a line is address on the left (again using
       Zap's line numbering system, so this is configurable), an ASCII dump
       of the word, followed by a binary or hex display of the opcode
       (binary or hex display is controlled by the `Binary OP codes'
       option), followed by the disassembly itself. Some instructions will
       have comments or warnings displayed off to the right, unless you
       suppress them with the `Comment free' option.

       Many of the normal keys don't perform as you'd expect in Code mode;
       instead they perform functions which are more useful in the context
       of editing ARM code.

       Firstly, typing any normal letter, as well as typing `Return', will
       place the disassembly of the instruction at the cursor in the
       minibuffer for you to edit. Pressing `Return' in the minibuffer will
       reassemble the command; this uses the BASIC assembler (optionally
       augmented by /ExtBASICAsm/ - see section 13.3.2), and so you can use
       BASIC functions sure as `ASC', `EQUD', `ADR' etc.

       Secondly, `Left' and `Right' work differently. `Right' will follow a
       referenced address in an instruction (for instance, pressing `Right'
       with the cursor on an instruction `BL &12345' will jump to address
       `&12345'); it also places a mark when it does so, so the `LASTMARK'
       and `NEXTMARK' commands (see section 9.1) can be used to help you
       keep track of function calls. To make life easier, pressing `Left'
       moves you back to the last mark.

       Thirdly, pressing `cI' will cause you to jump to the address given
       by the contents of the word at the cursor position - for instance in
       a module, the first word in the file gives the start offset of the
       module; pressing `cI' will jump to the start code. This also places
       a mark when it does so, and is known as /indirecting/ (the command
       `INDIRECT' does the same thing).

10.3.1 Code mode colours

       Code mode supplies a very rich set of options to configure how it
       colours the disassembly. First there are some 'utility' colours, not
       associated with the disassembly itself:

       (*) `ASCII chars' - Used for non-control characters in the ASCII
           dump of the word.

       (*) `Hex chars' - Used for the hex (or binary) number dump.

       (*) `Comment' - Comments, warnings and offset information.

       The other colours affect how the disassembly itself is coloured.
       There are also three options in the `Mode->Code' submenu which
       affect this:

       (*) `Unconditional' - Colour condition codes the same colour as the
           rest of the instruction.

       (*) `Minimal' - Colour instruction operands the same colour as the
           rest of the instruction.

       (*) `Condition back' - The `Conditions' colour affects the
           background rather than the foreground (see the entry on this
           colour below for more information).

       The colours are as follows:

       (*) `SWIs' - `SWI' instructions.

       (*) `Branches' - `BL' and `B' instructions.

       (*) `Push R14s' - `STM' instructions that push `R14' (these tend to
           indicate the start of a subroutine).

       (*) `Pull PCs' - `LDM' instructions that pull `PC' (these tend to
           indicate an exit from a subroutine).

       (*) `[ and ]' - The square bracket characters in `STR' and `LDR'
           instructions.

       (*) `{ and }' - The curly brace characters in `STM' and `LDM'
           instructions.

       (*) `#, !, ^ & -' - The character `#' prefixing an immediate
           constant; the character `!' used for writeback in
           `STM/LDM/STR/LDR', the character `^' used for `SPSR' to `CPSR'
           with `PC' in `LDM', and force user bank transfer for all other
           `STM' and `LDM' instructions, commas, and the character `-' used
           in a register list in `LDM' and `STM' instructions.

       (*) `Registers' - All registers.

       (*) `Numbers' - All numbers that aren't immediate constants
           (typically addresses in `ADR' and branch instructions).

       (*) `Immediate' - Immediate constants.

       (*) `Shifts' - Shift operators (`ASR', `LSL', `LSR', `ROR', `RRX').

       (*) `LDM or STM' - `LDM' and `STM' instructions (unless trapped
           above for push/pull `R14/PC').

       (*) `LDR or STR' - `LDR' and `STR' instructions.

       (*) `SWI names' - SWI names (if a SWI number can't be resolved to a
           name, it is displayed as the number, using the `Number' colour).

       (*) `Conditions' - Condition codes. If `Unconditional' is turned on,
           this won't do anything; if `Condition back' is turned on then it
           will affect the background instead of the foreground. Its style
           information will be used either way. If you want to change the
           style only, set `Condition back' and change the colour to the
           same as the `Background 2' colour..

       (*) `'Undefined'' - Undefined instructions. Note that this won't be
           used if the `DCD' option is turned on - see section 10.3.2.

       (*) `FP regs' - Floating point registers.

       (*) `CP regs' - Coprocessor registers.

       (*) `FP instrs' - Floating point instructions.

       (*) `CP instrs' - Coprocessor instructions.

10.3.2 Advanced disassembly

       If you have set Disassembler (Darren Salt's /Debugger Plus/) to be
       autoloaded (see section 13.3.2 and section 12.2.5), then the
       `Code->Disassembler' submenu will enable you to alter how the
       disassembler is done. In general, if you don't understand these
       options, you probably want to leave them at their default settings;
       however here is a brief description of what each does. The `Global'
       option at the top sets whether the alterations you make to the
       settings will only affect disassembly within Zap, or everything
       using /Debugger Plus/. For more information, see the documentation
       which comes with /Debugger Plus/, in `!Zap.Code.Extensions.ExtAsm'.

       (*) `FD if R13' - Use `FD' with `R13', eg: `STMDB R13' is
           disassembled as `STMFD R13'.

       (*) `APCS support' - Use APCS-R register set, and recognise C
           function entry.

       (*) `LFM Stack' - Use stack notation with `LFM' and `SFM' where
           possible.

       (*) `LFS & SFS' - Use `LFS' and `SFS' in preference to `LFM' and
           `SFM'.

       (*) `Quote SWIs' - Put quotes `"' around SWI names.

       (*) `DCD' - Use `DCD' instead of `Undefined instruction', and `BRK'
           where `DCD &x6000010' would be used.

       (*) `VDU' - Use `VDU x' instead of `SWI OS_WriteI+x'.

       (*) `More DCDs' - Use `DCD' instead of `ANDEQ, MOV Rn,Rn' (same
           register), etc.

       (*) `ADRL' - Use `ADRL/ADRX' instead of `ADR' then `ADD/SUB' on same
           register.

       (*) `ADRW' - Use `ADRW' instead of `ADD/SUB Rn,R12,#m' and `LDRW',
           `STRW', `LDRBW', `STRBW' instead of` xxxx Rn,[R12,#m]'.

       (*) `Long MULs' - Append `L' to `UMUL', `UMLA', `SMUL', `SMLA' (thus
           using the official forms).

       (*) `LDRL' - Use `LDRL' instead of
           `ADD/SUB Rn,Rm,#o + LDR Rn,[Rn,#p]' and
           `ADD/SUB Rm,Ra,#o + LDR Rn,[Ra,#p]!' and `STRL' instead of
           equivalent `STRs' (the `LDRWL' form is enabled by this option
           and `ADRW' together).

       (*) `NOP' - Use `NOP' instead of `MOV R0,R0'.

       (*) `Old PSR' - Use the old `PSR' suffixes `_ctl', `_flg', `_all'.

       (*) `Wide' - Disassemble for a wide display.

       (*) `HS and LO' - Use `HS' and `LO' instead of `CS' and `CC'.

       (*) `Shift' - Use `x<<y' comments where possible for numbers >=
           8192. This affects arithmetic and logic instructions; y is
           restricted to multiples of 4 if possible, unless x=1.

       (*) `Lower' - Force all register names to lower case.

10.3.3 Module disassembly

       If a file is filetyped as Module (&FFA), Code mode will attempt to
       display useful comments instead of disassembling garbage for the
       module header.

10.3.4 AIF disassembly

       AIF disassembly comes in two parts; firstly there's the part which
       isn't specific to AIF files, and secondly there's the part that is.
       The part that isn't is that when a disassembled offset (eg from an
       `ADR') points to a string or some other pointer information, a
       useful comment is printed alongside. For instance, if you have
       `ADR R0,<address>' where `<address>' contains a string, the comment
       will be `string: <string>'. This system also puts comments for
       embedded debugging information (function names). The possibilities
       are:

       (*) `'func: <name>'' - C-style function name embedded prior to the
           function.

       (*) `'-> code: <func>'' - C-style function reference; SharedCLibrary
           routines are identified in AIF files, where possible.

       (*) `'-> code: at <address>'' - Unidentified code reference (no
           embedded function name).

       (*) `'error: <string>'' - Reference to a standard error block (only
           when the `ADR' that finds the error is followed by an
           instruction which returns that error; only the string is shown).

       (*) `'string: <string>'' - Reference to a string, where the
           destination contains no control characters but 10, 13 and 9.

       (*) `'-> string: <string>'' - Reference to a string pointer.

       (*) `'-> <header definition>'' - Reference to the header of the
           file; this should work in both AIF and Modules.

       (*) `'-> ->... recursion: at <address>'' - A reference refers to
           itself (this isn't recursive, so it won't spot loops).

       (*) `'-> ->... too deep: at <address>'' - References which would
           imply more than four arrows.

       The second part is that AIF files (recognised by the `SWI OS_Exit'
       as the fifth instruction) have their headers given descriptive
       comments instead of disassembly garbage, much as for Modules. In
       addition, the bits of the header that /are/ valid ARM code are also
       given useful comments.

  10.4 BASIC editing modes

       The mode BASIC edits BASIC files directly in tokenised form. The
       mode BASTXT allows you to edit in detokenised form; however you need
       to load a BASIC file directly into it to detokenise it. Note that
       both these modes actually fiddle with the contents of the file to a
       greater or lesser extent to make editing easier - so you /must/ save
       BASIC files from the same mode as you loaded them into. If you
       don't, you'll probably get garbage.

       In its default setup, line numbers are displayed at the left hand
       side of the window, automatic renumbering occurs when needed, and
       all `GOTO' and `GOSUB' line number references are updated
       automatically. In addition, the mode will auto-expand keywords - for
       instance, typing `P' and then `.' will expand the `P' to `PRINT'.
       Unix tab mode also just advances to the next tab stop (spaces are
       inserted, and only then when you are at the end of a line; tab
       characters - ASCII 9 - cause problems in BASIC files).

       The documentation that comes with ZapBASIC contains far more details
       about these modes that this section does (in particular, it
       describes the colours, of which there are an awful lot).

10.4.1 /ARM Basic Editor/ emulation

       Once upon a time there was a BASIC editor called the ARM Basic
       Editor (ARMBE). This was single tasking, but at least it edited
       BASIC in tokenised form. If you want, Zap can emulate ARMBE fairly
       successfully (although you still have access to all the extended
       features).

       First, turn on line editing (`Edit->Misc->Line edit') and non
       standard editing (`Edit->Misc->Non standard'). The former will
       prevent you from editing across lines - you need to use `SPLITLINE'
       and `JOINLINE' (`sF1' and `cF1') to break up and reconstruct lines.
       The second strips spaces from the ends of lines as you type them.

       These options are provided for those who are familiar with ARMBE,
       and don't want to take the time to learn a new system; the default
       options have both these turned off, because it tends to be much
       easier to edit BASIC (even tokenised BASIC) as close to the way you
       edit normal text as is possible.

       To find out how to set these options permanently, see section
       12.2.1.

  10.5 C, C++ and Java editing modes

       /ZapMJE/ provides a set of modes; in addition to a simple Pascal
       editing mode (not documented here), and an ARM Assembly editing mode
       (see section 10.6), there are three program source modes for
       languages with similar syntax. These are C, C++ and Java. the modes
       share a number of features, including bracket matching (the cursor
       momentarily flicks back to a bracket if you type its pair), syntax
       colouring, and smart auto indentation which tries to follow a
       sensible indentation style. If you don't like these, you can turn
       them off.

       For information about all of these modes, see the documentation that
       comes with /ZapMJE/.

  10.6 ARM assembler editing mode

       Assembler mode is another part of /ZapMJE/; it provides basic syntax
       colouring. This is done simply by highlighting the first column as
       labels, and the rest as instructions, picking out comments, strings,
       operators, names, numbers and brackets in different colours. It also
       uses the `non standard' option (see section 6.8) to alter the way
       the `Tab' key works; with it turned on, it creates three 'tab
       stops', one for instructions, one for their arguments, and one for
       comments. Thereafter it does the normal job of `Tab'.

       For more information about Assembler mode, see the documentation
       that comes with /ZapMJE/.

  10.7 Throwback mode

       This mode handles the files generated by Zap's search to buffer, C
       throwback and /Find/ info output (as well as any other program which
       uses the throwback system). Double clicking on an item will jump to
       that item in the source file. `Shift' double clicking will jump to
       the item and then kill the throwback buffer. Clicking `Adjust' on a
       line will remove the line from the file. Triple clicking will move
       to the match and then bring the window to the front of the window
       stack.

       Clicking on the title of a file, or on the blank lines surrounding
       it, will simply load the file.

       Also note that `Return' acts in the same way as double click and
       `Delete' in the same way as adjust if you move into the file.

       Throwback mode provides simple colouring, colouring different types
       of messages and information differently. It has no support for, for
       instance, colouring the matched words in a throwback search.

  10.8 Taskwindow mode

       This mode handles task windows. To create a new taskwindow, press
       `cF12', or pick the appropriate option either from the Task manager
       iconbar menu, or from the `Create' submenu of Zap's iconbar menu.

       Basically, a task window acts like the command line, only running in
       the desktop. It is vaguely similar to the Command Prompt under
       Windows. You can type in commands, and they are executed - if you
       have Olly Betts' /Line editor/ loaded (see section 13.3.1), then you
       will have a command history available by pressing the arrow keys.

       If you change mode, you will temporarily suspend the task - changing
       back to Taskwindow mode will resume it.

       There are optios on the mode's menu to suspend, resume, unlink,
       relink, and terminate and resurrect the task. When unlinked, the
       task will continue to run independently of the output window,
       changing mode will no longer suspend it, and closing the window or
       quitting Zap will no longer terminate it. This can be of use in low
       memory conditions. If a task window becomes permanently separated
       from Zap in this manner, it may need to be killed from the Task
       Manager.

       The `Die silently' option allows you to kill the task without
       prompting simply by closing the window, for instance by pressing
       `cF2'.

       The `Bracket Matching' option will cause the cursor to flick back
       briefly to a bracket if you type its pair.

       More complete documentation is supplied with ZapBASIC, which
       contains the Taskwindow mode.

  10.9 Email reading and editing mode

       Email mode provides a powerful way to read and edit single emails
       (if you need to read or edit an entire BSD-style mbox, check out
       Newmail mode). It includes fancy things such as style-based emphasis
       recognition (like *this* etc.), header colouring, and a few
       automatic facilities. It also provides a button bar with access to
       many of the more common facilities.

       Email mode will work happily with /Messenger/, /TTFN/, /Marcel/,
       /GMail/, /Pluto/ and /ArcWeb/ to supply email editing facilities.

       You almost certainly won't be able to use Email mode straight off;
       you'll need to set it up so it knows which email system you use. See
       the documentation that comes with the mode for more information.

 10.10 HTML editing mode

       /HoTMeaL/ is a syntax colouring mode for HTML. It currently supports
       HTML 3.2, and has a variety of useful commands, and a button bar, to
       assist in HTML editing. You can also drop files into /HoTMeaL/ to
       create links - and with images, it will work out the relevant
       `WIDTH' and `HEIGHT' attributes.

       For full documentation of /HoTMeaL/'s features, see the supplied
       documentation.

       --------------------------------------------------------------------

       The next section in the manual is chapter 11, which explains in more
       detail Zap's command language, including a look a functions,
       variables, and conditional and looping constructs.

       Alternatively, you could move on to chapter 12, which looks at how
       to customise Zap to suit your specific needs.



Chapter 11: Commands: Zap's command language
--------------------------------------------

       Here we explore fully Zap's internal command language. Be warned
       that this gets fairly sophisticated - with this, you can effectively
       write your own commands to do a wide variety of things. This section
       is certainly unnecessary for the basic user of Zap (some might argue
       that it is only really useful to those seeking to bend a
       recalcitrant Zap to their every whim; but clearly this is not the
       truth :-).

       You might like to look at section 9.4 first, which introduces the
       basic system. However we'll go over that again here in more depth,
       so it's not essential.

       You can enter commands into Zap in a number of ways. Firstly, and
       most immediately, you can press `cEscape' and type them directly
       into the minibuffer; pressing `Return' will execute them at once.
       Secondly, you can bind them to a key, by entering them into the
       `Keys' file. Thirdly, you can attach them to a menu by entering them
       into the `Menus' file. See chapter 12, and in particular section
       12.3.3 and section 12.3.5 for information on the last two. You can
       also bind commands to be automatically executed when you load a
       particular file or type of file - see section 12.3.2 for more
       information.

       Throughout the rest of this section, where it matters, we will
       assume that you are entering commands into the minibuffer. The main
       difference is that errors are reported immediately (and you can't
       stop Zap from starting up by getting a command wrong in the
       minibuffer - you can sometimes in the configuration files).

       If you /do/ get something wrong, Zap will try to tell you roughly
       what's happened. Unfortunately, parts of Zap's command language are
       dealt with by the operating system, and the error messages from
       these bits can be a little obtuse at times. One irritating message
       is `Expression buffer overflow', which simply means that whatever
       you're trying to evaluate is too long; expressions cannot be longer
       than 255 characters (this is set by the OS, so unfortunately we have
       no way of increasing it).

       Remember that commands may be chained together using `:' (as in
       BASIC), and that comments may be placed after commands using `;' -
       these run until the next `:', or the end of the command string.

  11.1 Types of command

       Commands can take a parameter; there are four different types. These
       are:

       (*) `none' - command takes no parameters at all.

       (*) `byte' - command takes a byte; specifying a number that won't
           fit into a byte will be reduced to just the least significant
           byte.

       (*) `word' - command takes a word.

       (*) `string' - command takes a string.

       You must always get the parameter type right.

       Numbers may optionally be given enclosed in parentheses or quotes:
       `WRAPWIDTH 76', `WRAPWIDTH (76)' and `WRAPWIDTH "76"' are all valid.

       Strings may be given either in double quotes `"', in which case
       additional quotes must be doubled up (so
       `"He said ""Hi!"", then left"' would be a valid string); or in
       parentheses, in which case quotes within the parameter must be
       matched. So `("Go on", said Michael)' is valid, but `("Hey!)' isn't.
       Note that
       `("I thought (and it was a sensible thought) that you were dead.")'
       is also valid.

  11.2 Parameter evaluation

       Clearly, in some cases, you might want to do a quick calculation,
       and insert the result into Zap (or use it as the parameter to any
       command, in fact). You can do this: remember that the `INSERT'
       command takes a string parameter, and inserts that at the cursor.
       All we need to do is to evaluate an expression, and convert it to a
       string. This can be done using `INSERT $(50 + 70)'.

       This inserts the string `120' into your file.

       If you need to feed the result of an evaluation to a command that
       takes a numeric argument, you need to make the result be a number so
       it's the right type for the command. The `WRAPWIDTH' command is just
       such: `WRAPWIDTH #(50 + 70)'.

       This sets the wrap width to 120 for the current file.

       The bit inside the brackets is known as an /expression/; it is
       /evaluated/ to get a result, which is then converted to the right
       type (string or number) to become the parameter.

       (For historical reasons, you can also use `@(...)' instead of
       `$(...)'; this is strongly deprecated, and if you start using it
       will almost certainly cease to be supported at the most inconvenient
       moment!)

11.2.1 Allowed syntax

       Parameter evaluation actually uses the operating system call
       `OS_EvaluateExpression' (which is also used by `*EVAL'). Hence
       anything that can be fed to `OS_EvaluateExpression' is valid syntax
       for parameter evaluation. (In addition, Zap first substitutes the
       results from Zap function calls and Zap variables; we shall meet
       these later.)

       You can either build up a string using the evaluation system, or a
       number. (You then convert to whatever you need using either `$(...)'
       or `#(...)' as described above.) Operations you can perform on
       numbers include:

       (*) `+, -, *, /, MOD' - integer operations.

       (*) `=, <, >, <=, >=, <>' - integer comparison (the result is either
           false=0, or true=-1 - however if you try to just do
           `INSERT $(0 < 1)' Zap will actually insert `4294967295', which
           is the unsigned value of -1. To insert `-1', use
           `INSERT $(STR(0 < 1))').

       (*) `>>, <<' - arithmetic shift right and left.

       (*) `>>>' - logical shift right.

       (*) `STR' - convert to a string.

       (*) `AND, OR, EOR, NOT' - (bitwise) logical operators.

       String operations you can perform include:

       (*) `+' - string concatenation.

       (*) `=, <, >, <=, >=, <>' - string comparison (the result is either
           false=0, or true=-1, as above).

       (*) `VAL' - convert to an integer.

       (*) `RIGHT, LEFT' - substring extraction.

       (*) `LEN' - length of a string (result is an integer).

       Brackets can be used to force expansion and evaluation in a certain
       order. For instance the example `INSERT $(STR(0 < 1))' above
       evaluates (0 < 1), which yields an integer -1 (true), and then
       converts to a string `-1'. The parameter is then converted to a
       string (ie: nothing is done to it) before being passed to the INSERT
       command to insert it at the cursor position. This sounds like a lot
       of work just to insert the string `-1', but a few examples should
       help here. Only the parameter itself is given - it's assumed that
       you'll be using it as `INSERT $(<parameter>)'.

       (*) `STR ("Jimmy" < "Fish")' - Evaluates to `1' if `Jimmy' is before
           the alphabet than `Fish'. It isn't, so it actually evaluates to
           `0'.

       (*) `STR ((10 + 16) / 2) RIGHT 1' - Evaluates to the last digit (as
           a string) of result of the integer expression (10 + 16) / 2 (ie:
           3).

       (*) `"The " + "cat " + "sat " + "on " + "the " + "mat (slowly)."' -
           Evaluates to the string `The cat sat on the mat (slowly).'.

       These examples seem quite trivial. In the next section, we show how
       to use system variables (eg: `<Wimp$Scrap>') within expressions.

       You should beware of bugs in the operating system evaluation. For
       instance, `INSERT $(1<2 AND 3>4)' will insert `14', instead of the
       expected `0'. In this case, you can avoid the problem by doing
       `INSERT $(3>4 AND 1<2)' - similar workarounds are almost always
       possible.

11.2.2 Accessing system variables

       Since parameter evaluation uses the operating system routines, you
       can access system variables. This is done in the following way:
       `INSERT $(sys$date)'.

       We've given the entire command here because otherwise it might not
       have been obvious what was going on: anywhere that you would
       normally put a string (delimited by quotes) in an expression, you
       can put the name of a system variable and that will be inserted.
       Bear in mind that while most system variables are strings, some are
       numbers - so you can use a numeric system variable anywhere you
       might use a number in an expression. For instance, if you had a
       system variable myvar whose value was the number six (say created by
       `*seteval myvar 6'), you could do `INSERT $(myvar / 2)' to insert
       the string `3'.

11.2.3 Dynamic versus static evaluation

       The above examples are known as /dynamic evaluation/ - because the
       expression is evaluated every single time the parameter is required.
       While this is generally fine when you type things into the
       minibuffer, it clearly might not be so helpful if you want to use it
       in the `Keys' or `Menus' files, where it might be being executed
       regularly as part of a keystroke or menu item. Evaluating the
       expression takes time that you'd probably rather not spend; what we
       need is /static evaluation/, that only gets evaluated once, the
       first time the parameter is used (in the case of the `Keys' or
       `Menus' files, the parameter is actually evaluated when the file is
       loaded).

       We can do static evaluation as follows:

            WRAPWIDTH #=(50+70) 
            INSERT $=(Sys$Time) 
            INSERT $EVAL (Sys$Time LEFT 5)

       This works exactly the same way as for dynamic evaluation - the only
       difference is that the different brackets force static evaluation
       rather than dynamic. The last example is a static function call; the
       first two are static evaluations to number and string respectively.

       From the above examples, it may not be clear why dynamic evaluation
       - every single time the parameter is needed - is ever different from
       static. However consider that the value of system variables may
       change over time - and in the next two sections we will introduce
       functions and variables, which can be used inside evaluated
       parameters, and which can and will change as you use Zap. Using
       them, it should become clear that dynamic and static would have very
       different effects if the parameter say included a function call to
       find out where the cursor was.

       Further, when we consider looping constructs, which allow a group of
       commands to be executed an arbitrary number of times, the difference
       between dynamic and static evaluation for commands typed into the
       minibuffer will become important as well.

  11.3 Functions

       Functions are a special type of Zap command; instead of performing
       an action, they return a value which can be used in an expression.
       As such, they can take any of the parameter types of normal
       commands. In particular, they can take evaluated expression as
       parameters (although it starts to get rather difficult to find
       concrete and useful examples of this!).

       Functions are introduced with an `@' character. For instance:
       `INSERT $(@MODEN)'.

       This inserts the name of the current mode (in lower case).

       Many functions are supplied by Zap itself, and several more by the
       command extensions, particularly /ZapText/ and /ZapUtil/. You should
       see the documentation with each of these for more information, and
       several examples on how to use them.

       For completeness, here's the best example we could find which uses
       only core commands and functions, and demonstrates use of a function
       which in turn takes an evaluated expression as a parameter:
       `INSERT $(@CHAROFF #(my_charoff))'.

       This inserts the value (ie a number from 0 to 255) of the character
       at an offset given by the system variable my_charoff from the
       current cursor position. 255 is inserted if the character is outside
       the file (this is a feature of the `@CHAR' function).

  11.4 Variables

       Clearly if we can evaluate things, we might like to store them in
       variables somehow. You can do this using the `SET' command:
       `SET (variable=expression)'.

       For instance, `SET (foo="string")' sets the Zap variable called
       `foo' to the string value `string'. `SET (bar=12)' sets the Zap
       variable `bar' to the numeric value 12. Since we use an expression
       to set the value of a variable, we can perform calculations, use
       functions - and even use other variables (once we've shown you how
       to use them :-).

       Variable names may contain letters, digits, and the characters ``',
       `_' and `$'; must not start with a digit or `$'.

       To unset a variable, use the `UNSET' command. This takes a
       /wildcarded/ variable name. For instance, `UNSET (*)' unsets all the
       Zap variables; `UNSET (q*x)' unsets all Zap variables beginning `q'
       and ending `x'; `UNSET (b#r)' unsets all Zap variables with three
       characters in their names, the first being `b' and the last `r'.

       In order to use a variable in an expression, prefix it with `@$' or
       `@#.' Use `@$' with strings, and `@#' with numbers. For instance:
       `INSERT $(@$foo)'.

       To evaluate a variable as an expression, use `@=':
       `INSERT $(@=bar)'.

       If you need to include a literal `@', you'll have to quote it
       /unless/ it's in a string, eg:
       `$(Alias$@@RunType_FFF+" this @ doesn't need to be quoted")'.

11.4.1 Local variables

       To declare variables /local/, use the command `LOCAL', which takes a
       comma-separated list of variable names: `LOCAL (foo,bar)'.

       Not that the variables are /not/ initialised; all that happens is
       that their old values are stored ready to be restored when these
       local variables go 'out of scope'.

       Local variables remain in effect ('in scope') during the current
       command string. (It might help to think of it as treating each
       command string like a procedure in BASIC.)

  11.5 Conditional constructs

       We're almost into heavy territory, but don't give up, because one of
       the most useful features of the command language is about to be
       introduced: conditional constructs. These do things only if certain
       conditions hold, and in particular the `IF' construct is very useful
       in keystrokes.

       Conditional constructs may be nested.

11.5.1 `IF'

       The syntax of the `IF' construct is as follows:

            IF <condition>:<command(s)>:[ELSE:<command(s)>:]ENDIF

       The `ELSE' bit is optional - don't use it if you don't need it. The
       condition for an `IF' is an expression, so you can put things like
       functions in it:

            IF (@CHAR=@TABCHAR OR @CHAR=32):RIGHT:ENDIF

       Move the cursor right if it's on a tab or a space.

       One of the most useful functions for this is `@IN', which takes a
       comma-separated list of expressions. It returns true if the first
       element is the same as any one of the later ones (all elements must
       be of the same type):

            IF (@IN(@MODEN,"basic","code")=0):UPDATEWINDOW:ENDIF

       Redraw the window if not in BASIC or Code mode.

11.5.2 `CASE'

       `CASE' can be used instead of a whole chain of `IF' constructs. The
       syntax is:

            CASE <expression>: 
                    WHEN <list of expressions>:<command(s)>: 
                    WHEN <list of expressions>:<command(s)>: 
                    ... 
                    DEFAULT:<command(s)>: 
            ENDCASE

       The `<list of expressions>' for `WHEN' must be of the same type as
       the `<expression>' in the `CASE' command - in other words, you can
       either check for all strings, or all numbers, depending on what's in
       your `CASE' command.

       The `<list of expressions>' for `WHEN' is comma separated; if the
       expression in the `CASE' statement matches any of those in the
       `WHEN' statement, the commands in that `WHEN' 'block' (up until the
       next `WHEN') are executed. If no `WHEN' expressions match, the
       `DEFAULT' commands are executed.

       This acts more or less identically to BASIC's `CASE' construct,
       except that if the `CASE' expression is matches in more than one
       `WHEN', all matching `WHENs' have their commands executed - unlike
       BASIC where only the first match is executed.

       If you want functionality like C's `switch()' construct, then you
       can use `CWHEN' instead of `WHEN'; if the immediately preceding
       `CWHEN' or `WHEN' contained a matching expression, the commands for
       /this/ `CWHEN' will also be executed. Otherwise `CWHEN' works as for
       `WHEN'.

       You can break out of a `CASE' block using `BREAK' (useful if you
       have lots of `CWHEN' statements and you want to prevent fallthrough
       from the one you're in at the moment, but also want subsequent
       matching `CWHEN' expressions to have their commands executed).

       You can break out of the `CASE' statement using `CONTINUE' (so no
       more `WHEN' or `CWHEN' matches will be considered).

       For more information, you should read the internal help for each of
       these commands. For instance, to see the help on the `CASE' command,
       use `HELPCOM "CASE"', or `c\ 'c' "CASE"'.

  11.6 Looping constructs

       Now we consider looping. This is useful if you want to do something
       to, say, every line in a file, or every character in the selection.
       Many of these operations may already have commands dedicated to them
       which will almost certainly be faster - check before embarking on
       something complicated using Zap's command language, which can be
       quite slow at times.

       Note that infinite loops are very easy to get into - use
       `Alt+Escape' to break out if something looks like it's taking too
       long and might have become stuck.

       Looping constructs may be nested.

11.6.1 `WHILE'

       WHILE <condition>:<command(s)>:ENDWHILE

       The condition is a Zap expression, as you'd expect; if the condition
       is true, the loop is executed. On reaching the `ENDWHILE' command,
       control returns to the `WHILE' command and the test is done again.
       This continues until the condition is false. (So if the condition is
       false to start off with, the commands never get executed.)

11.6.2 `REPEAT'

       REPEAT:<command(s)>:UNTIL <condition>

       The condition is a Zap expression; if the condition is false,
       control returns to the `REPEAT' command. This continues until the
       condition is true. (So if the condition is false throughout, the
       commands will be executed once; contrast this to the `WHILE'
       construct, above.)

  11.7 Examples

       This concludes our foray into the Zap command language. To make life
       easier, and give some pre-built (and tested!) ways of using it to do
       useful things, here are a set of examples. Be warned that while the
       earlier ones are fairly simple, the later ones are significantly
       more complex.

       Note that the examples are given broken over several lines - this
       isn't possible in Zap. It is done here simply for readability.

11.7.1 Simple conditional

       Firstly, a relatively simple conditional. This does a variety of
       different tabbing actions depending on the mode you're in. For this,
       you'll need /ZapUtil/ installed (`@CURSORCOLUMN' is in /ZapUtil/;
       `MJE_REINDENT' is in /ZapMJE/, but so are the C, C++ and Java modes
       - the command won't be needed unless we're using one of these modes,
       and then it will be there already).

        CASE (@MODEN): 
          WHEN ("code"): 
            NOTIFYUSER "Tab isn't a useful action in code mode!" 
            ; WHEN, so this will now drop to the ENDCASE : 
          WHEN ("c","c++"): 
            IF (@CURSORCOLUMN > 0): 
              TAB:CONTINUE ; Drop to the ENDCASE : 
            ENDIF: 
          CWHEN ("java") ; drops through from the above 
            (providing the IF condition wasn't true) : 
            MJE_REINDENT ; reindent the line according to context : 
          WHEN ("basic"):INSERT "  " ; make it do a little spacing : 
          DEFAULT : TAB ; just the normal Tab action : 
        ENDCASE

       In C and C++ modes, if you're not right at the left-hand edge of the
       window, it will perform the normal tabbing action - otherwise it
       will reindent the line. It will always reindent the line for Java
       mode; for BASIC it inserts a couple of spaces (tabbing doesn't work
       normally in BASIC mode - see section 11.7.4 below for how to do a
       more sophisticated tab in BASIC mode). In Code mode it displays a
       brief error message, and in all other modes it does the normal
       action of `Tab'.

11.7.2 Simple loop

       Finding a simple loop without using conditionals is difficult.
       However one comes up: /ZapDS/ contains a number of commands which
       perform bitwise operations on the byte or word at the cursor. The
       following EORs the selection with a given value. You'll also need
       /ZapUtil/ for the functions. The rather gruesome bit of string
       manipulation at the beginning is to extract the window and start of
       the selection from `@SELECTION,' which also gives you the end of the
       selection. The function is known to return three comma-separated
       hexadecimal numbers, nine characters each (eight plus a leading
       '&'). In general it isn't advised to do things like this because of
       what might happen if the function changes; however in this case it's
       fairly guaranteed to remain constant.

       (Note that really this should be wrapped in
       `IF (@SELANYWHERE):...:ENDIF' - it's rather unsafe as it is, and
       will fall over with an error if there isn't a selection. However, in
       the interests of trying to find a simple example of a loop on its
       own which is also useful ...)

       CURSOR $(@SELECTION LEFT 19): 
       WHILE (@INSELECTION): 
         DS_EOR "60" ; EOR with 60 : 
       ENDWHILE

       Note that we might want to preserve the position of the cursor over
       this routine: you can either use marks (dropping a mark at the
       beginning, executing the command, and then doing `LASTMARK' to go
       back to where you were), or grab the cursor into a variable using
       `SET (pos=@CURSOR)'. Then you can restore using `CURSOR $(@$pos)'.
       Note that `CURSOR' and `@CURSOR' are in /ZapUtil/.

11.7.3 'For'-style loop and static evaluation

       Zap doesn't have an equivalent of BASIC's
       `FOR ... TO ... STEP ... NEXT' (C's `for(,,){}') construct. However
       you can simulate it using `WHILE'. This example also demonstrates
       the difference between static and dynamic expression evaluation.
       Note that you have to do this in two stages, because the static
       evaluation is done while parsing the command string - so unless the
       variable n is already set, you get an error.

       SET (n=32)

       WHILE (@#n<127): 
         CHAR #(@#n)  ; dynamic : 
         CHAR #=(@#n) ; static  : 
         SET (n=@#n+1): 
       ENDWHILE

       This will insert the ASCII characters from 32 (`SPC' - space) to 126
       (`~'), separated by spaces. An alternate way of doing it, which can
       be done in one go, is to wrap the `WHILE' loop in a `COMMAND' call:

       SET (n=32): 
       COMMAND ( 
         WHILE (@#n<127): 
           CHAR #(@#n)  ; dynamic : 
           CHAR #=(@#n) ; static  : 
           SET (n=@#n+1): 
         ENDWHILE 
       )

11.7.4 Loop and conditional

       Let's try to get a better tabbing action for BASIC mode - don't
       forget that tabbing itself doesn't work normally in BASIC. We'd like
       to indent, using spaces, to the next tab stop - where there's a tab
       stop every eight characters. For this, you'll need /ZapUtil/ for the
       `@CURSORCOLUMN' function.

       IF (@MODEN = "basic"): 
         SET (cur=@CURSORCOLUMN): 
         IF ((@#cur MOD 8) = 0) ; absolutely on a tab stop -  
           insert eight spaces straight off: 
           INSERT "        " : 
         ELSE: 
           SET (nexttab=((@#cur / 8) + 1) * 8): 
           WHILE ((@CURSORCOLUMN <> @#nexttab) 
                  AND (@CURSORCOLUMN >= @#cur)): 
             INSERT " ": 
           ENDWHILE: 
         ENDIF: 
       ENDIF

       The `... AND (@CURSORCOLUMN >= @#cur)' will stop us if something has
       gone too wrong and we wind up earlier on on the line (or a
       subsequent line) than we started. This could happen with wrapping,
       for instance. Alternatively, we could have used
       `... AND (@CURSORCOLUMN > 0)', since if it was /exactly/ 0, the
       branch which inserts exactly eight spaces would have been taken -
       because (0 MOD 8) = 0.

       Exercise for the reader: this is actually a terribly inefficient way
       of doing the job. It can be done simply using INSERT, @CURSORCOLUMN,
       and parameter evaluation, plus the check that we're in BASIC mode at
       the start.

       --------------------------------------------------------------------

       The next section in the manual is chapter 12, which looks at how to
       customise Zap to suit your specific needs.

       Alternatively, you could move on to chapter 13, which introduces a
       number of useful extensions to Zap. In particular, it looks at
       /ZapSpell/ (an interface to the Computer Concepts' spell checker),
       and introduces Olly Betts' invaluable /line editor/.



Chapter 12: Customising and configuring Zap
-------------------------------------------

       Now we will look at configuring Zap; as has been mentioned several
       times before, you can customise many of the features of Zap. Here
       we'll show you how. Note that some areas of configuration are
       substantially less complex than others; some, introduced in the
       first few sections (up to and including section 12.2.1), are both
       fairly simple and incredibly useful - you'll almost certainly want
       to read these at least briefly now. Later ones get increasingly
       complex - the last few sections of this chapter describe how to
       completely reconfigure how Zap deals with different filetypes; how
       to reconfigure all the keystrokes; and how to define Zap's menus!
       You're unlikely to need these features straight away - so you might
       want to skip the second part of this chapter until you have a need
       for these facilities.

       Zap uses two distinct types of configuration, known as /textual
       configuration files/ and /binary configuration files/. You don't
       really need to know why, but you do need to know what it means. The
       first options we'll look at are all handled by the binary
       configuration system, and these are options you can set up from
       inside Zap. This means that you can change them while it's running,
       experiment with the settings until you have them right, and then
       save them so you'll have the same options next time. The second set
       of options (from section 12.3.1 onwards) are part of the textual
       configuration system. To edit these, you'll need to load the
       relevant configuration file into a text editor, edit them to make
       the alterations, save them - and then you need to get Zap to reload
       them.

       All configuration options are stored within one place - ZapUser. As
       noted in section 2.2.1, in the installation notes, this means that
       you can carry your own options around with you, even while using Zap
       on a different computer.

       If you find that you want to configure Zap, but are having
       difficulty with the standard configuration methods, you might want
       to look at /ZapConfig/, which is a graphical configuration utility
       for many of Zap's features. See section 13.2 for more information.

  12.1 Other complete configuration setups

       If you don't like the default configuration, but don't want to get
       your hands dirty trying to set things up yourself - or want to save
       some time by starting with a configuration closer to what you want -
       then you might like to look at the alternative configuration sets
       available from the Zap ftp site. Due to time constraints, these may
       not be as 'pure' as is ideal - it would be nice to have an
       /Emacs/-like configuration, an /Edit/-like configuration, a
       /StrongED/-like configuration, and so on - what you will actually
       probably find is that the various developers have simply packaged up
       their own configuration sets, including whatever bizarre (and
       sometimes fairly specific) needs they have. Nonetheless, they should
       be useful to someone - in particular, they may well show some of the
       more sophisticated things that can be done with Zap.

       Complete replacement configuration setups come in the form of a copy
       of ZapUser; you should follow the instructions in the installation
       guide to change configuration sets - see section 2.2.1 for more
       information.

       For more information, see http://www.zap.uk.eu.org/download.html, or
       go straight to the FTP site at
       ftp://ftp.zap.uk.eu.org/pub/1.40/configs/.

  12.2 Binary configuration options

       Here we look at the binary configuration options. These can all be
       edited within Zap, so you can experiment with them until you're
       happy, then save them so they'll be the same next time.

12.2.1 Per-mode options

       Something we've been mentioning through the manual is that many of
       the options can be set on a per-mode basis; that is, that each mode
       can have these options configured independently of all the other
       modes. In addition to all the colours, the following options can be
       configured per-mode:

       (*) /Display options/ - Autowidth; wrap width; window wrap, infinite
           window wrap, word wrap, line wrap, softwrap, strong soft wrap
           and auto soft wrap.

       (*) /Edit options/ - Line edit, overwrite, non-standard edit,
           autoindent, hex entry, big endian, spell-as-you-type, block
           edit, strip spaces on save, and base keymap.

       (*) /Tabs/ - Display, entry (unix, as above, column; insert as
           spaces).

       (*) /Cursor/ - Smart movement, free click, confine vertically,
           confine at end of line, line select.

       (*) /Line numbers/ - Display (none, logical, physical, address),
           base (hexadecimal or decimal), margin width and colon display.

       There are two main ways of configuring these options (you can also
       configure them through /ZapConfig/). Firstly, and probably most
       usefully, you can change the options for a particular window, and
       then copy those options across to become the defaults for that mode.
       You do this with the `Misc->Copy ops' menu item. Note that this
       won't save those options - merely set them up as the defaults. To
       save the current default options, you either need to use
       `Options->Save options' from the iconbar menu, or
       `Misc->Copy ops->Save options' from the window menu - the latter
       will first copy the window's options across as the defaults, and
       then save the defaults for all modes.

       This system can be extended slightly - since each window 'remembers'
       the options it has for each mode, you can set up the options you
       like in all the modes using one window, and then set the default
       options for all modes from this one window in one go. Use
       `Misc->Copy ops->All modes' to do this. (Note that this doesn't save
       the options.)

       The only options that won't be copied across in this way are the
       read onlyread only attributes. This is because it would be rather
       irritating if every file were opened read only - doubly so if they
       were opened permanent read only, because then you couldn't make them
       writable again at all.

       The second method is via the iconbar menu. The `Options' submenu has
       a number of submenus and options; the important ones here are
       `Mode', `Edit' and `Display' - the mode selected in the `Mode'
       submenu is the mode for which you are configuring options (and the
       mode-specific options can be configured through this submenu), and
       the current settings in `Edit' and `Display' are its current
       defaults. You can therefore change the options for any mode by first
       switching `Options->Mode' to the relevant mode, then changing the
       options in `Options->Edit' and `Options->Display'. Once finished,
       you should always change `Options->Mode' back to whatever it was
       before - this is known as the 'default mode', and is used when Zap
       doesn't know what mode to drop a file into - and also as the mode
       when you load a file whilst holding down `Control'. In general, you
       probably want this to be either Text or Byte (make sure that it's a
       'core' mode - one of Text, Byte, Word, ASCII or Code - or you may
       get problems next time you load Zap).

       Again, changing options in this way doesn't save them - use
       `Options->Save options' to make these new defaults permanent.

12.2.2 Configuring Zap's cursors

       You may remember that Zap has four different cursors - the usual
       editing cursor, two cursors used when you are in copy mode, and a
       'mark' cursor to indicate where the cursor would be in a window that
       doesn't have the focus. (See section 3.3.1 for more information.)
       You can configure how these are drawn from `Options->Cursor types';
       each can be set to any one of `block', `square', `underscore', `bar'
       or `none'; they all should be fairly self-explanatory.

12.2.3 Configuring the minibuffer

       You can configure how the minibuffer works from
       `Options->Mini buffer'; you can set the foreground and background
       colour, whether the system font (the alternative being the desktop
       font) is used under RISC OS 3.5 or later (or the soft-loadable
       'nested wimp'), and whether the minibuffer is permanently available,
       or just pops up when needed.

12.2.4 Miscellaneous configuration options

       Zap has a variety of miscellaneous options which you can set on or
       off. They are configured through `Options->Misc', and are as
       follows:

       (*) `Auto-del files' - Auto-delete files when the last window is
           closed; if not, files will hang around until you remove them
           directly using `Files->Remove' or `Files->Close' on the iconbar
           menu.

       (*) `Auto-clr regions' - Automatically clear the selection when you
           do anything which doesn't use the selection (this is like
           various word processing and DTP packages).

       (*) `Undo supported' - Whether undo is supported for all
           newly-created or -loaded files.

       (*) `Flashing cursor' - Whether Zap's editing cursors flash - you
           can configure the flash rate (see section 12.3.1).

       (*) `Check datestamp' - Warn if you try to save to a file where the
           copy on disc is newer than the file you're trying to save (this
           can cause problems if saving over a network where the clocks on
           the different computers aren't properly in sync).

       (*) `Auto-clr search' - Clear the search window each time it is
           opened.

       (*) `Confine cursor' - Confine the cursor so that when you scroll a
           window it remains in sight.

       (*) `Trap MSDOS files' - Recognise files with MSDOS and Spool file
           line endings, and take appropriate action.

       (*) `Be tolerant' - Be tolerant of other applications which use
           broken Wimp messages; some applications, including /Fresco/, may
           not function properly with Zap unless this is turned on.

       (*) `Silent operation' - Don't beep.

       (*) `No anti-aliasing' - Don't use anti-aliasing when using DSA
           outline font redraw; sometimes it can look messy, so turning it
           off makes things easier to read.

       (*) `No h-scroll bar' - Avoid having a horizontal scrollbar when it
           isn't needed - it will be turned off when window wrap mode is
           turned on, and also when the window is at its fullest extent.
           The latter will only happen under the 'nested wimp'.

12.2.5 Autoloading internal extensions

       Zap has a number of 'internal' extensions, introduced in section
       13.3, which it can load automatically when it thinks it needs them.
       None of these is essential, but they can make life easier in some
       cases. Whether they are automatically loaded or not is configured
       from `Options->Misc->Autoload' (Zap will use them if they weren't
       set to be autoloaded, but were loaded for some other reason - for
       instance by the user, or by another application).

  12.3 Textual configuration

       Here we look at the different options that are part of the textual
       configuration system. This is all accessed through the bottom part
       of the `Options' submenu from the iconbar. Firstly, you can open any
       textual configuration file using the `Options->Edit config' submenu
       - and you can open the directory containing all of them by selecting
       `Options->Edit config' itself.

       Secondly, you reload the settings using `Options->Reload keys'. This
       will work for everything except the filetypes configuration, where
       you have to rebuild all the options first (this is because, in
       addition to the user-specified filetype configuration, each mode can
       tell Zap which types of file it knows about) - do this through
       `Options->Create keys', and then use `Options->Reload keys' to get
       the new options.

       Except for the `Menus' file, all the textual configuration files use
       the same format. Any non-blank line defines a single /key variable/,
       and is of the form `comment &xxx value' where `comment' is any text
       without a `&' character in it. Any line without an `&' in it is
       discarded completely. The &xxx is known as the /key number/, and
       dictates what the value is actually used for. For instance, it might
       be a particular setting, or it might be a key binding.

12.3.1 Miscellaneous settings

       The Settings file is divided into two sections: firstly Zap's search
       macros. These have key numbers &200 to &20F; the value is of the
       form `macro_string replacement_string', with the strings separated
       by whitespace. The macro string can be up to seven characters, and
       the replacement string up to 23 characters.

       The second part of the Settings file is various miscellaneous
       options. They are as follows:

       (*) `&300' - Date format to use for the `INSERTDATE' (`scD')
           command; see `OS_ConvertDateAndTime' for details of the format
           string.

       (*) `&301' - Time format to use for the `INSERTTIME' (`scT')
           command.

       (*) `&302' - Default anti-aliased font name.

       (*) `&303' - Number of blank lines to leave at the end of a window.

       (*) `&304' - Default anti-aliased font size in points.

       (*) `&305' - Number of pixels to shave off the top of an
           anti-aliased font character.

       (*) `&306' - Number of pixels to shave off the bottom of an
           anti-aliased font character.

       (*) `&307' - Codes to send to the printer at the end of a line for
           'quick print'. This string is `GSTrans'ed first.

       (*) `&308' - Number of characters to keep the cursor from the left
           margin.

       (*) `&309' - Number of characters to keep the cursor from the right
           margin.

       (*) `&30A' - Number of characters to keep the cursor from the top
           margin.

       (*) `&30B' - Number of characters to keep the cursor from the bottom
           margin.

       (*) `&30C' - Window left margin, in OS units.

       (*) `&30D' - Window left margin, in OS units.

       (*) `&30E' - Command to run when Select clicked on iconbar icon.

       (*) `&30F' - Command to run when Adjust clicked on iconbar icon.

       (*) `&310' - Number of pixels to shave off the left of an
           anti-aliased font character.

       (*) `&311' - Number of pixels to shave off the right of an
           anti-aliased font character.

       (*) `&312, &313' - Reserved.

       (*) `&314' - Minibuffer size in characters.

       (*) `&315' - Default indent string.

       (*) `&316' - Flashing cursor on period in centiseconds.

       (*) `&317' - Flashing cursor off period in centiseconds.

       (*) `&318' - Minimum auto-width width.

       (*) `&319' - Maximum auto-width width.

       (*) `&31A' - Name of the bitmap font to use in low resolution modes.

       (*) `&31B' - Name of the bitmap font to use in high resolution
           modes.

       (*) `&31C' - Default attributes to use for newly created files.

       (*) `&31D' - Dialogue box offsets from parent window, in OS units
           (as `x,y').

       (*) `&31E' - Reserved.

       (*) `&31F' - Codes to send to the printer at the start of the file
           for 'quick print'. This string is `GSTrans'ed first.

       (*) `&320' - Codes to send to the printer at the end of the file for
           'quick print'. This string is `GSTrans'ed first.

       (*) `&321' - Minimum time between backups, in seconds.

12.3.2 Zap's behaviour with different file types and locations

       There are two filetype configuration files: `Types (low)' and
       `Types (high)'. Typically you should put user configuration things
       in `Types (low)'. `Types (high)' is intended for resolving conflicts
       between different modes, which might both try to grab a particular
       file - `Types (high)' would allow you to ensure that the fight is
       always won by the mode that you choose.

       These files contain two types of variable. Firstly, &1xxx variables
       (which also includes &2000), which affect which mode files of a
       particular type are loaded into, and secondly &5xx variables, which
       affect which mode files with certain filenames are loaded into. Both
       have a similar final part, which is the /command/. This is of the
       form `[+]<mode name>[:<command(s)>]'.

       The mode name indicates which mode a file will be loaded into if it
       matches this rule; the optional `+', if present, will cause the file
       to be loaded even if Shift is not held down. The command(s) after
       the mode name, if present, will be executed after the file is
       loaded. For instance, the default configuration has the following
       command for all files of type &100: `Byte : STARTADDR 55'; files of
       this type are loaded into Byte mode, and then the command
       `STARTADDR 55' is executed. There is no '+', so you have to either
       drag the file to Zap's iconbar, or double click it while holding
       down `Shift' (left `Shift' on RISC OS 2).

       Now we'll look at the two different sorts of rules. The first is a
       very simple rule: is the file of a certain filetype? We use the
       &1xxx variables for this - they have the form
       `<comment> &1xxx <command>', where command is as above, and comment
       is as usual. The xxx specifies which filetype this rule matches, in
       hexadecimal. Use the key variable &2000 to match untyped files.

       The second possible rule is more complex. These are the &5xx
       variables, and they work by trying to match the complete filename
       against a Zap search string. The format is
       `<comment> &5xx <filetype> <path> <command>'. Comment and command
       are as above; path is a normal Zap search expression (see chapter 8
       - note that macros won't work, but \-commands will). The xx here is
       completely irrelevant - typically you would have all your &5xx
       variables actually using &500 as the key number. The command is
       executed only if both filetype and path match; a filetype of -1 can
       be used to match all filetypes.

       As an example, consider the following from the default
       configuration:

            &500    &FFD    \ #\*.o.\o\*     +Code

       This will load any file of type &FFD (Data), that is within a
       directory called `o', into Code mode. (ie: it ensures that object
       files, as produced by C compilers and similar, will be loaded into
       Code mode). The `+' ensures that it will be loaded without needing
       to drag to Zap's iconbar, or to hold down Shift.

       Remember that you must run `Options->Recreate keys' before reloading
       to get changes to the filetypes configuration to work properly.

12.3.3 Configuring Zap's keystrokes

       The `Keys' file defines all of Zap's keymaps. The key variables
       &000-&1FF define the keymap "Default" (number 0); the value is the
       command or commands (`:'-separated, as usual) to be executed on that
       keycode - we'll go into this in more detail in a minute. Subsequent
       keymaps are defined by key variables &yy0xxx, where yy is the keymap
       number and xxx is the keycode. The keymap used as the base map for
       any mode which doesn't choose its own is given by key variable &400.
       Alternate keymaps are defined using higher &4xx key variables, which
       have the format `<comment> &4xx <low> <high> <name>' - low and high
       and the lowest and highest inclusive keycodes used by that keymap
       (keycodes outside this range will do nothing in that keymap). The
       name is used on the `Misc->Keymap' menu, and by the `KEYMAPN' and
       `BASEMAPN' commands.

       Keycodes are based on those returned by `Wimp_Poll'; thus function
       keys return &180-&1FF, as documented in the PRMs. (Look at the
       `Keys' file if you don't have a copy of the PRMs - or get the
       WimpKeys manual for /StrongHelp/. Standard characters return their
       ASCII values &20-&FF as usual. &7F is unshifted `Delete'.
       Additionally, Zap augments these basic values to allow, for
       instance, to have `scD' and `cD' doing different things. These are
       documented in `Docs.Technical.E-Keycodes'.

       To make life easier, you can define a range of keycodes in one line,
       simply by specifying the range instead of a single keycode. For
       instance, to map `F1'-`F8' to insert
       `Please don't press this key again', use something like:

       F1-F8 &181-188 INSERT "Please don't press this key again"

       There are a number of special substitutions which happen for keycode
       definitions, both in the base keymap and in subsequent ones.
       Firstly, if you use `n' instead of the numeric parameter to a
       command, it will be replaced by the keycode. For instance:
       `Ascii chars &020-7E CHAR n' in the default keymap makes sure that
       typing a character will insert that character.

       Secondly, instead of a command you can use `*<n>'. Here, the command
       will be taken from the keycode n. If you omit the `n' (ie: just use
       `*'), then the keycode used will be the keycode you are currently
       defining, in the base keymap (for instance, in the /Emacs/ keymap -
       number 1 - we have `&1001E-1014E *' which defines most of the Emacs
       keymap to be the same as the Default keymap. If you use this
       substitution in a keycode range, it will work in the most sensible
       way: for instance, in the base keymap the keypad numbers are mapped
       to do the same as the number keys using `k0-k9 &1C0-1C9 *&30'.

       If you want to stop a keystroke from being passed on, bind `NULL' to
       it. Try to avoid binding anything to `F12', because it will stop you
       easily accessing the command prompt.

12.3.4 Configuring Click Send

       It is possible to configure the `Alt'+double click behaviour of Zap
       from the ClickSend file. This uses key variables &6xx (as with the
       &5xx variables, the xx doesn't matter and you should usually use
       &600 for all of them). The format is documented at the header of the
       file, and is fairly difficult to explain in any other way. In
       general you won't need to alter this, but if you do it's probably
       advisable to talk to Darren Salt, author of the Click Send system,
       if you start running into problems. See section 15.4 for details of
       how to get in touch with Darren.

12.3.5 Configuring Zap's menus

       Zap's `Menus' file defines all the menus that Zap uses. the format
       is fairly simple: any line starting with '|' is treated as a comment
       and is discarded; blank lines are also discarded. The file then
       starts with a single initial line which specifies the number of
       valid menu handles (so you need to set this to at least as many
       menus as you define, or some of them won't load). After this are a
       series of menu definitions.

       Each menu definition contains a declaring line of the form:

       `<handle>     <name>  <width>'

       Width specifies the width, in characters, required - in general you
       should set this to a little more than the widest item, to get things
       looking neat. The name must be given in quotes. Handles start at
       zero, and the first twenty (0-19) are used as follows:

       (*) `0' - Iconbar menu.

       (*) `1' - Window menu.

       (*) `2' - Filetype menu.

       (*) `3' - Mode menu.

       (*) `4' - Main font menu.

       (*) `5' - Byte mode menu.

       (*) `6' - Word mode menu.

       (*) `7' - Code mode menu.

       (*) `8-19' - Reserved.

       The remaining menu handles can be used however you like. The default
       `Menus' file gives a fairly sensible way of doing things.

       After the declaration for a menu is a series of lines giving the
       items in it. Each of these must be indented by a single tab
       character (ASCII 9), and is of the form:

            Text    [<command>]     [> <command> | <menu handle>]

       The text must be quoted; the first command is executed if the menu
       item is selected by the user. Anything after a `>' character defines
       a submenu - either give a command which can supply a submenu (any
       command that takes a string parameter can be used as a submenu; in
       addition, some commands specifically create submenus), or give a
       valid menu handle from the `Menus' file to use as the submenu.

       If you want to use a command which isn't part of the core, you can
       do so; it won't be loaded until it's actually needed. This allows
       you to have very flexible menus, without a huge memory overhead of
       loading all the extensions when Zap starts up.

       To get a separator line in a menu, use a line containing a tab
       character (ASCII 9) followed by a hyphen `-'.

       See the default `Menus' file for examples on how this all fits
       together; it's actually a lot easier to use than to describe.

       Note that it is impossible to get Zap to reload its menus. In order
       to get edited menus in Zap, you'll have to quit and restart it.

  12.4 Differences in different versions of RISC OS

       Due to different features supplied by different versions of RISC OS
       itself, Zap has a few issues which alter depending on which
       operating system you are using.

12.4.1 Dynamic areas

       Zap uses dynamic area storage for files and fonts from RISC OS 3.5;
       it uses the Wimp Slot in earlier versions of the operating system.
       (Note that there is a utility called /Dummy Dynamic Areas/, which
       supplies dynamic area support for earlier operating systems; Zap
       will use this if it is present.)

12.4.2 Fonts

       If using anti-aliased fonts on RISC OS 2, you will need the outline
       font manager version 2.42.

12.4.3 Task windows

       If using task windows on RISC OS 2, Zap will expect the module
       `Task' in the `System:Modules' directory. This should be the Task
       module supplied with DDE. `cF12' will not bring up the taskwindow on
       RISC OS 2 (unless a Zap window has the focus).

12.4.4 Loading files

       Only left `Shift' double click will load a non-text file under RISC
       OS 2; right `Shift' is deliberately not tested, since some people
       use it for other things. (Under RISC OS 3 `Shift' double click is
       handled by the operating system, and we have no control over it.)

12.4.5 Help

       There is no interactive menu help in RISC OS 2; you will have to
       read the `HelpData' file(s) directly.

12.4.6 Templates

       Zap uses appropriate Template files for different versions of RISC
       OS. This means that two-dimensional templates will be used under
       RISC OS 2.

       Note that there is a bug in the ROM fonts supplied with some
       versions of RISC OS 3.7 (notably for the A7000+), which means that
       the default template set doesn't work properly (it can spontaneously
       reset the desktop font to the system font). However since we have
       very few reports of this happening, and because the default
       templates are in our opinion the best set available, we haven't
       forced the set to one that doesn't cause this problem. to change the
       template set, open `!ZapUser.Config.!ZapRun' and edit the line at
       the bottom which reads:

            Set Zap$Templates       ZapTemplates:Default so that it reads:

            Set Zap$Templates       ZapTemplates:Tyler

       You'll have to make sure that the `Tyler' template set is installed
       for this to work (it is available in the core distribution, so it
       should be there).

12.4.7 NCOS

       In theory, Zap should work on NCOS (Network Computer Operating
       System - as used in Acorn's NetStation). There are two issues:
       firstly, the iconbar under NCOS is hidden until someone puts an icon
       on it; Zap supports a `-noicon' option to prevent it from doing
       this, and a command `INSTALLICON' to place an icon on the iconbar if
       it hasn't already done so. However `-noicon' isn't used as standard
       under NCOS; you'll have to edit `!Zap.!Run' (`!Zap.!Run,feb') to get
       this behaviour. Secondly, since NC's have no Filer, however, loading
       files is more tricky - particularly so if you don't have an iconbar
       icon either.

       The authors are uncertain about the utility of Zap under NCOS in any
       case; however if you have any difficulties with Zap on NCOS (or any
       information about its being useful :-), please get in touch (see
       section 15.4).

       --------------------------------------------------------------------

       The next section in the manual is chapter 13, which introduces a
       number of useful extensions to Zap. In particular, it looks at
       /ZapSpell/ (an interface to the Computer Concepts' spell checker),
       and introduces Olly Betts' invaluable line editor.

       Alternatively, you could move on to chapter 14, which you should
       read if you want to help with Zap development, whether in a
       technical or non-technical role.



Chapter 13: Extensions to Zap
-----------------------------

       Here we look at various useful extensions to Zap. Some of them may
       or may not have come with the core distribution; if not, they are
       available from wherever you got Zap itself (or, if not, from the
       main Zap site - see section 15.2).

  13.1 /ZapSpell/: spell checking for Zap

       /ZapSpell/ provides features to allow you to spell check from within
       Zap. A number of features are included; spell checking the selection
       or an entire file (using throwback to mark unrecognised words), and
       simple dictionary lookup.

       The front end is started by the `SPELL' command (`cA' or from the
       `Misc->Spell' menu). It will select the word at the cursor, and try
       to that word in the dictionary. The main window has a large number
       of buttons; `Previous' and `Next' move backwards and forwards
       through the file looking for unrecognised words; `Check selection'
       and `Check buffer' will open a throwback window containing all
       unrecognised words; `Replace' replaces the current selection in the
       file with the current word in the writable icon at the top of the
       spelling window.

       /ZapSpell/ uses Computer Concepts' /Impression/ Spell module (not
       supplied); it also provides an interface to Computer Concepts'
       /WordWorks/ thesaurus/dictionary application.

       More information is available in the documentation which comes with
       /ZapSpell/, which is a 'normal' Zap extension - ie it lives in
       `!Zap.Modules'.

  13.2 /ZapConfig/: graphical configuration of Zap

       If you have looked at chapter 12, you may already have been
       frustrated by the way that you have to go about configuring Zap.
       Fear not: many of these features can be configured in a graphical
       environment, using /ZapConfig/, which can be launched from the
       `Options' submenu from Zap's iconbar menu.

       /ZapConfig/ has its own detailed documentation, but basically
       loading it puts an icon on the iconbar which opens a main window
       when clicked on. From here there are lots of individual sections;
       any one can be open at a time, and each configures a separate
       section of Zap. You can configure more or less any part of Zap
       except colours and mode-specific options using /ZapConfig/; in
       particular, similar options (such as everything to do with display)
       are grouped under one section; this differs from Zap itself, because
       some of the display options are in the `Settings' file (see section
       12.3.1).

       The main drawback of /ZapConfig/ is that is works externally to Zap;
       in order to use all the changes you've made, you have to quit and
       reload Zap.

       /ZapConfig/ lives in `!Zap.Code.Config'.

  13.3 Behind-the-scenes extensions to Zap

       There are a few extensions which Zap can use to make your life
       easier. These are autoloaded when required (although you can turn
       that feature off - see section 12.2.5).

       These extensions all live in `!Zap.Code.Extensions' - in general
       this needn't concern you, however, because they tend to be supplied
       with the core distribution. Even if you obtain them separately, they
       will usually be supplied within a dummy `!Zap' structure, so you can
       simply copy them over the top of your current Zap installation.

       In general these aren't specific to Zap - but they are so useful
       with Zap that they can be installed with it, and automatically
       loaded by it.

13.3.1 Olly Betts' /Line editor/

       The most important extension is Olly Bett's excellent line editor.
       This supplies a variety of features to Zap: it is used to provide a
       history for the minibuffer and the search windows, and it is used in
       Taskwindow mode to provide a command line editing facility similar
       to tcsh (and other Unix shells) or 4DOS.

       We strongly suggest having this autoloaded (unless you load it in
       your boot sequence :-), because it makes life so much easier. See
       Olly's documentation for details on how to use and configure the
       line editor.

13.3.2 /ExtBASICAsm/: extended assembly and disassembly

       /ExtBASICAsm/ (and its companion, /Debugger Plus/) are a pair of
       extensions written by Darren Salt, and which give support for
       additional BASIC assembly, and disassembly options. In particular,
       many more of the more recent ARM opcodes are supported (including
       ones that in general won't be used in RISC OS).

       In the autoload menu (see section 12.2.5) they are referred to as
       `Disassembler' and `Assembler'.

       Documentation is supplied with them; in addition, you should look at
       section 10.3 for information on how to configure Zap's use of
       Debugger Plus when disassembling ARM code.

13.3.3 /HidePtr/: hiding the mouse pointer while you work

       This is a simple extension written by Martin Ebourne which hides the
       mouse pointer while you are typing, and then unhides it again when
       you use the mouse. This prevents your being distracted while working
       with a file in Zap, but gives you instant access to the mouse when
       you need it. It is also apparently a common feature amongst DTP and
       word processing packages.

13.3.4 /KeyboardExtend/: Better keyboard response

       This is an attempt to limit the problems Zap has to do with keyboard
       modifiers. For instance, if you save a file, and while saving press
       scT (insert current time), sometimes if the save takes a long time
       Zap will not notice that shift was held down when `cT' was pressed,
       and will perform the wrong action (in this case selecting the entire
       file).

       KeyboardExtend, in general, makes this much more bearable -
       unfortunately there are some conflicts with other programs. See the
       supplied documentation (or the FAQ and bugs pages on the web site)
       for details on these conflicts.

13.3.5 /FlashCar/: flashing the cursor in dialogue boxes

       You may have already noticed that Zap has a feature to flash its
       text cursor; this extension gives you the same facilities in all
       your RISC OS dialogue boxes.

13.3.6 /IClear/: clear writeable icons using the mouse

       Martin Fox's IClear allows you to clear the contents of a writeable
       icon using the mouse. Simply double click on the icon using `Select'
       or `Adjust', and the icon is inverted. As soon as you press a key,
       the text in the icon will be replaced with the character that you
       typed. With the icon inverted, a further click will de-invert the
       icon and put things back to normal (in case you decide you want the
       current contents after all).

       --------------------------------------------------------------------

       The next section in the manual is chapter 14, which you should read
       if you want to help with Zap development, whether in a technical or
       non-technical role.

       If not, you can move onto the last section of the manual, chapter
       15, which covers other user documentation included with Zap; the
       future of Zap, and how to get in touch with the Zap development
       team. It also discusses the Zap license, and covers things such as
       bug reports.



Chapter 14: Developing for Zap
------------------------------

       This section of the manual is for people who want to contribute to
       the Zap development effort. Firstly, it should be made clear that
       you /don't/ have to be a programmer to help with this! We also need
       people to thrash out ideas for future features, to test beta
       versions of Zap, to help write documentation, and many other things
       (probably including ones we haven't thought of :-).

  14.1 Developer mailing lists

       If you want to get involved with Zap, it is advisable to subscribe
       to one or more of the mailing lists. Whether you are intending to
       contribute to the main development, or whether you merely want to
       write an extension for your own use and are looking for help, the
       mailing lists are a good place to start.

       For information on how to subscribe, see
       http://www.zap.uk.eu.org/lists.html. The current lists are:

       (*) buglist@zap.uk.eu.org - This is the list where bug reports are
           discussed until they hang their heads in shame and go away (bug
           reports should be sent to bugs@zap.uk.eu.org).

       (*) beta@zap.uk.eu.org - This is the discussion list for beta
           versions of Zap (beta bug reports should be sent to
           betabugs@zap.uk.eu.org).

       (*) features@zap.uk.eu.org - A largely non-technical list for
           discussion of proposed new features.

       (*) devel@zap.uk.eu.org - Technical discussion of Zap's features;
           this is basically to stop the other lists from becoming
           cluttered with detailed discussion about /how/ to do things,
           rather than simply /if/ we should.

       (*) technical@zap.uk.eu.org - Other technical issues; this is where
           to ask questions such as "how do I write a mode to do ...?".

       (*) announce@zap.uk.eu.org - A list to which announcements of
           important changes is made. In general these announcements are
           also posted to comp.sys.acorn.announce. (This list is moderated;
           if you send email to it it will be vetted first before going out
           to the list.).

       If you think we need a new mailing list, email
       listmaster@zap.uk.eu.org to discuss it.

  14.2 Writing extensions to Zap

       First, it should be noted that in order to write extensions for Zap,
       you /do/ need to be able to write in ARM assembler. Although it is
       possible to write commands and, to a certain extent, modes in C, you
       still need to be able to use bits of support code, and probably
       write some of your own as well.

       Having said that, it's not quite as difficult as it sounds, because
       there are plenty of examples for which source is available - more or
       less all of the Zap distribution is available in source code form,
       and some of it, particularly the combined command extensions
       (/ZapText/, /ZapUtil/ etc.) are specifically designed so that the
       framework can be quickly re-used to create new extensions.

       Zap extensions are written as RISC OS modules, which allows them to
       be dynamically loaded, thus giving Zap a smaller memory footprint.
       In addition, Zap extensions are wrapped up in normal RISC OS
       application directories, which can then simply be dropped into Zap's
       `!Zap.Modules' directory to install them (you need to reboot Zap to
       actually recognise new extensions).

       You should read the file `Docs.Technical.!ReadMe' for an
       introduction to how to write a Zap extension.

14.2.1 Writing additional Zap commands

       In order to add commands to Zap, you need to call the Zap call
       `Zap_AddCommands'. This allows you to add a single data table,
       containing the information about the commands you wish to add. Zap
       currently has space reserved for 32 command tables, although this
       can easily be increased.

14.2.2 Writing a Zap mode

       To add a new mode to Zap, you need to call the Zap call
       `Zap_AddMode'. This adds a mode data table, giving the information
       about your new mode; as well as things such as the mode's name, it
       contains all the 'entry points' Zap uses when it needs your mode to
       do things.

       You will probably need to read most of the documentation in
       `Docs.Technical' before attempting to write a mode.

  14.3 Working on the Zap core

       Zap's core is currently being developed by a group of people.
       Unfortunately we currently don't use any version control system -
       we're hoping to put it under CVS in the near future, but there are
       technical difficulties which are slowing us down at the moment. The
       core source is available from the ftp site, and you are advised to
       keep a track of the changes you make so that you can submit only
       your changes back when you are ready. It will also help us keep the
       `Changes' file a bit more up to date than it has been recently :-/

       Urgent bug-fix changes should be sent to bugs@zap.uk.eu.org; other
       changes should either be emailed to devel@zap.uk.eu.org (if they are
       small), or to Tim Tyler for inclusion in the main source tree.

       Under CVS this will be much easier.

  14.4 Working on Zap's documentation

       Zap's documentation is now stored in an internal 'source' format,
       which can then be easily converted to produce both the text version
       distributed with Zap itself, and the HTML version used on the web
       site.

       If you want to work on the Zap documentation, the best thing to do
       is to contact the maintainer directly at docs@zap.uk.eu.org.

       --------------------------------------------------------------------

       The final section of the maual is chapter 15, which covers other
       user documentation included with Zap; the future of Zap, and how to
       get in touch with the Zap development team. It also covers things
       such as bug reports.



Chapter 15: How to find out more
--------------------------------

  15.1 Other documentation that comes with Zap

       In addition to the technical documentation described in chapter 14,
       Zap comes with a number of other helpful files:

       (*) `Docs.Boxes' - help on all Zap's dialogue boxes.

       (*) `Docs.Changes' - a list of recent changes to Zap.

       (*) `Docs.Copyright' - detailed copyright and license information.

       (*) `Docs.HelpData' - the help text for all Zap's dialogue boxes and
           commands - this is a useful file to look through to get an idea
           of some of the extra features of Zap.

       (*) `Docs.KeyStrip' - a function keystrip for Zap, as a drawfile.

  15.2 The future: ideas, bugs, and obtaining upgrades

       The official Zap web site is http://www.zap.uk.eu.org/, with the
       official ftp distribution site at ftp://ftp.zap.uk.eu.org/.

       Bug reports should be emailed for preference, to bugs@zap.uk.eu.org
       - please give as many details as possible as to the circumstances
       that caused it, including operating system version and any other
       programs you had running at the time which might have been involved.
       Try to get it repeatable if possible, because that makes it much
       easier to fix.

       Suggestions should be emailed for preference, to
       features@zap.uk.eu.org (this is a mailing list, so if you want to
       get involved in the discussion, you can do - see section 15.4 below
       for more details).

       Current suggested features, and a list of known bugs, is available
       from the web site. They may also have come with this distribution -
       if so they will be the files `Docs.Bugs' and `Docs.Features';
       however they don't always get distributed because they are subject
       to change. Before submitting a bug report or suggesting a new
       feature, please try to check the current lists to see if it is
       already there.

  15.3 Credits

       Zap was written and maintained by Dominic Symes up to version 1.35,
       released at the end of 1996. Since then, Zap has been worked on by a
       larger Zap development team. These include: Tim Tyler, Darren Salt,
       Martin Ebourne, James Aylett, Justin Fletcher, Daniel Wagenaar and
       Elliot Hughes.

       In addition to work on the core of Zap, much of its functionality
       owes to the many people who write and maintain extensions. Listing
       them all here would be rather pointless (and would require updating
       regularly); the documentation that comes with each extension will
       say who has worked on it.

       Thanks to the following for help/suggestions/donations/bug reports
       (the first list was compiled by Dominic while he maintained Zap, and
       has been edited only to remove people mentioned above; the second
       list is of those who have helped since then):

       (*) P.Allen, M.Anwar, M.Astley, B.Avison, M.Avison, R.Betz,
           M.Ben-Gershon, O.Betts, C.Booker, M.Borcherds, S.Borrill,
           B.Brand, T.Browse, B.Brunswick, N.Carson, D.Cass, C.Cepurneek,
           P.Colmer, A.Corey, M.Corley, J.Coxhead, N.Craig-Wood, G.Crow,
           R.Darlington, J.Davidson, M.Dorey, F.Elisei, A.Finch, J.Freeman,
           M.Geddes, I.Giblin, D.Gilbert, S.Glass, D.Good, M.Grainger,
           P.Greenham, Z.Gunnar, R.Hallas, M.Hamberly, B.Harris, P.Hazel,
           P.Hedderly, J.Hendrix, G.Heslington, B.Hogan, D.Holden,
           T.Houghton, D.Howe, T.Hughes, M.Hughes, P.Ingram, R.Johnson,
           H.Klingspohr, C.Latham, D.Layfield, T.Leddi, G.Lee, G.S.Long
           :-), P.Long, M.Lukat, C.Marshall, J.Marten, C.Manning,
           G.McCaughan, A.McMurry, P.McTiernan, A.Merritt, S.Monesi,
           P.Moore, D.Murphy, E.Naish, T.Olsson, J.Ovesen, I.Palmer,
           D.Pottage, O.Reinert, A.Raab, T.Roddis, C.Rodliffe, H.Rogers,
           M.Sabin, G.Saliaris, K.Sangrar, B.Scattergood, K.Schlichting,
           O.Schoen, A.Skelton, J.Smith, N.A.Smith, R.L.Smith, A.Southgate,
           C.Syntichakis, G.Taylor, L.Taylor, A.Thoukydides, C.Turnbull,
           J.Tytgat, E.van de Pol, J.Veness, D.Wagenaar, J.Wallace,
           R.Watts, P.Wheatley, M. Wilcox, T.Willemse, M.Williams,
           R.Wilson, M.Wooding, Wookey, D.Xanthakis, D.Yule; and all
           members of the Oxford Acorn User Group.

       (*) M.Alshayef, R.Atterer, J.Beranek, A.Berry, N.Bingham, J.Brady,
           S.Brodie, P.Clifford, D.Ellis, A.Fawcett, L.Gretton, R.Gunstone,
           J.Harvey, T.Hawtin, T.Hebbron, J.Heenan, D.Hood, I.Horvath,
           A.Hunter, R.James, B.Laughton, S.Liddington, C.McEvoy,
           D.Mortimer, D.O'Shea, A.Piper, S.Purchase, I.Richardson,
           J.Robinson, G.Royds, C.Rutter, I.Scott, P.Skirrow, S.Smith,
           R.Thomas, T.van der Hoff, G.Vik (for /StrongHelp/ :-), S.Watson,
           J.Whealing.

       Zap's original manual was written by Dominic Symes. A Zap primer was
       written and maintained up to version 1.35 by David Holden. This
       manual was written from scratch, with reference to those earlier
       documents, for version 1.40 by James Aylett, with advice and
       suggestions from the members of the beta mailing list. The source to
       text and HTML conversion system was originally written by Simon
       Tatham.

  15.4 Getting in touch with Zap developers

       There are a number of email addresses which you should use to get in
       touch with the Zap development team. These are all actually mailing
       lists that you can subscribe to (see
       http://www.zap.uk.eu.org/lists.html):

       (*) bugs@zap.uk.eu.org - submitting a bug report.

       (*) betabugs@zap.uk.eu.org - submitting a beta bug report.

       (*) features@zap.uk.eu.org - discussion of proposed new features.

       (*) devel@zap.uk.eu.org - more technical discussion of Zap's
           features - this is basically to stop the other lists from
           becoming cluttered with more detailed discussion about /how/ to
           do things, rather than simply /if/ we should.

       (*) technical@zap.uk.eu.org - other technical issues; use this
           address if you're writing an extension and need help.

       If you have a query or suggestion pertaining to a particular
       extension, rather than to Zap as a whole, then you should first try
       to contact the extension's author; if you have difficulties getting
       hold of them, then you can contact the Zap development team
       (although we may not actually be able to help if we didn't write the
       extension!).

       Each main Zap developer also has a personal email address so you can
       contact them specifically about an area that you know is their
       responsibility:

       (*) tim@zap.uk.eu.org - Tim Tyler.

       (*) ds@zap.uk.eu.org - Darren Salt.

       (*) dj@zap.uk.eu.org - James Aylett.

       In addition, many Zap developers read the `comp.sys.acorn'
       newsgroups; the best place to ask for help with Zap is
       `comp.sys.acorn.apps'. Information about new releases of Zap will be
       posted to `comp.sys.acorn.announce'.

       If you need to use snail mail, you can write to James:

              James Aylett 
              c/o Insigma Technologies 
              Norcote Barn 
              Norcote 
              Cirencester 
              GL7 5RH

       Note that Zap is not associated in any way with Insigma Technologies
       (nor with any of the employers of any of the other Zap developers).

       --------------------------------------------------------------------

       And that's it! We hope you find Zap a useful program.

       The Zap Development Team

Appendix A: Default keystrokes
------------------------------

       Note that the key short cuts are given in the menus. In the
       following list, s=`Shift', c=`Control', sc=`Shift+Control', k=Key on
       keypad.

   A.1 Common editing keys

       scSpace              Remove unnecessary space around the cursor

       Escape               Stops operation 
       sEscape              Cancel operation 
       cEscape              Open minibuffer for command (Emacs M-x)

       Backspace            Delete to the left 
       sBackspace           Delete to the left 
       scBackspace          Undo last operation

       Return               Performs return action for current mode 
       sReturn              Perform return action for current mode 
       cReturn              As Return, but doen't auto-indent 
       scReturn             Insert "<P>" (HTML paragraph)

       Delete               Delete to the left 
       sDelete              Delete the the right 
       cDelete              Delete the current line 
       scDelete             Delete to the end of the line

   A.2 Cursor keys

       Left                 Move cursor left 
       Right                Move cursor right 
       Down                 Move cursor down 
       Up                   Move cursor up

       sLeft                Move cursor left one word 
       sRight               Move cursor right one word 
       sDown                Move cursor down one page 
       sUp                  Move cursor up one page

       cLeft                Move cursor to start of line 
       cRight               Move cursor to end of line 
       cDown                Move cursor to end of file 
       cUp                  Move cursor to start of file

       scLeft               Scroll window left 
       scRight              Scroll window right 
       scDown               Scroll window down 
       scUp                 Scroll window up

   A.3 Miscellaneous keys

       Tab                  Tab 
       Insert               Inset/overwrite 
       Home                 Undo last operation 
       Copy                 Delete to the right

       sTab                 Switch tab mode 
       sInsert              Copy selection to clipboard 
       sHome                Selects the ANSI C identifier under the cursor 
       sCopy                Copy mode

       cCopy                Start selection by cursor movement 
       cInsert              Copy selection to clipboard

       scTab                Tabify 
       scHome               Select current line 
       scInsert             Copy selection to clipboard 
       scCopy               Dump textual representation of file

       c[                   Logical line numbers shown at left 
       c\                   Get help on Zap 
       c]                   Physical line numbers shown at left 
       c-                   Replace current word with a correct spelling 
       c0                   Insert blank (space in textual modes, 
                            NUL in binary)

       sc[ (ctrl {)         Turn off line numbers/addresses 
       sc\ (ctrl |)         Spell check entire buffer 
       sc] (ctrl })         Addresses shown at left 
       sc- (ctrl _)         Undo last operation 
       sc0 (ctrl ))         Insert a NUL (zero byte)

   A.4 Keypad keys

       sk/                  Insert date in format 
                            "Fri, 16 Oct 98 11:29:50 BST" 
       sk*                  Delete to the start of the word 
       sk#                  Delete to the end of the wor 
       sk-                  Outdent the selection 
       sk+                  Indent the selection 
       sk.                  Find the function at the cursor

       ck0                  Prefix key for miscellaneous keymap 
       ck1                  Copy selection to next icon clicked on 
       ck2                  Reindent current line of program source 
       ck4                  Select current word 
       ck5                  Select current line 
       ck/                  Run the program 
       ck*                  (Reserved) 
       ck#                  Prefix key for Emacs keymap 
       ck-                  Prefix key for Emacs cX keymap 
       ck+                  Prefix key for Emacs Escape (Meta) keymap 
       ckEnter              Prefix key for Emacs cX 4 keymap 
       ck.                  Prefix key for HTML utility keymap

   A.5 Function keys

       F0 (Print)           Quick print 
       F1                   Execute learned sequence 
       F2                   Load a file 
       F3                   Open the save dialogue 
       F4                   Open the search dialogue 
       F5                   Open the goto line/address dialogue 
       F6                   Drop a mark 
       F7                   Open the search to window dialogue 
       F8                   Undo last operation 
       F9                   Redo operation 
       F10                  Delete current line

       sF0 (sPrint)         Fancy print 
       sF1                  Split line at cursor position 
       sF2                  Swap to other window and bring to front 
       sF3                  Open save selection dialogue 
       sF4                  Open replace dialogue 
       sF5                  Undo last operation 
       sF6                  Go to last mark 
       sF7                  Next match in search 
       sF8                  Renumber program 
       sF9                  Go to next mark 
       sF10                 Delete to start of line 
       sF11                 Toggle mark

       cF0 (cPrint)         Open printer:$ 
       cF1                  Join lines 
       cF2                  Close window 
       cF3                  Save without prompting 
       cF4                  Open a new view on this file 
       cF5                  Toggle word wrap 
       cF6                  Format paragraph 
       cF7                  Go to last match 
       cF8                  Bind learned sequence 
       cF9                  ASCII/Hex entry mode 
       cF10                 Delete to end of line 
       cF11                 Go to last mark

       scF0 (scPrint)       Close printer:$ 
       scF1                 Change to Text mode 
       scF2                 Change to Byte mode 
       scF3                 Change to Word mode 
       scF4                 Change to ASCII mode 
       scF5                 Change to Code mode 
       scF6                 Change to BASIC mode 
       scF7                 Change to BASTXT mode 
       scF8                 Change to Email mode 
       scF9                 Change to C mode 
       scF10                Change to Assembler mode 
       scF11                Prefix key for Emacs keymap

   A.6 Control letters

       cA                   Start spell checker 
       cB                   Put window to back 
       cC                   Copy selection to cursor 
       cD                   Duplicate line 
       cE                   Copy selection into clipboard 
       cF                   Bring window to front 
       cG                   Cancel current operation 
       cH                   Get help on the word at the cursor 
                            (uses StrongHelp) 
       cI                   Indirect (move to the address given by the 
                            word at the cursor - useful in Code mode) 
       cJ                   Indent selection 
       cK                   Delete to end of line 
       cL                   Learn key sequence 
       cM                   Performs return action for current mode 
       cN                   Next match in search 
       cO                   Present the user with a * prompt 
       cP                   Previous match in search 
       cQ                   Quote next character 
       cR                   Reverse interactive search 
       cS                   Forward interactive search 
       cT                   Select entire buffer 
       cU                   Universal argument - perform next instruction 
                            'n' times 
       cV                   Move selection to the cursor 
       cW                   Set the window width 
       cX                   Delete selection and place it in the clipboard 
       cY                   Paste the clipboard at the cursor 
       cZ                   Clear selection

       scA                  Duplicate character above the cursor 
       scB                  Drop program into BASIC 
       scC                  Saves then run/compile program 
       scD                  Insert current date 
       scE                  Save then run a program, then exit 
       scF                  Run a program, then exit 
       scG                  Toggle window size 
       scH                  List function definitions 
       scI                  Move forward one track 
       scJ                  Move back one sector 
       scK                  Move forward one sector 
       scL                  Force lower case of next character/selection 
       scM                  Move back one track 
       scN                  Turn off line numbers/addresses 
       scO                  Line numbers shown in hex/decimal 
       scP                  Physical line numbers show at left 
       scQ                  Swap next two characters 
       scR                  Toggles window wrap 
       scS                  Swap case of next character/selection 
       scT                  Insert current time 
       scU                  Force upper case of next character/selection 
       scV                  (Reserved) 
       scW                  Toggle soft wrap 
       scX                  Close other open window 
       scY                  Yank cyclically through deleted regions 
       scZ                  Prefix key for Emacs keymap (eg: scZ Escape X 
                            is equivalent to M-x in Emacs)
