                                Zap manual
                                ==========

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.Resources.UK.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.Resources.UK.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.

 1.1.4 Recent changes

       Major new features and improvements in recent versions of Zap
       include:

        -  Internationalisation - see section 12.4

        -  Mode cloning - see section 12.2.2

        -  Configuration variables - see section 12.3.6

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

       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 in general 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).

       See section 2.4 if you are upgrading from Zap v1.40 or later.
       Unfortunately there is no simple upgrade path from earlier versions
       of Zap, because both the configuration and the layout of files
       within Zap itself have 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, the name of which
       will depend on which version you decided to download. There are
       three core packages:

        -  zap.zip. This is the smallest archive, containing just the files
           needed to get Zap running.

        -  intl.zip. As above, but adds French and German translations.

        -  devel.zip. As above, but adds some tools which may be useful to
           authors of Zap extension modes.

       This is the first thing you should set up; this process is described
       below in section 2.2.

       There are a number of extension modes which you may also have
       downloaded - 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, since the
           core archive comes with a minimal ZapFonts distribution; 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.

   2.2 Core setup

       The Zap core distribution contains an Install file (this document
       in text format), the !Zap, !ZapFonts and !ZapUser application
       directories, and a couple of other utilities. Please don't just copy
       it onto your hard disc - this is extremely limiting.

       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.

       If you have a RISC PC-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 RISC PC-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 put ZapUser inside Zap, as
       !Zap.!ZapUser. 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 should be 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.

       If you have a RISC PC-style boot structure, then you want to put
       ZapFonts in Boot:Resources. If you don't have a RISC PC-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 put ZapFonts inside the !Zap directory as !Zap.!ZapFonts,
       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 available 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 which you can simply copy
       it over the top of your installed !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.2.3 Support files

       Zap comes with some additional support files, !Country, !!DeepKeys
       and DDEU_Patch which you'll want to deal with when you're setting it
       up.

       It also comes with an Obey file, DontRun, which is supplied to
       assist upgrading configuration from v1.40 to v1.45 - see section 2.4
       for more information.

2.2.3.1 !Country

       !Country is a small utility that you should run at startup which
       determines the country you've set your computer up for. Ideally
       you should place it in Boot:Choices.Boot.PreDesk on a recent boot
       system, so it will be run before anything else, and indeed it is
       supplied inside a !Boot structure that you can copy over your
       current one. !Country sets the environment variable `Sys$Country'
       to whatever your current country is. Zap uses this in its
       internationalisation support (see section 12.4).

2.2.3.2 !!DeepKeys

       !!DeepKeys is a utility that should be run at startup which tries to
       stop RISC OS from losing modifier keys (such as Shift, Ctrl etc.).
       As for !Country, it should live in Boot:Choices.Boot.PreDesk, and is
       also supplied inside a !Boot structure to make this easier.

2.2.3.3 DDEU_Patch

       DDEU_Patch patches DDEUtils so that Zap can read the current prefix
       directory for a taskwindow. You should only run it if you're using
       version 1.53, 1.54 or 1.55 of DDEUtils. Versions later than 1.55
       do not need to be patched since they already include the necessary
       code.

       To check which version you have:

         *Help DDEUtils

       If this reports "No help found", then

         *Load System:Modules.DDEUtils
         *Help DDEUtils

       Version 1.54 is supplied in the standard !Boot, and version 1.59 is
       the first version to be included in ROM.

   2.3 Extensions setup

       Any extension archive you downloaded will contain a directory !Zap
       which should be copied over !Zap.

       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 !Zap.Modules directory of the
       archive _into_ !Zap.Modules in your installed setup.

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

   2.4 Upgrading from Zap v1.40 or later

       To upgrade from Zap v1.40 or later, you need to do three things.

        -  Replace !Zap - see section 2.4.1

        -  Upgrade !ZapFonts - see section 2.4.2

        -  Upgrade !ZapUser - see section 2.4.3

 2.4.1 Replacing !Zap

       Since all configuration is now held in !ZapUser, there is almost
       nothing which most people need to alter inside !Zap itself these
       days - including the extensions. This means that you should simply
       be able to replace your current !Zap application directory with a
       new one constructed from the core archive and whatever extensions
       you need, as explained earlier. Please _don't_ copy the new !Zap
       application over your old one since that will cause problems as some
       files have been relaced by directories - delete your existing !Zap
       first.

       Note that this won't work smoothly if you have been keeping
       !ZapFonts or !ZapUser inside the !Zap application directory. If
       you are doing so, please consider trying to find an alternative
       solution, because it will make your life much easier.

 2.4.2 Upgrading !ZapFonts

       The only change in !ZapFonts since Zap v1.40 was released is a new
       version of the ZapRedraw module. You should copy the new one from
       inside !ZapFonts in the core archive into your working !ZapFonts
       application directory. Alternatively, simply copy the new !ZapFonts
       over your old one.

 2.4.3 Upgrading !ZapUser

       The changes to upgrade your configuration from Zap v1.40 to Zap
       v1.45 are involved, however two facilities are available to assist
       the process:

        -  If you have Perl, you can download a script that will do
           the majority of the work for you - this is available from
           http://zap.tartarus.org/ftp/pub/1.45/upgrade-config.pl.

        -  The Zap developers are providing an upgrade service - package
           your !ZapUser into a Zipfile and send it via email to
           upgrade@zap.tartarus.org. One of the developers will upgrade
           your configuration for you and return it to you.

       If you want to upgrade your configuraton yourself, the following
       changes need to be made. All the files referred to below are in
       !ZapUser.Config.

       If you are upgrading from Zap v1.42 or later, some of these changes
       may be unnecessary for you.

        -  !ZapBoot has changed substantially; it is suggested that you
           copy the new version over and make any changes you need. In
           practice, you are unlikely to have changed anything, except
           perhaps the file type claims (lines such as ZapRunType FFF).

        -  !ZapRun has changed substantially to support
           internationalisation; it is suggested that you copy the new
           version over and make any changes you need. In practice, the
           only parts you are likely to have changed are the templates
           set, and perhaps the file type claims. Note that some template
           sets haven't been updated for v1.45, and so aren't supplied
           any more. In addition, note that the old system variables
           `Zap$HelpPath_<mode>' are no longer required.

        -  Country has been added to support internationalisation; it can
           be used to override your system country. You should copy this
           file over, but only edit it if you need to set your country
           explicitly.

        -  Settings has had two variables added. &322 can be used to
           specify a command to execute on startup, and &323 specifies the
           default mode. See section 12.3.1 for more information.

        -  A directory TMFs has been added. You should copy this across.
           TMFs (Textual Mode Files) are files that set per-mode variables,
           used to make some commands and operations more configurable.
           (See section 12.3.6 for more information.) If you are upgrading
           from v1.42 or later, you will already have this directory
           present; however it may contain TMFs which are now unnecessary.
           Unless you have edited any of these yourself, you should
           only have TMFs for core modes (Text, Byte, HalfWord, Word,
           DoubleWord, ASCII and Code) in this directory.

        -  Two new files, FileIdHigh and FileIdLow, have been added. These
           should be copied across. They allow modes to be selected on
           loading files based on the contents of the start of the file.

        -  The Keys file has changed significantly; firstly, the method
           of specifying alternate keymaps has changed from using &400
           variables in a block, to using &800 variables immediately before
           the keymap in question, to declare them. Secondly, support
           for country-specific Keys files has been added; instead of a
           single file, you should have a directory, ZapUser:Config.Keys,
           containing a file for each country (eg: ZapUser:Config.Keys.UK,
           ZapUser:Config.Keys.France). Unless you made significant
           alterations to your keys file, we suggest that you copy in the
           new Keys directory and make any changes you need. Alternatively,
           move your current ZapUser:Config.Keys to ZapUser:Config.Keys.UK
           (or another country name, as appropriate), and edit it to use
           the new file format. See section 12.4 for more information about
           internationalisation, and section 12.3.3 for more information
           about the new Keys file format.

        -  Also, some extension modules have their own Keys files. They
           may also be configured to use their keymaps by default; you can
           override this by altering the relevant module's TMF file (see
           section 12.3.6 for more information).

        -  The Menus file has also become internationalised, in the same
           way. In addition, we now generate menus files from a source
           format which allows you to name menus instead of referring to
           them by number. Further, areas of the source file can be made
           optional - the idea is that more or less everyone can use the
           same source file, while still being able to configure things a
           fair amount. We strongly suggest that, if you don't like the new
           default menus, you copy the new menus directory, look at, and
           possibly edit, the appropriate source file (they are supplied in
           the directory ZapUser:Config.Menus.Source), and generate your
           menus file from that. See section 12.4 for more information
           about internationalisation, and section 12.3.5 for more
           information about the new Menus source format, and the method
           for generating the final file from source.

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

       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 `Create->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
       file (line ends are `CRLF') or Spool file (line ends are `LFCR') as
       it does. If it is in either format, it doesn't just load the file,
       but converts it to use a lone `LF' for line ends 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
       relocatable 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' - currently 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 (used by Byte, HalfWord, Word and DoubleWord
           modes - see section 10.1) is enabled.

        -  `w' - Wordwrap is enabled (see section 6.3).

        -  `L' - Line wrap is enabled (see section 6.3).

        -  `l' - Line edit is enabled (see section 6.7).

        -  `n' - Non-standard is enabled (see section 6.8).

        -  `a' - Auto indent is enabled (see section 6.1).

        -  `W' - Window wrap is enabled (see section 6.3).

        -  `s' - Soft wrap is enabled (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_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 sCopy 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.3.

   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 between insert and overwrite.

        -  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,
       pressing 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 buttons
       in the dialogue box will act as if clicked if you hold down Control
       and press the first capitalised letter in the button'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 `cP' 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.4.)

       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 pressing 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.2.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.4).

       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'.

       Pressing F8 gives you fast undo; `scBackspace' is full undo.

 3.5.2 Quoting characters

       As we've already seen, Zap uses most combinations of Control and an
       alphabetic character 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 and byte of value 1 (which is `cA'). Use `cQ cSpace' for a
       byte of value 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' item in the main window 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 whether
       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 covers
       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 one 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 methods 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 `cE' (this is called _keeping_) and paste it with `cY'. Press
       `scY' to cycle through the previously cut selections (this is called
       _yanking_).

       Note that the `DELTOEND' (`cK') and `DELLINE' (`F10') commands also
       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 'yank 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 GNU filters

       This is a menu containing various GNU filter programs you
       can apply to the selection. Darren Salt has ported a range
       of GNU text filters to RISC OS; these are available from
       ftp://zap.tartarus.org/pub/ds/GNU/.

       See section 4.4.10 for more information on general filtering within
       Zap.

 4.4.4 Sort

       This simply sorts the lines of the selection into alphabetical
       order. See section 4.4.11 for more details.

 4.4.5 Format

       This simply formats the selection to 77 characters, with a first-
       line indent for each paragraph. See section 4.4.12 for more details.

 4.4.6 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.7 Upper case

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

 4.4.8 Lower case

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

 4.4.9 Bracket ()

       This simply places the selection in brackets.

