RISC DISC 1/RISC_DISC_1.iso/pd_share/utilities/zap/!Zap/3rdParty/ZapMJEHelp

Text File | 1994-06-06 | 20.3 KB | 534 lines

ZapMJE 0.56 help file
© Martin Ebourne, 1994

                              -=-=-=-=-=-=-=-
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, Acorn Assembler and Pascal source editing modes
  • Colour, compilation, indenting, bracket matching, function browsers,
    next/last function, swap to header, auto header file generation, strip
    spaces at end of lines on save, improved shift-left and right arrow
    (previous and next word), tab type mode specific, auto mode detection,
    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.08 or greater to work.


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

Colour
------

This is currently available in the C and assembler modes. Pascal will be
implemented one day (when someone has told me or I have figured out the
precise syntax). For C, the colours are as follows:

  Foreground  : Used for anything which doesn't classify below
  Comments    : Anything in /* */
  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)
  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 is
finding enough usable 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 include some grey ones. I
recommend you re-define the colours in the palette to make them usable if you
intend to use it seriously.

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 very powerful and is designed to cater for every situation. 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 256 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
------- --------

Currently only the 'as you type' matching is implemented and then only in the
C mode. When you type a close bracket (either ), } or ]) the cursor will jump
to the corresponding open bracket for the time specified in the pause entry
in the C mode menu (in centiseconds). The pause will be truncated if you
carry on typing. To disable it, set the pause to 0 centiseconds.


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

This feature works on all three 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, 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.


Excess space removal
------ ----- -------

This automatically occurs on saving the file, and simply removes any excess
whitespace on the ends of lines. These serve no purpose other than to waste
memory and slow things down, and since they are easily generated with the
auto-indentation, it needs some way of easy removal. This is present only as
a stop-gap until Zap supports it properly.


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 three 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:^   ^      ^       ^     ^  ^     ^     ^          ^


Tab type mode specific
--- ---- ---- --------

A problem with Zap which should be fixed soon is that not enough options are
mode specific. eg. tab type. This is bound to be different for different
modes (eg. column/Unix tab in assembler, Edit tab in C), so these modes
support it as mode specific. Normally this will be fine, but you may notice
that if you switch from text to one of these modes and back to text, the tab
type will have changed. This is because text does not have a setting for it.


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

This is hopefully only temporary, and 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 three modes. Thus if header files are set to C,
then on loading if an assembler or Pascal comment is found as the first
non-whitespace character in the file, the appropriate mode will be used
instead.


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

These all work in all three modes and are:

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

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

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 '#if 0\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 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 "7: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 comma separated list of mode numbers for which the commands are
to execute in. You can also use a hyphen for ranges. eg. "1,3-5,7:..." No
other characters, not even spaces are allowed before the colon, apart from
the option of a ! immediately before it. This has the effect of negating
the condition. eg. "0,2,6,8-255!:" is the same as the previous example.

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



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 suing 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!
(Most of the stuff which is C mode only.) This will have to be replaced in
the course of making it work on all modes sooner or later. :-(

Thanks to Mercury for not charging quite as much as BT. (It means I'm just
broke rather than completely bankrupt. :-]  Correction: It means it took me
very slightly longer to become completely bankrupt.)


Contacting
==========

I can be contacted through email to [e-mail] all year round (faster
response time during term). Alternatively, snail to:

Martin Ebourne,
1 Malvern Road
Acocks Green
Birmingham
B27 6EG

I can also be contacted on Arcade, though only through private messages since
I hardly ever read the public ones. (It's bad enough trying to keep up with
Usenet/NetNews, and that's free!) A much faster response by modem can be
obtained by calling Challenger on 021 445 3913 [user #3]. 24hr; V21, V22,
V22bis, V23, V32, V32bis, with MNP1-5, V42 or V42bis; 7E1. Oh, and it's
Viewdata. :-)

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
  • Bracket matching correctly on all modes
  • 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:

  • 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!), its 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. Unfortunately, the deadline has been very tight & it's
    been close to get the colouring work, let alone the function finding
  • There are a multitude of bugs in the colouring, but I bet you won't find
    many! :-)

Pascal:

  • Function finding cheats (like assembler)

Miscellaneous:

  • This is Zap's fault, but swap to header doesn't load file into correct
    mode