ZapMJE 0.76 help file
 Martin Ebourne, 1997 - 1988

                              -=-=-=-=-=-=-=-
This software is COPYRIGHT, but has been released as FREEWARE. Please see the
end of this file for conditions of use and distribution.
                              -=-=-=-=-=-=-=-


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)
   Support for using StrongHelp directly
   A command to enable keys to have different bindings for different modes
   A command to alter the current selection (the same as Edit's F6)

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


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

Colour
------

This is currently available in the C, C++, Java, and assembler modes. Pascal
will be implemented one day (when someone has told me or I have figured out
the precise syntax). For C/C++/Java, the colours are 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). Never used
                for Java
  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 the C mode, 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 C mode
menu, and should have the value 0 to disable the feature.


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.


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
---- ------ ---- ----------

This is only in its simple stages at the moment, but 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 */', deleting everything following it. 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.


Previous and next word
-------- --- ---- ----

The previous and next word commands (shift-left & shift-right) of Zap are
intended for use when text editing, and as such only stop after whitespace or
parentheses. This is fine for text, but totally unsuitable for program
editing unless you are liberal with your spaces (I'm not). For instance,
previous/next word would jump right over 'whatever=this+that/something_else;'
which is not very useful. For that reason all of the extra modes have a much
more powerful implementation as standard. It can be thought of as working
like this:

There are 5 categories of character, classified in descending order as:

  5: Newline character
  4: Letters and numbers
  3: Anything else non-whitespace (ie. symbols)
  2: Whitespace (space and tab)
  1: Newline character

When you press shift-left or shift-right, the cursor will be moved in that
direction until the classification of the next character (in the direction it
is moving) is greater than that of the current character, upon which it will
stop. Newline appears twice in order to ensure that the cursor will always
stop on each side of it. (ie. at start & end of line).

This probably sounds quite complicated, but it is in actual fact very easy,
and very intuitive to use. As an example, these are the points that the
cursor would stop at:

Line:  if((char2=getchar())!=0 && char2!=line_terminator)
Fwd :^ ^   ^     ^           ^ ^  ^      ^    ^          ^
Back:^   ^      ^       ^     ^  ^     ^     ^          ^^


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)


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.


Help commands
==== ========

These work in all Zap modes (except tokenised BASIC at the moment). Together,
they provide a more comprehensive interface to StrongHelp than StrongEd does.
:-)


Context sensitive
------- ---------

This provides help on whatever is by the cursor. Currently it only works if
the cursor is on text of some description, but it is subject to improvement
when I have time. It is invoked with the command MJE_HELPCONTEXT.


Previous
--------

This doesn't work at the moment, though it will do one day. MJE_HELPLAST is
the command, and it will re-produce the last x previous help screens going
back up a stack. (This is more for the native system.)


Topic/keyword
----- -------

This has 3 modes of operation:

The command MJE_HELPTOPIC "text" will look for help on the keyword text. This
is handy to have keys for a main menu, etc.

The command MJE_HELPTOPIC with no parameter will search for help on whatever
is selected, assuming it is in the current window and not too long. (This
allows help on words with symbols in, which MJE_HELPCONTEXT would discard as
irrelevant.)

If it still hasn't worked out what to search for, a minibuffer will be opened
for you to type in the appropriate topic.


General features
======= ========

MJE_IFMODE
----------

This enables you to use keys for different functions in different modes, or
more normally, provide the same function in several modes where one or more
of them doesn't check the mode before performing the function. eg. A mapping
for next function could be:

MJE_NEXTFUNC:MJE_IFMODE "Cmode:C_NEXT_FUNCTION"

This is needed because the C_NEXT_FUNCTION command executes regardless of
mode and would thus mess things up in any of the other modes.

The syntax is:

MJE_IFMODE "Modelist:Commands"

Modelist is a space or comma separated list of mode names for the modes which
the commands are to execute in. The colon can optionally be preceded by a !
in order to invert the sense of the list. eg. MJE_IFMODE "C C++ !: BEEP"
would beep in any mode except C or C++.

Commands is a list of commands in the normal way.


MJE_ALTERSEL
------------

This works in the same way as Edit's F6. If there is no selection the
character after the cursor is selected, else the operation is equivalent to
clicking adjust with the mouse. This is very handy if you select something
with the keyboard but get it slightly wrong - it saves you re-selecting the
whole lot. Another essential use is to select a line/several lines with the
following command sequence:

CLEFT:MJE_ALTERSEL:CRIGHT:DOWN:CLEFT:MJE_ALTERSEL

Handy hint for people who like the PC method of selection - ie. holding down
shift and pressing the cursor keys. If you re-bind the shift-cursor keys as
follows, then Zap should behave in the same manner:

sLEFT		&19C	LEFT:MJE_ALTERSEL
sRIGHT		&19D	MJE_ALTERSEL:RIGHT:MJE_ALTERSEL
sDOWN		&19E	MJE_ALTERSEL:DOWN:MJE_ALTERSEL
sUP		&19F	MJE_ALTERSEL:UP:MJE_ALTERSEL


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.


Copyright
=========

The conditions of copying this program and its associated documentation are
the same as those of the main Zap application, except you do not need my
permission to copy it if you have Dominic's.

This software is provided as is with no warranty as to its suitability or
otherwise for any particular task. If it does anything nasty then I want to
know so I can fix it, but I'm not taking any responsibility. (Besides,
there's no point in sueing me since I've got no money.)

Non-release versions of this module (identify themselves as test versions on
*Help ZapMJE) are *NOT* distributable without my express permission. They are
also more likely to fall over. ;-) [Note that such versions have various bits
of debugging code included, and will not work on RISC OS 2 due to the use of
pipes for debugging. They might also do other strange (intended) things.]

Please note that I reserve the right to make alterations to this program, its
operation, documentation, and/or conditions of use without notice in any way
I see fit. Hopefully it will be an improvement.


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
==========

I can be contacted through email to martin@galaxy.tcp.co.uk. Alternatively,
snail to:

Martin Ebourne,
2 Waltham Crescent,
Aldermoor,
Southampton,
SO16 5NX

Please let me know of any bugs or undocumented features if you ever find any
(and they aren't listed at the end of the file - that's the hard bit!). Also,
ideas for improvement are welcome. A few of my current ideas are:

   Completely re-written and vastly superior indenting code
   A really cool native help system of which the details are secret at the
    moment... ;-) If you've got any ideas for it however, then now's the time
    to let me have them
   A pretty nifty selection mechanism for C & Pascal (possibly even
    assembler)
   Colour redraw for Pascal
   Remove any features which aren't listed in this help file

If anybody wants to help me pay off some of the 'phone bill this module has
incurred, then all donations are gratefully accepted at the address above.
(Well you can't blame me for trying, can you!)


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
   The header generation copies static functions into the header
   There are a multitude of bugs in the colouring, but I bet you won't find
    many! :-)

Pascal:

   Function finding cheats (like assembler)
