home *** CD-ROM | disk | FTP | other *** search
/ Media Share 9 / MEDIASHARE_09.ISO / basic / bled.zip / BLED.DOC < prev    next >
Text File  |  1993-05-01  |  40KB  |  898 lines
  1.      DOCUMENTATION for BLED version 2.2
  2.      by Ken Goosens, 5020 Portsmouth Road, Fairfax, VA 22032
  3.      16 May 1993
  4.  
  5.      **********************************************************************
  6.      * BLED is copyrighted by its author.  BLED can be freely distributed *
  7.      * by non-profit organizations and bulletin boards.  BLED cannot be   *
  8.      * distributed commercially nor included in any commercial product    *
  9.      * without the explicit written consent of the author.  Individuals   *
  10.      * are encouraged to give free copies to other individuals.           *
  11.      *    All rights to the code are held by the author and any use       *
  12.      * or modification of the code requires permission of the author.     *
  13.      **********************************************************************
  14.  
  15.      BLED is supported by its author.  Individuals are encouraged to report
  16.      bugs, suggest enhancements, or, preferably, to make improvements to
  17.      the code available to others through the author.
  18.  
  19.      BLED should be distributed with the following files:
  20.  
  21.      BLED.DOC - this file
  22.      BLED.EXE - compiled, executable code
  23.      BLED.BAS - program source code
  24.  
  25.      BLED uses assembler subroutines from the fine library ADVBAS by 
  26.      TOM HANLIN.  The author has paid Tom Hanlin for rights to use his
  27.      code.
  28.  
  29.      CONTENTS
  30.  
  31.      What is BLED
  32.      What Use is BLED
  33.      What are the Advantages of BLED
  34.      New Features of BLED
  35.      How Does BLED Work
  36.      How do you Identify Lines
  37.      Line Number Merging
  38.      Metacommands
  39.      How to Invoke BLED
  40.      How BLED Runs
  41.      The Major BLED Functions
  42.      CONFIGURE
  43.      FILE COMPARE
  44.      LINE MERGE
  45.      MERGE
  46.      Stylistic Considerations
  47.      How to Recompile BLED
  48.  
  49.      What is BLED
  50.  
  51.      BLED is  a Batch Line EDitor.  Editor - because it changes text files.
  52.      Line - because  it  operates  on  entire  lines  of  text  rather than
  53.      individual characters  or phrases.  And batch - because the changes to
  54.      be made are not  specified interactively,  but are  pre-specified in a
  55.      file describing the changes, which is created outside of BLED.
  56.  
  57.  
  58.      What Use is BLED?
  59.  
  60.      BLED is  most useful when different people have to communicate changes
  61.      to a text file that they jointly maintain.  The typical use of BLED is
  62.      for producing  modifications to source code for programs.  Interactive
  63.      Microsoft BASIC has long had  a  MERGE  command  which  functions like
  64.      BLED.  It  inserts, deletes, and replaces lines based on line numbers.
  65.      Other public domain programs  would  compare  two  BASIC  programs and
  66.      produce  a  merge  file  to  convert  one to the other using the merge
  67.      command.  BLED  is  a  generalized  program  that  combines  these two
  68.      functions.
  69.  
  70.  
  71.      What are the Advantages of BLED?
  72.  
  73.      o    Lines of text do not have to be numbered.
  74.  
  75.      This means  that BLED  will work with source code that allows lines of
  76.      code to have no  numbers, including  Mircosoft QuickBASIC,  as well as
  77.      Pascal and other languages.
  78.  
  79.      o    Comment lines are supported.
  80.  
  81.      BLED comment  lines are  completely ignored  when merging.  This means
  82.      that documentation  can be  included right  inside a  BLED merge file.
  83.      One of  the disadvantages of the BASIC merge command was that the only
  84.      type of line possible was BASIC  code,  so  that  documentation  for a
  85.      merge always had to be included in a separate file.
  86.  
  87.      o    Logical lines can span multiple physical lines.
  88.  
  89.      One of  the more  disagreeable features of old BASIC was that a single
  90.      line of code (i.e. a line beginning with a  number) had  to be  on one
  91.      physical   line.    Newer   languages   like   QuickBASIC   support  a
  92.      line-continuation character (e.g the underscore) that  allows the same
  93.      logical line  to span  multiple physical lines.  This greatly improves
  94.      the readability of source  code by  allowing grouping  by indentation.
  95.      BLED recognizes and supports logical lines.
  96.  
  97.      o    Powerful metacommands for controling merges.
  98.  
  99.      QuickBasic supports only an INCLUDE of a file, and the the included
  100.      file cannot contain a SUB.   The BLED include has no such restriction.
  101.      Micosoft does not support any conditional logic at all.  BLED supports
  102.      up to 99 metavariables that can be set to any value and IF-THEN-ELSE
  103.      logic can test these variables for values and do conditional includes.
  104.  
  105.      o    Can be run batch from DOS, or interactively.
  106.  
  107.      Commands telling  BLED what  to do  can be specified as DOS arguments,
  108.      and BLED has a batch mode in which it will run without further prompts
  109.      and return  automatically to  DOS.  BLED will prompt for any arguments
  110.      it needs which are not specified.
  111.  
  112.      o    Configurable.
  113.  
  114.      BLED comes pre-set to  work  with  Microsoft  QuickBASIC,  but  can be
  115.      configured to work with different languages.
  116.  
  117.  
  118.      New Features of BLED
  119.  
  120.      BLED 2.2 has two changes:
  121.  
  122.         o   BLED works properly with line number labels that are
  123.             only the prefix of a line label, rather than the entire
  124.             label.  This allows the merge to work and descriptive
  125.             labels to be used.  E.g. instead of "12600" can have
  126.             "12600.LOCK.MESSAGES:".
  127.  
  128.         o   BLED was not properly detecting the end of a block
  129.             in some cases, which caused erroneous error message
  130.             warnings.
  131.  
  132.      BLED 2.1 has two new changes:
  133.  
  134.         o   new command line option to remove comments from code
  135.  
  136.             This allows highly commented code to be reduced in size so
  137.             that more memory is left for compilation.
  138.  
  139.         o   maximum number of metavariables increased from 50 to 99.
  140.  
  141.      BLED 2.0 has one major enhancement and fixes 5 bugs.
  142.  
  143.         o   Bled now supports metacommands with file includes,
  144.             conditional logic, and in-line blocks.
  145.  
  146.         o   The opening help now shows that the warning file
  147.             name can be specified.
  148.  
  149.         o   The reported file size for the old version was wrong
  150.             and actually was the file size of the new version.
  151.  
  152.         o   The ignore case option for labels in configuration now
  153.             works properly in the merge option.
  154.  
  155.         o   The merge option now works properly with LABEL#.
  156.  
  157.         o   The UP (UPTO) option now works properly in the merge
  158.             option.
  159.  
  160.      Note:  BLED 2.0 will no longer compile with versions of Quick
  161.      Basic earlier than 4.0.
  162.  
  163.  
  164.      BLED 1.61 adds beeps at the end of a batch run.
  165.  
  166.      BLED 1.6 fixes 3 bugs.
  167.  
  168.         o   The main prompt now includes option "F" (file compare) in
  169.             its short list of valid responses.
  170.  
  171.         o   When preserving BLED comments, a source BLED comment no
  172.             longer adds an extra space when converted to a BLED comment
  173.             in a file compare.
  174.  
  175.         o   When preserving BLED comments, a merge floats bled comments
  176.             above the line only when the bled comment is in a continued
  177.             line instead of always.
  178.  
  179.      This change allows BLED source comments to a line to be added just
  180.      above its line number, a BLED file compare to be created, and when the
  181.      resultant merge is applied, the BLED comments will no longer be one
  182.      line higher than they should be.  Now the comments will remain in
  183.      place.
  184.  
  185.  
  186.                          History of Other Changes
  187.  
  188.      BLED 1.5 has two major enhancements, some bug fixes, and some
  189.      cosmetic changes.
  190.  
  191.         o   A new option to support preserving BLED comments.
  192.  
  193.      On a merge, BLED comment lines were always eliminated and there
  194.      was no way to put temporarily comments on changes as source code
  195.      comments.  Now there is a configuration parameter that will cause
  196.      BLED comment lines to be converted to a specially formatted source
  197.      code comment lines in a merge and, conversely, convert these special
  198.      source code comments to BLED comments when doing a file compare to
  199.      produce a merge.  This change allows programmers to work with equal
  200.      fecility with merges or directly on the full program and readily
  201.      document changes and yet easily remove these temporary comments
  202.      when the code is put into production.
  203.  
  204.      Other changes in 1.5 included:
  205.  
  206.          o   BLED is about 33% faster because it has been recompiled
  207.              under QUICKBASIC 2.0.
  208.  
  209.          o   The automatic documentation in a file compare has been
  210.              enhanced to include the date and file size of the old
  211.              version of the code so that there is no ambiguity about
  212.              what version of the code the new merge goes against.
  213.  
  214.          o   A bug has been fixed that caused the character used for
  215.              a source code remark not to be read in properly from a
  216.              configuration file.
  217.  
  218.          o   A bug has been fixed that caused the maximum number of
  219.              physical lines allowed in a logical line not to be read
  220.              in properly from a configuration file.
  221.  
  222.          o   Status line reports now use a mixture of upper and lower
  223.              case rather than all upper case.  This improves readability
  224.              and reserves all upper case words for special emphasis.
  225.  
  226.          o   When a file is missing and the proper name is entered,
  227.              the status line is now properly restored.
  228.  
  229.          o   When the user Quits in interactive mode, the cursor is
  230.              left at the bottom of the screen rather than in the middle
  231.              of previous text.
  232.  
  233.          o   A parameter has been added which was in the code but missing
  234.              from the documentation.  Other parts of the documentation
  235.              have been added or made more thorough, including a statement
  236.              of distribution rights and how to recompile BLED.
  237.  
  238.      BLED 1.4 had one major change.  Output is now internally buffered.
  239.      Before, every line was written out immediately.  Now up to 100 lines
  240.      are held internally before writing.  This dramatically reduces the
  241.      number of disk i/o's and reduces the head movement, usually making
  242.      the program faster.  My test showed a 12% improvement with RBBS.
  243.          The only other change is that the default maximum number of lines
  244.      between line numbers is now 400 rather than 200.
  245.  
  246.      BLED 1.3 fixes a bug.  If a line begins with a comment other than in
  247.      column 1 and ends with a line continuation character (e.g. source code
  248.      commented out), BLED would get not correctly identify the line as a
  249.      comment and would get an illegal function call.
  250.  
  251.      BLED 1.2 has two two features: (1) autodocumenting merge, and (2) test
  252.      run mode.
  253.  
  254.      AUTODOCUMENTING.   When you do a file compare to produce a merge, BLED
  255.      produces a  header on  what files were used to make the merge and date
  256.      and time stamps the merge.  Also, BLED  produces a  header comment for
  257.      each change indicating whether the line is being INSERTED, DELETED, or
  258.      REPLACED (changed).  Also, for replacement lines longer than one line,
  259.      BLED will insert a comment marking the first different line.
  260.  
  261.      TEST MODE.   There is a new "T" (for Test) parameter.  This limits the
  262.      run to a specificed number of logical lines in the  master file.   You
  263.      will not normally use this parameter.
  264.  
  265.  
  266.      How Does BLED Work?
  267.  
  268.      Like a  block editor.   Think of how you would work with a full screen
  269.      text editor, if you  had to  work from  the top  to the  bottom of the
  270.      file.  You basically do two things:
  271.  
  272.      o    Mark a block of lines.
  273.  
  274.      o    Say what  to do  with the block - either keep, delete, or replace
  275.           by another block of code; or insert a block of code.
  276.  
  277.      BLED has a BLOCK command to identify the block of text, followed  by a
  278.      disposition  command  of  KEEP,  DELETE,  REPLACE, or INSERT.  This is
  279.      BLED's general MERGE.
  280.  
  281.  
  282.      How do You Identify Lines?
  283.  
  284.      You have to specify what blocks of lines you want to work with.  There
  285.      are three ways.
  286.  
  287.      o    By physical line number.
  288.  
  289.      The  absolute  physical  line  numbers are 1,2,3,etc. for each line of
  290.      text.  Relative lines can also  be  specified,  e.g. from  the current
  291.      position in the file forward three lines.
  292.  
  293.      o    By line labels.
  294.  
  295.      Line labels  are identifiers  or names  for lines.  BLED supports both
  296.      numeric line labels (it calls  them  label  numbers)  and alphanumeric
  297.      labels (simply labels).  BLED ASSUMES THAT A LINE LABEL OCCURS ONLY AS
  298.      THE FIRST WORD ON A LINE.  Some  languages allow  labels to  be put in
  299.      the  middle  of  a  physical  line,  but  this is bad practice because
  300.      interior labels are hard to find.
  301.  
  302.      o    By strings.
  303.  
  304.      Strings are just sequences of characters that can occur inside lines.
  305.  
  306.      So, in BLED, a block can be identified as beginning or ending  with an
  307.      absolute or relative line number, a line label, or a string.  And so a
  308.      block can be defined as
  309.  
  310.           the first five lines
  311.           everything between label-1 and label-2
  312.           from line 50 to label-1
  313.           from label-1 to the line with "HELP" in it
  314.  
  315.  
  316.      Line Number Merging
  317.  
  318.      BLED also supports  a  more  specialized  merge  much  like  the BASIC
  319.      merge.  Details  are given  below.   This line merge mode is just like
  320.      the BASIC merge command except that  logical blocks  of physical lines
  321.      replace the single physical line, and comment lines are supported.
  322.  
  323.      BLED  supports   the  specialized   line  number   merge  because  the
  324.      assumptions  greatly  simplify  the  merge  files.   No  special  BLED
  325.      commands are required:  no blocks, no block dispositions.  To insert a
  326.      line, just give it a line  number between  the original  line numbers.
  327.      To delete,  put only  the line  number in the merge file.  To replace,
  328.      use the same line number.
  329.  
  330.      The BLED line number merge treats all lines between line  numbers as a
  331.      single block,  i.e. as  if they  are one  single logical line, even if
  332.      they are multiple physical  and logical  lines.   For example,  in the
  333.      BASIC code
  334.  
  335.                200 X = X+1
  336.                    IF X>5 THEN_
  337.                      Y=0
  338.                210 Y = Y+1
  339.  
  340.      you might  think that  you could  delete the  first line 200 by having
  341.      "200" alone in the merge.   In fact,  the first  three lines  would be
  342.      deleted rather than the first only.
  343.  
  344.  
  345.      Metacommands
  346.  
  347.      Metacommands are instructions to BLED which control its merge rather
  348.      than being lines that are included in the merge.  A bled metacommand
  349.      begins with the documentation character (default of '*') followed
  350.      by the dollar sign '$'.   There are 4 metacommands:
  351.  
  352.      (1)  SET.  Used to set the value of a bled metavariable.
  353.  
  354.      The format is
  355.                     SET <metavariable> = <value>
  356.  
  357.      For example, to set the metavariable 'ML' to 'OFF' the BLED line is
  358.  
  359.                         *$ SET ML = OFF
  360.  
  361.      (2)  INCLUDE.  Used to switch the lines being processed to another
  362.           file.
  363.  
  364.      After the second file is processed, processing resumes in the original
  365.      file.   This way bled merges can be shared between different merges.
  366.      For example, if the file COM.INC has some code common to two modules,
  367.      rather than duplicate the code twice, and include can be used to
  368.      generate the full code from a bled merge.   The format is
  369.  
  370.                            INCLUDE <filename>
  371.  
  372.      An example is
  373.  
  374.                       *$ INCLUDE C:\CCODE\COM.INC
  375.  
  376.      (3)  IF-THEN-ELSE.  Used to do conditional includes.
  377.  
  378.      The format is
  379.  
  380.      IF <metavar> = <value> THEN <meta expression> ELSE <meta expression>
  381.  
  382.      The ELSE condition is not required but will generate a warning when
  383.      the if-condition is false.
  384.  
  385.      An example is
  386.  
  387.         *$ IF ML = OFF THEN INCLUDE NOML.INC ELSE INCLUDE ML.INC
  388.  
  389.      The <meta expression> can be a SET or an INCLUDE.
  390.  
  391.      (4)  BLOCK IF-THEN-ELSE.  Used to do conditional logic.
  392.  
  393.      BLOCK IFs allow entire blocks of in-line merges to be conditionally
  394.      included.   This is the only metacommand than can be on more than
  395.      one physical line.   The format is
  396.  
  397.                     IF <metavar> = <value> THEN BLOCK
  398.                        ....     (antecedent block)
  399.                     ELSE
  400.                        ....     (consequent block)
  401.                     END IF
  402.  
  403.      If it is true that <metavar> = <value> then the antecdent block
  404.      will be executed and the consequent block skipped.   If it is
  405.      false, the antecdent block will be skipped and the consequent
  406.      block be processed.
  407.  
  408.      The antecdent and consequent blocks cannot contain a BLOCK IF,
  409.      but they can contain other metexpressions or regular code to be
  410.      merged.   For example, the code
  411.  
  412.              *$ IF ML = ON THEN BLOCK
  413.                    100 X = INP(Y)
  414.                    110 GOTO 50
  415.              *$ ELSE
  416.                    100 RETURN
  417.                    105
  418.                    110
  419.              *$ END IF
  420.  
  421.     would conditionally process one block or the other depending on the
  422.     value of ML.   If file MLON has in it the antecdent block and MLOFF
  423.     has the consequent block, the same effect could be achieved using
  424.  
  425.               *$ IF ML = ON THEN INCLUDE MLON ELSE INCLUDE MLOFF
  426.  
  427.     or
  428.  
  429.              *$ IF ML = ON THEN BLOCK
  430.              *$    INCLUDE MLON
  431.              *$ ELSE
  432.              *$    INCLUDE MLOFF
  433.              *$ END IF
  434.  
  435.      BLED is effect is a batch "make" utility for creating source code.
  436.      Using metacommands, a person can in effect select a customized
  437.      version of code, to reduce execution size.   Typically the
  438.      metavariables will be set at the top of a BLED merge and then
  439.      conditional logic controls what code is included.   For example,
  440.  
  441.        *  Change ML to OFF if you are not using Multi-link.
  442.        *$ SET ML = ON
  443.        *  Change MULTIUSER to OFF if you are running single-user
  444.        *$ SET MULTIUSER = ON
  445.        *$ IF ML = ON THEN INCLUDE ML.INC ELSE INCLUDE ML.LIT
  446.        *$ IF MULTIUSER = ON THEN INCLUDE MU.INC ELSE INCLUDE MU.LIT
  447.  
  448.      Current restrictions on BLED metacommands are:
  449.  
  450.      (1)  At most 99 metavariables can be set.
  451.  
  452.      (2)  An INCLUDE file cannot include another INCLUDE file, except
  453.           at the very end (chaining one include after another is okay).
  454.  
  455.      (3)  Each metacommand must be on a single line, except for the
  456.           BLOCK IF structure.
  457.  
  458.      (4)  Values of metavariables must be a single word with no blanks.
  459.  
  460.  
  461.      How to Invoke BLED
  462.  
  463.      BLED is invoked at DOS by typing
  464.  
  465.          BLED[/options] [spec-1] [spec-2] [spec-3] [spec-4] [spec-5]
  466.          where a spec has the format [drive:][\path\][filename]
  467.  
  468.      Everything in  brackets is  optional and  may be omitted.  The options
  469.      after BLED are
  470.           /B   -    run batch.  Means to ask no questions and automatically
  471.                     return  to  DOS  when  done.   Must be used with one of
  472.                     following options and requires first three specs.
  473.  
  474.           /F   -    file compare.  Means to produce a merge file which will
  475.                     transform spec-1  (old version) into spec-2.  Output is
  476.                     spec-3.
  477.  
  478.           /L   -    line number merge.  Do a  merge of  spec-2 into spec-1,
  479.                     based  on   line  number  identifiers  in  both  files,
  480.                     outputting to spec-3.
  481.  
  482.           /M   -    general merge based  on  BLED  commands.    Into spec-1
  483.                     merge spec-2, producing spec-3.
  484.  
  485.           /T=XXX -  test mode.  Do not process all line from master (first)
  486.                     file.  Instead, end the  run  after  processing  XXX (a
  487.                     number)  of  logical  lines  in  the master file.  Used
  488.                     mainly for testing BLED.  So you can  run against large
  489.                     real files without having to create smaller samples.
  490.  
  491.          /RC  -    Remove comments.  No comment lines will be written out
  492.                    except those containing QuickBasic metacommand to include
  493.                    a file ("$INCLUDE").  Lines beginning with "REM" or
  494.                    "'" will be omitted, and comments on the ends of lines
  495.                    will also be removed.
  496.  
  497.      Note:  /F,/L,/M  options  are  incompatible  and  at  most  one can be
  498.      specified.  BLED checks  for consistency  and required  parameters and
  499.      will abort  with an  error message  and help.  Optional parameters not
  500.      specified at DOS are supplied using full screen prompts.
  501.  
  502.      Spec-4 is used when you want to override the default warning file name
  503.      (WARNING is the default configuration value).  BLED keeps appending to
  504.      the warning file as long as you continue to run within it.   Each time
  505.      you reenter  BLED from  DOS, however,  BLED will begin overwriting the
  506.      warning file.  The override is useful if you want to preserve previous
  507.      warning files.
  508.  
  509.      Spec-5  is  for  overriding  the  default  configuration  file name of
  510.      BLED.CFG.
  511.  
  512.      Note:  the meaning of the first three file specs is different  for the
  513.      /F option.  Merges mean
  514.  
  515.                [source file]  [merges]   [source+merge]
  516.  
  517.      But for the /F option the specs mean
  518.  
  519.                [old version]  [new version]  [merges]
  520.  
  521.  
  522.      How BLED Runs
  523.  
  524.      BLED makes  a single pass through the original file, doing comparisons
  525.      to the second file.  Therefor all references to line  labels should be
  526.      in the  same order they occur in the original file.  BLED gives an on-
  527.      screen status report of what it is doing,  the files  it is  using, as
  528.      well as  counts of  the number  of records  it reads and writes at the
  529.      bottom of the screen.
  530.  
  531.      The Major BLED Functions
  532.  
  533.      The four major BLED functions are
  534.  
  535.      o    CONFIGURE.  General configuration parameters.
  536.  
  537.      o    FILE COMPARE.  Create a merge file.
  538.  
  539.      o    LINE MERGE.  Merge based on line number labels.
  540.  
  541.      o    MERGE.  Merge using explicit  BLED  block  and  block disposition
  542.           commands.
  543.  
  544.      The main menu in BLED uses the first letter of each choice.
  545.  
  546.  
  547.      CONFIGURE
  548.  
  549.      BLED  has  10  configuration  parameters,  which  are  stored  in  the
  550.      configuration file BLED.CFG.   If no  configuration file  exists, BLED
  551.      uses as a default parameters suitable for QuickBASIC.
  552.  
  553.      (1)  Default extension for source files.  If no extension is given for
  554.           source files, BLED will  add this.   Default  for this  option is
  555.           BAS.  Source files include spec-1, and also spec-3 for merges and
  556.           spec-2 for file compares.
  557.  
  558.      (2)  Default extension for changes to  source.    If  no  extension is
  559.           given for this file, BLED will add this.  Default for this option
  560.           is MRG.  In merges, this  applies to  spec-2.   In file compares,
  561.           this applies to spec-3.
  562.  
  563.      (3)  Character using to begin remarks in source.  Default character is
  564.           the single quote (').    When  looking  for  a  line continuation
  565.           character at  the end  of a line, BLED will ignore all text after
  566.           the remark character.
  567.  
  568.      (4)  BLED phrase indicating end of  block.    Used  with  INSERT BLOCK
  569.           command.   What follows is a block of code to be inserted.  Tells
  570.           BLED where the code ends.
  571.  
  572.      (5)  Character beginning a line  of  BLED  documentation.    BLED will
  573.           completely  ignore  a  line  beginning  with  this character when
  574.           merging.  Allows comments or documentation  to be  included right
  575.           in a merge file to explain changes.  The character need not be in
  576.           column 1 - only the first non-blank character.   Default  is "*".
  577.           The  documentation  character  should  never  occur  as the first
  578.           character in your source text.
  579.  
  580.      (6)  Character at end of  every alphanumeric  label.   Default is ":".
  581.           BLED assumes  that line  labels occur only as the first word in a
  582.           line.  Leading spaces are ignored,  so that  labels can  begin in
  583.           any column.   This label character is used by BLED to help locate
  584.           labels.  When specifying blocks in a BLED  command, you  need not
  585.           include the  end-character.   BLED knows,  for example, what when
  586.           you say "LABEL LOOPER" that "LOOPER:" is what  actually occurs in
  587.           the source code.
  588.  
  589.      (7)  Character beginning  BLED commands.   Default  is none.  BLED can
  590.           distinguish its commands from source code lines by when a command
  591.           is needed and by key phrase.  If confusion might result, however,
  592.           you can specify that  BLED commands  begin with  a character that
  593.           will never  occur at  the beginning  of a  line of  text, such as
  594.           possibly "$" or "-".
  595.  
  596.      (8)  Whether case is ignored in alphanumeric labels.   Default is yes,
  597.           so that "looper" and "LOOPER" are treated as the same.
  598.  
  599.      (9)  Line continuation  character.  One way for a logical line to span
  600.           multiple physical lines is to insert a special  line continuation
  601.           character at  the end  of a  line that logically continues on the
  602.           following line.  Default is  "_"  (underscore).    May  differ in
  603.           languages other  than QuickBASIC.   Many other freeform languages
  604.           use  a  statement  terminator   character.      Fortran   puts  a
  605.           continuation  character  in  column  6, which is not supported by
  606.           BLED.  (BLED can still work on FORTRAN files though.)
  607.  
  608.      (10) File that warning messages  are written  to.   From the  time you
  609.           enter BLED  until you  exit DOS,  BLED may issue warning messages
  610.           based on its  file  comparison  or  merge.    These  messages are
  611.           written to  this file  for perusal  later.  This way BLED can run
  612.           completely batch with no  loss of  information.   You can nullify
  613.           these  messages  by  making  the  file "NUL:" or send them to the
  614.           screen using  "SCRN:".   BLED will  report the  number of warning
  615.           messages during  its operation.   Sending  messages to the screen
  616.           will interfere with BLED's normal report  of its  progress on the
  617.           screen.  The default name for this warning is "WARNING".
  618.  
  619.      (11) Maximum number of physical lines in a logical line.  There are
  620.           several functions that require BLED to hold an entire logical
  621.           line in memory before it can decide what to do with the line.
  622.           For example, a file compare requires BLED to determine whether
  623.           there has been any change anywhere in common line numbers.
  624.           There are only so many physical lines that BLED can hold in
  625.           memory from a master or transaction file.  The default is 400.
  626.           This parameter allows the user to increase that number.
  627.  
  628.      (12) Preserve BLED comment lines.  It is important to be able to
  629.           append notes to source code to explain changes.  These can
  630.           be left permanently in the code by making them source code
  631.           comments.  But often it is desired to leave comments in the
  632.           text only temporily.  The only facility for doing this in
  633.           versions of BLED prior to 1.5 was to include special BLED
  634.           comment lines in a merge file which would be stripped out when
  635.           a merge was done.
  636.               For people who prefer to work with the full
  637.           source code rather than merges, and then to do a BLED file
  638.           compare against the original version to produce a BLED merge,
  639.           the explanations of changes got stripped and there was no good
  640.           way to add in temporary comments while making changes.  The
  641.           parameter to preserve BLED comment lines remedies these problems.
  642.           It will cause BLED comment lines to be kept as a specially formatted
  643.           source code comment in a merge.  The BLED comment lines will be
  644.           "floated" up to the top of the line number and the BLED comment
  645.           symbol (* by default) will be replaced by the source code comment
  646.           symbol (' by default) followed by "<" with the BLED comment symbol
  647.           followed by ">".  For example, "* Corrects spelling of VARIABLE"
  648.           becomes "'<*> Corrects spelling of VARIABLE".
  649.               Conversely, this parameter will cause source code comments in
  650.           the proper format to be converted to BLED comment lines in a
  651.           file compare that produces a merge.  This allows programmers who
  652.           work directly with the full source to insert temporary comments.
  653.           For example, "'<*> Moved here from line 830" becomes "* Moved here
  654.           from line 830".  By running this BLED generated merge with this
  655.           option off, so that BLED comment lines are stripped, the temporary
  656.           commentary goes deleted.
  657.               The default for this parameter is "N", so that persons desiring
  658.           to preserve BLED comments must edit and save the configuration.
  659.  
  660.           
  661.      FILE COMPARE
  662.  
  663.      The function  of this module is to produce a BLED merge file that will
  664.      convert an old version of a file to a new, modified version.  All that
  665.      is in the merge are the necessary changes.  This is a very complex and
  666.      difficult programming task which is only partially implemented  in the
  667.      current version.   The  file comparison will only work for source with
  668.      line number labels.  Essentially,  the  assumption  is  that  the line
  669.      number labels  are ordered  from low  to high  in both versions of the
  670.      file.  A comparison utility must  have  some  way  to  identify lines.
  671.      Ideally, this  constraint should  be relaxed  to apply to alphanumeric
  672.      labels with no assumptions about order.  Please send me  your ideas or
  673.      code changes  if you  think you  can solve this problem.  So, the ONLY
  674.      TYPE OF MERGE FILE THAT FILE COMPARISON WILL  PRODUCE IS  ONE FOR LINE
  675.      MERGING, and not for general merging.
  676.  
  677.      Operationally, this  means that  if you  are not using line numbers in
  678.      your source code, you should make  your  code  changes  directly  in a
  679.      merge file, and apply the merge file to produce the modified code.  If
  680.      you directly change the old version, there will  be no  way to isolate
  681.      just the changes later.
  682.  
  683.      NOTE: the BLED file compare is NOT A GENERAL FILE COMPARE.  General
  684.      file compares, like the DOS utility, compare two files by relative
  685.      byte position with a file.  BLED does a logical line by logical
  686.      line compare.  Apply the BLED file compare ONLY TO COMPILEABLE SOURCE
  687.      CODE, otherwise the result will be unpredictable.
  688.  
  689.  
  690.      LINE MERGE
  691.  
  692.      This  option  is  a  generalization  of  the BASIC merge command.  The
  693.      assumptions are that
  694.  
  695.      o    the lines of code are numbered at the beginning of a line.
  696.  
  697.      o    Physical lines of text are to be blocked from a line number up to
  698.           the next  line number.  The merge operates only on such blocks as
  699.           a unit.
  700.  
  701.      o    The line numbers are ordered from low to high in  both the source
  702.           and merge file.
  703.  
  704.      o    Lines in  the source  not in the merge file are to be kept, lines
  705.           in the merge not in the source are to be  inserted, and  lines in
  706.           both are  to be  replaced by  the line  (i.e. block) in the merge
  707.           file.
  708.  
  709.      o    Lines in the merge file with only a line number are to be deleted
  710.           from the source file.
  711.  
  712.      o    The merge maintains the low to high line number order.
  713.  
  714.  
  715.      MERGE
  716.  
  717.      The general  merge in  BLED allows  merges even when there are no line
  718.      numbers.  The BLED  commands are  BLOCK, INSERT,  DELETE, REPLACE, and
  719.      KEEP.  Each of these commands can be abbreviated by their first letter
  720.      (e.g "B FROM LINE 1 TO LINE 5" means "BLOCK FROM LINE  1 TO  LINE 5").
  721.      The syntax is
  722.  
  723.      BLOCK [FROM] [linetype] lineid [TO/UPTO/THRU] [linetype] lineid
  724.      [block disposition] [lineid]
  725.  
  726.      where [linetype] is LINE/LABEL/LABEL#/STRING.
  727.  
  728.      The BLOCK  command is  for marking  a block of text in the source file
  729.      (spec-1).  It must specify where the block begins and ends.  The first
  730.      three phrases  after BLOCK  identify the beginning, the last three the
  731.      end.   All phrases  enclosed in  brackets are  optional.   LINE is the
  732.      default linetype if none is specified.
  733.  
  734.      Linetype has four options.
  735.  
  736.      o    LINE means the physical line number, either absolute or relative.
  737.  
  738.      The lineid  distinguishes the two.  Absolute line numbers are positive
  739.      integers, relative line numbers  are  "*+n",  where  n  is  a positive
  740.      integer.
  741.  
  742.      o    LABEL means an alphanumeric label.
  743.  
  744.      o    LABEL# means a numeric line label (a positive integer).
  745.  
  746.      o    STRING means a string of characters.
  747.  
  748.      LABELS must be the first word on a line, STRINGS can occur anywhere in
  749.      a line.
  750.  
  751.      Lineid matches with the  linetype.   LABEL and  STRING require  a word
  752.      with any  characters.   LABEL# requires  a positive integer.  And line
  753.      requires either a positive  integer, or  the string  "*+" to  mean the
  754.      current line  in the  text file  plus" a  positive number, or the word
  755.      "END" to indicate thru the end of file.
  756.  
  757.      The phrase TO and UPTO are  equivalent.    They  mean  up  to  but not
  758.      including.    The  phrase  THRU  means  up  to and include.  TO is the
  759.      default if no phrase is specified.
  760.  
  761.      There are  three block  dispositions: KEEP/DELETE/REPLACE.   They tell
  762.      BLED what  to do  with a  defined block  and therefor  make sense only
  763.      after a BLOCK command.  DELETE deletes the block, KEEP keeps it.
  764.  
  765.           REPLACE [BLOCK/n]
  766.  
  767.      This replaces a defined block with  another.   The "n"  means that the
  768.      next n  physical lines  go in  place of  the defined block.  And BLOCK
  769.      means that all following lines up  to  the  end-block  phrase  are the
  770.      replacements.
  771.  
  772.      Another BLED command is to insert new lines.
  773.  
  774.           INSERT [BLOCK/n]
  775.  
  776.      This means  to insert  a block of lines at the current position in the
  777.      source file, i.e. just  before the  current line  that has  been read.
  778.      The "n"  means to  insert the  following n  physical lines.  The BLOCK
  779.      means to take all following lines up to the end-block phrase.
  780.  
  781.      EXAMPLES
  782.  
  783.         (SOURCE)                           (MERGES)
  784.      CALL INITIALIZE              BLOCK FROM LINE 1 TO STRING OPENFILES
  785.      GOSUB OPENFILES              REPLACE 1
  786.      LOOPER:                      CALL HELP
  787.      IF X=1 THEN GOTO ALLDONE:    BLOCK FROM LINE * THRU LABEL ALLDONE 
  788.      X = X+1                      KEEP
  789.      GOTO LOOPER                  INSERT BLOCK
  790.      ALLDONE:                     CLOSE
  791.      END                          ENDBLOCK
  792.                       (RESULT)
  793.                    CALL HELP
  794.                    GOSUB OPENFILES
  795.                    LOOPER:
  796.                    IF X=1 THEN GOTO ALLDONE:
  797.                    X = X+1
  798.                    GOTO LOOPER
  799.                    ALLDONE:
  800.                    CLOSE
  801.                    END
  802.  
  803.               (SOURCE)                    (LINE MERGE)
  804.      110 IF GOT.COMMAND THEN_     115 NO.HELP = -1
  805.            IF NO.HELP THEN_       150 IF HELPFUL THEN_
  806.              PRINT "SORRY"              WHILE X>5 AND NOT EOF(2):_
  807.      120 GOSUB CHKFILES                   GOSUB CHECKER:_
  808.      150 IF HELPFUL THEN_               WEND
  809.             WHILE X>5:_           200
  810.               GOSUB CHECKER:_     220 END
  811.             WEND
  812.      200 IF X>10 THEN X=12
  813.  
  814.                          (RESULT)
  815.                   100 IF GOT.COMMAND THEN_
  816.                         IF NO.HELP THEN_
  817.                           PRINT "SORRY"
  818.                   115 NO.HELP = -1
  819.                   120 GOSUB CHKFILES
  820.                   150 IF HELPFUL THEN_
  821.                         WHILE X>5 AND NOT EOF(2):_
  822.                           GOSUB CHECKER:_
  823.                         WEND
  824.                   220 END
  825.  
  826.  
  827.      Stylistic Considerations
  828.  
  829.      A good merge file includes the following information at the top of the
  830.      file.
  831.  
  832.      o    author
  833.  
  834.      o    date of merge
  835.  
  836.      o    what merge is to be applied to
  837.  
  838.      o    how to apply the merge (line number merge, general merge?)
  839.  
  840.      o    a list of the general fixes or enhancements made, listed in order
  841.           of most to least important coupled.
  842.  
  843.      In the body of the merge the following documentation should be
  844.      included.
  845.  
  846.      o    a line by line explanation of the changes made stating what is
  847.           changed and why.  The explanation should precede the line.
  848.  
  849.      o    lines should be grouped together if they implement a common
  850.           function.
  851.  
  852.                           A Model Merge File
  853.  
  854.      ***************************************************************** 
  855.      *  EXAMPLE.MRG                                                  * 
  856.      *  by Ken Goosens   Jan 1, 1986                                 * 
  857.      *                                                               * 
  858.      *  to be applied to BLED.BAS version 1.1                        * 
  859.      *  using the general merge of BLED.EXE                          * 
  860.      *                                                               * 
  861.      *  This merge makes two changes:                                * 
  862.      *     (1) the defaults when no configuration exists are changed * 
  863.      *         to be appropriate for TURBO Pascal rather than        * 
  864.      *         QuickBASIC.                                           * 
  865.      *     (2) The warning message when no configuration file exists * 
  866.      *         is changed to beep and delay for 3 seconds rather     * 
  867.      *         than quietly and hurriedly display.                   * 
  868.      ***************************************************************** 
  869.       
  870.      * reset extensions for original and new files to "PAS" 
  871.       
  872.         BLOCK FROM LABEL USEDEFAULTS TO STRING ENDBLK 
  873.         REPLACE BLOCK 
  874.         USEDEFAULTS:      
  875.           DEORIGFILE$ = "PAS"  
  876.           DEBTCHCMDS$ = "MRG"  
  877.           DENEWFILE$  = "PAS"  
  878.         ENDBLOCK 
  879.       
  880.      * Change call from EXPLAIN to EXPERR 
  881.       
  882.      BLOCK FROM LABEL ERROPEN THRU STRING CALL 
  883.      REPLACE BLOCK 
  884.      ERROPEN:  
  885.         X$ = "Error"+STR$(ERR)+" opening file "+FF$  
  886.         CALL EXPERR (X$)  
  887.      ENDBLOCK 
  888.  
  889.  
  890.      How to Recompile BLED
  891.  
  892.      BLED is written in QuickBasic 4.0 and is distributed with the source
  893.      code.  People wishing to modify or fix the source code can recompile
  894.      the code as follows.
  895.  
  896.      BC BLED ,,/O/X;
  897.      LINK BLED,,NUL.MAP,advbas
  898.