
         ZapMakeFile - A syntax colouring mode for Makefiles
         ===================================================

Contents
========

1.0 : Features.
2.0 : Installation.
3.0 : What it does.
  3.1 : Command recognition
  3.2 : Bracket matching
  3.3 : Command completion
  3.4 : Buttons
4.0 : Problems.
5.0 : History.


1.0 Features
============

   + Syntax colouring for Makefiles
   + Bracket matching
   + Command completion


2.0 Installation
================

Copy the !MakeFile application into Zap's Modules directory.

Zap will then need to be restarted.


3.0 What it does
================

It syntax-colours make files.  make is a command line tool which originated
on unix systems to assist management of programming projects.

Make files have been around for donkey's years, and in that time have had
many syntactic enhancements to make Joe programmer's life easier. MakeFile mode
doesn't even attempt to colour the more esoteric (but widely used) features of 
make files, concentrating instead on the format accepted by Acorn's AMU. A 
brief overview of what MakeFile mode understands follows:

Comments:    anything from # up to the end of the line
Strings:     any text enclosed in double quotes
<...>:       GSTrans system variables or control codes (eg <foo$Dir> or <7>)
$(...):      MakeFile macros. The syntactic equivelent ${...} is also understood.
Commands:    system commands to run in order to make a target.
Punctuation: miscellaneous punctuation characters which may have significance to Make
Numbers:     numbers. Any word starting with a numeric
-switches:   Command line switches. Anything starting with a '-' after a command
+Commands:   More system commands, those only relevant under RISC OS, or rarely used
c.file:      C file names
h.header:    header file names
o.object:    object file names
s.assembler: assembler file names

3.1 : Command recognition
-------------------------

Commands are recognised as such when preceeded by whitespace, '@', or '%'. They may
also be preceeded by '-' (which instructs make to ignore errors when executing the
command) if that '-' is the first non-whitespace character on a line, or the first
non-whitespace character after a semicolon. The latter rule is for the

target:; command

syntax accepted by make.

The list of commands understood by MakeFile mode is contained near the end of the
module; you may add extra commands there if you wish, provided the table is kept
in alphabetical order. If you do this, we'd prefer you to send a bug report as well
(see the end of this file) so we can update future versions :)


3.2 : Bracket matching
----------------------

MakeFile mode supports bracket matching on certain characters. This means that while
typing in makefiles, when a '>', ')' or '}' character is entered, the cursor 
momentarily jumps back to the corresponding open bracket character. This behaviour 
may be controlled from the MakeFile mode menu = select MakeFile->Match.


3.3 : Command completion
------------------------

MakeFile mode also allows commands to be abbreviated in a manner aimilar to Operating
System commands, or as in BASIC. Simply type the beginning of the command name, then
press '.' - the rest of the command will be entered into the file. The minimum number
of characters you can type to make the command prefix unambiguous depends on the 
order of the commands in the table, as such it may change between versions of MakeFile
mode.

If you find this behavious annoying, it can be turned off from the MakeFile mode
menu - select MakeFile->Complete.


3.4 : Buttons support
---------------------

MakeFile mode has a simple buttons bar which can be turned on from the Display menu if
you have installed ZapButtons. For more information regarding buttons bars, see the 
help that comes with ZapButtons, in the !Zap.Modules.!Buttons directory.



4.0 : Problems
==============

Mainly oriented around Acorn-style make files.

In particular there is not currently any support for the primitive foo.c or
foo/c naming conventions widely in use on other platforms.


5.0 : History
===================

v0.12 - (25-Sep-03)
      * Added support for amu's new functions and directives. functions are called
        from inside $(...) sequences, like $(subst t.,o.,$(Hs)). Macros must start
        at the beginning of the line, and be prefixed by nothing, ., or -..
      
v0.11 - (05-Mar-03)
      * # is now treated as the start of comments anywhere on the line, as opposed
        to just at the start. This is in accordance with amu 5.27.

v0.10 - (30-Jan-03)
      * Removed the now unnecessary Buttons code

v0.08 - (25-Feb-02)
      * Command completion now lower case

v0.07 - (24-Feb-02)
      * Commands may also be prefixed with %
      * '-' handling improved to allow commands to be prefixed with it, only
        if the characters before the '-' are whitespace or ';'. If this is the
        case, the '-' is a punctuation colour, and the command is a command. 
	Otherwise the whole thing is a switch.
      * Bug fix to allow c++ to be coloured as a command.
      * CMunge, IfThere and Wipe added to the command list
      * ToANSI and ToPCC removed, because they can't be called from makefiles.

v0.06 - (23-Feb-02)
      * Commands are only coloured if preceeded by whitespace or '@'. This
        prevents targets like $(TDIR).!Run being coloured as a command.

v0.05 - (21-Feb-02)
      * ${...} is now treased as identical to $(...), and both are now
        only coloured if the initial '$' is present.

v0.04 - (06-Jul-01)
      * Bugfix to Scripts loading code.

v0.03 - (27-Jun-2001)
      * Long switches are now coloured fully
      * as and drlink added to list of recognised commands
      * Fix for bug causing data aborts in new files

v0.02 - (10-May-1998)
      * *Help now works.
      * The mode now never makes visual modifications to displayed switches.

v0.01 - (03-Apr-1998)
      * First released version.


6.0 : Contact
=============

If you have any comments or bug reports concerning MakeFile mode, we'd love to
hear from you. The best place to send messages to is the zap-users mailing
list at <zap-users@zap.tartarus.org> - you don't have to be subscribed to the
list to post to it. Alternatively, you could contact one of the Zap
developers directly - our addresses are in the Contact section of Zap's
website, which is at <http://zap.tartarus.org/>.
