<!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>Developing for Zap</title>
</head>
<body background='/img/background.png' text="#000000" bgcolor="#DCDCDC" link="#20209F" vlink="#008000" alink="#FF2020">
<p align='center'><a href="Chapter13">Previous</a> | <a href="Contents">Contents</a> | <a href="IndexPage">Index</a> | <a href="Chapter15">Next</a></p>

<ul>
<li><a href="#C14">Chapter 14: Developing for Zap</a>
<ul>
<li><a href="#S14.1">14.1 Developer mailing lists</a></li>
<li><a href="#S14.2">14.2 Writing extensions to Zap</a>
<ul>
<li><a href="#S14.2.1">14.2.1 Writing additional Zap commands</a></li>
<li><a href="#S14.2.2">14.2.2 Writing a Zap mode</a></li>
</ul></li>
<li><a href="#S14.3">14.3 Working on the Zap core</a></li>
<li><a href="#S14.4">14.4 Working on Zap's documentation</a></li>
</ul></li>
</ul>
<h1><a name="C14"></a>Chapter 14: Developing for Zap</h1>
<p>
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 <em>don't</em> 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 :-).
</p>
<h2><a name="S14.1"></a>14.1 Developer mailing lists</h2>
<p>
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.
</p>
<p>
For information on how to subscribe, see <a href="http://zap.tartarus.org/lists">http://zap.tartarus.org/lists</a>. The current lists are:
</p>
<ul><li>
<a href="mailto:zap-buglist@zap.tartarus.org">zap-buglist@zap.tartarus.org</a> - 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 <a href="mailto:bugs@zap.tartarus.org">bugs@zap.tartarus.org</a>).
</li>
<li>
<a href="mailto:zap-beta@zap.tartarus.org">zap-beta@zap.tartarus.org</a> - This is the discussion list for beta versions of Zap (beta bug reports should be sent to <a href="mailto:betabugs@zap.tartarus.org">betabugs@zap.tartarus.org</a>).
</li>
<li>
<a href="mailto:zap-features@zap.tartarus.org">zap-features@zap.tartarus.org</a> - A largely non-technical list for the discussion of proposed new features.
</li>
<li>
<a href="mailto:zap-devel@zap.tartarus.org">zap-devel@zap.tartarus.org</a> - Technical discussion of Zap's features; this is basically to stop the other lists from becoming cluttered with detailed discussion about <em>how</em> to do things, rather than simply <em>if</em> we should.
</li>
<li>
<a href="mailto:zap-technical@zap.tartarus.org">zap-technical@zap.tartarus.org</a> - Other technical issues; this is where to ask questions such as "how do I write a mode to do ...?".
</li>
<li>
<a href="mailto:zap-announce@zap.tartarus.org">zap-announce@zap.tartarus.org</a> - A list to which announcements of important changes is made. In general these announcements are also posted to <code>comp.sys.acorn.announce</code>. (This list is moderated; if you send email to it it will be vetted first before going out to the list.).
</li>
</ul>
<p>
If you think we need a new mailing list, email <a href="mailto:listmaster@zap.tartarus.org">listmaster@zap.tartarus.org</a> to discuss it.
</p>
<h2><a name="S14.2"></a>14.2 Writing extensions to Zap</h2>
<p>
First, it should be noted that in order to write extensions for Zap, you <em>do</em> 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.
</p>
<p>
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 (<a name="i0"></a><em>ZapText</em>, <a name="i1"></a><em>ZapUtil</em> etc.) are specifically designed so that the framework can be quickly re-used to create new extensions.
</p>
<p>
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 <code>!Zap.Modules</code> directory to install them (you need to reboot Zap to actually recognise new extensions).
</p>
<p>
You should read the file <code>!Zap.Resources.UK.Docs.Technical.!ReadMe</code> for an introduction to how to write a Zap extension.
</p>
<h3><a name="S14.2.1"></a>14.2.1 Writing additional Zap commands</h3>
<p>
In order to add commands to Zap, you need to call the Zap call <code>Zap_AddCommands</code>. 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.
</p>
<h3><a name="S14.2.2"></a>14.2.2 Writing a Zap mode</h3>
<p>
To add a new mode to Zap, you need to call the Zap call <code>Zap_AddMode</code>. 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.
</p>
<p>
You will probably need to read most of the documentation in <code>Docs.Technical</code> before attempting to write a mode.
</p>
<h2><a name="S14.3"></a>14.3 Working on the Zap core</h2>
<p>
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 <a href="http://cvs.tartarus.org/zap/">http://cvs.tartarus.org/zap/</a>, or grab a copy of the latest source from the CVS pserver - there are full details at <a href="http://zap.tartarus.org/cvs/">http://zap.tartarus.org/cvs/</a>.
</p>
<p>
Urgent bug-fix changes should be sent to <a href="mailto:bugs@zap.tartarus.org">bugs@zap.tartarus.org</a>; other changes should either be emailed to <a href="mailto:zap-devel@zap.tartarus.org">zap-devel@zap.tartarus.org</a> (if they are small), or to <a href="mailto:ds@zap.tartarus.org">Darren Salt</a> or <a href="mailto:dj@zap.tartarus.org">James Aylett</a> for inclusion in the main source tree.
</p>
<h2><a name="S14.4"></a>14.4 Working on Zap's documentation</h2>
<p>
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.)
</p>
<p>
If you want to work on the Zap documentation, the best thing to do is to contact the maintainer directly at <a href="mailto:docs@zap.tartarus.org">docs@zap.tartarus.org</a>.
</p>
<hr>
<p>
The final section of the maual is <a href="Chapter15#C15">chapter 15</a>, 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.
</p>

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