<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=US-ASCII">
<meta name="author" content="mailto:webmaster@zap.tartarus.org">
<meta name="description" content="Zap is a configurable programmers' editor for Acorn RISC OS">
<title>Installation: making sure everything's in the right place</title>
</head>
<body background='/img/background.png' text="#000000" bgcolor="#DCDCDC" link="#20209F" vlink="#008000" alink="#FF2020">
<p align='center'><a href="Chapter1">Previous</a> | <a href="Contents">Contents</a> | <a href="IndexPage">Index</a> | <a href="Chapter3">Next</a></p>

<ul>
<li><a href="#C2">Chapter 2: Installation: making sure everything's in the right place</a>
<ul>
<li><a href="#S2.1">2.1 Getting the right files</a></li>
<li><a href="#S2.2">2.2 Core setup</a>
<ul>
<li><a href="#S2.2.1">2.2.1 ZapUser: user configuration files</a></li>
<li><a href="#S2.2.2">2.2.2 ZapFonts: the global bitmap font resource</a></li>
<li><a href="#S2.2.3">2.2.3 Support files</a></li>
</ul></li>
<li><a href="#S2.3">2.3 Extensions setup</a></li>
<li><a href="#S2.4">2.4 Upgrading from Zap v1.40 or later</a>
<ul>
<li><a href="#S2.4.1">2.4.1 Replacing !Zap</a></li>
<li><a href="#S2.4.2">2.4.2 Upgrading !ZapFonts</a></li>
<li><a href="#S2.4.3">2.4.3 Upgrading !ZapUser</a></li>
</ul></li>
</ul></li>
</ul>
<h1><a name="C2"></a>Chapter 2: Installation: making sure everything's in the right place</h1>
<p>
Zap is a fairly complex application, and while you <em>can</em> 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 <em>don't</em> set it up properly).
</p>
<p>
See <a href="#S2.4">section 2.4</a> 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.
</p>
<h2><a name="S2.1"></a>2.1 Getting the right files</h2>
<p>
Zap comes in a number of parts. Which parts you need will depend on what you're intending to do.
</p>
<p>
Firstly there is the core distribution, which contains merely those files <em>required</em> 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.
</p>
<p>
Secondly there is a group of extensions which is <em>recommended</em>; you don't need these to run Zap, but they provide lots of useful features which you will probably want.
</p>
<p>
Thirdly, there are some <em>optional</em> extensions which many people won't need, but which some people will find useful.
</p>
<p>
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:
</p>
<ul><li>
<code>zap.zip</code>. This is the smallest archive, containing just the files needed to get Zap running.
</li>
<li>
<code>intl.zip</code>. As above, but adds French and German translations.
</li>
<li>
<code>devel.zip</code>. As above, but adds some tools which may be useful to authors of Zap extension modes.
</li>
</ul>
<p>
This is the first thing you should set up; this process is described below in <a href="#S2.2">section 2.2</a>.
</p>
<p>
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 <a href="#S2.3">section 2.3</a> below.
</p>
<p>
The following additional archives are optional:
</p>
<ul><li>
<code>zfonts.zip</code> - a full <a name="i0"></a>ZapFonts distribution, containing lots and lots of fonts. Generally you don't need this for Zap, since the core archive comes with a minimal <a name="i1"></a>ZapFonts distribution; however ZapFonts is used by some other applications, so you may want the additional fonts for use with them. See <a href="#S2.2.2">section 2.2.2</a> below for more information.
</li>
</ul>
<h2><a name="S2.2"></a>2.2 Core setup</h2>
<p>
The Zap core distribution contains an Install file (this document in text format), the <code>!Zap</code>, <code>!ZapFonts</code> and <code>!ZapUser</code> application directories, and a couple of other utilities. Please don't just copy it onto your hard disc - this is extremely limiting.
</p>
<p>
Let's look at where they should be going. We'll deal with ZapUser first.
</p>
<h3><a name="S2.2.1"></a>2.2.1 <a name="i2"></a>ZapUser: user configuration files</h3>
<p>
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.
</p>
<p>
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 <code>Boot:Choices</code> (<code>Shift</code> double-click on <code>!Boot</code> on your main hard disc, and then double-click on Choices in the directory viewer that come up; then you can move the <code>!ZapUser</code> application by <code>Shift</code> dragging).
</p>
<p>
If you <em>don't</em> 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 <em>before</em> 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 <code>!Zap.!ZapUser</code>. While that's far from ideal, it's a lot easier than setting up a boot structure just to deal with ZapUser.
</p>
<p>
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 <a href="Chapter15#S15.2">section 15.2</a>.
</p>
<h3><a name="S2.2.2"></a>2.2.2 <a name="i3"></a>ZapFonts: the global bitmap font resource</h3>
<p>
ZapFonts is the global bitmap font resource; it is to bitmap fonts what <code>!Fonts</code> is to outline fonts. Zap uses bitmap fonts in all its file windows, and several other applications also use it, including <a name="i4"></a><em>Messenger</em> and <a name="i5"></a><em>FreeTerm</em>. Consequently we want it to be somewhere that they can all get at it.
</p>
<p>
If you have a RISC PC-style boot structure, then you want to put ZapFonts in <code>Boot:Resources</code>. 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 <code>!Zap</code> directory as <code>!Zap.!ZapFonts</code>, 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.
</p>
<p>
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 <a href="Chapter15#S15.2">section 15.2</a>); it will come as a <code>!ZapFonts</code> application directory which you can simply copy it over the top of your installed <code>!ZapFonts</code> 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).
</p>
<p>
For more information on using ZapFonts, please see the documentation supplied inside its application directory.
</p>
<h3><a name="S2.2.3"></a>2.2.3 Support files</h3>
<p>
Zap comes with some additional support files, <code>!Country</code>, <code>!!DeepKeys</code> and <code>DDEU_Patch</code> which you'll want to deal with when you're setting it up.
</p>
<p>
It also comes with an Obey file, <code>DontRun</code>, which is supplied to assist upgrading configuration from v1.40 to v1.45 - see <a href="#S2.4">section 2.4</a> for more information.
</p>
<h4><a name="S2.2.3.1"></a>2.2.3.1 !Country</h4>
<p>
<code>!Country</code> 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 <code>Boot:Choices.Boot.PreDesk</code> on a recent boot system, so it will be run before anything else, and indeed it is supplied inside a <code>!Boot</code> structure that you can copy over your current one. <code>!Country</code> sets the environment variable <code>Sys$Country</code> to whatever your current country is. Zap uses this in its internationalisation support (see <a href="Chapter12#S12.4">section 12.4</a>).
</p>
<h4><a name="S2.2.3.2"></a>2.2.3.2 !!DeepKeys</h4>
<p>
<code>!!DeepKeys</code> 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 <code>!Country</code>, it should live in <code>Boot:Choices.Boot.PreDesk</code>, and is also supplied inside a <code>!Boot</code> structure to make this easier.
</p>
<h4><a name="S2.2.3.3"></a>2.2.3.3 DDEU_Patch</h4>
<p>
<code>DDEU_Patch</code> 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.
</p>
<p>
To check which version you have:
</p>
<pre><code>*Help DDEUtils
</code></pre>
<p>
If this reports "No help found", then
</p>
<pre><code>*Load System:Modules.DDEUtils
*Help DDEUtils
</code></pre>
<p>
Version 1.54 is supplied in the standard <code>!Boot</code>, and version 1.59 is the first version to be included in ROM.
</p>
<h2><a name="S2.3"></a>2.3 Extensions setup</h2>
<p>
Any extension archive you downloaded will contain a directory <code>!Zap</code> which should be copied over <code>!Zap</code>.
</p>
<p>
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 <em>from</em> the <code>!Zap.Modules</code> directory of the archive <em>into</em> <code>!Zap.Modules</code> in your installed setup.
</p>
<p>
You will then need to quit and restart Zap to complete the setup.
</p>
<h2><a name="S2.4"></a>2.4 Upgrading from Zap v1.40 or later</h2>
<p>
To upgrade from Zap v1.40 or later, you need to do three things.
</p>
<ul><li>
Replace !Zap - see <a href="#S2.4.1">section 2.4.1</a>
</li>
<li>
Upgrade !ZapFonts - see <a href="#S2.4.2">section 2.4.2</a>
</li>
<li>
Upgrade !ZapUser - see <a href="#S2.4.3">section 2.4.3</a>
</li>
</ul>
<h3><a name="S2.4.1"></a>2.4.1 Replacing !Zap</h3>
<p>
Since all configuration is now held in <code>!ZapUser</code>, there is almost nothing which most people need to alter inside <code>!Zap</code> itself these days - including the extensions. This means that you should simply be able to replace your current <code>!Zap</code> application directory with a new one constructed from the core archive and whatever extensions you need, as explained earlier. Please <em>don't</em> 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.
</p>
<p>
Note that this won't work smoothly if you have been keeping <code>!ZapFonts</code> or <code>!ZapUser</code> inside the <code>!Zap</code> application directory. If you are doing so, please consider trying to find an alternative solution, because it will make your life much easier.
</p>
<h3><a name="S2.4.2"></a>2.4.2 Upgrading !ZapFonts</h3>
<p>
The only change in <code>!ZapFonts</code> since Zap v1.40 was released is a new version of the <code>ZapRedraw</code> module. You should copy the new one from inside <code>!ZapFonts</code> in the core archive into your working <code>!ZapFonts</code> application directory. Alternatively, simply copy the new <code>!ZapFonts</code> over your old one.
</p>
<h3><a name="S2.4.3"></a>2.4.3 Upgrading !ZapUser</h3>
<p>
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:
</p>
<ul><li>
If you have <code>Perl</code>, you can download a script that will do the majority of the work for you - this is available from <a href="http://zap.tartarus.org/ftp/pub/1.45/upgrade-config.pl">http://zap.tartarus.org/ftp/pub/1.45/upgrade-config.pl</a>.
</li>
<li>
The Zap developers are providing an upgrade service - package your !ZapUser into a Zipfile and send it via email to <a href="mailto:upgrade@zap.tartarus.org">upgrade@zap.tartarus.org</a>. One of the developers will upgrade your configuration for you and return it to you.
</li>
</ul>
<p>
If you want to upgrade your configuraton yourself, the following changes need to be made. All the files referred to below are in <code>!ZapUser.Config</code>.
</p>
<p>
If you are upgrading from Zap v1.42 or later, some of these changes may be unnecessary for you.
</p>
<ul><li>
<code>!ZapBoot</code> 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 <code>ZapRunType FFF</code>).
</li>
<li>
<code>!ZapRun</code> 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 <code>Zap$HelpPath_&lt;mode&gt;</code> are no longer required.
</li>
<li>
<code>Country</code> 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.
</li>
<li>
<code>Settings</code> has had two variables added. &amp;322 can be used to specify a command to execute on startup, and &amp;323 specifies the default mode. See <a href="Chapter12#S12.3.1">section 12.3.1</a> for more information.
</li>
<li>
A directory <code>TMFs</code> 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 <a href="Chapter12#S12.3.6">section 12.3.6</a> 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.
</li>
<li>
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.
</li>
<li>
The <code>Keys</code> file has changed significantly; firstly, the method of specifying alternate keymaps has changed from using &amp;400 variables in a block, to using &amp;800 variables immediately before the keymap in question, to declare them. Secondly, support for country-specific <code>Keys</code> files has been added; instead of a single file, you should have a directory, <code>ZapUser:Config.Keys</code>, containing a file for each country (eg: <code>ZapUser:Config.Keys.UK</code>, <code>ZapUser:Config.Keys.France</code>). Unless you made significant alterations to your keys file, we suggest that you copy in the new <code>Keys</code> directory and make any changes you need. Alternatively, move your current <code>ZapUser:Config.Keys</code> to <code>ZapUser:Config.Keys.UK</code> (or another country name, as appropriate), and edit it to use the new file format. See <a href="Chapter12#S12.4">section 12.4</a> for more information about internationalisation, and <a href="Chapter12#S12.3.3">section 12.3.3</a> for more information about the new <code>Keys</code> file format.
</li>
<li>
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 <a href="Chapter12#S12.3.6">section 12.3.6</a> for more information).
</li>
<li>
The <code>Menus</code> 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 <code>ZapUser:Config.Menus.Source</code>), and generate your menus file from that. See <a href="Chapter12#S12.4">section 12.4</a> for more information about internationalisation, and <a href="Chapter12#S12.3.5">section 12.3.5</a> for more information about the new <code>Menus</code> source format, and the method for generating the final file from source.
</li>
</ul>
<hr>
<p>
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.
</p>
<p>
The next section in the manual is <a href="Chapter3#C3">chapter 3</a>, 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.
</p>

<hr><address><a href='/copyright'>&copy; Copyright Zap Developers 1992-2004</a>. All Rights Reserved.
</address></body>
</html>
