ZapMJE 0.85 help file
 Martin Ebourne, 1997 - 1999
 Zap Developers, 2000 - 2005

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 2 of the License, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

The General Public License is included as !ZapMJE.Copying. Source is available
via CVS; see <http://zap.tartarus.org/cvs> for more information.



Introduction
============

ZapMJE provides several new modes and various other extensions for the Zap
text editor. In brief, these are:

   C, C++, Java, Acorn Assembler, and Pascal source editing modes
   Colour, compilation, indenting, bracket matching, function browsers,
    next/last function, swap to header, auto header file generation, improved
    shift-left and right cursor (previous and next word), auto mode
    detection, ensuring linefeed termination, and various commenting features
    for the new modes (not all features in all modes)

Please note that ZapMJE requires Zap version 1.46 or greater to work.


Mode specific features
==== ======== ========

Colour
------

This is available all modes. For C/C++/Java/Pascal as follows:

  Foreground  : Used for anything which doesn't classify below
  Comments    : Anything in /* */, or after // for C++/Java
  Strings     : Strings, character constants and include filenames
                (ie. anything in "", '' or, after a #include, <>)
  Instructions: Reserved words (eg. switch, void)
  Preprocessor: Anything on preprocessor lines not under any other category
                (including preprocessor keywords such as #define). Its use
                in Java mode is optional (MJE_PREPROSET).
  Functions   : Function name in definitions, calls and macros. Not however,
                when used as a pointer
  Variables   : Any other user defined word, including parameter-less macros
  Numbers     : Things like 6.5!

The assembler colours are:

  Foreground  : Used for anything which doesn't classify below
  Comments    : Anything after ;
  Strings     : Strings and character constants (ie. anything in "" or '')
  Instructions: Anything in the instruction field (first section of line
                following whitespace), plus anything else which is part of
                the instruction (eg. {, }, !). Also instruction shifts
                (eg. ASL)
  Operators   : Assembler expression operators (eg. :SHL:)
  Labels      : Anything in the label field (text at very start of line)
  Names       : Any user defined words in the parameters of an instruction
  Numbers     : Things like 2_1101

Colouring is automatic, and if you want to switch it off you will have to set
all the foreground colours the same. A problem you are bound to have in 16
colour modes is finding enough useable colours to display. In C they are best
as all different (in assembler some of them are very closely related and
hence are best coloured the same), but unfortunately there are only 5 usable
colours in the normal Wimp palette. Hence the defaults are designed for 256+
colour modes and I've no idea what they'll look look like in 16 colours. If
using 16 colour modes, I recommend you re-define the colours in the palette
to include some useable ones.

Please note that the colouring is defined to colour CORRECT source code
correctly. What it does with incorrect source is arbitrary since then even
the compiler/assembler will not accept it and it is hence not source code.


Compilation
-----------

This is quite powerful and is designed to cater for most situations. The way
it operates is as follows (in order):

1. Look for sourcefile.^.^.MakeFile (standard name and location for a
makefile)

2. If it is type Text (FFF) or Makefile (FE1) then pass it round as a message
Data Open for either Make or AMU to pick up on. Note that it is passed round
as type FE1 regardless of whether it is Text or not. This is because a lot of
makefiles are typed to Text, and Make and AMU will not pick these up (but Zap
will!). Also note that for AMU to intercept this message, it needs a
'filetype &FE1;' line inserted into the top section of the description file.

3. If no task claims the message then amu is invoked from the command line in
a task window. The default amu options used are '-desktop -k'. The taskwindow
options used are '-display -quit'.

4. If sourcefile.^.^.MakeFile file is not of type Text or Makefile, then it
is run using Wimp_StartTask. This allows for obey files and the like to be
used, giving absolute flexibility.

5. If sourcefile.^.^.MakeFile file does not exist, then the source file is
compiled/assembled direct. It cannot be passed round as a Wimp message
because it is text, and so cannot be claimed by CC or whatever. Thus it is
compiled/assembled in a task window along the same lines as amu if invoked
above. The options used depend on the mode and are as follows:

  C      - '-IC: -throwback -LC:o.RISC_OSlib,C:o.stubs -Desktop ^'
  Asm    - Assembly does not work at the moment. Makefiles are still ok
           though
  Pascal - '-ranprv -LC:o.Stubs -throwback -desktop ^'

6. There is one last feature to ensure 100% flexibility. If the characters
'/*+', ';+' or '(*+' (depending on mode) are found within the first 1k of
the source file when invoking amu or compilation/assembly directly in a task
window, then the following characters until the next close comment or end
of line are used INSTEAD of the default options string. This means that if
you don't like the default options, you can supply your own. (For instance,
if you include extra libraries or want debug code generated.)

Note that the maximum length for the command issued is 255 characters,
including the filename, commands and the various options. Also, NO
translation is carried out in copying the options. However, when calling
*TaskWindow, the command is placed in quotes - so if any were required in the
options string they would have to be doubled up originally.


There are two commands to invoke compilation; COMPILE which saves and then
compiles (assuming the save was ok), and RUN which compiles without saving
the current file. (These correspond to the equivalent BASIC commands.)


Indenting
---------

This is currently only present in C, C++ and Java modes, and simply puts the
requested number of extra spaces onto the indent for the line following a {,
and aligns }s up with the corresponding {. The indent is set via the mode
menu, and should have the value 0 to disable the feature.

Comments are optionally reindented (MJE_INDENTCOMMENTSET).

Bracket matching
------- --------

There are two types of bracket matching available, which both work on all
three kinds of bracket (ie. ), }, and ]) and in all modes.

