home *** CD-ROM | disk | FTP | other *** search
/ ftp.uni-stuttgart.de/pub/systems/acorn/ / Acorn.tar / Acorn / acornet / dev / basic / bascmp.spk / !Help next >
Text File  |  1995-06-17  |  20KB  |  770 lines
  1.  
  2.  
  3.  
  4.  
  5.                                                                               
  6.  Y8888bo                .d88oo                                                
  7.   88[ 88[              d8`  '8                                                
  8.   88[ ]8P             ]8P    '[                                               
  9.   88[ 88`  .ooo  .oo. d8[     `.oo,  oo.oo oo, .o,oo   oo.o  ooo  .oo. .oo.
  10.   88888o   8[]8[ 88 Y 88[     .8`'8['88"Y8P"88 Y8P 8b '88P8`d8 8b 88 Y 88 Y
  11.   88[ '88  " ]8[ 88b' 88[     88  88 88 ]8[ 88 ]8[ 88[ 88  ]8P""" 88b' 88b'
  12.   88[  88[ oP]8[ '888 Y8b    .88  88`88 ]8[ 88 ]8[ 88[ 88  ]8[    '888 '888
  13.   88[ ]88`]8[]8[]  Y8['88,   dY8  88 88 ]8[ 88 ]8[ 88` 88  ]8b   ]  Y88  Y8[
  14.  o888888" '8b/8b,bodP  'Y8boP`'YbdP`.88,d8b.88,]88o8" .88,  Y8bo' bodP bodP
  15.                                                ]8[
  16.                                                ]8[
  17.                                                ""`
  18.  
  19.  
  20.                       BasCompress v1.65, 06-Jun-1995
  21.     
  22.                   A BASIC compressor and cross-referencer
  23.  
  24.                            For RISC OS computers
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  ============================================================ BasCompress ==== 
  67.  
  68.  
  69.  
  70.  
  71.      [1]        License . . . . . . . . . . . . . . . . . . . . . .  1
  72.      [2]        Installation  . . . . . . . . . . . . . . . . . . .  1
  73.      [3]        Synopsis and features . . . . . . . . . . . . . . .  2
  74.      [4]        A quick run through of the program  . . . . . . . .  3
  75.      [4.1]      The basic options . . . . . . . . . . . . . . . . .  3
  76.      [5]        Problems and solutions (quickfire)  . . . . . . . .  4
  77.      [5.1]      `ENDPROC found in a function' error . . . . . . . .  4
  78.      [5.2]      `unexepcted UNTIL/ENDIF/ENDWHILE' errors  . . . . .  4
  79.      [5.3]      `Undefined routine: <routine> (used <location>)'  .  4
  80.      [5.4]      `Internal error 3.7'  . . . . . . . . . . . . . . .  5
  81.      [5.5]      Run-time `No such function/procedure' error . . . .  5
  82.      [5.6]      Run-time `Syntax error' error . . . . . . . . . . .  5
  83.      [5.7]      Run-time logic errors . . . . . . . . . . . . . . .  6
  84.      [6]        Updates . . . . . . . . . . . . . . . . . . . . . .  7
  85.      [6.1]      Frontend Updates  . . . . . . . . . . . . . . . . .  7
  86.      [6.2]      Backend Updates . . . . . . . . . . . . . . . . . .  8
  87.      [6.3]      Bugs  . . . . . . . . . . . . . . . . . . . . . . .  9
  88.      [6.4]      Credits . . . . . . . . . . . . . . . . . . . . . .  9
  89.      [7]        Registration form . . . . . . . . . . . . . . . . . 10
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  ======================================================== BasCompress ========
  131.  
  132.  
  133.  
  134.  [1] License
  135.  
  136.     This program is supplied "as is".  No warranty, express or implied, of
  137.     the  merchantability of this program or its fitness for any particular
  138.     purpose is given.  In no circumstances shall the author, or any
  139.     provider or distributor of this program, be liable for any damage,
  140.     loss of profits, or any indirect or consequential loss arising out of
  141.     the use of this program.
  142.     
  143.     Please note that this program is SHAREWARE, it is not free.  You may
  144.     use this software for a trial period.  If, after this  you decide you
  145.     would like to continue using it, then you are required to REGISTER.
  146.     Failing to register, you are obliged to destroy all copies of this
  147.     program. A trial period ends when you realise that this program could
  148.     be used on your latest program.
  149.     
  150.     Registration currently involves you sending a cheque for 15 (fifteen)
  151.     pounds sterling to the author, for which you will get a disc with the
  152.     latest version with your name in the info dialogue box (so PLEASE TYPE
  153.     CLEARLY).  There is a form at the end of this document that you can use
  154.     to register.  Registration will encourage the author to continue to
  155.     develop this program further.
  156.     
  157.     For a further 5 pounds, registration will include a printed (600
  158.     d.p.i. laser) copy of the documentation.  Note that this is not a
  159.     `professional' printing, just a pamphlet printed on a LaserDirect,
  160.     folded and stapled.
  161.     
  162.     Payment in other currencies accepted so long as at the end of the day
  163.     I end out with the same amount of money.  Credit cards not accepted.
  164.     Alternatively, send a CD of any contemporary composers or foreign
  165.     Zappa pressings.
  166.  
  167.     Free updates are available from bc@cheepnis.demon.co.uk.  Or send a
  168.     stamped, self-addressed jiffy bag if you do not have an email address.
  169.  
  170.  
  171.  [2] Installation
  172.  
  173.     To get a working system, just copy the application directory (!BC) to
  174.     a writable media (so that any choices can be saved).
  175.  
  176.     If you are not getting any throwbacks, please see S4.1 in the main
  177.     manual.
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.                                   Page   1
  193.  
  194.  ======================================================== BasCompress ========
  195.  
  196.  
  197.  
  198.  [3] Synopsis and features
  199.  
  200.  
  201.     BasCompress is a BasicV (v1.05) compressor and cross-referencer, i.e.
  202.     
  203.      o    Supports throwback
  204.      o    Removes spaces and comments
  205.      o    Removes all unused routines, and the junk left between routines
  206.      o    Removes all constant variables, replacing use with definition
  207.      o    Removes NEXT variables
  208.      o    Reduces all labels (shortens them)
  209.      o    Reduces numbers
  210.      o    Converts SWI strings to numbers
  211.      o    Converts ASC("x") to a number
  212.      o    Loads in LIBRARYs, and OVERLAYs
  213.      o    Handles line numbers
  214.      o    You can tell it which labels NOT to reduce (i.e. EVALuated vars)
  215.      o    Full cross-referencing, multi-level, multi-sort
  216.      o    It is FAST
  217.  
  218.     BasCompress consists of two programs, a Wimp front end, and the actual
  219.     program itself (the back end).  You can use the back end directly in
  220.     your script files, and use the Wimp front end for casual use.  The
  221.     back end supports throwback.
  222.  
  223.     The Wimp front end supports interactive help, and it is suggested that
  224.     the first time user use this.  Interactive help can be turned on by
  225.     running the !Help application that came supplied with the computer.
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.                                   Page   2
  257.  
  258.  ======================================================== BasCompress ========
  259.  
  260.  
  261.  
  262.  [4] A quick run through of the program
  263.  
  264.  
  265.     Drag the Log file icon from the control window to a directory display.
  266.     
  267.     Now drag one of your BASIC files onto the control window.
  268.     
  269.     If any errors were found in the code then your text editor will 
  270.     display a throwback window.  This allows you to click an error line
  271.     and the editor will show that line.  StrongED, SrcEdit and Zap
  272.     support throwback.
  273.  
  274.     The log file will appear (auto-loading Edit if need be).  Don't close
  275.     this window yet, although you may resize/move it.
  276.     
  277.     Now drag the BASIC (output) file icon from the control window onto a
  278.     directory display.
  279.     
  280.     Click ADJUST on the icon bar icon (which re-load's last file using
  281.     the current options)
  282.  
  283.  
  284.  [4.1] The basic options
  285.  
  286.     Because Basic is a highly idiosynchratic language, BasCompress prefers
  287.     code that conforms to a certain style.  It can get confused when asked
  288.     to process some types of (valid) Basic.
  289.  
  290.     For `safe' usage of BasCompress, ie where BasCompress turns off all
  291.     its' intelligence then ensure that:
  292.  
  293.      o    menu item `Input->Ignore exits from a routine (`dumb')' ON
  294.      o    menu item `Output->Parse numbers' OFF
  295.      o    menu item `Output->Remove constant variables' OFF
  296.      o    all menu items `Output->Reduce variable names' OFF
  297.      o    all menu items `Output->Reduce routine names' OFF
  298.  
  299.     with all the above settings then BasCompress will not abuse your code
  300.     too much.  However, the quality of compressed code is not that great.
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.                                   Page   3
  321.  
  322.  ======================================================== BasCompress ========
  323.  
  324.  
  325.  
  326.  [5] Problems and solutions (quickfire)
  327.  
  328.  
  329.  [5.1] `ENDPROC found in a function' error
  330.  
  331.     If the log file has lots of these warnings:
  332.     
  333.                     warning 9: ENDPROC not at end of procedure
  334.                     warning 10: = not at end of function
  335.     and these errors:
  336.                     error 2: ENDPROC found in a function
  337.                     error 1: = found in a procedure
  338.     
  339.     then the quick solution is to enable menu item
  340.     `Input->Ignore exits from a routine (`dumb')'.  These errors have
  341.     occured because BasCompress was unable to determine when a routine
  342.     ended, eg.
  343.     
  344.                     DEF FNmin(a,b)
  345.                     IF a<b THEN =a ELSE =b
  346.     
  347.     To cure this append a dummy "= 0" after it, and disable the menu item.
  348.  
  349.  
  350.  
  351.  [5.2] `unexepcted UNTIL/ENDIF/ENDWHILE' errors
  352.  
  353.     If you come across the following errors in the log file:
  354.     
  355.                     error 18: Unexpected UNTIL/ENDIF/ENDWHILE
  356.                     error 17: Unexpected UNTIL/ENDIF/ENDWHILE in a
  357.                               REPEAT/IF/CASE structure
  358.     
  359.     then ensure menu item `Input->Ignore exits from a routine (`dumb')' is
  360.     enabled.  This places BasCompress into a `dumb' mode.  Here it will
  361.     not attempt to discover the true end of a routine, and will parse
  362.     everything between successive DEF PROC/FN's.
  363.  
  364.  
  365.  
  366.  [5.3] `Undefined routine: <routine> (used <location>)'
  367.  
  368.     Generated after all files have been parsed, it warns of routines used
  369.     but never defined.  This is usually seen because BasCompress failed
  370.     to "see" the definition of the routine, due to the previous routine
  371.     not being terminated properly.  See S2.8.3.
  372.  
  373.     If this is not the case, then it is probably indicating a real error
  374.     in the source code - usually obscure routines only called in error
  375.     handlers.  If you know for sure that this routine will never be
  376.     called, just put an empty version in your main file to suppress this
  377.     error.
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.                                   Page   4
  385.  
  386.  ======================================================== BasCompress ========
  387.  
  388.  
  389.  
  390.  [5.4] `Internal error 3.7'
  391.  
  392.     This means that BasCompress tried to skip past the last routine in a
  393.     file, but couldn't because the routine end was on the last line.
  394.  
  395.     To cure this just ensure there is a blank line at the end of the
  396.     input file.
  397.  
  398.  
  399.  
  400.  [5.5] Run-time `No such function/procedure' error
  401.  
  402.     If the compressed program runs but causes the error
  403.     
  404.                     No such function/procedure
  405.     or
  406.                     Unkown or missing variable
  407.     
  408.     then the quick solution is to disable in the first case routine name
  409.     reduction, and in the second case variable name reduction.  These
  410.     changes can be done by ensuring all items in the sub menu
  411.     `Output->Reduce routine names' are not ticked, and similarly for
  412.     variables.
  413.  
  414.     The reason for the error is because the original file made use of
  415.     EVAL's or DATA with hard-coded variable/routine names.  BasCompress
  416.     renamed these variables but did not change the EVAL/DATA statements.
  417.  
  418.     The long-term solution to this is to create a Special file, see the
  419.     manual.
  420.  
  421.  
  422.  
  423.  [5.6] Run-time `Syntax error' error
  424.  
  425.     If this occurs then ensure that menu item
  426.     `Output->Reduce variable names->`E' suppression' is ticked.  See the
  427.     example file `EVariable' for an explanation.  See S8.2.
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.                                   Page   5
  449.  
  450.  ======================================================== BasCompress ========
  451.  
  452.  
  453.  
  454.  [5.7] Run-time logic errors
  455.  
  456.     If the program runs incorrectly in BasCompress'ed form then it is
  457.     probably, in the Authors' experience, caused by the source missing out
  458.     the THEN keyword in single-line IF statements.  E.g
  459.  
  460.         IF x>1024 E=4
  461.  
  462.     could get BasCompress'ed down to either:
  463.  
  464.         IFx>1024E=40
  465.  
  466.     with no parsing of numbers, or:
  467.  
  468.         IFx>&400E=40
  469.  
  470.     with number parsing enabled (as it is by default).
  471.  
  472.     The solution is to ensure your source code uses the THEN keyword.  See
  473.     S8.2.
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.  
  481.  
  482.  
  483.  
  484.  
  485.  
  486.  
  487.  
  488.  
  489.  
  490.  
  491.  
  492.  
  493.  
  494.  
  495.  
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.                                   Page   6
  513.  
  514.  ======================================================== BasCompress ========
  515.  
  516.  
  517.  
  518.  [6] Updates
  519.  
  520.  
  521.  [6.1] Frontend Updates
  522.     
  523.     v1.10 29-May-1992 ??
  524.     v1.20 11-Jul-1992 Compress "library" files separately
  525.                       assembler "B 0" compresses correctly
  526.     1.25  07-Oct-1992 RO3 support (menu help, Sprites22, desktop save,
  527.                       DragASprite)
  528.     1.30  11-Oct-1992 Frontend to new backend features
  529.                       Can save full pathname for log/xref/output files
  530.                       Pointer changes shape over writable icons
  531.     1.31  18-Jan-1993 Anti-aliased fonts in templates
  532.     1.32  28-Jan-1993 Dynamic font handling over screen resolution changes
  533.                       removed all Interface code!!
  534.     1.33  07-Feb-1993 hi-rez sprites
  535.     1.33b 12-Feb-1993 registration form at end of this document
  536.     1.34  27-Feb-1993 hi-rez menu items
  537.     1.35  26-Mar-1993 internal update
  538.     1.35b 10-Jun-1993 hi-rez menu items definable in Messages file
  539.     1.36  18-Jul-1993 new FontWindow module to cope with new Wimps' menus
  540.     1.36b 19-Sep-1993 hi-rez mono sprites added
  541.     1.37  24-Feb-1994 newlook, loads sprites on mode change, drag proginfo
  542.     1.40  17-Jul-1994 Choices dialogue box, runs on Risc PC
  543.     1.41  23-Oct-1994 Updated manuals
  544.     1.50  20-Nov-1994 Reflects updated backend
  545.     1.52  28-Nov-1994 Reflects updated backend
  546.     1.52a 01-Dec-1994 Manual/Help errors fixed
  547.     1.52b 10-Dec-1994 Manual/Help files now 7-bit clean
  548.     1.53  28-Dec-1994 New logo in Help file
  549.     1.54  15-Jan-1995 Registered version has no text on icon bar icon
  550.     1.60  04-Feb-1995 Reflects updated backend
  551.                       Rationalised the input/output/log sub menus
  552.                       Added throwback/DDEUtils support
  553.                       Again autoloads text editor if need to
  554.           11-Feb-1995 Added in this file 'internal error 3.7'
  555.     1.63  08-May-1995 Copyright notice now reflects reality
  556.                       (For Justin Fletcher a new icon!)
  557.     1.64  04-Jun-1995 New release
  558.  
  559.  
  560.  
  561.  
  562.  
  563.  
  564.  
  565.  
  566.  
  567.  
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.                                   Page   7
  577.  
  578.  ======================================================== BasCompress ========
  579.  
  580.  
  581.  
  582.  [6.2] Backend Updates
  583.  
  584.     1.23  23-Sep-1992 In assembler "SWI &7" was compressed to "SWI&7"
  585.                       In assembler ".zappa FN(foo_bar)" now ok
  586.                       Start of file consists of filename/copyright notice
  587.     1.24  01-Oct-1992 If an error occured during file output, this is now
  588.                         reported (eg file not having write access)
  589.     1.30  11-Oct-1992 Corrupted basic error message now "correct"
  590.                       File header (acorn guidelines) leaf name only
  591.                       -EVariable option
  592.     1.31  18-Jan-1993  assembler handles array labels (eg [OPT4:.x%(y%):]
  593.                        regular expressions used on variable names
  594.     1.50  20-Nov-1994  Handles "DIM x!24 80" correctly
  595.                        Correctly handles spaces after monadic minuses
  596.                        Handles consecutive monadic minuses
  597.                        Compresses ASC("x") into a number
  598.                        Constant variables are deleted
  599.                        Integers use hex notation as much as possible
  600.                        Handles lines exactly 256 bytes long
  601.     1.51  22-Nov-1994  Copes with multi-defined deleted routines
  602.           26-Nov-1994  Recognises `DEF PROCx:a=1' as an assignment
  603.           27-Nov-1994  New `dumb' mode which disables eof routine tracking
  604.                        Handles duplicate routines' lines exactly 256 bytes
  605.                        Constant variables allowed if ref'ed before assigned
  606.                        Constant variables listed separately in log file
  607.                        Special variables can suppress constantness
  608.           28-Nov-1994  `{0-1}' does NOT compress to `{0 -1}'!
  609.                        internal checks that never generates 256-byte lines
  610.     1.52  30-Nov-1994  SWAP is recognised as assignment
  611.                        handles long input lines better (eg 1 line programs)
  612.                        MOVE/DRAW/LINE/PLOT BY handled better now
  613.     1.53  28-Dec-1994  Recognises RETURN parameters being assignments
  614.     1.54  15-Jan-1995  some checks for wrong number of parameters
  615.                        &,= in assembly recognised/used (DCD, DCB/EQUS)
  616.                        OPT 'assigns' O%, L%, P% to stop const var deletion
  617.                        if no const vars now does not run out of memory!
  618.     1.55  24-Jan-1995  handles array multiplication: foo().bar()
  619.     1.60  03-Feb-1995  OVERLAY handling, TOP re-recognition, NEXT
  620.                        compaction, keep initial REMs, throwback/DDEUtils
  621.                        support
  622.     1.61  17-Feb-1995  special file OVERLAY bug fix
  623.                        added inline LOCK variable
  624.     1.62  09-Apr-1995  handles assembler "STMFD sp !, {lr}"
  625.     1.63  08-May-1995  hex constants now upper case for compilers
  626.     1.64  27-May-1995  work-around bug in DDEUtils_ThrowbackEnd
  627.     1.65  06-Jun-1995  corruption of symtable when sees OPT!
  628.  
  629.  
  630.  
  631.  
  632.  
  633.  
  634.  
  635.  
  636.  
  637.  
  638.  
  639.  
  640.                                   Page   8
  641.  
  642.  ======================================================== BasCompress ========
  643.  
  644.  
  645.  
  646.  [6.3] Bugs
  647.     
  648.     NONE!  Unless you know better...
  649.  
  650.  
  651.  
  652.  [6.4] Credits
  653.  
  654.     David Coronel for the `E' suppression solution
  655.  
  656.     John Kortink for the solution to error 18's !
  657.  
  658.     Richard Sargeant for assembler &/= definitions
  659.  
  660.     R.J. Wilks for array multiplication
  661.  
  662.     Robert Templeman for STMFD sp ! problems
  663.  
  664.     Matthew Bloch for compilation compatibility
  665.  
  666.     Tim Nicholson for help in tracking down DDEUtils bug
  667.  
  668.     Emil for pointing out the OPT symbol table bug
  669.  
  670.     Frank Zappa for musical entertainment
  671.  
  672.     Everybody that has registered
  673.  
  674.  
  675.  
  676.  
  677.  
  678.  
  679.  
  680.  
  681.  
  682.  
  683.  
  684.  
  685.  
  686.  
  687.  
  688.  
  689.  
  690.  
  691.  
  692.  
  693.  
  694.  
  695.  
  696.  
  697.  
  698.  
  699.  
  700.  
  701.  
  702.  
  703.  
  704.                                   Page   9
  705.  
  706.  ======================================================== BasCompress ========
  707.  
  708.  
  709.  
  710.  [7] Registration form
  711.  
  712.  
  713.         I would like to register as a Single User of BasCompress v1.65
  714.         
  715.         and have enclosed __________.
  716.         
  717.         This DOES / NOT (delete as applicable) include a manual.
  718.         
  719.         
  720.         Title:          ____________
  721.  
  722.         Name (Type):    ____________________________
  723.         
  724.         Address:        ________________________________
  725.         
  726.                         ________________________________
  727.         
  728.                         ________________________________
  729.         
  730.                         ________________________________
  731.         
  732.         Postcode:       _______________
  733.         
  734.         Country:        _______________
  735.         
  736.         Email:          _________@______________________
  737.  
  738.         Where obtained
  739.         BasCompress:    ____________________________
  740.         
  741.         Machine:        ___________________________________
  742.  
  743.         Possible
  744.         improvements:   ___________________________________
  745.         
  746.                         ___________________________________
  747.         
  748.         Make cheques / postal orders payable to: Mr. CY J. BOOKER
  749.         
  750.  
  751.                         86 Church View,  Main Road,
  752.                         Crockenhill,  Swanley,
  753.                         Kent.
  754.                         BR8 8JW.
  755.                         U.K.
  756.  
  757.                 Internet: bc@cheepnis.demon.co.uk
  758.                 Arcade BBS (Fidonet#2:254/27.0): Cy Booker
  759.  
  760.  
  761.  
  762.  
  763.  
  764.  
  765.  
  766.  
  767.  
  768.                                   Page  10
  769.  
  770.