4.4.10 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.

       A number of useful filters are supplied with Zap, and are described
       below. You can use the `Selection->Process->Filter...' menu option
       to enter their names: eg, for filter `ZF:sort', you would type
       `ZF:sort' at the minibuffer that pops up.

4.4.11 Filter `ZF:sort'

       The sort filter sorts in straight ASCII order. The option on the
       menu (`Selection->Process->Sort') 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.12 Filter `ZF: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, but it is also on the
       menu as `Selection->Process->Filter'.

       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.13 Filter `ZF: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. This can be
           modified by holding down various keys while clicking with the
           mouse. Shift will only position the cursor if that would leave
           it outside the current selection. Control won't move the cursor,
           but will clear the selection.

        -  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). Alt-Shift brings up the `Selection' menu if there is a
           selection in that window; otherwise you get the `Modes' menu as
           you would for Alt.

        -  Click Adjust - If the window doesn't have the input focus, it
           gets the input focus and the cursor 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 has the input focus 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:

        -  Dragging Select defines a new selection.

        -  Dragging 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 clicks select a word.

        -  Treble clicks select a line.

        -  Quadruple clicks select a paragraph.

        -  Quintuple clicks 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' only selects `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 things 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 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 distance 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 arrow' - 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.

        -  `Dashes & arrow' - As for 'As spaces', but the tab spacing is
           filled by a series of dashes 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, key presses 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 above: `scF11' executes `KEYMAPN "Emacs"', `cX'
       executes `KEYMAP 2', and `cS' executes `SAVEFILE'. Thereafter
       the current keymap returns to the basemap (normally the Default
       keymap). `KEYMAPN' is case-insensitive - so `KEYMAPN "EMACS"' and
       `KEYMAPN "Emacs"' are the same.

       See section 12.3.3 for more information about keymaps, and about how
       to configure new keymaps.

       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, by the `BASEMAPN' command
       (which works in the same way as the `KEYMAPN' command, except that
       the effect is more permanent), or from the `Misc->Keymap' submenu.

       To change the basemap back to the default, use the `DEFAULTMAP'
       command, or use the `Misc->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 select 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 rightwards
       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).

       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 HalfWord, Word, DoubleWord 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->Save options' 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' (also on the
       `File->Save options' submenu). 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 configuration

       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 turned 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 instead of decimal 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 three different options, set from the
       `Display->Font->Font display settings' submenu:

        -  `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). Zap comes with a small
           number of bitmap fonts; see section 2.2.2 for information on how
           to install more. See section 7.2.1 for the variations on bitmap
           font display.

        -  `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 fonts'; the normal RISC OS outline fonts. See
           section 7.2.2 for the variations on outline font display.

       You can select which bitmap font to use from the
       `Display->Font->Bitmap font' submenu, which is arranged by font size
       and then font name.

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

       Note that 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.2.1 Bitmap font options

       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.

 7.2.2 Outline font options

       Outline fonts can be drawn in two different ways, `Anti-aliased VDU'
       and `Anti-aliased DSA'.

       VDU is outline fonts drawn by the operating system. It is the
       slowest of all Zap's options, but allows eight sub-styles (see
       section 7.3.1).

       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.

   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(s) 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 (but
       see below), 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.

       _All modes_, as used here, means all modes which were loaded when
       the window was opened or have since been loaded and used in that
       window; specifically, modes which have since been loaded but not
       used in that window will not be affected by colour configuration
       changes in said window. This is complicated slightly by the fact
       that a new view created from an existing window initially has an
       identical configuration to the original window.

       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 (for instance, 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 the
       Print key 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
       _UNIX_ regular expression searching (as used, for instance, in
       _Emacs_. 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 the
       F4 and F7 keys, by `sF4', and by `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:

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

        -  `#' expands to `\ #' (matches any character).

        -  `\d' expands to `\[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 brackets, but may be referred to in the
           replace string (see section 8.3 below).

        -  `\#' - Matches any character. eg: `a\#d' matches `and', `aid'
           and `aad', but not `ad'.

        -  `\.' - Matches any character except the return character.

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

        -  `\%' - Matches as many as possible 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 immediately 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 followed 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', eg: `\x2D').

       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 decimal 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: (the empty string) removes all occurrences of `cat'.

        -  S:`\{cat\}', R:`&1s' replaces `cat' with `cats', preserving
           case.

        -  S:`time=\{\#\*\}', R:`time is &1' replaces `time=58' with
           `time is 58' etc.

       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 display `(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 slash-
       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, use `DROPMARK' (F6).
       To move to the next mark, use `NEXTMARK' (`sF9'), and to move to the
       previous mark, use `LASTMARK' (`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).

        -  `V' - Variable help - type the variable name (see section
           12.3.6).

        -  `D' - Documentation (opens the documentation directory for the
           current country).

        -  `Z' - Help on Zap (opens the manual for the current country).

       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://sudden.recoil.org/stronghelp/).

   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. Press F1 to execute the
       learnt sequence. (`EXECUTE', bound to F1, also stops the learning
       process.)

       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.

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

       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. (In addition, cloned modes that haven't been loaded will
       be on the `Mode->Load clone' submenu - see section 12.2.2 for
       information about cloned modes.)

       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'.

       Of course, quite often you might want to edit certain files in a
       particular mode with one set of options, and others in the same mode
       with different options. While you could change the options each time
       you look at a file, it is easier to _clone_ a mode, essentially
       giving you two copies of the mode you want to use, and which you can
       then configure independently. For more information about this, see
       section 12.2.2.

       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 using an 'atomic size' of byte, halfword (sixteen bit
       quantity), word or doubleword (sixty-four bit quantity). The four
       modes are called Byte, HalfWord, Word and DoubleWord, 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_ (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. The others 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, halfword 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.

       For DoubleWord mode, you can only edit using 'hex entry' - pressing
       Return in DoubleWord mode has no effect.

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, halfwords, words or doublewords 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, words or whatever,
       and the ASCII dump at the far right. The group size must be the same
       in both cases (the `Group size' submenu from the mode's options
       menu gives the value used for both); a space is displayed between
       each group. In the default setup, DoubleWord groups to every second
       doubleword, Word mode groups to every fourth word, HalfWord groups
       to every four halfwords, and Byte mode groups to every eight bytes.

       Thirdly, you can change the 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, all four 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 binary 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).

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

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

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

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.2.2), and so you can use
       BASIC functions sure as `ASC', `EQUD', `ADR' etc.

       Secondly, the arrow keys 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 instructions, 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.2.2 and section 12.2.6), then the
       `Code->Disassembler' submenu will enable you to alter how the
       disassembly 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 Rn,Rn,Rn, `MOV Rn,Rn'
           (same register), etc.

        -  `ADRL' - Use ADRL / ADRX instead of ADR followed by 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 `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. Adjust clicking on a file title will
       remove all throwback entries for that file.

       Also note that Return acts in the same way as double click and
       Delete in the same way as Adjust for the throwback entry at the
       cursor.

       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.2.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 options 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
           `Fish' in the alphabet. It isn't, so it actually evaluates to
           `0'.

        -  `STR ((10 + 16) / 2) RIGHT 1' - Evaluates to the last digit (as
           a string) of the 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 expressions 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 `$', 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.4.2 Configuration variables

       In addition to the variables described above, Zap has a special
       set of variables called c-vars; this stands for _configuration
       variables_. These are variables which are used to configure how a
       command, or a particular part of Zap, operates. For instance, the
       _StrongHelp_ support in _ZapText_ uses the c-var `HelpSearchPath' to
       configure the order in which the _StrongHelp_ manuals are searched.

       Note that these are not accessible as normal Zap variables; they are
       mentioned here merely for completeness.

       For more information on c-vars, see section 12.3.6.

  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 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.

  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://zap.tartarus.org/download.html, or
       go straight to the FTP site at ftp://zap.tartarus.org/pub/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. 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->Set default options' 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-
       >Set default options->Save defaults' from the window menu.

       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-
       >Set default options->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 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. Note
       that the default mode is actually a textual configuration option -
       once Zap is loaded you can change it from the iconbar menu, but you
       can't change the default setting without editing one of the textual
       configuration files. See section 12.3.1 for how to do this.

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

12.2.2 Mode cloning

       Several of Zap's modes are fairly non-specific; they can be used to
       edit a variety of different types of file. For instance Text, Byte
       HalfWord, Word and DoubleWord modes assume very little about the
       content of the file - unlike Code, Email or HoTMeaL (the HTML mode),
       for instance. Consequently you may want to use them in different
       situations with different default settings.

       The way to do this is to create a _clone_ of the mode. This is an
       exact copy of a mode, given a different name, and which you can
       configure differently. A cloned mode is used exactly as you would a
       normal mode.

       Clones are managed via `Options->Clone modes...' from the iconbar
       menu. This opens a small dialogue box which lists the current clones
       you have (as Zap is supplied, there are no clone modes). The top
       half of the window allows you to select the different clones you
       have, to see which mode they are based on, and to `Delete' and
       `Hide' the one currently being shown. Deleting a clone will also
       delete its options; only do this if you won't need them again!
       Hiding a clone removes it from currently loaded modes; since Zap can
       only cope with thirty two modes loaded at one time, this allows you
       to work with many more clones.

       To create a new clone, click on `New' in the dialogue box. This
       creates another small dialogue allowing you to enter the new clone's
       name, and to select which mode you would like the clone to act like.
       Currently, in addition to the core modes Text, Byte, HalfWord, Word,
       DoubleWord, ASCII and Code, only Email mode can be cloned - and
       clones themselves can be cloned. Clicking on `Create' will create
       the clone, set up initially with the options of the base mode you
       selected.

       Cloned modes show up in blue instead of black in the mode menu. Non-
       core modes (such as Email) show up in grey.

       Clone don't appear on `Mode->Load mode' in the main window, or
       `Options->Mode->Load mode' in the iconbar menu; instead, they have
       their own `Load clone' submenu.

       As with all binary options, you must remember to save Zap's options
       (`Options->Save options' from the iconbar menu) once you have made
       alterations to your clones - otherwise you will lose them when you
       quit Zap.

12.2.3 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.4 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.5 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-delete 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-clear 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 also 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.

        -  `Remove H scroll' - 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'.

        -  `Force startup command' - Forces the startup command to be
           executed even if files are being loaded on startup. See section
           12.3.1 for more information.

        -  `Minibuffer autowidth' - Sets the width of the minibuffer to
           match the width of the window it's being used with. Otherwise it
           will use the width set for it in the Templates file (which isn't
           terribly useful).

12.2.6 Autoloading internal extensions

       Zap has a number of 'internal' extensions, introduced in section
       13.2, 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 following form.

         <comment> &xxx <value>

       The comment is any text without an ampersand (`&') character in it.
       Any line without an ampersand 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 GSTransed 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 GSTransed first.

        -  &320 - Codes to send to the printer at the end of the file for
           'quick print'. This string is GSTransed first.

        -  &321 - Minimum time between backups, in seconds.

        -  &322 - Command executed on startup. This will only be
           executed if no files are being loaded on startup, unless the
           `Force startup command' option is enabled. This variable may be
           useful for NCOS users.

        -  &323 - Default mode.

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 (high)'. `Types (low)' is intended for default filetype
       recognition for the core of Zap (extension modes that handle
       filetypes have their own filetype configuration files).

       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 Zap's base keymaps: in addition, extensions
       can have their own Keys files in the extension directory so that
       keymaps that are useful only to individual extensions don't need to
       be supplied with the main Zap distribution.

       Each keymap is introduced by an &800 key variable, with the
       exception of the first keymap in the Keys file, which is the
       default. (Note that this only applies to Zap's core Keys file - per-
       extension files cannot contain default keymaps, and must have all
       their keymaps introduced by an &800 variable.) The value of an &800
       variable is actually four values; it looks as follows.

         <comment> &800 <low> <high> <name> <base>

       <low> and <high> define the range of the keymap, in keycodes - for
       keypresses outside that range, the keymap will do nothing. <name> is
       the name of the new keymap; this name is used on the `Misc->Keymap'
       menu, and by the `KEYMAPN' and `BASEMAPN' commands. <base> is the
       name of the base for this keymap - any keycodes that are not defined
       in the keymap, but which fall within the range of the keymap, are
       inherited from this base keymap.

       The key variables &000-&1FF define the keymap itself; 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.

       The keymap used as the base map for any mode which doesn't choose
       its own is given by key variable &400. Base maps for modes can be
       set using the configuration variable `Basemap' - see section 12.3.6
       for more information about configuration variables.

       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,
       we have:

         &01E-14E *

       which defines most of the Emacs keymap to be the same as the Default
       keymap that it inherits from. 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>

       The name must be given in quotes. In Zap's actual Menus file,
       handles are numbers that start at zero, with the first twenty (0-
       19) reserved for internal use (see below). However it is more
       convenient to work from a 'source' format, where the handles
       are names instead of numbers - symbolic handles start with a
       dot (`.'). Zap is supplied with a program called MakeMenus
       which generates the actual Menus file from the source file;
       it lives in ZapCode:Tools.MakeMenus, which also contains
       more detailed documentation. Source menus files live in
       ZapUser:Config.Menus.Source.

       In addition to allowing handles to be names instead of numbers,
       MakeMenus provides a preprocessor vaguely similar to that used by
       C compilers. This allows a source file to provide various options
       which can be turned either on or off when generating the real file.
       Zap is supplied with a program that gives a simple text interface
       to configuring these options, called MenuConf (which also lives in
       ZapCode:Tools.MakeMenus.

       In order to work, MenuConf requires a block somewhere in the file
       describing the options supported by that file. The block is of the
       form:

         | Start options
         |  [*]<option name>   <description>
         ...
         | End options

       A star (`*') at the start of an option name indicates that the
       option is turned on in the default configuration. The delimiter
       lines (`| Start options' and `| End options' must be preserved
       exactly. See ZapUser:Config.Menus.Source.UK for an example with
       plenty of options.

       The `Options->Edit config->Menus' submenu from the iconbar contains
       three options which use this: `Menus source' opens the source file
       for the current country, `Run MenuConf' allows you to select which
       of its options are enabled and disabled, and generates the real
       file, and `Rebuild defaults' rebuilds the default menus for the
       current country.

       The following menu handles are reserved for internal use, and are
       listed here with the symbolic names that MakeMenus supports.

        -  0 - Iconbar menu. Symbolic name: Zap.Iconbar

        -  1 - Window menu. Symbolic name: Zap.Window

        -  2 - Filetype menu. Symbolic name: Zap.Filetypes

        -  3 - Reserved.

        -  4 - Main font menu. Symbolic name: Zap.Fonts

        -  5 - Selection menu. Symbolic name: Zap.Selection

        -  6-9 - Reserved.

        -  10 - Throwback mode menu. Symbolic name: Mode.Throwback

        -  11 - Byte mode menu. Symbolic name: Mode.Byte

        -  12 - Word mode menu. Symbolic name: Mode.Word

        -  13 - Reserved.

        -  14 - Code mode menu. Symbolic name: Mode.Code

        -  15 - HalfWord mode menu. Symbolic name: Mode.Halfword

        -  16 - DoubleWord mode menu. Symbolic name: Mode.Doubleword

        -  17-19 - Reserved.

       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).

              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 to use as the submenu.

       If you need to, you can specify Wimp help text for each menu and
       menu item. This is done using a line of the form:

              *       Text

       The line should come immediately after the entry it describes. To
       supply default help for a menu, place the help line first in the
       menu definition (before any menu entries). The text must be quoted.

       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 supplied Menus file, and the supplied source files, 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.3.6 c-vars

       Configuration variables (or c-vars for short) are Zap's way of
       allowing the same command or feature to function in different ways
       depending on the mode you're in. Each mode within Zap can have a
       _Textual Mode File_, or TMF_TMF_ for short, which defines the c-vars
       for that mode.

       For a mode <name>, its TMF is looked for first as
       ZapUser:Config.TMFs.<name>, and then in the file given the system
       variable `Zap$TMF_<name>'. Core modes and clones will typically just
       have their TMFs in ZapUser:Config.TMFs; other modes will usually
       have their default TMFs within their application directory: you
       should copy them into ZapUser:Config.TMFs and edit there to override
       their options.

       The format of a TMF is as a _MessageTrans_ file (the same format as
       used for Zap's internationalised messages files - see section 12.4
       for internationalisation issues). This means that lines starting
       with a `#' character are treated as comments (ignored), and that all
       other lines must be of the form:

         <variable>:<value>

       The value is subjected to _interpolation_ to find the final
       value; this allows the values of other c-vars to be used within
       the definition of any given c-var (although care must be taken to
       ensure that you don't indirectly include the value you are trying to
       define, or Zap may enter an infinite loop while trying to figure out
       what to do!).

       The syntax for interpolation is `/<modename>:<variablename>/',
       where both `<modename>' and `<variablename>' are optional -
       although at least one must be present (otherwise you're trying to
       include yourself!). If either is missing, it will be filled in
       with the appropriate value for the variable being defined - so
       `/:<variablename>/' will expand to the value of `<variablename>'
       in the current mode, and `/<modename>:/' (or `/<modename>/') will
       expand to the value of the current variable in mode `<modename>'.

       In addition, `<modename>' can be either one of the special
       characters `^' (meaning the parent of the current mode) or `@'
       (meaning the current mode).

       This means that the `/' (slash) character can't be inserted directly
       into the value of a c-var. To get around this, the `\' (backslash)
       character 'escapes' the following character - so `ab\cd' is
       equivalent to `abcd', and `ab\/d' will come out as `ab/d'.

       A few examples should explain things:

         HelpSearchPath:MySearch,/C++/

       Sets the value of the c-var `HelpSearchPath' to `MySearch,<foo>'
       where `foo' is the value of `HelpSearchPath' in C++ mode.

         SetNameStart:\\<\/* >

       Sets the value of the c-var `SetNameStart' to `\</* >'.

       Any c-vars not listed for a given mode will be _inherited_ from
       the mode's parent. For instance, if the variable `TestVariable' is
       defined in Text mode, but not in C mode, using it within C mode
       will actually use the value given for Text mode - because C mode is
       derived from Text mode. What this means is that if you want to set a
       c-var once for all modes, you should put it in the TMF for Text mode
       (since all modes are derived from Text mode).

       Note that c-vars for cloned modes inherit from the clone's base,
       and _not_ from the clone's base's parent. So if, in the example
       above, we clone C mode as D, and then give `TestVariable' a value
       for C mode that is different to its value for Text mode, when we
       use `TestVariable' in D mode, the value from C mode will be used
       (which is more or less what you'd expect). C mode will still inherit
       variables from its parent, in this case Text.

       c-vars are case-sensitive. When developing your own features
       using c-vars, please remember that mixed-case c-vars (eg:
       `HelpSearchPath', `SetNameStart') are reserved for 'official' use
       - ie for features that have been finished. While developing new
       features, either prepend `_' (underscore) to your c-var name, or use
       all upper or all lower-case.

       In order to get help on a c-var, use the `HELPVAR' command, or type
       `c\ v' and type in the c-var name.

       In the future, c-vars will be able to be set on a per-file basis.
       Currently this isn't possible.

  12.4 Internationalisation

       As it is supplied, all Zap's communication with you will be in
       English. However there is support for complete and relatively
       painless translation to other languages. In order, Zap will use the
       system variable `Zap$Country', the system variable `Sys$Country' or
       "UK" to determine which country it needs to run for.

       To make life easier, Zap has a single file, ZapUser:Config.Country,
       where you can set the country to use. By default, the line to set
       this is commented out, so Zap will use your system setting - only
       change this if you want to force Zap to use a different country.

       If a particular part of Zap isn't available in the country you
       choose, Zap will use the English (UK) version instead. Currently
       much of Zap's core distribution is supplied for France and Germany
       as well as the UK (see section 15.3).

  12.5 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. Note that as of v1.45, Zap no longer
       supports RISC OS 2.

12.5.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.5.2 Templates

       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 OldStyle template set doesn't work properly (it can
       spontaneously reset the desktop font to the system font). This
       problem does not affect the Default template set.

12.5.3 NCOS

       In theory, Zap should work on NCOS (Network Computer Operating
       System - as used in Acorn's NetStation, and other similar products).
       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 NCOS has no
       Filer, loading files is more tricky - particularly so if you don't
       have an iconbar icon either. The settings variables &322, which
       allows you to specify a command to run at startup, can be set to
       `NEWFILE (Text &FFF)' to open a blank text file automatically in
       this case. You can then use `FINDFILE' (F2) to load files.

       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 find 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 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.6).

       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.2.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.2.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 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.6) 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.2.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.2.4 _DeepKeys_: 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).

       DeepKeys makes this much more bearable. Unlike its predecessor,
       KeyboardExtend, there are no known conflicts with other programs.

13.2.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.2.6 _IClear_: clear writeable icons using the mouse

       Martyn 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://zap.tartarus.org/lists.html. The current lists are:

        -  zap-buglist@zap.tartarus.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.tartarus.org).

        -  zap-beta@zap.tartarus.org - This is the discussion list for
           beta versions of Zap (beta bug reports should be sent to
           betabugs@zap.tartarus.org).

        -  zap-features@zap.tartarus.org - A largely non-technical list for
           the discussion of proposed new features.

        -  zap-devel@zap.tartarus.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.

        -  zap-technical@zap.tartarus.org - Other technical issues; this
           is where to ask questions such as "how do I write a mode to do
           ...?".

        -  zap-announce@zap.tartarus.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.tartarus.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 !Zap.Resources.UK.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 64 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, and
       the source is kept under a version control system called CVS. You
       can browse the source at http://cvs.tartarus.org/zap/, or grab a
       copy of the latest source from the CVS pserver - there are full
       details at http://zap.tartarus.org/cvs/.

       Urgent bug-fix changes should be sent to bugs@zap.tartarus.org;
       other changes should either be emailed to zap-devel@zap.tartarus.org
       (if they are small), or to Darren Salt or James Aylett for inclusion
       in the main source tree.

  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. (Currently we are half-way between an old version of the
       system, which was rather grotty, and a new version that hasn't
       been finished yet, so for the moment working on things is a little
       tricky.)

       If you want to work on the Zap documentation, the best thing to do
       is to contact the maintainer directly at docs@zap.tartarus.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://zap.tartarus.org/, with the
       official ftp distribution site at ftp://zap.tartarus.org/.

       Bug reports and suggestions should be emailed to zap-
       users@zap.tartarus.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. It is also incredibly
       helpful, if an error box mentions a particular address in memory,
       if you can supply this address along with the base addresses of all
       currently-loaded relocatable modules - the easiest way to do this
       is the RISC OS `*Modules' command. (<em>zap-users</em> 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 file !Zap.Resources.UK.Docs.Buglist; however
       they don't always get distributed because it is subject to change.
       Before submitting a bug report or suggesting a new feature, please
       try to check the current list 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, Christian Ludlam, Justin Fletcher,
       Daniel Wagenaar and Elliot Hughes. Localisations by Jerome Mathevet
       and Benoit Gilon (France), and Richard Atterer and Detlef Thielsch
       (Germany).

       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.Hambley, 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, A.Raab, O.Reinert, 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.

        -  B.Adam, M.Alshayef, A.Andersen, B.Ardler, J.Arnold, F.Bambrough,
           A.Baeumel, C.Bell, S.Bellon, J.Beranek, A.Berry, N.Bingham,
           S.Birtwistle, W.Blatchley, K.Brownhill, D.Bryan, N.Boalch,
           G.Borland, L.Bosman, J.Brady, R.Briscoe, S.Brodie, J.Bursa,
           J.Carey, A.Carter, J.Chetwynd, F.Chin, P.Clifford, T.Dawson,
           F.Devereux, J.Duffell, O.Dunn, C.Egan, N.Elliott, D.Ellis,
           S.Ellis, A.Fawcett, J.Ferguson, P.Foster, T.Fountain, E.Furtner,
           J.Ganzevles, N.Gare, L.Graham, C.Granville, L.Gretton,
           G.Griffin, S.Grint, R.Gunstone, J.Hampshire, P.Hardy, J.Harvey,
           J.Haskell, T.Hawtin, T.Hebbron, J.Heenan, H.Helliwell, R.Hems,
           C.Hetherington, A.Hill, G.Hilpert, D.Hood, I.Horvath, E.Hughes,
           R.Hudson, A.Hunter, R.James, T.Joseph, P.Johnson, S.Joyce,
           J.Keates, D.Kefford, J.Kerslake, D.Koekoek, J.Kortink, J.Lagrue,
           D.Lambley, B.Laughton, G.Lavallin, V.Lefevre, S.Liddington,
           P.Ludlam, R.Lund, P.Lurcock, A.Macfarlane Smith, T.Markettos,
           M.Martin, D.McDowell, C.McEvoy, A.Melis, D.Moore, D.Mortimer,
           P.Nolan, D.O'Shea, J.Oldak, R.Palmer, A.Partridge, G.Pearce,
           A.Pereira, M.Phillips, A.Piper, J.Poulter, D.Plunkett,
           R.Purchase, S.Purchase, D.Randles, N.Regan, S.Revill,
           I.Richardson, J.Robinson, C.Rogers, G.Royds, D.Ruck, C.Rutter,
           M.Sackman, A.Schaefer, D. Schalig, I.Scott, R.Share, A.Sidwell,
           P.Skirrow, S.Smith, M.Somerville, P.Spencer, D.Tanis, The Tanner
           Family, R.Thomas, K.Thomsen, A.Timmermans, I.Truskett, S.Truss,
           B.Tucker, R.van der Hoff, T.van der Hoff, B.Veasey, P.Vigay,
           G.Vik (for _StrongHelp_ :-), S.Watson, J.Whealing, R.Whincup,
           A.Wingate, C.Wishart, G.Wraith, J.Wright, R.Young, G.Youngs.

       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, with advice and suggestions from the
       members of the beta mailing list. The manual is produced using
       buttress, 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://zap.tartarus.org/lists.html):

        -  zap-users@zap.tartarus.org - submitting a bug report, asking for
           help, or suggesting new features.

        -  zap-technical@zap.tartarus.org - more technical discussion of
           Zap's features.

       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:

        -  ds@zap.tartarus.org - Darren Salt.

        -  dj@zap.tartarus.org - James Aylett.

        -  christian@zap.tartarus.org - Christian Ludlam.

       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 Digital Advertising and Marketing Ltd
                Eldon House
                1 Dorset Street
                LONDON
                W1U 4BB
                UK

       Note that Zap is not associated in any way with Digital Advertising
       and Marketing Ltd (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 doesn't auto-indent
         scReturn             As Return, but doesn't auto-indent

         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               Toggle Insert/Overwrite mode
         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 word
         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#                  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

   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
         F11                  Open a new blank text window

         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
         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)

       Copyright Zap Developers 1992-2004