With as you type matching the cursor jumps to the corresponding open bracket
for the time specified in the pause entry in the mode menu (in centiseconds)
whenever you type a close bracket. The pause will be truncated if you carry
on typing, and the matching can be disabled completely by setting the delay
to 0.

Bracket highlighting highlights a pair of brackets when the cursor is
immediately to the right of either of the pair. The brackets are highlighted
by setting their background to the colour specified under 'Brackets' in the
colour menu. To disable highlighting set the colour to be the same as the
background colour.


Function browsers
-------- --------

This feature works on all except the C++ and Java modes, and simply provides
a browser of all the function definitions in the source file. C mode
correctly copes with old and new style function definitions, as well as
contrived statements such as:

#ifdef __STDC__
int wibble(int wobble)
#else
int wibble(wobble)
int wobble;
#endif
{
  ...

which are designed to work under both pcc and ANSI compilers. Assembler mode
simply lists all the lines on which labels are defined. This feature is
invoked with the standard command LISTFNS.


Next/last function
---- ---- --------

These work in the same way as the function browser, but place the cursor at
the definition of the next or previous function in the source file. They are
invoked with MJE_NEXTFUNC and MJE_LASTFUNC respectively.


Find function
-------------

Assembler and C like modes support Zap's FINDFUNCTION command (ck. in the
defalt keymap). When executed, the definition of the functon named under the
cursor is found, and the cursor moved there.


Swap to header
---- -- ------

This moves the input focus onto the corresponding header/source file (ie.
with the same leafname) for the current source/header file (assuming one
exists). It also loads the file if necessary. The corresponding header file
is of the form sourcefile.^.^.h.sourcefile, and the corresponding sourcefile
is of the form headerfile.^.^.x.headerfile where x is c, c++, j, s, or p
depending on mode. This feature is invoked with MJE_SWAPTOHEADER.


Auto header file generation
---- ------ ---- ----------

On executing MJE_GENERATEHEADER (C mode only), function prototypes will
automatically be generated and appended to the respective header file (see
MJE_SWAPTOHEADER). The prototypes are appended immediately after the first
occurrence of the sequence '/* Auto */', replacing everything following it up
to the sequence '/* End Auto */'. If the sequence is not found in the file,
then it will be appended along with the prototypes.

Currently this only deals with functions, but variables will be included at a
later date. Note also that if the header file does not exist, one will NOT be
created. This is done deliberately so that you can't accidentally generate
unwanted header files.

MJE_CREATEHEADER will create a header file in the same way, surrounding the
declarations with preprocessor guards. If the corresponding header file
already exists, this will simply call MJE_GENERATEHEADER.


Auto mode detection
---- ---- ---------

This is provided so that header files are loaded into the correct mode.
Currently Zap can only detect mode on filetype and file name. However, header
files have type text and are in a h directory, but they can be any of the
five modes. Thus if header files are set to C then on loading if a C++,
assembler, or Pascal comment is found as the first non-whitespace character
in the file, the appropriate mode will be used instead.


Linefeed termination
-------- -----------

This quite simply ensures that there is a linefeed at the end of your file
whenever you save it, in order to prevent the compiler from throwing an error
and you having to re-compile for something so simple. It is functional in all
four modes.


