                                  JFPatch
                                  =======
Version 2.40 (09 Apr 1997)
     
Introduction
------------
If you've ever programmed in Assembler, you will probably knmow how difficult
it is to create a module, or to patch a file to do something different. The difficulty lies not in knowing what you are doing, but in remembering the exact
format of what you do, and making no silly mistakes; plus the time that it
takes to write all the basic header and footer.

You could, of course, cut this time down by creating a simple template which
you modify each time. However, this is still prone to inaccuracy and
mistakes. The alternative to that is to use another assembler than Basic.

There are a few of these, and I'll list them here :

  ObjAsm   -  Object Assembler
              Acorn's DDE assembler. Allows local labels, macros, structure,
              AOF output, libraries and more. Commercial.
  CMHG     -  C Module Header Generator
              Acorn's utility to make creating modules easier. You give a
              description of the module header and it will create it. I don't
              know the format, but none of JFPatch's more esoteric features
              will be handled.
  Sasm     -  Simple assembler
              An extremely useful assembler which provides a simple interface
              to Basic assembly routines by just letting you define the code
              to assemble. The code is turned into basic assembler which is
              then assembled. Allows basic functions as macros. Local labels
              not allowed.
  ARMMaker -  An AOF assembler which interfaces with the DDE supplied with
              Acorn C. This simply means that it can produce linkable files
              and will integrate seamlessly with Make to produce code. Text
              format is similar to ObjAsm and has many of the same features.
  ExtAsm   -  An Extended Assembler for ARM RISC processors
              Allows includes, structures, macros. Format is a cross between
              Sasm and ARMMaker.
  JFPatch  -  Justin Fletcher's Patch utility
              Originally, that was all that JFPatch did. Now, however, it
              does slightly more than that. Libraries, structures (sort-of),
              macros (similar to Sasm) and local labels are supported, as
              well as automatic header generation. Format is similar to Sasm,
              and closely modelled on Basic assembler. Code is translated to
              Basic and then assembled, leaving a stand-alone piece of code
              to be distributed.
  Compile_A - Compile Assembly
              I don't know much about this, but it seems to be an interface
              to Basic in the same way as Sasm and JFPatch. Multiple files
              allow code to be split sensibly. Forrey has now abandoned the
              development of Compile_A and now uses JFPatch. Some of the
              Compile_A features have been added to JFPatch.

Strictly, not all of these are assemblers. Sasm, JFPatch, and Compile_A are
pre-processors for Basic Assembler, but the result is pretty much the same.


Why should you use JFPatch over the others ?
--------------------------------------------
Erm, don't ask me... I wrote JFPatch because it suited my programming style,
and needed specific features. JFPatch allows me (and hopefully you too) to
/very/ quickly write a module and test something. In the others, modules are
more difficult, and Patching a program is impossible (I think).


Usage
-----
JFPatch files are typed 13C, and running these will process and run the code.
The front end for JFPatch is very simple, and handles the grabbing of the
file run event, and contains a (small) options menu. This menu is not
finished. The buttons which are really relevant are :

   Throwback      : Will force the application to use Throwback when errors
                    occur. Alternatively, if off the original technique of
                    finding the line in which the error occured will be used.
                    This is basically checking for the file being edited
                    being the file being compiled, and if so moving to the
                    line using F5. This should work with Zap, Edit and SrcEdit.

   Warnings       : Currently unimplemented.
   
   Create app.    : Forces the processor to copy the files required for a stand
                    alone distributable code file to the same directory. Same as
                    the inline App header entry.
                    
   TaskWindow     : Displays all output in a taskwindow for you to see
                    Similar to this option is the inline directive #Capture
                    
   Use VDUStream  : Instead of output from the debugging routine REM being sent
    REMs            to the screen, it is instead sent to VDUStream which can
                    display the output in a window on the screen.

Clicking OK will activate the settings you have specified.


Code format
-----------
The code format is similar to Basic assembler, with a few additions. I would
recommend that you use JFPatch with Zap in Tim Tyler's Asm mode.
For full details on the format, refer to the file Format.

    
How it works
------------
Erm... Don't ask me... I will go into long and boring detail about it's many
short comings and failings. The problem is that there is just too much to
describe here. Basically, however, the front-end calls the Patch program
which may use the Module program to create a module header, and Workspace to
define workspace parameters. If errors occur, these are passed back to the
front-end in system variables and it then acts on them by taking you to the
correct line in the file using the editors Goto feature (if throwback is not
selected), or by the program using DDEUtils to send Throwback messages to to
handler. If the code is processed properly, the file is run and the code
saved (plus post directives being run), and then control is handed back to
the front end which will copy the files into the directory for the
stand-alone application if required.

