home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / PROLST.ZIP / PROGLIST.DOC < prev    next >
Encoding:
Text File  |  1986-11-08  |  13.1 KB  |  256 lines
  1.   ********************************************************************
  2.   *                 Program Lister  Version 1.00                     *
  3.   *                       by Donald Gloistein, 1986                  *
  4.   *                 Credit for some logic routines:                  *
  5.   *                  ListText.C, Don Gloistein, options,etc.         *
  6.   *                  Modify.Pas, Brian Foley, for saving defaults    *
  7.   *                  Qklist.Pas, Unknown, uploaded by two people.    *
  8.   *                  Lister.Pas, Borland International, for the idea *
  9.   *                             and begining logic.                  *
  10.   ********************************************************************
  11.   This is the first draft version.  Please give me feedback on what would
  12.   be more convenient in the program.
  13.  
  14. **************************************************************************
  15.     Written by Don Gloistein , 1986
  16.       Telephone:  713-331-9372
  17.       CIS      :  76010,474
  18.       Addrress : 2500 Fairway Dr. #922
  19.                  Alvin, TX  77511
  20.  
  21.     This program is released to public domain for personal, non-
  22.     commercial use ONLY.  You may use it yourself, give it to your
  23.     friends, or distribute it for a cost-based fee as part of a user's
  24.     group or bulletin board service.
  25.  
  26.  
  27.     As this is just a first draft program, it needs more features and
  28.     the ability to do more sophisicated printing.  When I have added all
  29.     of that, I feel I will be out of the realm of editing existing work
  30.     and into a new program.
  31.  
  32. ********** A Unique ShareWare, Money or Help Me Improve the Program *****
  33.  
  34.     If you ask for support or updates of this program, please expect
  35.     to make a donation.  This donation is either in the form of money or
  36.     sweat.  If you are a programmer like me, you like to improve programs
  37.     and make them more useful.  You teach me, that is worth money to me.
  38.     If this program is of use to you please consider a donation of $10.00.
  39.                            OR
  40.     Contribute Ideas:
  41.     As the program and source is fleshed out, only the compiled version and
  42.     the instalation programs will be given out.  The source code will be
  43.     shared with those who help with suggestions and programming hints.
  44.  
  45.     Compiled on Turbo Pascal ver 3.01A and MS-Dos.
  46. ***********************************************************************
  47. NOTE:    Some routines may be Dos specific, please check.
  48.  
  49.     These include the opening of the 'PRN' file and the MSDOS specific
  50.     cursor control.  These are easy to change.  Global change of the
  51.     OutFile to lst will make it print to the printer.  However, there
  52.     would be no ability to print to a file.  I don't know the way to
  53.     declare it in CP/M, so I hope the change is superficial.  I wanted
  54.     to avoid testing each Write statement against the PrintFile variable.
  55.     Otherwise, I am trying to write with the least amount of problems.
  56.     CAUTION: the Modify.Pas procedure (SaveDef.inc) works only for MSDOS
  57.     Turbo 3.01A.  The file date and time functions (FDTTM.INC) work with
  58.     MSDOS 3.01A.  They use file handles, these could be changed for other
  59.     versions, with little trouble.
  60. *************************************************************************)
  61.  
  62.    PURPOSE:  This Program Lister was designed primarily for Pascal Program
  63.    listing.  I needed a way to print documentation easily for placing in
  64.    binders.  When I used MicroStar, there were so many include files, I
  65.    also did not want to print each one out.  So the include file option
  66.    is in the program.  I also wanted to know where procedures were declared
  67.    and written, thus the quick listing option.  
  68.        While writing and debugging this program, I was using a lot of paper,
  69.    so I wrote to a file.  I left the option in, as I like the speed.  I use
  70.    and editor to read the result.  When I am rewriting a lot, I like to
  71.    see the changes quickly, but don't need a new set of documentation each
  72.    time.
  73.        I have an office full of program listings.  When I am in a major
  74.    project with multiple modules, I get confused which is the latest.  So
  75.    each is printed with a banner naming the file printed and the time and
  76.    date it was last updated.  I can go through back copies and check what
  77.    is what.
  78.  
  79.  
  80.    BACKGROUND: In Software Tools by Kernighan and Plauger, they mention that
  81.    much is written to support writing other programs.  A good tool must be
  82.    easy to master, graceful of mistakes, (some error routines would be useful
  83.    in this program) and make natural assumptions.  It should be written for
  84.    general purposes.   The original listing program in C language, I have
  85.    been using for two years for programing, Focus Procedure documentation,
  86.    etc.  They also show some tools that have complex options, but that
  87.    they don't get in the way of using defaults.  I tried to incorporate
  88.    that idea.
  89.  
  90.        A number of programs assume that everyone has an Epson printer,
  91.    like only defaults, etc.  I have made all defaults configurable from
  92.    the command line.  I don't like to recompile a program each time I
  93.    use it. I was also very tired of getting source code written for some
  94.    other compiler than my own.  Thus, if you have MS or PC Dos, the .COM
  95.    file will run as is.  No need to have Turbo Pascal.
  96.  
  97.    INSTRUCTIONS : type PROGLIST ? <CR> to see the help menu with defaults.
  98.  
  99.    The program should be fairly self explanitory, Please try it and see
  100.    what it is like.  You will get used to it very quickly.  All config
  101.    changes can be made by command line commands or program prompts. Thus,
  102.    if you do not have Turbo Pacal 3.01A, but do run MsDos or PcDos, the
  103.    .COM file will run as is.  The first thing to do is to run the querry
  104.    command   PROGLIST ? <CR> to find out the present defaults.  Then
  105.    change them to your taste; e.g.
  106.             PROGLIST /SXQO-   <CR>
  107.    This will set the default to Quick Listing and Output to printer then
  108.    prompt you for the name you named the ProgList.Com and the path it
  109.    resides in.  After that, unless you change the name or path, you only
  110.    have to use the /S parameter without the X to permanently change the
  111.    defaults.  Without the /S, any changes are for that time only!
  112.  
  113.    The command line parser is very forgiving.  I wrote it that way because
  114.    I intend to have a version for C Language listings.  So the command line
  115.    syntax will accept MSDOS like command options, C or Unix type options:
  116.           PROGLIST filename /O /E+    (MsDos)
  117.           PROGLIST -o -e+ filename     (Unix)
  118.           PROGLIST -oe+  filename      (joined options)
  119.           PROGLIST /O  filename -e+    (Combinations)
  120.    If a logic true is intended the plust [+] can be omitted.  It is included
  121.    for completness.  There are a couple  of exceptions to the jointing.
  122.    If the command is to change a default extension, then it must be the
  123.    last joined option or separately stated.
  124.            PROGLIST /OEDtxt  filename   (.TXT will be default extension)
  125.                or
  126.            PROGLIST /O /Dtxt /E filename (same result)
  127.  
  128.    NOTE: Full usage is :
  129.           PROGLIST <InputFileName [OutputFileName]> [/options|-options]
  130.  
  131.    All options are processed before action is taken to save if /S or /SX
  132.    is given.  There can be only one file name given. If a second filename
  133.    is given, it is assumed that it will be the output file.  Thus, you
  134.    do not have to specify /O# if you enter the second name. A default
  135.    extension of .PRN is added if no extension is given.
  136.  
  137.    The help listing can be called at a number of levels,
  138.          PROGLIST ?
  139.          PROGLIST /?
  140.          PROGLIST
  141.              prompt for file name: ?
  142.    I know this is over kill.  But I give something for everyone.
  143.    The program is not completely failsafe, I am sure.  But it does
  144.    not write to a file if there is one existing.  As yet, there is
  145.    no provision for wild cards or path searches.  I am not sure
  146.    it is needed. (Any Comments?)
  147.  
  148.  
  149.    PROBLEM:  When in quicklisting mode, there is a time that the whole
  150.     * procedure or function line will not be written out. When it is
  151.       written like this:
  152.     *    Procedure   anyone(var:var1,
  153.                             var:var2);
  154.          instead of:
  155.     *    Procedure   anyone(var:var1,var:var2);
  156.       There is a temporary fix in the GetFirstWord function, it can
  157.       be commented out.  It will limit the search to the first number of
  158.       columns as declared by MaxColCheck variable.
  159.  
  160.    I did some short cuts to delete and find characters.  These have some
  161.    notes in the source to watch out for endless loops.  If you play with
  162.    the source, watch out for them.
  163.  
  164.   FUTURE:  Support of dot {.pa} commands for formatting.
  165.            Filling out the basic listing shell to include many features,
  166.            while keeping the basic Software Tool concept intact.
  167.            Installable Printing format strings.
  168.  
  169.   OPTIONS:
  170.  
  171.   This is a quick listing of the details of the extensions.  The options
  172.   are self explanatory for the most part.
  173.  
  174.   Options take the form of a designator, a slash '/' or a dash '-' followed
  175.   by the option letter.  This is followed by a specifier.
  176.       Boolean (true/false) options:
  177.           Specifier  =  '-'             False
  178.           Specifier  =  '+' or (none)   True
  179.       Number  n options:
  180.           Specifier  = one to three digits.
  181.       Letter  a options:
  182.           Specifier  = one to three letters.
  183.           Letter specifiers must be the final joined option or listed
  184.           separately.
  185.  
  186.   /Daaa    This changes the default extension for the main file.
  187.            You must use this as the last option in a sequence or
  188.            a separate option. It changes it to the text '.AAA',
  189.            do not put the dot separator in the command.  Less than
  190.            three letters will be filled with blanks.
  191.  
  192.   /Caaa    This changes the default extension for the include files.
  193.            Same usage and note as for the /D option.
  194.  
  195.   /S       This will save the new defaults after they are processed.
  196.            I have always hated to recompile a program or worse, not have
  197.            the source listing and want to change the parameters.
  198.  
  199.   /SX      This will save any changed defaults and prompt for the file
  200.            name and path name.  This gives you a chance to put the file in
  201.            your \BIN directory for instance and change the name.  You can
  202.            have a number of programs configured differently.  I use two,
  203.                   AList.com  to list the entire document
  204.                   QList.com to list the headings.
  205.            Both are set up so that I just use a couple of parameters
  206.            to customize the printing.
  207.  
  208.   /Q       These options are listed together, they are actually logic
  209.   /A       toggles.  Only the last one specified is in effect.  /A will
  210.            cause the listing to list all lines in main file and if /I
  211.            then in the include file.  /Q selects just the procedure and
  212.            function key words to list.
  213.  
  214.   /I       This selects listing the include files.
  215.  
  216.   /M       This will list all lines in the main file upto the first
  217.            procedure or function.  This is useful to include heading
  218.            documentation and globals in the listing, but just quick
  219.            listing the balance of the document.
  220.  
  221.    /Vnnn   This sets the vertical tab.  It is used at the page top. Use
  222.            it to give yourself white space.  I set it to 3 because I use
  223.            top hole file folders.
  224.  
  225.    /Lnnn   This sets the number of printed lines per page, NOT the total
  226.            lines.  Use this and /V option to format top and bottom white
  227.            space.
  228.  
  229.    /B      This places a Banner with the file's date and time of change
  230.            on both top and bottom of the page.  If you have had a pile of
  231.            listings on the floor and tried to figure out which was the
  232.            latest, you will appreciate it.  The Banner line and following
  233.            space is subracted from the /L option. The banner is considered
  234.            part of the printed lines per page.
  235.  
  236.    /T      This selects tab expansion.  Some listings I download have tabs
  237.            or some of the documentation has form feeds, this filters all of
  238.            them so that the lister works better.  I have tried to make
  239.            allowances for many people's different writing styles and editors.
  240.            This slows the line processing down a little, but is useful.
  241.  
  242.    /Hnnn   This used with the /T option to set the size of the tabs. Some
  243.            editors are set up for Pascal (2) or C (3) or (4) or text (8).
  244.            It has no effect if /T- is used.
  245.  
  246.    /Wnnn   This sets the printed characters per line (page width).  This
  247.            is very useful if you have a printer that prints compressed or
  248.            more than 80 chars per line.  (I hate programs that think all
  249.            printers are 10 pitch and 80 chars.)
  250.  
  251.    /Rnnn   Use this to pad the right margin with blanks.  When the line
  252.            is longer than the page width, the wrapped line will be padded
  253.            also.  I leave it to 0 because I punch holes at the top.  This
  254.            is best for three ring binders.
  255.  
  256.