Various commenting features
------- ---------- --------

These all work in all four modes and are:

MJE_OPENCOMMENT
  This inserts the appropriate open comment text (ie. '/*', '// ', ';' or
'(*').

MJE_CLOSECOMMENT
  Inserts appropriate close comment ('*/' or '*)' [none for C++ and
assembler]).

MJE_COMMENT
  This inserts both the start and end comments leaving the cursor in the
middle.

MJE_IF
  Inserts 'pre-processor comment'. ie. uses conditional compilation/assembly
to effectively comment out the stuff ahead.. (Handy if there are comments
around, since you can't nest them in C). Inserts '#if0\n' or '[ 1=0\n'
depending on mode.

MJE_ENDIF
  Finishes 'pre-processor comment'. (ie. inserts '#endif\n' or ']\n'.)

MJE_COMMENTLINE
  Comments out line and moves onto next. (ie. inserts '/*' & '*/', '// ',
';', or '(*' & '*)' at start and end of line.)

MJE_UNCOMMENTLINE
  Reverses above. (ie. removes '/*' & '*/', '// ', ';', or '(*' & '*)'
if present and moves onto next line)


Where a language has two different possible comment styles, the command
MJE_COMMENTSET allows you to select the alternative one.


Non-standard option
--- -------- ------

This will not be very useful to many people, except if they lay their
assembler source out the same way as I do. Basically, if enabled then on
pressing tab you will be advanced to the next 'source column' rather than tab
stop. It only works sensibly with Unix or column tab, and the 'source
columns' are laid out as follows (using Unix tab):

Label ->------->Ins --->Operands ------>------->------->Comment

(ie. 2, 1 and 4 tab stops)

If your source looks like that, then try it, you might like it. If it doesn't
then don't switch it on and no harm done. The only reason it is in there is
because it is easier than disabling it for release. Also, Dominic wanted me
to use the non-standard option in order to justify its existence. I bet he'll
remove it now just to spite me. ;-) This feature is probably only a stop-gap
until Zap supports variable tab stops properly.


Optional behaviour
-------- ---------

MJE_COMMENTSET, MJE_INDENTCOMMENTSET and MJE_PREPROSET let you toggle
various optional behaviours, as noted earlier. They in general should only
be used in the menus file, as supplied. Briefly, they take a word argument
which has the internal mode number in the top halfword, with the bottom
halfword clear.


Note to mode authors
==== == ==== =======

Do not use any of the modes in this module as base modes - it will not work.
This is due to the way that the same code is re-used for all of the modes. If
you want a similar mode to these then contact me and maybe it can go in the
module. Adding a new mode which takes advantage of the commenting, function
finding, compiling, etc. requires nine ARM instructions and is therefore very
easy and efficient. Mode specific features, such as colouring, need extra
code.

ZapMJE also provides support for writing less speed critical routines in C to
reduce development time for your modes. However, again these facilities are
available only within the module.


Acknowledgements
================

Thanks to Dominic for writing Zap and not even charging for it! (Though he's
partly responsible for a rather large amount of damage to my 'phone bill.
:-()

Thanks to Brian Scattergood for writing his Cmode which this originally came
from - it made initial development a lot easier (although I did have to hack
it first :-]). There's even some original (slightly modified) code left! This
will have to be replaced in the course of making it work on all modes sooner
or later. :-(


Contacting
==========

If you have any comments or bug reports concerning MJE's modes, 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/>.


Known mis-features
===== === ========

(These are just the important ones :-()

Assembler:

   Assembling with no make file doesn't work
   Function finding cheats (uses search)

C/C++:

   Auto header generation is very basic (yes, it's intentional!)
   The syntax colouring is slow with large files and multiple views of the
    same file, but then when constructs such as:
    #inc\
    lude /* *\
    / <std\
    io.h>
    are valid (try it, it works!), it's hardly surprising. However, this will
    be improved in later versions.
   Problems with function finding:
    1) Preprocessor # not at start of line not recognised
    2) foo () isn't found
    3) It doesn't cope with \ outside of preprocessor
    These 'bugs' are due to me not knowing precisely how the C syntax worked
    when I wrote it
   Typing } after this sequence causes it to get locked into a loop:
     a{
    a
   There are a multitude of bugs in the colouring, but I bet you won't find
    many! :-)

Pascal:

   Function finding cheats (like assembler)


