



                                                                              
 Y8888bo                .d88oo                                                
  88[ 88[              d8`  '8                                                
  88[ ]8P             ]8P    '[                                               
  88[ 88`  .ooo  .oo. d8[     `.oo,  oo.oo oo, .o,oo   oo.o  ooo  .oo. .oo.
  88888o   8[]8[ 88 Y 88[     .8`'8['88"Y8P"88 Y8P 8b '88P8`d8 8b 88 Y 88 Y
  88[ '88  " ]8[ 88b' 88[     88  88 88 ]8[ 88 ]8[ 88[ 88  ]8P""" 88b' 88b'
  88[  88[ oP]8[ '888 Y8b    .88  88`88 ]8[ 88 ]8[ 88[ 88  ]8[    '888 '888
  88[ ]88`]8[]8[]  Y8['88,   dY8  88 88 ]8[ 88 ]8[ 88` 88  ]8b   ]  Y88  Y8[
 o888888" '8b/8b,bodP  'Y8boP`'YbdP`.88,d8b.88,]88o8" .88,  Y8bo' bodP bodP
                                               ]8[
                                               ]8[
                                               ""`


                      BasCompress v2.0, 14-Mar-1997
    
                  A BASIC compressor and cross-referencer

                           For RISC OS computers









































 ============================================================ BasCompress ==== 




     [1]        License . . . . . . . . . . . . . . . . . . . . . .  1
     [2]        Installation  . . . . . . . . . . . . . . . . . . .  1
     [3]        Synopsis and features . . . . . . . . . . . . . . .  2
     [4]        A quick run through of the program  . . . . . . . .  3
     [4.1]      The basic options . . . . . . . . . . . . . . . . .  3
     [5]        Problems and solutions (quickfire)  . . . . . . . .  4
     [5.1]      ENDPROC found in a function error . . . . . . . .  4
     [5.2]      unexepcted UNTIL/ENDIF/ENDWHILE errors  . . . . .  4
     [5.3]      Undefined routine: <routine> (used <location>)  .  4
     [5.4]      Run-time No such function/procedure error . . . .  5
     [5.5]      Run-time Syntax error error . . . . . . . . . . .  5
     [5.6]      Run-time logic errors . . . . . . . . . . . . . . .  5
     [5.7]      Squeeze wont work  . . . . . . . . . . . . . . . .  6
     [6]        Updates . . . . . . . . . . . . . . . . . . . . . .  7
     [6.1]      Frontend Updates  . . . . . . . . . . . . . . . . .  7
     [6.2]      Backend Updates . . . . . . . . . . . . . . . . . .  8
     [6.3]      Bugs  . . . . . . . . . . . . . . . . . . . . . . .  9
     [6.4]      Credits . . . . . . . . . . . . . . . . . . . . . .  9
     [7]        Author  . . . . . . . . . . . . . . . . . . . . . . 10








































 ======================================================== BasCompress ========



 [1] License

    This program is supplied "as is".  No warranty, express or implied, of
    the  merchantability of this program or its fitness for any particular
    purpose is given.  In no circumstances shall the author, or any
    provider or distributor of this program, be liable for any damage,
    loss of profits, or any indirect or consequential loss arising out of
    the use of this program.
    
    Please note that this program is now released as Freeware, and is
    no longer shareware.  The programs' copyright still remains with the
    author.


 [2] Installation

    To get a working system, just copy the application directory (!BC) to
    a writable media (so that any choices can be saved).

    If you are not getting any throwbacks, please see 4.1 in the main
    manual.





































                                  Page   1

 ======================================================== BasCompress ========



 [3] Synopsis and features


    BasCompress is a BasicV (v1.05) compressor and cross-referencer, i.e.
    
         Supports throwback
         Removes spaces and comments
         Removes all unused routines, and the junk left between routines
         Removes all constant variables, replacing use with definition
         Removes NEXT variables
         Reduces all labels (shortens them)
         Reduces numbers
         Converts SWI strings to numbers
         Converts ASC("x") to a number
         Loads in LIBRARYs, and OVERLAYs
         Handles line numbers
         You can tell it which labels NOT to reduce (i.e. EVALuated vars)
         Full cross-referencing, multi-level, multi-sort
         It is FAST

    BasCompress consists of two programs, a Wimp front end, and the actual
    program itself (the back end).  You can use the back end directly in
    your script files, and use the Wimp front end for casual use.  The
    back end supports throwback.

    The Wimp front end supports interactive help, and it is suggested that
    the first time user use this.  Interactive help can be turned on by
    running the !Help application that came supplied with the computer.






























                                  Page   2

 ======================================================== BasCompress ========



 [4] A quick run through of the program


    Drag the Log file icon from the control window to a directory display.
    
    Now drag one of your BASIC files onto the control window.
    
    If any errors were found in the code then your text editor will 
    display a throwback window.  This allows you to click an error line
    and the editor will show that line.  StrongED, SrcEdit and Zap
    support throwback.

    The log file will appear (auto-loading Edit if need be).  Dont close
    this window yet, although you may resize/move it.
    
    Now drag the BASIC (output) file icon from the control window onto a
    directory display.
    
    Click ADJUST on the icon bar icon (which re-loads last file using
    the current options)


 [4.1] The basic options

    Because Basic is a highly idiosynchratic language, BasCompress prefers
    code that conforms to a certain style.  It can get confused when asked
    to process some types of (valid) Basic.

    For safe usage of BasCompress, ie where BasCompress turns off all
    its intelligence then ensure that:

         menu item Input->Ignore exits from a routine (dumb) ON
         menu item Output->Parse numbers OFF
         menu item Output->Remove constant variables OFF
         all menu items Output->Reduce variable names OFF
         all menu items Output->Reduce routine names OFF

    with all the above settings then BasCompress will not abuse your code
    too much.  However, the quality of compressed code is not that great.



















                                  Page   3

 ======================================================== BasCompress ========



 [5] Problems and solutions (quickfire)


 [5.1] ENDPROC found in a function error

    If the log file has lots of these warnings:
    
                    warning 9: ENDPROC not at end of procedure
                    warning 10: = not at end of function
    and these errors:
                    error 2: ENDPROC found in a function
                    error 1: = found in a procedure
    
    then the quick solution is to enable menu item
    Input->Ignore exits from a routine (dumb).  These errors have
    occured because BasCompress was unable to determine when a routine
    ended, eg.
    
                    DEF FNmin(a,b)
                    IF a<b THEN =a ELSE =b
    
    To cure this append a dummy "= 0" after it, and disable the menu item.



 [5.2] unexepcted UNTIL/ENDIF/ENDWHILE errors

    If you come across the following errors in the log file:
    
                    error 18: Unexpected UNTIL/ENDIF/ENDWHILE
                    error 17: Unexpected UNTIL/ENDIF/ENDWHILE in a
                              REPEAT/IF/CASE structure
    
    then ensure menu item Input->Ignore exits from a routine (dumb) is
    enabled.  This places BasCompress into a dumb mode.  Here it will
    not attempt to discover the true end of a routine, and will parse
    everything between successive DEF PROC/FNs.



 [5.3] Undefined routine: <routine> (used <location>)

    Generated after all files have been parsed, it warns of routines used
    but never defined.  This is usually seen because BasCompress failed
    to see the definition of the routine, due to the previous routine
    not being terminated properly.  See 2.8.3.

    If this is not the case, then it is probably indicating a real error
    in the source code  usually obscure routines only called in error
    handlers.  If you know for sure that this routine will never be
    called, just put an empty version in your main file to suppress this
    error.






                                  Page   4

 ======================================================== BasCompress ========



 [5.4] Run-time No such function/procedure error

    If the compressed program runs but causes the error
    
                    No such function/procedure
    or
                    Unkown or missing variable
    
    then the quick solution is to disable in the first case routine name
    reduction, and in the second case variable name reduction.  These
    changes can be done by ensuring all items in the sub menu
    Output->Reduce routine names are not ticked, and similarly for
    variables.

    The reason for the error is because the original file made use of
    EVALs or DATA with hard-coded variable/routine names.  BasCompress
    renamed these variables but did not change the EVAL/DATA statements.

    The long-term solution to this is to create a Special file, see the
    manual.



 [5.5] Run-time Syntax error error

    If this occurs then ensure that menu item
    Output->Reduce variable names->E suppression is ticked.  See the
    example file EVariable for an explanation.  See 8.2.



 [5.6] Run-time logic errors

    If the program runs incorrectly in BasCompressed form then it is
    probably, in the Authors experience, caused by the source missing out
    the THEN keyword in single-line IF statements.  E.g

        IF x>1024 E=4

    could get BasCompressed down to either:

        IFx>1024E=40

    with no parsing of numbers, or:

        IFx>&400E=40

    with number parsing enabled (as it is by default).

    The solution is to ensure your source code uses the THEN keyword.  
    See 8.2.







                                  Page   5

 ======================================================== BasCompress ========



 [5.7] Squeeze wont work

    The squeeze program is used to compress executable files, but is
    not distributed with BasCompress due to copyright reasons.

    The squeeze program can be found residing inside Acorns Patch
    application, inside the !Patch.Library file.  Copy this file into
    your $.Library directory, and everything will be OK.  See 2.22.


















































                                  Page   6

 ======================================================== BasCompress ========



 [6] Updates


 [6.1] Frontend Updates
    
    v1.10 29-May-1992 ??
    v1.20 11-Jul-1992 Compress "library" files separately
                      assembler "B 0" compresses correctly
    1.25  07-Oct-1992 RO3 support (menu help, Sprites22, desktop save,
                      DragASprite)
    1.30  11-Oct-1992 Frontend to new backend features
                      Can save full pathname for log/xref/output files
                      Pointer changes shape over writable icons
    1.31  18-Jan-1993 Anti-aliased fonts in templates
    1.32  28-Jan-1993 Dynamic font handling over screen resolution changes
                      removed all Interface code!!
    1.33  07-Feb-1993 hi-rez sprites
    1.33b 12-Feb-1993 registration form at end of this document
    1.34  27-Feb-1993 hi-rez menu items
    1.35  26-Mar-1993 internal update
    1.35b 10-Jun-1993 hi-rez menu items definable in Messages file
    1.36  18-Jul-1993 new FontWindow module to cope with new Wimps menus
    1.36b 19-Sep-1993 hi-rez mono sprites added
    1.37  24-Feb-1994 newlook, loads sprites on mode change, drag proginfo
    1.40  17-Jul-1994 Choices dialogue box, runs on Risc PC
    1.41  23-Oct-1994 Updated manuals
    1.50  20-Nov-1994 Reflects updated backend
    1.52  28-Nov-1994 Reflects updated backend
    1.52a 01-Dec-1994 Manual/Help errors fixed
    1.52b 10-Dec-1994 Manual/Help files now 7-bit clean
    1.53  28-Dec-1994 New logo in Help file
    1.54  15-Jan-1995 Registered version has no text on icon bar icon
    1.60  04-Feb-1995 Reflects updated backend
                      Rationalised the input/output/log sub menus
                      Added throwback/DDEUtils support
                      Again autoloads text editor if need to
          11-Feb-1995 Added in this file 'internal error 3.7'
    1.63  08-May-1995 Copyright notice now reflects reality
                      (For Justin Fletcher a new icon!)
    1.64  04-Jun-1995 New release
    1.66  06-Jul-1995 handles TRACE PROC
    1.67  16-Jul-1995 only reports errors/warnings once
    1.68  23-Jul-1995 support for Absolute/Squeeze'd generation
                      separate BasCompress$Choices system variable
    1.70  06-Sep-1996 click on reduce menu items
    2.00  14-Mar-1997 Freeware release












                                  Page   7

 ======================================================== BasCompress ========



 [6.2] Backend Updates

    1.23  23-Sep-1992 In assembler "SWI &7" was compressed to "SWI&7"
                      In assembler ".zappa FN(foo_bar)" now ok
                      Start of file consists of filename/copyright notice
    1.24  01-Oct-1992 If an error occured during file output, this is now
                        reported (eg file not having write access)
    1.30  11-Oct-1992 Corrupted basic error message now "correct"
                      File header (acorn guidelines) leaf name only
                      -EVariable option
    1.31  18-Jan-1993  assembler handles array labels (eg [OPT4:.x%(y%):]
                       regular expressions used on variable names
    1.50  20-Nov-1994  Handles "DIM x!24 80" correctly
                       Correctly handles spaces after monadic minuses
                       Handles consecutive monadic minuses
                       Compresses ASC("x") into a number
                       Constant variables are deleted
                       Integers use hex notation as much as possible
                       Handles lines exactly 256 bytes long
    1.51  22-Nov-1994  Copes with multi-defined deleted routines
          26-Nov-1994  Recognises DEF PROCx:a=1 as an assignment
          27-Nov-1994  New dumb mode which disables eof routine tracking
                       Handles duplicate routines lines exactly 256 bytes
                       Constant variables allowed if refed before assigned
                       Constant variables listed separately in log file
                       Special variables can suppress constantness
          28-Nov-1994  {0-1} does NOT compress to {0 -1}!
                       internal checks that never generates 256-byte lines
    1.52  30-Nov-1994  SWAP is recognised as assignment
                       handles long input lines better (eg 1 line programs)
                       MOVE/DRAW/LINE/PLOT BY handled better now
    1.53  28-Dec-1994  Recognises RETURN parameters being assignments
    1.54  15-Jan-1995  some checks for wrong number of parameters
                       &,= in assembly recognised/used (DCD, DCB/EQUS)
                       OPT 'assigns' O%, L%, P% to stop const var deletion
                       if no const vars now does not run out of memory!
    1.55  24-Jan-1995  handles array multiplication: foo().bar()
    1.60  03-Feb-1995  OVERLAY handling, TOP re-recognition, NEXT
                       compaction, keep initial REMs, throwback/DDEUtils
                       support
    1.61  17-Feb-1995  special file OVERLAY bug fix
                       added inline LOCK variable
    1.62  09-Apr-1995  handles assembler STMFD sp !, {lr}
    1.63  08-May-1995  hex constants now upper case for compilers
    1.64  27-May-1995  work-around bug in DDEUtils_ThrowbackEnd
    1.65  06-Jun-1995  corruption of symtable when sees OPT!
    1.68  23-Jul-1995  support for Absolute generation
                       INPUT parameters are assignments
    1.69  04-Aug-1995  If last routine is deleted, no internal errors
    1.70  06-Sep-1996  handles FN0, PROC2, etc
    1.71  19-Sep-1996  first REM in OVERLAYs is retained
    2.00  14-Mar-1997 Freeware release






                                  Page   8

 ======================================================== BasCompress ========



 [6.3] Bugs
    
    NONE!  Unless you know better...



 [6.4] Credits

    I'd like to thank the following people for sending in bug reports,
    making suggestions, and generally keeping BasCompress up to scratch:

               Bloch, M
               Brunavs, E
               Coronel, D
               Kortink, J
               Nicholson, T
               Sargeant, R
               Templeman, R
               Thomas, D
               Wilks, RJ
               Williams, S

    BasCompress could never have been written without the musical
    entertainment provided by Frank Zappa.

    I'd also like to thank everyone who has registered.
































                                  Page   9

 ======================================================== BasCompress ========



 [7] Author

    The author can be contacted as:

                        Cy Booker
                        86 Church View
                        BR8 8JW
                        U.K.

                Internet: bc@cheepnis.demon.co.uk
















































                                  Page  10

