 | Documentation Latest release ZapRedraw Contact Download |
 |  |
 | |
Previous | Contents | Index | Next
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.
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.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.
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.
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.
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.
!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).
!!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.
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.
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.
To upgrade from Zap v1.40 or later, you need to do three things.
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.
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.
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:
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.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.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.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.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.
Previous | Contents | Index | Next