**********************************************************************
*                      VAN NUYS BRIDGE TOOLKIT                       *
**********************************************************************
*                  COPYRIGHT 1983 EUGENE H. MALLORY                  *
**********************************************************************
    
    The Van Nuys Bridge Toolkit is a collection of text processing 
    tools, operating on CP/M 2.2, which are similar to the type of 
    tools generally provided in UNIX.  They can be used to shape or 
    change text for a great number of purposes. 
    
    Most of the tools have two inputs and an output.  One input is 
    the command line itself.  That generally provides any options or 
    arguments as well as providing specifications for the standard 
    input and standard output stream.  Without any specification for 
    the standard I/O, input is from the console and output is to the 
    console. Input from the console uses a "*" prompt.
    
    Input may be redirected by specifying a file name with the format:
    
    A>TOOL <filename
    
    The default output is to the console screen.  Output may be 
    redirected to a file, to a printer or to both the screen and a 
    file.  

    Redirection can take the following forms:
	
	    > fid	Output redirection to file
	    < fid	Input rediredtion from file
	    + fid	Output redirection to file and screen
	    ~ fid	Output redirection to file and printer
	    >> fid	Append to file
	    +> fid	Append to file and output to screen
	    ~> fid	Append to file and output to printer
	    > LST:	Output to LST device
	    >> LST:	As above
	    + LST:	Output to LST device and screen
	    > LP1:	Output to LP1 (IOBYTE = 0x80)
	    >> LP1:	As above
	    + LP1:	As above and to screen
	    > LP2:	Output to LP2 (IOBYTE = 0xC0)
	    >> LP2:	As above
	    + LP2:	As above and to screen
	    > OUT:	Output to PUNCH DEVICE
	    >> OUT:	As above
	    + OUT:	As above and to screen
	    ~ OUT:	As above and to printer
	    < IN:	Input from READER device
	    
	    | prog	Pipe output to next program
	    +| prog	As above and to screen
	    ~| prog	As above and to printer
	
    Redirection and pipe character may be separated from
    the file or program name by white space or not.
	
    File specifications may be complete with user number (##) and 
    disk name (d) in the form:
	
			##/d:name
	
    Pipe specification will be first tried as is, if the file 
    does not exist, disk A, user 0 will be tried using the same 
    name.
	
    Control C will abort program and submit file execution.
    When inputing from keyboard use Control C except at    
    column 1. (CP/M catches it there.)  If an old version of
    the output file existed, it will be recovered by Control C.
	
    It is permissable to input and output from the same file,  
    BUT the input specification must be first and the output
    specification must be second!  otherwise the order and 
    location of the redirection specifications is not
    significant.
	
    A number of the tools use ambiguous file names or wildcards to 
    identify a list of file names.  The format is the same for all 
    tools.  The ambiguous file name characters are a superset of 
    those used by CP/M DIR.  * means any number of any character, ? 
    means exactly one of any character.  Unlike DIR, a list of 
    ambiguous file names may be used.  Also, if an ambiguous file 
    name is preceded by a !, files matching that specification will 
    be EXCLUDED from the list.  See LS to get more information.
    
    These tools have some limitations.  They are able to only handle 
    normal CP/M text files.  Files must have these characteristics:
    
    1)  They must not be null or totally empty.
    
    2)  They must have a CR LF pair at the end of each line
        including the last line.
    
    3)  Lines more than 132 characters will cause the programs
        to blow up.
    
    4)  Both kinds of CP/M eof conditions are handled well.
    
    5)  Some of the tools will behave badly if they get text
        with CR's, backspaces and other control characters
        in the text.  This is noted in the individual HELP files.
    
    6)  The output file must be on the current logged on disk.
        Specification of another disk will be ignored and
        the output will end up on the current disk anyway.
        (Final output file is created by REN of a temp file.)
    
    7)  Input files and tools may be on other disks.  Tools
        are searched for on the current disk first, and on 
        disk A: second if no specification is made.  It is
        handy to put the tools all on disk A: and work on 
        another disk. 

    CLEAN may be able to clean up many files with these problems.
    
    Error messages are prefixed by the tool name which generates the
    message.  An exception is when an error is made in the input or
    output redirection or in the pipe specification.  In these cases,
    the message is prefixed with the name DIO: for Directed IO.
    
    Note that where tools have "-" options such as -U, the options 
    may be run together so that 2UP -N4M10S2 is the same as -N4 -M10 
    -S2.  The redirection specification and "-" options may be in any 
    order on the command line.  They are processed and removed before 
    the parameters, if any, are passed to the tool.  Thus SUB <A ABC 
    DEF >B  is the same as SUB >B <A ABC DEF. Also, any tools that 
    have options, have the option -H. By saying TOOL -H, you will 
    get, on the console, a summary of all the legal options.
    
    You cannot specify as the standard output a file on another disk. 
     This is because a temp file is created on the current disk first 
    and then renamed correctly at the end.  This does allow both 
    standard input and standard output to be the same file name. If 
    you use a +file to specify the standard output, you can abort the 
    process if you see that the results are not as expected (easy to 
    happen when using many metacharacters with SUB or SELECT).  A CTL 
    C will kill the process without wiping out file.  Operations such 
    as CLEAN <FILE >FILE  or SUB <FILE ABC DEF +FILE are ok and 
    useful.
    
    The full power of these tools is shown when they are used within 
    .SUB files with SUBMIT.  Once a sequence is worked out to to a 
    particular task, it can be canned and put to general use by 
    creating a .SUB file.
    
    The tools are partcularly useful in creating a .SUB file 
    containing a string of commands to operate on a list of files. LS 
    can create a list of file names, and SUB can transform them into 
    a series of commands for each file in the list.  There is  an 
    example in the page on SUB.