



                                                                              
 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 won't 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 S4.1 in the main
    manual.





































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



 [3] Synopsis and features


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

     o    menu item `Input->Ignore exits from a routine (`dumb')' ON
     o    menu item `Output->Parse numbers' OFF
     o    menu item `Output->Remove constant variables' OFF
     o    all menu items `Output->Reduce variable names' OFF
     o    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/FN's.



 [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 S2.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
    EVAL's 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 S8.2.



 [5.6] Run-time logic errors

    If the program runs incorrectly in BasCompress'ed 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 BasCompress'ed 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 S8.2.







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



 [5.7] Squeeze won't 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 S2.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 ref'ed 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