Got that ? Well, if you have it's further complicated by the fact that AOF
assembly requires that areas be embedded in the file with their own offsets
and there must be various tables (symbol, string, relocation, etc) which
have to be built up on the fly. The majority of the AOF processing is
performed by the Basic part of the code - I've even used binary trees in a
vague attempt to speed things up :-). Also, it prints up some little messages
if you are running it in a TaskWindow, 'cos I'm nice like that...


Files
-----
The files inside the Applic directory are copied to the directory of the
Patch file if App is set. You will need to change the !Help file so that it
has your address and details in. The Summary file in Help details all the
commands in the original notation form I use for quick reference. In some
ways, Summary is more detailed, in others, less so. You should be able to
cope with just reading Format.


Plaster
-------
The Plaster drawfile inside this application was initially left there by
accident in the initial releases, however, it seems to be appearing
everywhere now (Dave Thomas you're famous :-) ) so I'll make this official
statement that this is the only part of the application which should be
distributed seperately.


<BasicLibrary$File>
-------------------
This application requires Justin Fletcher's JFShared library to function.
This can be obtained from Arcade and possibly other bulletin boards. I have
seen QuickHelp on Digital Databank, so it is possible that JFShared exists
there also. JFShared is also currently being carried by Hensa and can be
obtained from Justin's website.


Compatibility
-------------
This application has been tested on the author's A5000, but due to the lack
of friends with Acorns has not been tested on other systems. Therefore, it
ought to work on any RO3.1 machine, and with a RO2 machine if it is
recognised in JFShared and uses no specific RO3 features. This program has
been tested with RO2 on a RO3 machine - ie by using some of the modules from
RO2 to 'emulate' RO2 behaviour. It seems to run ok under that emulation, so,
although I cannot say that it /will/ work, I can say that it /might/ work :-)

I use JFPatch with Zap, using a vastly modified keymap, so others may like to
use that also... If you have problems with other editors I would like to know
so that I may rectify them.


Disclaimer
----------
The author accepts no responsibility for any problems which this
application may cause or loss of data resulting in its use. This application
is Public Domain. This means that it may be distributed, so long as no charge
other than copying costs are charged for it.

You do not have to mention anywhere in the documentation that the program
was created by JFPatch (but it'd be nice). Nor are there any restrictions on
JFPatch's commercial usage, but I should like to know what you are writing so
that I can keep you up to date. This does not mean that you can supply
JFPatch with a commercial product - it is PD.


Contact
-------
Any comments, queries, donations or bug reports can be sent to Justin
Fletcher at :

E-Mail : Gerph@essex.ac.uk
URL    : http://users.essex.ac.uk/users/gerph
IRC    : On #Acorn as Gerph
Finger : finger jrflet@postman.essex.ac.uk
Tel    : (01842) 813979

Snail Mail :
    Justin Fletcher
    Galadriel
    17b Cromwell Road,
    Weeting,
    Brandon,
    Suffolk.
    IP27 0QT


History
-------
Too long and dull currently... If you are really interested, then you may as
well refer to the file Patch in the Code directory.

2.22 (17 Feb 1996)
2.23 (22 May 1996)
  Fixed minor bugs in the handler code
2.24 (29 May 1996)
  Updated to take Macros into account
  Fixed bug in the String library which stopped the wildcard searches from
  working
2.26 (29 May 1996)
  Resynced with the MkPatch program.
2.27 (24 Sep 1996)
  Filetype &13C allocated.
2.28 (09 Nov 1996)
  Services call added (but not documented)
2.29 (21 Dec 1996)
  Directory structure changed to be a little tidier
2.33 (05 Feb 1997)
  Version number updated to keep up with Code.Patch
2.40 (09 Apr 1997)
  Version number updated to keep up with Code.Patch (AOF added - Beta
  release)


VDUStream
---------
VDUStream is  Computer Concepts I think.
