---

DiscWorld

Aaron Timbrell dives into the software directory.

It's yet another packed DiscWorld this issue (well you better unpack it before it gets sent out - HJ) with our usual number of goodies.

Emotions

This month the full commercial offering is the classic platformer from GEK, Emotions. Full instructions for playing Emotions are inside the program, and are reproduced as an article in this issue. You can access the in-game instructions from the screen headed PLAY, from here you can set the a number of options including the keys used. The default keys are:

  Left                    Z
  Right                   X
  Up/Jump                 '
  Down/Pickup             /
  Fire/Drop forward       RETURN
  Dynamite                SPACE
  Pause                   F1
  Skip Intro/Suicide      ESCAPE

Zap

Zap Manual - Chapter 2: Installation

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 replaced 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 configuration 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 complete DiscWorld line up

So to sum up this issues DiscWorld looks like this...

Emotions

The full commercial game from GEK Programs.

Games

The complete SDL (Simple DirectMedia Layer) package from EQ Labs, along with some sample games. Also the latest demo version of Vingt et Un from Ian Mcfarlane.

MakeHTML

Following on from last issue, we have HTML converters for the Impression family.

Modules

All the source code and the executables, from Brian Pickard's series.

PD

All the latest PD, shareware and freeware releases from the PD column. This issue we focus on one author, Jochen Lueg

PowerBase

The latest version of PowerBase and the example files discussed in Derek Haslam's article.

ReadARGS

The sample program discussed in Hariet Bazley's article.

Zap

The latest version of !Zap (the first in over two years).

Aaron Timbrell