Programmer 7500/MAX_PROGRAMMERS.iso/CLIPPER/MISC/SRC14.ZIP/SOURCE.DOC

Text File | 1993-04-22 | 127.9 KB | 2,809 lines

                                   SOURCE


                                Version 1.4

                               April 22, 1993


                                 Written by

                                 Rick Maddy

                          SOURCE Table of Contents

     1    Distribution . . . . . . . . . . . . . . . . . . . . . .   1

     2    What is SOURCE?  . . . . . . . . . . . . . . . . . . . .   1

     3    Quick Start  . . . . . . . . . . . . . . . . . . . . . .   2

     4    The SOURCE Command Line  . . . . . . . . . . . . . . . .   3
          4.1  Global Options  . . . . . . . . . . . . . . . . . .   3
          4.2  Filenames . . . . . . . . . . . . . . . . . . . . .   4
          4.3  Local Options . . . . . . . . . . . . . . . . . . .   5
          4.4  Full Command Line . . . . . . . . . . . . . . . . .   6

     5    SOURCE Options . . . . . . . . . . . . . . . . . . . . .   6

     6    SOURCE.CFG . . . . . . . . . . . . . . . . . . . . . . .  21
          6.1  SOURCE.CFG Location . . . . . . . . . . . . . . . .  21
          6.2  Named Configuration Options . . . . . . . . . . . .  22
          6.3  SOURCE.CFG Format . . . . . . . . . . . . . . . . .  23
          6.4  Commenting SOURCE.CFG . . . . . . . . . . . . . . .  23
          6.5  Modifying SOURCE.CFG  . . . . . . . . . . . . . . .  24

     7    SOURCE.PRT . . . . . . . . . . . . . . . . . . . . . . .  24
          7.1  Default Printer . . . . . . . . . . . . . . . . . .  24
          7.2  SOURCE.PRT Format . . . . . . . . . . . . . . . . .  24
          7.3  Modifying Your Printer  . . . . . . . . . . . . . .  29

     8    SOURCE.LNG . . . . . . . . . . . . . . . . . . . . . . .  29
          8.1  SOURCE.LNG Location . . . . . . . . . . . . . . . .  29
          8.2  SOURCE.LNG Format . . . . . . . . . . . . . . . . .  30
          8.3  Commenting SOURCE.LNG . . . . . . . . . . . . . . .  30
          8.4  Defining Language Specific Features . . . . . . . .  31
               8.4.1     Comments  . . . . . . . . . . . . . . . .  31
               8.4.2     String and Character Literals . . . . . .  32
               8.4.3     Blocks  . . . . . . . . . . . . . . . . .  33
               8.4.4     Keywords  . . . . . . . . . . . . . . . .  34
               8.4.5     Include Files . . . . . . . . . . . . . .  35
               8.4.6     Page Feeds  . . . . . . . . . . . . . . .  36
               8.4.7     Complete Definition . . . . . . . . . . .  37
          8.5  General Points  . . . . . . . . . . . . . . . . . .  38

     9    Network Support  . . . . . . . . . . . . . . . . . . . .  39

     10   Definition of Shareware  . . . . . . . . . . . . . . . .  40

     11   Disclaimer - Agreement For Using SOURCE  . . . . . . . .  40

     12   Registering  . . . . . . . . . . . . . . . . . . . . . .  41

     13   Future Enhancements  . . . . . . . . . . . . . . . . . .  41

     14   Acknowledgements . . . . . . . . . . . . . . . . . . . .  41

     15   Release History  . . . . . . . . . . . . . . . . . . . .  42

     SOURCE REGISTRATION . . . . . . . . . . . . . . . . . . . . .  46

                                     i
                                   SOURCE

     SOURCE Version 1.4 - Source Code Printing Program
     Copyright 1992, 1993 Rick Maddy

     1    Distribution

     The SOURCE program is made up of these files:

          SOURCE.EXE     The SOURCE program file.
          SOURCE.DOC     This documentation file.
          SOURCE.PRT     The default printer definition file.
          SOURCE.CFG     The default configuration option file.
          SOURCE.LNG     The default language definition file.
          README.1ST     Quick summary and last minute notes.
          REGISTER.TXT   Order form to register SOURCE.

     This unregistered shareware program is distributed in a self-
     extracting compressed file.  SRCV14.EXE may be passed onto as
     many people as you like, provided it remains intact, ALL files
     are kept together, and only the original files are distributed.
     DO NOT compress and pass on your modified files.  See section 10
     below for further information on shareware.

     2    What is SOURCE?

     SOURCE, in its most basic form, is a program for printing source
     code and text files.  However, using SOURCE to its fullest
     potential gives you an extremely powerful and flexible program
     for printing source code and allows for numerous options for
     formatting the output:

          - Custom page sizing
          - Adjustable margins
          - Page orientation (portrait or landscape)
          - Character pitch (pica, elite, or compressed)
          - Number of columns per page
          - User definable page header/footers
          - Optional banner page before/after files
          - Output may be redirected to any device or file
          - Printing ranges may be specified, including starting
            and/or ending line or page numbers
          - Multiple files can be queued for printing
          - List files may used to specify a number of files to print
          - Manual duplex printing
          - Verification and stats on each file prior to printing

     In addition to these basic printing options, SOURCE contains many
     options specifically geared toward formatting source code (such
     as C, Pascal, Fortran, dBase, or whatever you code in).  These
     include:

          - User definable line and page numbering
          - Comments in the source code may be printed as bold,
            italic, or underlined
          - Keywords may be highlighted
          - Code blocks grouped graphically

                                     1
                                   SOURCE

          - Adjustable tab sizes for printing
          - Automatic printing of include files
          - Configurable language support

     These are just some of the powerful options available to you.
     Virtually nothing about SOURCE is hard coded.  If you do not like
     the way something is printed, you can change to your tastes and
     need.  Yet, SOURCE is very easy to use.  SOURCE only needs to
     know the name of the file(s) you wish to print and it does the
     rest.  You can use SOURCE right out of the box (so to speak).

     For example:

     C:\> SOURCE kludge.c

     This would print your file to the default printer using the built
     in defaults.

     You may configure each option to suit your needs.  See section 5
     for a complete list of all the options.  Besides the printing
     options, SOURCE is extremely flexible in its ability to work with
     almost any printer and most programming languages.

     To facilitate this dynamic environment, SOURCE consists of an
     executable (SOURCE.EXE) and three support files:

          SOURCE.PRT:    Contains all the printer definitions.
          SOURCE.CFG:    Contains all the default options used by
                         SOURCE to print your files.
          SOURCE.LNG:    Contains all the language and filename
                         extension specifications needed for comment
                         and keyword highlighting and block grouping.

     By default, all four files that make up SOURCE are named
     "SOURCE.???" where '???' is "EXE", "PRT", "CFG", and "LNG".  If
     you prefer to use a different name, such as "SRC", instead of
     "SOURCE", simply rename all four files to the same prefix.
     Example:

          C:\>ren source.* src.*

     This will result in all four files having the "SRC.???" name
     instead of "SOURCE.???".  Anywhere in this documentation you are
     to execute "SOURCE", enter "SRC" instead.  The only advantage to
     this is to save on typing "SOURCE" all the time, now you enter
     "SRC".  You could even change all the names to "S" if you really
     like terse, UNIX-like command names.

     3    Quick Start

     Before running SOURCE for the first time (as if you have read
     this far without having already done so), make sure you have
     placed SOURCE.EXE, SOURCE.PRT, SOURCE.LNG, and SOURCE.CFG all
     within the same directory.  You may also wish to include this
     directory in your path so that you can run SOURCE from anywhere

                                     2
                                   SOURCE

     on your system.  If you need more information on PATHs, see your
     DOS manual.

     The simplest way of running SOURCE is to type:

          SOURCE filename.ext

     "SOURCE" is the program SOURCE and "filename.ext" is the name of
     the file you are going to print.  You may press the [Esc] key
     anytime while a file is printing to abort SOURCE and stop the
     current file from printing.  Remember, most printers have buffers
     and the printing will probably not stop immediately.

     The first time you run SOURCE you will be asked to select your
     default printer.  This printer should be the one connected to
     printer port one, "LPT1:".  If you are using a different port,
     see section 6.5 for information on changing the printer port used
     by SOURCE.  The list of printers initially supported by SOURCE
     contains printers which should cover most of the printers in use.
     Pick the printer that closest matches the one you have.

          Note:  If none of the printers are like yours, select
          the "Generic" printer for now.  You will still be able
          to print files, you just won't be able to take full
          advantage of SOURCE's strengths.  Later on you'll see
          how to modify SOURCE.PRT to take full advantage of your
          printer.  See section 7 for more information on printer
          definitions.

     Typing "SOURCE" at the prompt with no options will give you a few
     lines about the general command line syntax.  You may type
     "SOURCE -?" to see a few screens showing the command line syntax,
     what each option is, and the options' current defaults.  After
     the options, you will be shown what printers, languages, and
     named configuration options are defined in the SOURCE.PRT,
     SOURCE.LNG, and SOURCE.CFG files.

     4    The SOURCE Command Line

     SOURCE is a command line program.  To run SOURCE, type the name
     of this program, SOURCE, followed by any options you wish to use
     along with the filename(s) of the file(s) you wish to print.  The
     command line syntax is as follows:

     SOURCE [-global options] filename.ext [-local options] . . .

     Objects in square brackets are optional and the ". . ." means you
     may repeat as many filenames as you wish to have printed.

     The command line has two levels of options, global and local.
     Global options are configuration options that apply to all files
     on the command line.  Local options only apply to the files that
     immediately precede them.

     4.1  Global Options

                                     3
                                   SOURCE

     Global options appear after the program name and before the first
     filename.  These options apply to all the files specified on the
     command line.  Global parameters are optional.  The syntax of
     global options is a hyphen ( - ) followed by a one letter option
     followed by any required parameters.  Options that take
     parameters require that there be no space between the option and
     the parameter.  String parameters are slightly different.  A
     space before the parameter is allowed.  String parameters may
     also be enclosed in double quotes.  The quotes are required only
     if the string contains spaces.  An example is:

          SOURCE -n -N4 -r com1

     The above example only contains global options (in this case,
     four digit line numbers with output redirected to comm port one).
     This example will not actually produce any output because no
     files are specified yet.

     Options that you use frequently can be permanently preset within
     the SOURCE.CFG file.  This way, you do not have to specify them
     each time you use SOURCE.  See section 6 for a discussion on
     setting global options as defaults.

     4.2  Filenames

     After the global parameters, if any, you may specify the files
     you wish to print.  In the simplest form, this would be a single
     filename and its extension.

          SOURCE foobar.c

     Running this would cause SOURCE to print the file "foobar.c" from
     the current directory.  To specify a file in another directory or
     on another disk drive, use the full path name, as in the example
     below:

          SOURCE c:\src\code.pas

     This would print the file "code.pas" found in the "c:\src"
     directory despite your current working directory.

     There are four methods for printing multiple files.  The most
     tiresome is to run SOURCE once for each file you need to print.

     The second option is to use wildcards when specifying the
     filename.  The wildcards allowed are '*' and '?'.  These behave
     exactly like the wildcards used by DOS commands (such as copy and
     delete).  If you do not understand how wildcards work, please
     refer to your DOS manual for more information.  An example of
     wildcard use is:

          SOURCE *.c




                                     4
                                   SOURCE

     This would cause SOURCE to print all files in the current
     directory that had the extension ".c".  Each file will be printed
     separately, starting on page one, line one.

     The third method for printing multiple files is to enter more
     than one name on the command line:

          SOURCE program.c data.txt

     This would cause SOURCE to print the two files, "program.c" and
     "data.txt", from the current directory.  You may specify as many
     files as the command line has room for.

     The final method makes use of what is known as a list file.  A
     list file is simply a text file that contains a list of files,
     one per line.  Each line may specify one pathname.  This pathname
     may be just a filename (with or without wildcards), or a filename
     with a complete path.  A sample list file would look as follows:

          c:\src\file.c
          src.*
          myfile.txt

     This list file contains three entries.  The first line specifies
     to print the file named "file.c" located in the "c:src"
     directory.  The second line specifies to print all files which
     have the name "src" with any extension located in the current
     directory.  The last line specifies to print the file named
     "myfile.txt" located in the current directory.  To specify a list
     file in the command line, enter it as if it were the file to be
     printed but precede the name with the '@' sign.  Assuming the
     earlier list of three items was placed in a file called
     "mylist.txt" in the current directory, the command line would
     look as follows:

          SOURCE @mylist.txt

     The name of the list file can include a pathname if needed but it
     may not contain any wildcards ('?' or '*').

     Any combination of these four methods may be used, for example:

          SOURCE *.c b:*.txt @files.lst c:\proj\*.*

     This command line would print all 'C' files in the current
     directory, all files with the extension ".txt" from the disk in
     the B drive, all files listed in the "files.lst" list file, and
     all files from the "proj" directory of the C drive.

     4.3  Local Options

     In addition to the global options, you may specify "local"
     options after each filename.  These local options override the
     global options and only apply to the file they immediately follow
     on the command line.  If they follow a list file, the local

                                     5
                                   SOURCE

     options apply to all files specified by the list file.  Local
     options are optional.  The syntax for local options is identical
     to that of global options (see section 4.1).  Example:

          SOURCE -n hello.c goodbye.c -n-

     This command will cause SOURCE to print the file "hello.c" from
     the current directory with line numbers and "goodbye.c" without
     line numbers.  The global option "-n" causes line numbering to be
     turned on for all files.  Specifying "-n-" after "goodbye.c"
     tells SOURCE to turn line numbering off only for "goodbye.c" and
     does not affect "hello.c".  Local options used after filenames
     with wildcards will apply to all the files matched by the
     wildcards:

          SOURCE *.c -b -cb

     will print all 'C' files with block tracing and comments
     highlighted in bold print for each file.  This also shows that
     you may specify more than one local option per file.  Of course,
     you do not have to specify any local options if they are not
     needed.

     4.4  Full Command Line

     The command line for SOURCE is very flexible.  This flexibility
     can also lead to some pretty long and complicated command lines.
     There are many ways to remedy this.  See section 6 for ways to
     minimize the command line options.  The most complex command line
     would be as follows:

          SOURCE -n -N4 file.pas -cb -b *.c -h2 *.dat -n-

     This line contains global options and three file specifications
     each giving their own local options.  You will not normally have
     such lines, but the power is there to use.

     5    SOURCE Options

     What follows is an alphabetized list of all the command line
     options that SOURCE recognizes.  These options may be specified
     as global or local options on the command line (unless indicated
     otherwise).  They may also appear in the SOURCE.CFG file to
     define default options for those options you wish to have in
     effect each time you run SOURCE.  See section 6 for more on the
     SOURCE.CFG file.  All options are case sensitive so do not run
     SOURCE with your caps lock on.

     Conventions used below:

          [x]       Square brackets indicate optional items.  There
                    may not be a space between the option and the
                    parameter if specified.  Example:

                    n[-] may entered as n or n-.

                                     6
                                   SOURCE

          {x|y}     Curly braces containing a list of choices
                    separated with a vertical bar indicate that you
                    must select one of the options available for that
                    item.  There may not be a space between the option
                    and the chosen parameter.  Example:

                    a{a|o|r} allows aa, ao, or ar.

          "text"    Quotes indicate that you must enter a text string.
                    You do not have to type the double quotes unless
                    the string contains spaces.  There may be a space
                    between the option and the string.  Example:

                    z "list" allows:
                         z.exe.obj      <== No spaces
                         z".exe.obj"    <== Quotes optional, no spaces
                         z".exe .obj"   <== Quotes required, spaces
                         z .exe.obj
                         z ".exe.obj"
                         z ".exe .obj"

                    Not allowed would be:

                         z .exe .obj

                    because the parameter contains a space and must be
                    enclosed in quotes.

          #         A pound symbol indicates that you must enter a
                    number after the option.  Numbers may be made up
                    of the 10 numeric digits and minus for negative
                    numbers.  There may not be a space between the
                    option and the number.  Example:

                    w# allows w1, w2, w3, etc.
                    h# allows h-1, h2, h0, etc.


     Option         Description

     -?             Help.  The '?' option displays a quick command
                    summary showing all the available options and
                    their current defaults.  Running SOURCE with no
                    options simply shows the command line syntax and
                    the '-?' option.

     -$             Shareware Message.  The '$' option causes a full
                    screen message to display about registering
                    SOURCE.  This command is only recognized if in
                    SOURCE.CFG or as a global command line option.

     -a{a|o|r}      Append/Overwrite.  The 'a' option describes the
                    action SOURCE will take when redirecting the
                    output to a file and the file already exists.  See
                    the 'r' option for more on redirecting the output.

                                     7
                                   SOURCE

                    When the 'a' option is followed by an 'a', SOURCE
                    will automatically append the new output to the
                    previous contents of the file.  When followed by
                    an 'o', SOURCE will automatically overwrite the
                    old contents of the file and leave only the new
                    output.  When followed by an 'r', SOURCE will
                    interactively prompt you for the action to take.
                    You may specify 'append', 'overwrite', enter a
                    different file, or quit SOURCE.  Default is 'ar',
                    request.

     -b[-]          Block Grouping.  The 'b' option sets whether block
                    grouping is turned on or not.  The 'b' may be
                    followed by '-'.  The 'b' option alone turns on
                    block grouping, the minus turns it off.  For this
                    option to work, SOURCE must know what language the
                    file is written in.  This is done by using the
                    filename extension as defined in the SOURCE.LNG
                    file or the 'x' option may be used to force a
                    specific language.  The lines used for block
                    grouping may be drawn using either standard ASCII
                    characters or the IBM line drawing characters.
                    See the 'g' option to set how the lines are drawn.
                    Default is 'b', block grouping on.

                    Below is some sample C code with block grouping
                    turned on:

                         while (x < 10)
                              ┌{
                              │if (a < b)
                              │    ┌{
                              │    │puts("Hello");
                              │    └}
                              │else
                              │    ┌{
                              │    │puts("Goodbye");
                              │    └}
                              │x++;
                              └}

                    The above also assumes the 'g' option is on.  With
                    the 'g' option off, the same code looks as
                    follows:

                         while (x < 10)
                              +{
                              |if (a < b)
                              |    +{
                              |    |puts("Hello");
                              |    +}
                              |else
                              |    +{
                              |    |puts("Goodbye");
                              |    +}

                                     8
                                   SOURCE

                              |x++;
                              +}

     -B[*]#         Banner.  The 'B' option allows you to print a
                    banner before and/or after each file.  The banner
                    contains the filename and extension in BIG
                    letters.  The 'B' must be followed by a number
                    from 0 to 3.  0 means no banner at all.  1 means a
                    banner only before the file.  2 means a banner
                    only after the file.  3 means a banner before and
                    after the file.  You may also specify an optional
                    asterisk ('*') before the number.  This will cause
                    the letters of the banner to be made up of
                    asterisks instead of the default individual
                    letter.  Default is 'B3', print banner before and
                    after using letters.

     -c{b|u|i|o|n}  Comment Highlighting.  The 'c' option sets whether
                    comments within your programming code are
                    highlighted or not.  The 'c' may be followed by
                    'b'old, 'u'nderline, 'i'talic, 'o'ther, or 'n'one.
                    For this option to work, SOURCE must know what
                    language the file is written in.  This is done by
                    using the filename extension as defined in the
                    SOURCE.LNG file or the 'x' option may be used to
                    force a specific language.  The highlighting
                    method used is as defined in the SOURCE.PRT file
                    for the selected type.  Default is 'cb',
                    highlighted comments in bold.

     -d "printer"   Select Printer.  The 'd' option specifies which
                    printer definition in the SOURCE.PRT file SOURCE
                    should use when printing out files.  The 'd' must
                    be followed by the printer name.  The name
                    specified is not case sensitive.  If you only have
                    one printer connected to your computer you will
                    not need to use this option.

                    If you have multiple printers connected to
                    different ports, you can specify this option at
                    the command line when you are using a printer
                    other than the default.  If this is the case, you
                    will also need to use the 'r' option to specify
                    the port the printer is connected to.  If you use
                    different printers often, you may wish to define a
                    named configuration in the SOURCE.CFG file for
                    each printer.  Then all you need to specify on the
                    command line is the 'u' option.  See the 'u'
                    option for more details on using named
                    configurations.  The default printer is selected
                    by the user the first time SOURCE is run or by
                    modifying the SOURCE.PRT file.  See section 7 for
                    more on SOURCE.PRT.



                                     9
                                   SOURCE

     -e[-]          Escape Codes.  The 'e' option sets whether printer
                    escape codes are output along with your text or
                    not.  Normally you would want this left on so your
                    printer will print the file properly.  Turning
                    this option off would typically be used when
                    redirecting output to a file when you would not
                    want the escape codes embedded in the target file.
                    The 'e' may be followed by '-'.  The 'e' option
                    alone causes the codes to be printed, the minus
                    prevents the codes.  Default is 'e', codes
                    printed.

     -E{t|b|l|r}#   Page Margins.  The 'E' option is used to set the
                    page margins to specified values.  The 'E' must be
                    followed by a 't', 'b', 'l', or an 'r'.  These
                    represent the top, bottom, left, and right margins
                    respectively.  The letter must then be followed by
                    a positive number in inches for the margin.  An
                    example would be 'El1.5', this would set the left
                    margin to 1.5 inches.  A value of zero means the
                    margin specified in the selected printer
                    definition will be used.  More than one margin may
                    be set by stringing the options together.  To set
                    both the top and bottom margin, specify 'Et.75b1'.
                    This would cause a 3/4 inch top margin and a one
                    inch bottom margin.  Just like in the printer
                    definition, the margin value must be equal to or
                    greater than the corresponding edge value from the
                    selected printer definition.  If the specified
                    margin is too big or too small, the default margin
                    from the printer definition will be used instead.
                    Default is 'Et0b0l0r0', use all the printer
                    definition defaults.

     -f#            Final Line.  The 'f' option allows you to specify
                    the last physical line number of the file to print
                    out.  This would be used to print only a desired
                    block of code instead of having to print the
                    entire file.  The 'f' must be followed by a
                    positive number.  Specifying zero means the last
                    physical line.  This option may not be used with
                    the 'F' or 'I' options unless set to zero.
                    Default is 'f0', print through last line.

     -F#            Final Page.  The 'F' option allows you to specify
                    the number of the last physical page of the file
                    to print out.  This would be used to print only a
                    block of code, or part of a page range, instead of
                    printing out the entire file.  The 'F' must be
                    followed by a positive number.  Specifying zero
                    means the last physical page.  This option may not
                    be used with the 'f' or 'i' options unless set to
                    zero.  Default is 'F0', print through last page.



                                     10
                                   SOURCE

     -g[-]          Graphics.  The 'g' option determines how the block
                    group lines are printed (see option 'b' for more
                    on block grouping).  When the option is on, the
                    lines will be printed using the IBM line drawing
                    characters.  With the option off, simple ASCII
                    characters will be used.  If your printer cannot
                    print the extended IBM character set then turn
                    this off.  If your printer can print the lines
                    then set this to on.  You may need to send a
                    special code to your printer to select the IBM
                    extended character set.  To do so, place the
                    proper printer codes in the 'Init' record in the
                    SOURCE.PRT file for your printer.  Default is
                    'g-', print using standard ASCII.

     -h#            Header Page.  The 'h' option is used to specify
                    when to print the page header or footer.  The 'h'
                    must be followed by a number.  Zero means no
                    header or footer will be printed.  A one means to
                    print the header only on the first page.  Any
                    value of two or more will result in the header
                    being printed on all pages.  To cause the header
                    to be printed at the bottom of the page (now a
                    footer), specify a negative number.  Negative one
                    means to print a footer only on the first page.
                    Any number of -2 or less (-100 etc.) will cause
                    the footer to be placed on all pages.  Page
                    headers and footers are underlined and printed in
                    10 pitch regardless of the pitch selected for the
                    rest of the file.  The contents of the header are
                    defined by using the 'H' option.  Default is 'h2',
                    header on all pages.

     -H "header"    Header Definition.  The 'H' option is used to
                    define the contents of the header or footer.  See
                    the 'h' option to specify when to print the
                    header/footer.  The definition consists of literal
                    text and escape codes.  Since the definition will
                    likely contain literal spaces, remember to enclose
                    the definition within double quotes.  The escape
                    commands are case sensitive and literal text will
                    be shown as entered.  The escape sequences are
                    described here:

                    &fn       Current filename and extension.  The
                              filename is shown in uppercase.  No path
                              is displayed.
                    &fd#c     File creation date in specified format
                              where # is 1 to 5 and c is the delimiter
                              character ('/', ',', or '.').
                    &ft#c     File creation time in specified format
                              where # is 1 to 4 and c is the delimiter
                              character (':', ',', or '.').



                                     11
                                   SOURCE

                    &cd#c     Current date in specified format where #
                              is 1 to 5 and c is the delimiter
                              character ('/', ',', or '.').
                    &ct#c     Current time in specified format where #
                              is 1 to 4 and c is the delimiter
                              character (':', ',', or '.').
                    &pn#      Current page number in specified format
                              where # is the number of digits the page
                              number will take up.  The value must be
                              in the range 1 to 9.  The page number
                              will be left padded with spaces.  If you
                              prefer zeros instead, precede the number
                              with a zero.  Example:  &pn03.
                    &pctext#  Page count in specified format where
                              text is literal text to be printed
                              before the number (including spaces) and
                              # is the number of digits the page count
                              will take up.  The value must be in the
                              range 1 to 9.  The page count will be
                              left padded with spaces.  If you prefer
                              zeros instead, precede the number with a
                              zero.  Example:  &pc of 03.  This will
                              print " of 99" where 99 is the actual
                              page count.  The page count and the
                              specified text only appear if the 'q'
                              option was used to determine the total
                              number of pages.  If the 'q' option was
                              not used, the page count and its text
                              will not appear at all in the header.
                              When used with the 'I' or 'J' options
                              with values other than one, the page
                              number and page count will seem strange.
                    &li       Initial line number on page.
                    &lf       Final line number on page.
                    &h+       Turn on highlighting (using bold).
                    &h-       Turn off highlighting (using bold).
                    &jl       Left justify text.
                    &jc       Center justify text.
                    &jr       Right justify text.
                    &&        Prints a literal ampersand character.

                    Date formats:
                    1)   mm dd yy       ex.  &fd1/     07/31/92
                    2)   dd mm yy       ex.  &cd2.     31.07.92
                    3)   yy mm dd       ex.  &cd3,     92,07,31
                    4)   dd Mmm yy      ex.  &fd4-     31-Jul-92
                    5)   Month dd  yyyy ex.  &cd5,     July 31, 1992

                    Time formats:
                    1)   hh mm ss       ex.  &ct1:     15:45:21
                    2)   hh mm          ex.  &ft2.     15.45
                    3)   hh mm ss am    ex.  &ft3,     03,45,21 pm
                    4)   hh mm am       ex.  &cd4:     03:45 pm

                    Example header definition:

                                     12
                                   SOURCE

                    '&h+File:&h-  &fn&jr&h+Page:&h-  &pn03'

                    This definition results in the following text:

                    File:  filename.ext                     Page:  001

                    where the text 'File:' and 'Page:' are
                    highlighted, 'filename.ext' is the actual filename
                    of the file, and the page number is right
                    justified on the page.  Default is "File:  ",
                    filename, file date, file time, "Printed:  ",
                    date, time, "Page:  ", page number.

     -i#            Initial Line.  The 'i' option allows you to
                    specify the first physical line number of the file
                    to output.  This would be used to print only a
                    block of code instead of the whole file.  The 'i'
                    must be followed by a positive number.  Specifying
                    zero means the first physical line.  It is likely
                    that 'i' would be used in conjunction with the 'f'
                    option to print a specific range of text starting
                    and finishing at the line numbers chosen.  This
                    option may not be used with the 'F' or 'I' options
                    unless set to zero.  Default is 'i0', the first
                    line.

     -I#            Initial Page.  The 'I' option allows you to
                    specify the first physical page number of the file
                    to output.  This would be used to print only a
                    block of code instead of the whole file.  The 'I'
                    must be followed by a positive number.  Specifying
                    zero means the first physical page.  It is likely
                    that 'I' would be used in conjunction with the 'F'
                    option to print a specific range of text starting
                    and finishing at the page numbers chosen.  This
                    option may not be used with the 'f' or 'i' options
                    unless set to zero.  Default is 'I0', the first
                    page.

     -j#            Beginning Line.  The 'j' option allows you to
                    begin line numbering at a number other than the
                    actual line number.  For example, if you specify
                    'SOURCE -j35 file.ext', SOURCE will print the
                    file's line numbers starting at 35 instead of 1.
                    This may also be used in conjunction with the 'i'
                    or 'I' options.  'SOURCE -i100 -j23 file.txt' will
                    cause SOURCE to print physical lines 100 to the
                    end of file.txt but will show them as line 23 and
                    up.  Default is 'j0', use actual line numbers.

     -J#            Beginning Page.  The 'J' option allows you to
                    begin page numbering at a number other than the
                    actual page number.  For example, if you specify
                    'SOURCE -J6 file.ext', SOURCE will print the
                    file's page numbers starting at 6 instead of 1.

                                     13
                                   SOURCE

                    This may also be used in conjunction with the 'i'
                    or 'I' option.  'SOURCE -I10 -J2 file.txt' will
                    cause SOURCE to print physical pages 10 to the end
                    of file.txt but will show them as page 2 and up.
                    Default is 'J0', use actual page numbers.

     -k{b|u|i|o|n}  Keyword Highlighting.  The 'k' option sets whether
                    keywords within your programming code are
                    highlighted or not.  The 'k' may be followed by
                    'b'old, 'u'nderline, 'i'talic, 'o'ther, or 'n'one.
                    Only those words listed in the "keyword" section
                    of a language definition are highlighted.  For
                    this option to work, SOURCE must know what
                    language the file is written in.  This is done by
                    using the filename extension as defined in the
                    SOURCE.LNG file or the 'x' option may be used to
                    force a specific language.  The highlighting
                    method used is as defined in the SOURCE.PRT file
                    for the selected type.  Default is 'k',
                    highlighted keywords on.

     -l{6|8}        Line Spacing.  The 'l' option specifies the number
                    of lines per inch to print.  The 'l' must be
                    followed by a 6 or an 8.  Ensure that the proper
                    printer codes have been defined in the SOURCE.PRT
                    file for the eight lines per inch option to work.
                    Default is 'l6', six lines per inch.

     -L[#,]#        Block Indenting Level.  The 'L' option specifies
                    how to indent the block trace lines if the 'b'
                    option is used.  Normally the block trace lines
                    are drawn adjacent to the block beginning.  The
                    'L' option allows you to specify the equivalent of
                    tab stops for the block levels.  The first, and
                    optional, parameter to the 'L' option specifies
                    the first column to place block level one in.  The
                    second, required, parameter specifies the indent
                    size.  Example:  'L1,3' will cause block level 1
                    to be shown in column 1, level 2 in column 4,
                    level 3 in column 7, etc.  These levels are used
                    regardless of the actual column the block is in.
                    The starting column should almost always be 1
                    since typically the outer most procedure blocks
                    are in column one.  The indent size should not be
                    any larger than the tab size.  Doing so could
                    cause the block line to be drawn farther out than
                    the block.  Specifying an indent size of 0 results
                    in the default action of printing the block line
                    adjacent to the block.  Default is 'L0,0'.

     -m{i|a}[v][r]  Include Files.  The 'm' option specifies what to
                    do when SOURCE finds a reference to an include
                    file.  The 'm' must be followed by an 'i' or an
                    'a'.  The 'i' tells SOURCE to ignore the include
                    file.  The 'a' tells SOURCE to print the include

                                     14
                                   SOURCE

                    file as if it was a file specified on the command
                    line.  The 'i' or 'a' may optionally be followed
                    by a 'v' and/or an 'r'.  The 'v' causes SOURCE to
                    ask for verification before printing the include
                    file.  The 'v' is only needed if both the 'q' and
                    the 'v' options are off.  If either is on, you
                    will be asked anyway.  The 'r' is used to report
                    include files that could not be found on the
                    include paths.  See the 'M' option for more on
                    include paths.  The include file will be printed
                    under the same options as the master file.  The
                    printing of include files is recursive.  In other
                    words, if a reference is found to an include file
                    inside an include file, the second will also be
                    printed.  For this option to work, SOURCE must
                    know what language the file is written in.  This
                    is done by using the filename extension as defined
                    in the SOURCE.LNG file or the 'x' option may be
                    used to force a specific language.  The default is
                    'mi', do not print include files.

     -M "path"      Include Search Path.  The 'M' option is used to
                    specify additional directories to search when an
                    include file is found.  See the 'm' option for
                    more on printing include files.  These directories
                    are searched prior to the directories specified in
                    the "include" section of the language definition.
                    To specify more than one directory, separate them
                    with a space.  Do not use a semicolon on the
                    command line since DOS treats the semicolon as a
                    command separator.  If you specify two or more
                    directories, use must enclose them in double
                    quotes because of the space.  The default is 'M',
                    no additional paths to search.

     -n[-]          Line Numbering.  The 'n' option is used to specify
                    whether line numbers will be shown or not.  Line
                    numbers are shown in the format specified in the
                    'N' option.  The 'n' may be followed by '-'.  The
                    'n' option alone turns on line numbering, the
                    minus turns it off.  Default is 'n', line
                    numbering on.

     -N [beg]#[end] Line Number Format.  The 'N' option specifies the
                    size and format of line numbers.  The value of #
                    must be a number between 1 and 9.  The terms "beg"
                    and "end" represent literal text that may be shown
                    before and after the line numbers.  For example,
                    if you want four digit line numbers within square
                    brackets, you would specify the option as 'N[4]'.
                    This would result in [   1], [   2], etc., being
                    printed.  Another example would be if you wanted
                    to specify 'N04:', which is the default, and this
                    would result in the line numbers being printed as
                    0001:, 0002:, and so on.

                                     15
                                   SOURCE

                    The line numbers are left padded with spaces.  If
                    you prefer the number to be left padded with
                    zeros, precede the number with a zero.  For
                    example:  'N4' will cause    1,    2, entering
                    'N04' will cause 0001, 0002, etc.  Both the
                    'begin' and 'end' text are optional.  If there is
                    no 'end' text, the source code will be adjacent to
                    the line number.  To avoid this, you may wish to
                    specify 'N"4 "'.  The space inside the double
                    quotes will print after each line number.

                    Specifying a value for the number of digits that
                    is too small for the number of lines in the file
                    to be printed will result in the line numbers
                    wrapping around.  For example, if you specify N01
                    and have 19 lines, line 10 would show up as 0, and
                    line 11 would become 1.  This wrapping holds true
                    for any size specified.  If your code typically
                    has less than 1000 lines, specify 3 for the value
                    of #, less than 10,000 lines, specify 4.  The
                    default is 'N04:' which will produce 0001:, 0002:,
                    etc.

     -o{l|p}        Page Orientation.  The 'o' option specifies the
                    page orientation.  This will probably only work on
                    laser printers since most dot matrix printers
                    cannot print in landscape.  The 'o' must be
                    followed by 'l' or 'p'.  The 'l' indicates
                    landscape (sideways) printing and the 'p' is
                    portrait (normal).  The landscape option requires
                    that the 'landscape' field be filled in in the
                    SOURCE.PRT file.  Default is 'op', portrait.

     -O{a|e|o|b}    Page Output.  The 'O' option specifies what pages
                    of the source file to print.  The 'a' parameter
                    specifies that all pages are to be printed.  The
                    'e' parameter specifies that only the even
                    numbered pages are to be printed.  The 'o'
                    parameter specifies that only the odd numbered
                    pages are to be printed.  The 'b' parameter will
                    first print the odd numbered pages, ask for a key
                    press, then print the even numbered pages.  This
                    pause allows you to go to the printer and re-feed
                    the paper upside down for manual duplex printing.
                    Once the paper has been replaced, press any key
                    for the even pages to print.  Keep in mind that
                    the odd pages cannot simply be turned over and
                    placed back in the sheet feeder.  You must reverse
                    the order so page one is on top of the pile when
                    turned over.  One way to avoid this on some laser
                    printers is to open the back door.  This will
                    result in the pages being stacked in the proper
                    order.



                                     16
                                   SOURCE

                    The terms 'odd' and 'even' for page numbers are
                    based on the 'I' option, not the 'J' option.
                    Example:  If you specify "-I2 -J5 -Oo" to print
                    starting with physical page 2, but show page
                    numbers starting with 5, and print the "odd"
                    pages, physical pages 3, 5, 7, etc. will come out.
                    Though they will be numbered 6, 8, 10, etc.  This
                    happens because page 2 becomes 5, 3 becomes 6,
                    etc.  The default is 'Oa', all pages.

     -p{p|e|c}      Pitch.  The 'p' option indicates the character
                    pitch to print the files in.  The 'p' must be
                    followed by 'p' (pica or 10 cpi), 'e' (elite or 12
                    cpi), or 'c' (compressed using your printers
                    compressed value, usually 15, 16.666, or 17).  If
                    your printer allows large pitch sizes such as 5
                    cpi, you could also use the compressed setting for
                    this.  See section 7 for more on setting the
                    compressed pitch value.  Default is 'pp', pica.

     -P{p|c|i}      Page Break.  The 'P' option tells SOURCE whether
                    to begin printing on a new 'p'age, or a new
                    'c'olumn when it encounters a form feed character,
                    or to 'i'gnore the form feed character all
                    together.  The 'P' option is also used to specify
                    the action to take when a page feed command is
                    found as specified in the language definition.
                    Default is 'Pp', perform page break.

     -q[-]          Page Count Query.  The 'q' option causes SOURCE to
                    pre-scan each file and return the number of lines
                    in the file and how many pages (excluding any
                    banner pages) are required to print it based on
                    all other print options.  You are then asked to
                    confirm whether to print the file or not.
                    Pressing 'Y' or 'y' will cause the file to be
                    printed.  Any other keystroke will prevent the
                    file from being printed.  Pressing the [Esc] key
                    will cause SOURCE to terminate.  The 'q' may be
                    followed by '-'.  The 'q' option alone turns on
                    the print statistics, the minus turns it off.
                    Turning on the 'q' option automatically turns on
                    the 'v' (print verification) option.  The 'q'
                    option must be used for the '&pc' page header
                    command to print.  Default is 'q', show page
                    count.

     -Q[-]          Show Print Statistics.  The 'Q' option causes
                    SOURCE to print a line showing the total number of
                    files, pages, and lines printed.  The 'Q' may be
                    followed by '-'.  The 'Q' option alone prints the
                    statistics, the minus turns it off.  Default is
                    'Q', show print statistics.



                                     17
                                   SOURCE

     -r "output"    Redirect.  The 'r' option allows you to redirect
                    the output to a file or other device such as the
                    screen or another printer port.  The 'r' must be
                    followed by a filename or device name.  The file
                    or device name is not case sensitive.  Example
                    devices would be "LPT1", "PRN", or "COM2".  You
                    may even specify "CON" to send the output to the
                    screen.  When specifying a file, enter as much of
                    the full path name as is needed.  You may specify
                    another drive or directory.  You may specify
                    wildcards in the filename.  This allows you to do
                    things like:

                         SOURCE *.c -r*.prn

                    This will result in each 'C' file being output to
                    its own '.prn' file.  The wildcards act just like
                    they would in a DOS COPY command.  If the
                    specified file already exists, SOURCE will act as
                    specified by the 'a' option.  If more than one
                    file being printed is to be redirected to the same
                    output file, the latter ones will be appended to
                    the first.  Default is 'r lpt1', output to printer
                    port one.

     -s{1|2|3|4}    Column Count.  The 's' option specifies the number
                    of columns to print per page.  The 's' must be
                    followed by a 1, 2, 3, or 4.  It is recommended
                    that compressed landscape printing be used with
                    two or more columns.  Using two columns in 10
                    pitch, portrait print, leads to some difficult to
                    read output.  Default is 's1', one column per
                    page.

     -S[-]          Show Column Separator.  The 'S' option is used in
                    conjunction with the 's' option.  When you specify
                    more than one column, the columns are separated by
                    a vertical line.  The 'S' option allows you to
                    tell SOURCE whether to display this vertical line
                    or not.  The 'S' may be followed by '-'.  The 'S'
                    alone turns the line on, the minus turns it off.
                    Default is 'S', line on.

     -t[#,]#        Tab Stop [Start and] Size.  The 't' option allows
                    you to specify how many spaces a tab character
                    should be printed as and optionally specify the
                    first tab column.  The 't' may be followed by a
                    number from one to the line length.  This optional
                    number represents the first tab column.  If used,
                    this number must be followed by a comma.  If not
                    specified, the default start column is column one.
                    Next, the 't' must be followed by a number from 0
                    to 8.  This required number specifies the tab
                    size.  Specifying a size of zero is equivalent to
                    having all tabs removed from the file.  Default is

                                     18
                                   SOURCE

                    't8', eight spaces per tab stop starting from
                    column one.

     -T#            Truncate Line.  The 'T' option is used to print
                    only the first '#' characters per line.
                    Specifying zero results on no line truncation.
                    Default is 'T0', no line truncation.

     -u "name"      Use Named Configuration.  The 'u' option is used
                    to specify a named configuration from within the
                    SOURCE.CFG file.  See section 6.2 for more on
                    named configurations.  The 'u' must be followed by
                    a configuration name that has been defined in
                    SOURCE.CFG.  The name is not case sensitive.  No
                    default.

     -v[-]          Print Verification.  The 'v' option is used to ask
                    the user to confirm the printing of each file.
                    This would most likely be used in conjunction with
                    wildcards in the filename.  For example, you want
                    to print all but one or two files in a directory.
                    Specify "*.*/v" on the command line to select all
                    the files.  SOURCE will then ask you to confirm
                    the printing of each file.  Just press 'Y' or 'y'
                    for the ones you want to print.  Any other key
                    stroke other than 'Y' or 'y' will be the same as
                    no.  Pressing the [Esc] key will cause SOURCE to
                    terminate.  The 'v' option is automatically turned
                    on when the 'q' option is turned on.  The 'v'
                    option may be followed by '-'.  The 'v' option
                    alone turns on the print verify, the minus turns
                    it off.  Default is 'v-', do not ask about each
                    file.

     -w#            White Space.  The 'w' option is used to specify
                    the number of blank lines printed between the
                    header/footer and the first/last line of text of
                    the file on the page.  The 'w' must be followed by
                    a value between 0 and 9.  Specifying zero will
                    result in no blank space.  See the 'h' and 'H'
                    options for more on user definable headers and
                    footers.  Default is 'w1', one line.

     -W[-]          Word Wrap.  The 'W' option specifies whether to
                    wrap long lines or to truncate them.  The 'W' may
                    be followed by '-'.  The 'W' option alone turns on
                    word wrapping, the minus truncates the lines.
                    Default is 'W', word wrap on.

     -x "language"  Force Language.  The 'x' option allows you to tell
                    SOURCE the language of a file regardless of its
                    extension.  This option is useful only when using
                    the 'b', 'c', or 'k' options (block grouping and
                    comment or keyword highlighting).  The 'x' must be
                    followed by a language name defined in SOURCE.LNG.

                                     19
                                   SOURCE

                    The name is not case sensitive.  For example, if
                    you have a file with a 'bak' extension that really
                    is a Pascal program, by following the file with
                    the '-xPascal' option, SOURCE will treat the file
                    as Pascal code so comments and blocks print
                    correctly.  This assumes that there is a
                    definition for 'Pascal' in the SOURCE.LNG file.
                    Default is none (use extension).

     -y[-]          Sound.  The 'y' option determines whether the
                    speaker will emit a bell or buzz sound when
                    prompts or errors occur.  This option is not
                    recognized as a local option.  The 'y' may be
                    followed by '-'.  The 'y' option alone turns on
                    sound, the minus turns them off.  Default is 'y-',
                    sound off.

     -z "list"      Ignore These Extensions.  The 'z' option is used
                    to tell SOURCE what files to ignore during
                    wildcard expansion.  For example, if you run
                    SOURCE with "*.*", you will have a mess at your
                    printer when it tries to print executables and
                    object code!  You could specify the 'v' option
                    each time and say no to files with ".exe" or
                    ".obj" extensions, or you could use the 'z' option
                    to tell SOURCE to automatically ignore the ".exe"
                    and ".obj" extensions every time.  The syntax for
                    the 'z' option is the list of extensions
                    (including the period) between a pair of double
                    quotes (if you place a space between each).  The
                    list is not case sensitive.  To continue the
                    example, specify the 'z' option as 'z ".exe
                    .obj"'.  You may specify as many extensions as you
                    like as long as all are specified with one 'z'
                    option.  Using two 'z' options will cause the
                    first one to be ignored.  Default is 'z ".exe .com
                    .sys .obj"'.

     Below is a list of the command line options broken out by
     category.

     Page Format:
     -p             Pitch.
     -o             Page Orientation.
     -s             Column Count.
     -S             Show Column Separator.
     -l             Line Spacing.
     -g             Graphics.
     -e             Escape Codes.
     -P             Page Break.
     -E             Page Margins.

     Page Layout:
     -t             Tab Stop Start and Size.
     -n             Line Numbering.

                                     20
                                   SOURCE

     -N             Line Number Format.
     -h             Header Page.
     -H             Header Definition.
     -w             White Space.
     -B             Banner.
     -W             Word Wrapping.
     -T             Line Truncation.

     Language Features:
     -b             Block Grouping.
     -L             Block Level Indenting.
     -c             Comment Highlighting.
     -k             Keyword Highlighting.
     -m             Include Files.
     -M             Include Search Path.
     -x             Force Language.

     File Selection:
     -i             Initial Line.
     -f             Final Line.
     -I             Initial Page.
     -F             Final Page.
     -j             First Line Number.
     -J             First Page Number.
     -q             Page Count Query.
     -v             Print Verification.
     -z             Ignore These Extensions.

     Output:
     -r             Redirect.
     -a             Append/Overwrite.
     -d             Select Printer.
     -O             Output Pages.

     Miscellaneous:
     -?             Help.
     -y             Sound.
     -u             Use Named Configuration.
     -Q             Show Print Statistics.

     6    SOURCE.CFG

     The SOURCE.CFG file is used to store groups of configuration
     options that may be used by SOURCE.  Among these groups are a set
     of default options.  These default options are seen by running
     SOURCE with the '-?' global option.  These default options, as
     initially defined, are actually the same defaults hard coded
     within SOURCE itself.

     6.1  SOURCE.CFG Location

     SOURCE.CFG is actually not needed.  If SOURCE can not find
     SOURCE.CFG, it will fall back on the built in defaults and
     continue to work fine.  SOURCE.CFG can be located in many
     different places.  By default, you should place a copy in the

                                     21
                                   SOURCE

     same directory as SOURCE.EXE (from now on referred to as the
     SOURCE directory).  With this setup, running SOURCE from any
     directory will cause SOURCE to use the defaults defined in
     SOURCE.CFG in the SOURCE directory.

     In addition to placing SOURCE.CFG in the SOURCE directory, you
     may also place other copies in any other directory you wish.  For
     example, you have a 'prog' directory on your hard disk.  If you
     place another copy of SOURCE.CFG in 'prog' and run SOURCE while
     your default directory is 'prog', SOURCE will use the SOURCE.CFG
     file in the 'prog' directory instead of the SOURCE directory.  By
     tailoring the SOURCE.CFG file to the files in 'prog', you can
     minimize the amount of command line options you need to specify.
     The whole point to allowing this kind of flexibility is that you
     might be working on different projects that require different
     printing styles.  By placing tailored SOURCE.CFG files in the
     different directories, you can easily accomplish the diverse
     printing needs.

     6.2  Named Configuration Options

     If you have looked at the contents of SOURCE.CFG, you will notice
     that there seems to be more than just defaults defined in there.
     SOURCE.CFG can actually store up to fifty sets of configuration
     options.  The first of which (as supplied) is the default
     options.  These different sets of options are referred to as
     named configuration options.  The supplied defaults are actually
     a named configuration option titled 'Default'.  SOURCE
     automatically looks for 'Default' and loads the options in if
     found.  In addition to the 'Default' setup, you may define 49
     more of your own design.  If for some reason you do not want the
     defaults loaded, rename 'Default' to something else.  You may
     then refer to the defaults explicitly by using the 'u' option on
     the command line.  See section 5 for more information on
     selecting named configurations from the command line using the
     'u' option.

     The idea behind named configurations allows you to define a
     commonly used, but cumbersome, set of configuration options into
     a simple, single command line option.  A common use for them
     might be on a LAN where each user has their own favorite set of
     defaults.  The SOURCE.CFG file could contain one set for each
     user using their name or initials to name the options.  On the
     command line, simply specify "-u name" and all the options
     defined as "name" in SOURCE.CFG will be used.  Another
     circumstance could be to use named options when you are using
     SOURCE with multiple printers.  If you have "printer1" on "lpt1"
     and "printer2" on "com3", you could add two named configurations,
     "p1" and "p2".  "p1" would have '-d printer1 -r lpt1' and "p2"
     would have '-d printer2 -r com3'.  You could also add the 'g'
     option if one printer could print the IBM line drawing characters
     and one could not.  Typing 'source -u p1' at the command line is
     easier than 'source -d printer1 -r lpt1 -g'.  One other
     possibility would be if you wished to print source code in
     different languages in different formats.

                                     22
                                   SOURCE

     The named set of options may also contain a 'u' option.  This
     allows for nested definitions.  As an example, let's say you have
     two named configurations, "name1" and "name2".  If "name1"
     contains '-u name2', "name1" will pull in the options defined in
     "name2".  The result of using "name1" will be all the options in
     "name1" and all the options in "name2" being used.

     6.3  SOURCE.CFG Format

     The format of the SOURCE.CFG file is simple.  A named
     configuration begins with the key word "begin" followed by a
     name.  This name can contain any characters you can type at the
     DOS prompt.  I recommend descriptive names that indicate what the
     options represent.  Spaces are not allowed in the name.  The only
     limit is the full name must be 20 characters or less.  After the
     "begin" line, enter any set of options you like.  There are two
     ways of entering the options.  The easiest to read is to place
     one command per line.  Each command must be preceded by a hyphen.
     Example:

     -t3
     -pp

     The second method allows more than one command per line.  This is
     identical to global options on the command line.  Simply separate
     the commands by at least one space.  Again, each command must be
     preceded by a hyphen.  Example:

     -l8  -s2

     You may also enter the commands using any combination of the two
     methods.  Example:

     -q  -i5 -f100
     -z ".exe .obj .sys"

     After all options have been specified, enter the key word "end"
     on a line by itself to signal the end of the named definition.
     You may define up to 20 named configurations.  A full definition
     would look as follows:

          begin Test
          -q -F2
          end

     6.4  Commenting SOURCE.CFG

     You may place comments in the SOURCE.CFG file by beginning a line
     with a semicolon ( ; ).  All text on that line will be ignored by
     SOURCE.  Do not place comments on lines with options.  The
     comment must go on a line by itself.  Example:

     ; This is a valid comment
     -b -cb   ; This is not a valid comment - must be on own line


                                     23
                                   SOURCE

     6.5  Modifying SOURCE.CFG

     I recommend you modify the 'Default' named option in SOURCE.CFG
     to suit your most common needs.  This will result in having to
     specify little on the command line other than the filenames to
     print.  If you need to print a file slightly different one time,
     specify only the options required for the difference.  Add other
     named options for other commonly used configurations like those
     mentioned above.  This allows you to use very different print
     formats with minimal command line typing.

     One common change to the defaults would be to specify a different
     printer port.  Initially, SOURCE assumes printer port one, LPT1:.
     If you are using a serial printer on a COM port or another
     printer port, change the default setting for the 'r' option.
     Replace the word 'lpt1' with 'com1' or 'lpt2' or whatever is
     appropriate for you.

     7    SOURCE.PRT

     This file allows you to define any printer configuration you may
     have.  Only one copy of SOURCE.PRT is used and this must reside
     in the same directory as SOURCE.EXE.  This file is required and
     SOURCE will not run if not found.  SOURCE.PRT can contain printer
     definitions for up to 20 different printers, though I doubt you
     will ever need that many.  Once you define your printer, you can
     delete all other definitions if you like.  However, if you have
     more than one printer, leave all the necessary definitions.

     7.1  Default Printer

     If you have more than one printer defined, you must make one the
     default.  This can be done automatically the first time you run
     SOURCE.  If you would like to change that default at a later
     time, you must manually edit the SOURCE.PRT file.  To make a
     printer the default, place the keyword "default" after the
     printer name.  Example:  'begin HPLJII+ default'.  If you specify
     more than one default, the fist one will be chosen.  Remember you
     can use the 'd' option to select a printer other than the default
     if needed.  If you only have one printer defined in SOURCE.PRT
     you do not need to specify the keyword "default".

     7.2  SOURCE.PRT Format

     Similar to SOURCE.CFG, each definition in SOURCE.PRT begins with
     the keyword 'begin' followed by a name.  The name may be made up
     of any characters you can type at the DOS prompt up to 20
     characters.  The name may not contain spaces.  The printer
     definition ends with the keyword 'end' on a line by itself.  In
     between are the lines specifying your printer setup.  The syntax
     of each line is a field name, a colon, and the value you enter
     for that field.  Each line can contain only one field.

     For those fields that require a printer escape sequence, you can
     enter the codes as literal characters or by entering the decimal

                                     24
                                   SOURCE

     value in square brackets.  You may also enter the code as a
     combination of both.  For example, the reset code on a Hewlett
     Packard Laser Jet is [Esc]E.  You might not be able to enter a
     literal escape character in your editor.  The solution is to use
     the decimal value in square brackets.  [Esc] is ASCII value 27.
     The 'E' can be entered literally.  The two codes together would
     be entered into the reset field as:  [27]E.  Since the square
     brackets are being used as special characters by SOURCE, you may
     not enter them as literal characters in the printer code.  If
     your code needs the characters '[' or ']', enter the decimal
     value in square brackets.  The left bracket '[' becomes [91] and
     the right bracket ']' becomes [93].  The value inside the bracket
     must be a decimal number from 1 to 255.  If an ASCII character of
     32 (space) is required, you may enter a literal space or [32].

     A list of the fields and a description of each is as follows:

     page width:    This field is the physical page width in inches.
                    This will typically be 8.5 for standard letter
                    sized paper.  If you are using wide computer
                    paper, this could be 14.  This field is required.

     page length:   This field is the physical page length in inches.
                    Normal letter size paper would be 11.  Legal size
                    paper would be 14.  This field is required.

     top margin:    Indicates the top margin in inches.  The first
                    printed line will be placed this far from the top
                    of the page.  A standard half inch margin would be
                    .5.  This value must be greater than or equal to
                    the top edge.  This field is required.

     bottom margin: Indicates the bottom margin in inches.  The last
                    line printed will be this far from the bottom of
                    the page.  This value must be greater than or
                    equal to the bottom edge.  This field is required.

     left margin:   This is the left margin in inches.  The left most
                    characters will be this far from the left edge of
                    the paper.  This value must be greater than or
                    equal to the left edge.  This field is required.

     right margin:  This is the right margin in inches.  The right
                    most characters will be this far from the right
                    edge of the paper.  This value must be greater
                    than or equal to the right edge.  This field is
                    required.

     top edge:      The top edge is used to define the physical
                    limitation of the printer to print at the top of
                    the page.  Laser printers typically are set with a
                    half inch limit at the top.  By entering .5 here,
                    the margin specified in 'top margin' will come out
                    correctly.  This field is required.


                                     25
                                   SOURCE

     bottom edge:   The bottom edge is used to define the physical
                    limitation of the printer to print at the bottom
                    of the page.  Laser printers typically are set
                    with a half inch limit at the bottom.  By entering
                    .5 here, the margin specified in 'bottom margin'
                    will come out correctly.  This field is required.

     left edge:     The left edge is used to define the physical
                    limitation of the printer to print at the left
                    edge of the page.  Laser printers typically cannot
                    print on the first quarter inch of the left edge.
                    By entering .25 here, the margin specified in
                    'left margin' will come out correctly.  The exact
                    value entered may be slightly different.  Try .2
                    or .3.  Experiment with the proper value to set
                    your printer up correctly.  This field is
                    required.

     right edge:    The right edge is used to define the physical
                    limitation of the printer to print at the right
                    edge of the page.  Laser printers typically cannot
                    print on the last quarter inch of the right edge.
                    By entering .25 here, the margin specified in
                    'right margin' will come out correctly.  The exact
                    value entered may be slightly different.  Try .2
                    or .3.  Experiment with the proper value to set
                    your printer up correctly.  This field is
                    required.

     10 pitch:      This field is used to enter the escape sequence
                    used by your printer to print text at ten
                    characters per inch.  Enter the sequence exactly
                    as shown in your printer manual including case.
                    Used when the 'pp' option is used.

     12 pitch:      This field is used to enter the escape sequence
                    used by your printer to print text at 12
                    characters per inch.  Enter the sequence exactly
                    as shown in your printer manual including case.
                    This field is required to use this feature.  Used
                    when the 'pe' option is used.

     compressed:    This field is used to enter the escape sequence
                    used by your printer to print text in compressed
                    mode.  This is usually 15, 16.66, or 17.  You may
                    even enter the code for enlarged print such as 5
                    cpi.  Enter the sequence exactly as shown in your
                    printer manual including case.  Make sure the size
                    of the print is specified in the 'comp size'
                    field.  This field is required to use this
                    feature.  Used when the 'pc' option is used.

     comp size:     This field is used to specify the characters per
                    inch your printer will print while in compressed
                    mode.  Typically this value will be 15, 16.666, or

                                     26
                                   SOURCE

                    17 (or even 5 for enlarged print).  This field is
                    required to print in compressed mode.  Used when
                    the 'pc' option is used.

     underline on:  This is the printer escape sequence used to print
                    comments or keywords when the 'c' or 'k' option is
                    set to 'u'.  This code should be set to turn on
                    underlined print.  This code is also used on page
                    headers or footers.  DO NOT use a code that prints
                    in a different size font like expanded or double
                    height.  This will cause the file to print
                    incorrectly.  Whatever code is used must not
                    change the current print size.  This field is
                    required to use this feature.

     underline off: This is the printer escape sequence used to turn
                    off the code used by 'underline on'.  This field
                    is required to use this feature.

     bold on:       This is the printer escape sequence used to print
                    comments or keywords when the 'c' or 'k' option is
                    set to 'b'.  This code should be set to turn on
                    bold print.  DO NOT use a code that prints in a
                    different size font like expanded or double
                    height.  This will cause the file to print
                    incorrectly.  Whatever code is used must not
                    change the current print size.  This field is
                    required to use this feature.

     bold off:      This is the printer escape sequence used to turn
                    off the code used by 'bold on'.  This field is
                    required to use this feature.

     italic on:     This is the printer escape sequence used to print
                    comments or keywords when the 'c' or 'k' option is
                    set to 'i'.  This code should be set to turn on
                    italic print.  DO NOT use a code that prints in a
                    different size font like expanded or double
                    height.  This will cause the file to print
                    incorrectly.  What ever code is used must not
                    change the current print size.  This field is
                    required to use this feature.

     italic off:    This is the printer escape sequence used to turn
                    off the code used by 'italic on'.  This field is
                    required to use this feature.

     other on:      This is the printer escape sequence used to print
                    comments or keywords when the 'c' or 'k' option is
                    set to 'o'.  This code could be almost anything
                    your printer can do.  Examples are inverse or
                    outline.  DO NOT use a code that prints in a
                    different size font like expanded or double
                    height.  This will cause the file to print
                    incorrectly.  What ever code is used must not

                                     27
                                   SOURCE

                    change the current print size.  This field is
                    required to use this feature.

     other off:     This is the printer escape sequence used to turn
                    off the code used by 'other on'.  This field is
                    required to use this feature.

     init:          This code is sent to the printer before the first
                    file is printed.  This should contain all required
                    printer initialization codes to setup your
                    printer.  Examples would be the initialize printer
                    code, character set selection (not pitch size),
                    and print quality (draft, NLQ, etc.).  There
                    should be nothing in here for selecting pitch or
                    page orientation since this will be done using the
                    other codes specific to those settings.  This is
                    not required.

     reset:         This code is sent to the printer after the last
                    file is sent.  This can be blank.  This may be
                    used to place the printer back into the mode it
                    was prior to the "Init" code being sent.  This is
                    not required.

     portrait:      This is the code sent to the printer to set the
                    paper orientation to portrait - the usual way the
                    page is set.  This only applies to laser printers
                    since dot matrix printers cannot print any other
                    way using straight text printing (as opposed to
                    graphics).  This must be filled in if your printer
                    supports portrait and landscape printing.

     landscape:     This is the code sent to the printer to set the
                    paper orientation to landscape - sideways
                    printing.  This only applies to laser printers
                    since dot matrix printers cannot print landscape
                    without using graphics.  This must be filled in to
                    make use of the landscape printing feature.

     6 lpi:         This code is used to print the file at six lines
                    per inch.  This is the usual default for all
                    printers.  If your printer does not support eight
                    lines per inch than you may leave this blank,
                    otherwise this is required.  Used with the 'l6'
                    option.

     8 lpi:         This code is used to print the file at eight lines
                    per inch.  If your printer does not support eight
                    lines per inch than you may leave this blank,
                    otherwise this is required to use the feature.
                    Used with the 'l8' option.

     There are many relationships between the values placed in the
     above fields.  The sum of the top and bottom margins must be less
     than the page length.  The sum of the left and right margins must

                                     28
                                   SOURCE

     be less than the page width.  All margins must be greater than or
     equal to their corresponding edge.  If you only have 10 pitch
     printing, you may leave all three pitch codes blank.  If you can
     only print at six lines per inch, you may leave both the six and
     eight lines per inch codes blank.

     Certain combinations of print options do not work together on
     some printers.  For example, Hewlett Packard laser jet printers
     will not print bold or italic while in compressed print.  If you
     specify -cb -pc on the command line (bold comments, compressed
     print) for a Laserjet printer, the comments will not be bold.

     7.3  Modifying Your Printer

     As delivered, the SOURCE.PRT file has only a few basic printers
     within it.  These may not fit your printer completely if at all.
     To take full advantage of your printer's abilities, you can edit
     SOURCE.PRT by placing an entry for your printer within it.  To do
     so, either reuse an existing entry that is similar to your
     printer or copy the 'Generic' definition and rename the copy to
     match your printer name.  Once you have this done, open up your
     printer's reference manual to the section that describes all the
     features and their associated escape sequences.  Enter the codes
     you need into the proper fields and you will be ready to go.  It
     may take some trial and error to get everything perfect, but it
     can be done.

     8    SOURCE.LNG

     SOURCE.LNG contains the definitions for the language support
     features of SOURCE.  The five options are comment highlighting,
     keyword highlighting, code block grouping or tracing, include
     file printing, and page feed commands.  The SOURCE.LNG file
     details what makes a comment, a literal string and character,
     what represents a code block, the list of keywords, how to find
     an include file, and the list of page feed commands.

     8.1  SOURCE.LNG Location

     SOURCE.LNG is not a required file.  If SOURCE can not find
     SOURCE.LNG, it will ignore the use of the b, c, and k options and
     continue to work fine.  SOURCE.LNG can actually be located in
     many different places.  By default, you should place a copy in
     the same directory as SOURCE.EXE (from now on referred to as the
     SOURCE directory).  With this setup, running SOURCE from any
     directory will cause SOURCE to use the definitions in the
     SOURCE.LNG in the SOURCE directory.

     In addition to placing SOURCE.LNG in the SOURCE directory, you
     may also place other copies in any other directory you wish.  For
     example, you have a 'prog' directory on your hard disk.  If you
     place another copy of SOURCE.LNG in 'prog' and run SOURCE while
     your default directory is 'prog', SOURCE will use the SOURCE.LNG
     file in the 'prog' directory instead of the SOURCE directory.  By


                                     29
                                   SOURCE

     tailoring the SOURCE.LNG file to the files in 'prog', you can
     work with different dialects of the same language.

     The whole point to allowing this kind of flexibility is that you
     might be working on different projects that require different
     language definitions.  By placing tailored SOURCE.LNG files in
     the different directories, you can easily accomplish the diverse
     needs.

     8.2  SOURCE.LNG Format

     The format of SOURCE.LNG is similar to the other support files.
     You begin a language definition with the keyword 'beginlang'
     followed first by the name of the language and then a list of
     filename patterns associated with the language.  The language
     name can be any characters you can type at the DOS prompt.  The
     name cannot contain spaces and may be up to 20 characters long.
     The list of filename patterns is used to tell SOURCE to treat any
     file matching the pattern as a file of that language.  The file
     pattern may contain wild cards like those used in the 'DIR'
     command.  An example would be:  'beginlang C *.c *.h'.  This
     defines a language called "C".  Any file with the extension ".c"
     or ".h" would be treated as a "C" file.  You may specify up to 10
     patterns per language.

     The second line of the definition is a list of legal characters
     that may be found in identifiers and keywords.  Identifiers
     include variables and labels within a program.  These characters
     are used to tell SOURCE how to discern between two words in a
     program.  Most languages allow letter and numbers.  Some also
     allow some punctuation like underscores.  See your language
     reference.  It should detail the allowable characters.  The list
     of characters must be contiguous and on one line with no spaces.
     You only need to specify either lower or upper case letters, not
     both.

     The language definition is completed with the keyword 'endlang'
     on a line by itself.  This may be followed by the keyword 'case'
     to indicate that the language is case sensitive and/or 'part' to
     indicate that keywords only need to match partially.  This is
     explained in detail below.  Any other keywords, or none at all,
     indicate that the language is case independent and keywords
     require a full match.  Example:  'endlang case' terminates the
     language definition and specifies case dependency.  'endlang' or
     'endlang nocase' indicate the end of a case independent language.

     The SOURCE.LNG file may contain up to twenty language
     definitions.  You only need those for which you have use, so feel
     free to delete unneeded languages from the supplied SOURCE.LNG
     file.

     8.3  Commenting SOURCE.LNG

     You may place comments in the SOURCE.LNG file by beginning a line
     with a semicolon (;).  All text on that line will be ignored by

                                     30
                                   SOURCE

     SOURCE.  Do not place comments within a language definition, only
     before the 'beginlang' line or after the 'endlang' line.

     8.4  Defining Language Specific Features

     8.4.1  Comments

     After the 'beginlang' line, you specify how comments are defined.
     This begins with the line ':comment:'.  After the ':comment:'
     line, you specify three lines.  The first line is the begin
     comment command, the second is the end comment command.  The
     third line contains a number from zero to 80 or the letter 'B'.
     If a number is specified, it indicates the column that the begin
     comment command must begin in.  A zero indicates that the comment
     may begin in any column.  If the letter 'B' is specified, it
     means that the begin comment marker may begin in any column but
     must be the first non white space character on the line.  An
     example for the 'C' language would be:

          :comment:
          /*                       <== Begin comment
          */                       <== End comment
          0                        <== Comment may be in any column

     You may specify more than one comment.  For example, Turbo Pascal
     allows the following:

          :comment:
          {
          }
          0
          (*
          *)
          0

     For languages such as BASIC where comments are terminated by the
     end of line, specify the begin command on the first line and
     leave the second line blank.  Example:

          :comment:
          REM
                                   <== This is a blank line
          0

     One of the few examples of specifying a non-zero column number
     would be for FORTRAN.  Comments in FORTRAN are specified by
     placing a 'C' in column one.  The definition for this would be:

          :comment:
          C                        <== Comments begin with a C
                                   <== Terminated by end-of-line
          1                        <== 'C' must be in column one

     An example of using the 'B' column position is dBASE.  The 'note'
     and '*' comment markers used for comments must be the first

                                     31
                                   SOURCE

     characters on the line (not necessarily column one).  The
     definition would be:

          :comment:
          *                        <== Comment begins with '*'
                                   <== Terminated by end-of-line
          B                        <== * must be first character
          note                     <== Comment begins with 'note'
                                   <== Terminated by end-of-line
          B                        <== 'n' must be first character

     Since blank lines are interpreted as part of the syntax, you may
     not leave blank lines within a language definition in the
     SOURCE.LNG file unless it is required as above.  You may define
     up to 10 comment marker pairs per language.

     8.4.2  String and Character Literals

     After defining the comments, you define what makes up literal
     strings and characters.  This is done just like comments.  You
     begin with the line ':string:'.  After this line, you enter two
     lines per string or character.  The first line contains the
     delimiter used to begin and end a literal string or character
     (typically a single or double quote).  The second line specifies
     an escape sequence.  This is the sequence (usually one character)
     used to allow the delimiter character to be used literally within
     a string or as a character.  'C' is a good example of this.
     Strings are set in double quotes.  To place a double quote within
     a string, you must precede the double quote with a backslash ("He
     said \"Hello\"").  The definition would be as follows:

          :string:
          "                        <== String Delimiter
          \                        <== Escape Sequence

     Characters in 'C' are similar.  Literal characters are defined by
     single quotes.  To assign a literal single quote in 'C', you
     precede the literal quote with a backslash ('\'').  The
     definition would be:

          :string:
          '                        <== Character Delimiter
          \                        <== Escape Sequence

     For languages such as Pascal where strings are defined by single
     quotes and a literal single quote is specified by two single
     quotes ('It''s mine'), simply place the following definition:

          :string:
          '                        <== String & Character Delimiter
          '                        <== Escape Sequence

     For languages such as BASIC which do not allow you to place the
     string delimiter within the string, you would leave the second
     line blank.

                                     32
                                   SOURCE

     You may declare up to five pairs of delimiters per language.  The
     full string definition for 'C' would be:

          :string:
          "
          \
          '
          \

     8.4.3  Blocks

     After specifying the string definition, you must define what
     commands make up blocks.  The keywords defined here are used with
     the 'b' option to allow block grouping to work.  The definition
     begins with the keyword ':block:'.  Following are two lines per
     block.  The first line is the begin block command and the second
     line is the end block command.  For 'C', this is easy because all
     blocks are marked the same.  Blocks begin with a left curly brace
     and end with a right curly brace.  The definition would be:

          :block:
          {
          }

     For languages like Pascal, you may have numerous block pairs.
     Example:

          :block:
          begin
          end
          record
          end
          case
          end
          repeat
          until

     For most languages, the keyword used to define a block must be
     entered in its entirety.  You can't specify

          beg
          ...
          end

     in Pascal for example.  You must enter the whole keyword.  A
     counter example to this is the dBase programming language.  dBase
     allows you to enter only the first four letters of each keyword.
     A 'while' loop could be entered as:

          do while                           do whil
          ...                 or             ...
          enddo                              endd

     For SOURCE to work with a language such as this, you must specify
     the "part" or "partial" keyword after the "endlang" keyword at

                                     33
                                   SOURCE

     the end of the language definition followed by the number of
     characters needed.  SOURCE will use this number when comparing
     the block specified in SOURCE.LNG with words found in the source
     file.  If the number of characters required is 4, and the keyword
     is 'endif', SOURCE will recognize 'endi' and 'endif', but not
     'end', 'endis' or 'endif1'.  If the 'part' keyword is not
     specified, SOURCE will treat the comment and block keywords in
     SOURCE.LNG as the full keyword that must be found in the file
     being printed.

     You may have more than one block that ends with the same keyword.
     For example, 'if' - 'end', 'while' - 'end'. This would be defined
     as:
          :block:
          if
          end
          while
          end

     You may also specify blocks that begin with the same keyword and
     may end with more than one keyword.  One example is in Clipper.
     the 'while' block may end with the 'end' or 'enddo' keywords.
     This would be defined as:

          :block:
          while
          end
          while
          enddo

     In such cases, SOURCE will end the while block when ever if find
     'end' or 'enddo', which ever is first.

     8.4.4  Keywords

     After specifying the block definition, you must define those
     keywords that you would like highlighted when the 'k' option is
     active.  The definition begins with the keyword ':keyword:' and
     is followed by one keyword per line.  The keywords may have
     spaces in them.  The words may be entered in any order.  You may
     enter any words you like.  The idea is to highlight reserved
     words so you can pick out variables and function names easier.
     If you have certain functions or other words you would like
     highlighted, simply add them to the list.  A partial list for 'C'
     would be:

          :keyword:
          auto
          break
          case
          char
          const
          continue
          . . .


                                     34
                                   SOURCE

     If the language is case dependant, ensure the keywords are
     entered in the proper case.  If case independent, the entered
     case is irrelevant.  If the language supports partial keyword
     matching (like dBASE), you must still enter the entire keyword.
     SOURCE will highlight the entire keyword found in the program.
     For example, if you have the keyword 'endtext' in the language
     definition, SOURCE will highlight 'endt', 'endte', 'endtex', or
     'endtext' in the program if the 'part 4' definition was placed at
     the end of language definition.

     It is important that the keywords entered into the definition
     only contain those characters entered on the second line of
     language definition.  If other characters are used, the keyword
     may not be highlighted properly.  You may define up to 400
     keywords per language.

     8.4.5  Include Files

     After specifying the keyword section, you must specify the syntax
     for include file references.  The definition begins with the
     keyword ':include:' and is followed by five lines per include
     file reference syntax.  The first line contains the text to be
     found prior to the name of the include file.  It is assumed that
     this is the first characters found on the line.  The second and
     third lines contain two possible strings that can occur after the
     filename.  The fourth line contains a list of directories to
     search for the include file.  The fifth line contains the default
     extension for the include file.  If the language does not supply
     default extensions, leave the line blank.  The list of
     directories will be searched in order.  If more than one
     directory is listed, they must all be on the same line separated
     by a semicolon or a space.

     An example of the include file syntax for Turbo Pascal is:

          {$I filename.ext}

     This would be entered into SOURCE.LNG as follows:

          :include:
          {$I
          }
                                   <== Blank line
          .;c:\pascal\include
          .pas                     <== Default extension

     The third line is blank since only one possible string can follow
     the filename.  The search path contains two directories.  The
     first is the current directory, the second is the
     'c:\pascal\include' directory.

     The 'C' language has two possible syntaxes.  These are:

          #include "filename.ext"
          #include <filename.ext>

                                     35
                                   SOURCE

     These would be defined in SOURCE.LNG as:

          :include:
          #include "
          "
                                   <== Blank line
          .;c:\include
                                   <== Blank line
          #include <
          >
                                   <== Blank line
          c:\include
                                   <== Blank line

     The first definition has two directories while the second only
     has one.  The first includes the current directory which is the
     only functional difference between the two syntaxes in 'C'.
     Neither syntax has a default extension.

     COBOL is an example of using the third line.  The syntax for
     include files in COBOL is:

          COPY filename.txt [optional commands].

     Since this syntax includes some optional text after the filename
     before the period, the filename could end with a space or a
     period.  The definition would be:

          :include:
          COPY
                                   <== One space or blank line
          .
          c:\path;c:\another
                                   <== Blank line

     In this case, the second line may contain a single space or be
     blank.  SOURCE will treat a blank second line like a space to
     mark the end of the filename.  If no space is found, SOURCE will
     then look for a period character to end the filename.

     Currently, a language may have up to five syntaxes for include
     files.  The path list may be up to 198 characters long (again,
     all on one line).  If a language does not support include files,
     simply enter nothing after the ':include:' keyword.

     8.4.6  Page Feeds

     After specifying the include file section, you must specify the
     list of page feed commands.  The definition begins with the
     keyword ':pagefeed:' and is followed by one line per page feed
     command.  You may enter up to three page feed commands per
     language.  Very few standard languages have such commands.  The
     ones, as supplied, are Ada and RPG/free.  The command is assumed
     to be the first characters on the line.  A sample command for Ada
     is the 'page' pragma.  The definition would be as follows:

                                     36
                                   SOURCE

          :pagefeed:
          pragma page

     This is a very simple example.  The handling of the page feeds is
     specified by the 'P' option which also handles form feed (ASCII
     12) characters.  If a language does not have a page feed command,
     simply place nothing after the ':pagefeed:' keyword.

     8.4.7  Complete Definition

     Now that you have seen each part of the definition, here is a
     full definition as it would appear in SOURCE.LNG for 'C'.

          beginlang C *.c *.h
          abcdefghijklmnopqrstuvwxyz0123456789_   <== Valid characters
          :comment:
          /*
          */
          0                        <== Any column
          :string:
          "
          \
          '
          \
          :block:
          {
          }
          :keyword:
          auto
          break
          case
          char
          const
          continue
          . . .          <== There are more, but you get the point
          :include:
          #include "
          "
                                   <== Blank line
          .;c:\include
                                   <== Blank line
          #include <
          >
                                   <== Blank line
          .;c:\include
                                   <== Blank line
          :pagefeed:               <== No page feeds
          endlang case

     For dBase, the full definition would be:

          beginlang dbase *.prg
          :comment:
          *
                                   <== Comments end with end-of-line

                                     37
                                   SOURCE

          B                        <== Any column, but first character
          &&
                                   <== Comments end with end-of-line
          0                        <== Comment begins in any column
          note
                                   <== Comments end with end-of-line
          B
          :string:
          "
                                   <== No double quotes in strings
          :block:
          do case
          endcase
          do while
          enddo
          if
          endif
          text
          endtext
          :keyword:
          accept
          additive
          alias
          all
          all like
          append
          append from
          . . .          <== There are more, but you get the point
          :include:      <== dBase does not have include files
          :pagefeed:     <== No page feed commands either
          endlang part 4

     8.5  General Points

     Some points to keep in mind when defining a language.  If you
     have more than one language with the same extension, SOURCE will
     choose the last.  To override this, you can use the 'x' option on
     the command line to explicitly choose the language you really
     need.

     While defining a comment, you may not define two or more pairs
     that begin with the same keyword, regardless of the ending
     keyword.  However, you may define any number of pairs that have
     the same ending keyword as long as the beginning keywords are
     unique.  Blocks do allow multiple ending keywords for the same
     beginning keyword.

     When defining blocks for the language, be careful with statements
     using variable syntax.  A good example is the 'IF' statement in
     some BASICs.  The syntax can be:

     1)   IF condition THEN statement [ELSE statement]

          or


                                     38
                                   SOURCE

     2)   IF condition THEN
            statements
          [ELSE
            statements]
          ENDIF

     DO NOT specify in your block definitions 'IF' - 'ENDIF' because
     if SOURCE encounters the first syntax, the line will never
     terminate because it will not find the 'ENDIF'.  Unfortunately,
     there is no solution to this.  The only downside is that you will
     not get trace lines for your IF statements.  If you know for a
     fact that you did not use the first syntax, then go ahead and
     specify the 'IF' - 'ENDIF' block.

     Another area to watch for is keywords that have multiple uses.  A
     good example is the 'for' keyword in Clipper.  'For' can be used
     in a 'FOR' - 'NEXT' loop (block) or in commands like 'display for
     ...'  If a 'FOR' - 'NEXT' block is defined and SOURCE comes
     across a line like 'display for NAME = "HELLO"', the 'for' will
     cause a block to begin.  For this reason, the 'FOR' - 'NEXT'
     block is not defined.

     9    Network Support

     SOURCE currently has limited network support.  The support
     offered at this time allows you to define an environment variable
     called "USER".  SOURCE will determine the value of "USER" and
     load the named configuration, from SOURCE.CFG, of the same name.
     This configuration option will be used as the default set of
     options instead of "Default".

     This setup allows SOURCE to be installed on a network server.
     Each user would add a line like:

     set USER=<name>

     to their "autoexec.bat" file.  The <name> would be a unique
     identifier for that person.  This could be a last name or
     initials.  The SOURCE.CFG file in the SOURCE directory would
     contain a named configuration for each user on the network.

     Care must be taken to limit write access to the common SOURCE.CFG
     file.  You may wish to allow only the network supervisor to
     update this file to prevent problems with each user adding their
     options.  Data will get lost if two people try editing at the
     same time.

     If SOURCE cannot find a named configuration with the same name as
     the value of "USER", SOURCE will fall back on the "Default" named
     configuration.

     Having the environment variable defined is slightly different
     from using the '-u <name>' command line option.  When using the
     environment variable, the matching named configuration is used in
     place of the default named configuration.  When using the 'u'

                                     39
                                   SOURCE

     option, the matching named configuration is loaded in addition to
     the default named configuration.

     10   Definition of Shareware

     Shareware distribution gives users a chance to try software
     before buying it.  If you try a Shareware program and continue
     using it, you are expected to register.

     Copyright laws apply to both Shareware and commercial software,
     and the copyright holder retains all rights, with a few specific
     exceptions as stated below.  Shareware authors are accomplished
     programmers, just like commercial authors, and the programs are
     of comparable quality.  (In both cases, there are good programs
     and bad ones!)  The main difference is in the method of
     distribution.  The author specifically grants the right to copy
     and distribute the software, either to all and sundry or to a
     specific group.  For example, some authors require written
     permission before a commercial disk vendor may copy their
     Shareware.

     Shareware is a distribution method, not a type of software.  You
     should find software that suits your needs and pocketbook,
     whether it's commercial or Shareware.  The Shareware system makes
     fitting your needs easier, because you can try before you buy.
     And because the overhead is low, prices are low also.  Shareware
     has the ultimate money-back guarantee -- if you don't use the
     product, you don't pay for it.

     11   Disclaimer - Agreement For Using SOURCE

     Users of SOURCE must accept this disclaimer of warranty:

          "SOURCE is supplied as is.  The author disclaims all
          warranties, expressed or implied, including, without
          limitation, the warranties of merchantability and of
          fitness for any purpose.  The author assumes no
          liability for damages, direct or consequential, which
          may result from the use of SOURCE."

     SOURCE is a "shareware program" and is provided at no charge to
     the user for an evaluation period of 30 days.  Feel free to share
     it with your friends, but please do not give it away altered or
     as part of another system.  The essence of "user-supported"
     software is to provide personal computer users with quality
     software without high prices, and yet to provide incentive for
     programmers to continue to develop new products.  If you find
     this program useful and find that you are using SOURCE and
     continue to use SOURCE after the trial period, you must make a
     registration payment to Rick Maddy.

     The registration fee will license one copy for use on any one
     computer at any one time.  You must treat this software just like
     a book.  An example is that this software may be used by any
     number of people and may be freely moved from one computer

                                     40
                                   SOURCE

     location to another, so long as there is no possibility of it
     being used at one location while it's being used at another.
     Just as a book cannot be read by two different persons at the
     same time.  Site-License arrangements may be made by contacting
     Rick Maddy.

     You are encouraged to pass a copy of SOURCE along to your friends
     for evaluation.  Please encourage them to register their copy if
     they find that they can use it.  All registered users will
     receive a copy of the latest version of SOURCE in your name,
     printed documentation, a quick reference card, upgrade notices
     and discounts, and customer support.

     12   Registering

     You may use SOURCE for a free 30 day trial period.  If you
     continue to use SOURCE after the 30 day trial period, you are
     required to register your copy of SOURCE.

     When you register SOURCE you will be sent a disk with the latest
     version of SOURCE in your name, printed documentation, a quick
     reference card, upgrade notices and discounts, and customer
     support.  The cost of registration is $25.00.

     You can order directly from Rick Maddy by completing the
     registration form and mailing it and a check to:

                         Rick Maddy
                         2727 Folsom Street, Apt 104
                         Boulder, CO  80304

     The registration form is at the end of this document and in a
     separate file called register.txt.

     If you have any questions or comments, feel free to call Rick
     Maddy at [phone] or leave a mail message on Compuserve at
     76460,1601.

     13   Future Enhancements

     I have a few ideas for making SOURCE an even better program.
     Here is a brief list:

          - Full screen interface to replace command line.
          - Full screen programs for editing printer, language, and
            configuration files.
          - Windows 3.1 version.  (Under development).
          - Optional log file of all printed files.
          - Expanded network/multi-user support.

     I am open to any comments or suggestions for improvements or
     additions to SOURCE.  Please drop me a line.

     14   Acknowledgements


                                     41
                                   SOURCE

     I would like to thank the following people for all there help in
     finishing this program:

          - Scott Sidel for his help with making this program easier
            to use and writing this documentation.

          - Robert Harvey and William Moussiaux for beta testing
            SOURCE.

          - All the kind people who answered my questions on
            Compuserve.

          - All the people who sent in suggestions for improvements
            with their registrations.

     15   Release History

     10/14/92       Version 1.01
          - Original public release.

     10/21/92       Version 1.1
          - Fixed comment highlighting bug.  If two comment markers
            were found one character apart, SOURCE picked the one
            defined first in SOURCE.LNG instead of the first on the
            line.  Example in C:

                    //*** Comment ***

            SOURCE found the /* marker and then the // marker.  Since
            the starting position was only one character apart, SOURCE
            chose the /* marker since it was defined first.

          - Added additional comment support by adding the 'B'
            position specifier.  This allows you to define a comment
            to be anywhere on the line as long as it is the first non
            white space character found.  Example in dBASE:

                    * This is a comment
                    A = B * C

            The '*' is a comment marker.  The entire first line is a
            comment.  The second line does not contain a comment since
            the '*' is not the first character.  Version 1.01 would
            have highlighted the '*' and the 'C' on the second line
            since the comment position was specified to be 0, any
            position.

          - Fixed Append/Overwrite mode with numerous files.  When
            specifying overwrite mode with a list of files, the output
            of each file overwrote the output of the previous file.
            Now, each subsequent file's output is appended to the
            first file's output.

          - Fixed a bug that caused comment highlighting to always be
            on if keyword highlighting was on.

                                     42
                                   SOURCE

          - Fixed a bug that caused keyword highlighting to work
            incorrectly if comment highlighting and block tracing were
            turned off.

          - Added a print statement explaining which language SOURCE
            will default to for an extension defined in more than one
            language.

     10/30/92       Version 1.2
          - Changed 'B' option to allow user to specify whether the
            letters of the banner are made up of the specific letter
            or asterisks.

          - Changed how SOURCE performs query or verify so all files
            are checked before any printing is done.

          - Enhanced a few error messages so they are more clear.

          - Enhanced the 'r' option to allow wildcards when
            redirecting to a file.  The functionality is now
            equivalent to the DOS COPY command.

     11/07/92       Version 1.3
          - Changed how partial keyword matching is implemented.  This
            change now requires that the full keywords be listed in
            the SOURCE.LNG file for languages like dBASE and Clipper.
            This makes their definition like all other languages
            except for the 'part #' after the 'endlang' line in the
            definition.  This change will lower the number of
            extraneous keyword highlighting occurrences.

          - Fixed a small bug that only occurred if you had a [91] or
            [95] in the 8 lpi line of a printer definition.

          - Fixed a small bug that prevented SOURCE from reporting an
            error if the printer code was too long for a given
            attribute.

     04/22/93       Version 1.4
          - Expanded the maximum source code line length from 255
            characters to any length.

          - Expanded the 's' option to allow up to four columns per
            page.

          - Added the 'P' option to allow you to specify how to handle
            form feed characters.

          - Expanded the 't' option to specify the first tab stop in
            addition to the tab size.

          - Fixed a bug that occurred when you asked for highlighted
            keywords but regular comments.  In this case, multi-line
            comments had the 2nd and subsequent lines highlighted
            anyway.

                                     43
                                   SOURCE

          - Removed the restriction that keywords specified in
            SOURCE.LNG had to begin with a letter.  Now any character
            can begin a keyword.

          - Expanded the number of comments per language to 10.

          - Dynamically determine the path separator in pathnames ('/'
            or '\') by looking at the PATH environment variable.  This
            allows SOURCE to work with UNIX shells under DOS.

          - Fixed a problem when showing line and page numbers in a
            page footer.

          - Added the 'Q' option to show print statistics at the end.
            This shows the number of files, pages, and lines printed.

          - Added the 'j' and 'J' options.  This allows you to force a
            specific line or page number as the first number used when
            printing, regardless of the physical number.  This worked
            real well when using SOURCE from within an editor like
            Brief.  I created a macro that will print the currently
            highlighted block of code using SOURCE.  The macros copies
            the code to a temporary file and SOURCE is called to print
            the file.  By specifying the 'j' option with the real line
            number of the first line in the temporary file, I get a
            print out with the proper line numbers.

          - Added the L option to specify what indentation level to
            use when printing block lines from the 'b' option.

          - Added the 'O' option to allow you to print odd or even
            pages, or both with a pause.  This allows for manual
            duplex printing.

          - Added the 'W' option to specify whether long lines should
            be wrapped or not.

          - Changed the SOURCE.PRT file to specify underline, bold,
            and italic printer codes.  This allows comments and
            keywords to be highlighted differently.

          - Changed the 'c' and 'k' options to take 'b', 'u', 'i',
            'o', or 'n' to facilitate the above change to SOURCE.PRT.

          - Changed language blocks to allow two or more blocks to
            begin with the same keyword but have different ending
            keywords.

          - Fixed memory problems when printing with the query option
            on.

          - Changed the filename extension list in a language
            definition to be filename patterns.  This allows a
            language to match on any part of the filename, not just
            the extension.

                                     44
                                   SOURCE

          - Added the 'T' option to allow lines to be truncated to a
            specific length prior to printing.

          - Fixed a small bug with the 'x' option.  The bug prevented
            you from placing a space between the 'x' and the language
            name.

          - Added the 'm' and 'M' options to work with include files.

          - Now compact pathnames that had '..' or '.' references in
            them.  Example:  'c:\src\code\..\file.ext' is now
            'c:\src\file.txt'.

          - Added the &pc function to the page header/footer
            definition to show the total number of pages.  This allows
            for 'Page 1 of 5' type printing in the header.

          - Fixed bug that prevented the 'h-2' option from printing a
            footer on every page.  The 'h-1' option worked though.

          - Added the 'E' option to specify page margins for a
            specific file.

          - Added support for page feed commands within a language.

          - Added support for list files on the command line.






























                                     45
                            SOURCE REGISTRATION

     Remit to:                     From:

     Rick Maddy               Name:__________________________________
     2727 Folsom Street       Company:_______________________________
     Apt. 104                 Street:________________________________
     Boulder, CO 80304        City:__________________________________
     [phone]           State/Zip:_____________________________
                              Phone:_________________________________
     Compuserve Id:           Compuserve Id:_________________________
     76460, 1601
                              Name to register in:
                              (Up to 40 characters)
                              _______________________________________


     Qty:                     Unit Price               Total:

     ____ SOURCE Software     $25.00 (20 + 5 S&H)      ________


     Specify Disk Size:

     _____  5 1/4"       _____  3 1/2"


     Current Version of Source:______________________________________

     Where Obtained:_________________________________________________

     Comments: