home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / PSP.ZIP / PSP.DOC next >
Encoding:
Text File  |  1988-06-12  |  10.9 KB  |  331 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.                             Pascal Source Processor
  10.  
  11.                                     PSP.EXE
  12.  
  13.  
  14.  
  15.  
  16.  
  17.                       A Shareware Programmer's Utility for
  18.                                 Turbo Pascal 4.0
  19.  
  20.                                        by
  21.  
  22.  
  23.                                   Lee Lorentz
  24.                              3205 Harbor Lane North
  25.                               Plymouth, MN  55447
  26.                                  (612) 557-1308
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.             Copyright (C) 1988 as an Unpublished Work by Lee Lorentz.
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.                      Pascal Source Processor Documentation
  68.  
  69.  
  70.  
  71.  
  72.  
  73.                                     -------
  74.                                     SUMMARY
  75.                                     -------
  76.  
  77.        PSP produces a formatted listing of a Turbo Pascal source file,
  78.        including a banner page, a table of contents, the source code
  79.        listing, and a cross-reference of the symbols found in the
  80.        source.  Output can be directed to any one of the printer, the
  81.        screen, or a text file on disk.
  82.  
  83.        The files included on the distribution disk include:
  84.             PSP.EXE    - The executable program
  85.             PSP.DOC    - This documentation file
  86.             SAMPLE.PAS - A sample source code file
  87.  
  88.  
  89.  
  90.  
  91.                               --------------------
  92.                               INPUT CONSIDERATIONS
  93.                               --------------------
  94.  
  95.        PSP was designed to function with Turbo Pascal source code files
  96.        written to a specific set of programming standards.  It will pro-
  97.        cess files that vary from these standards, but with varying de-
  98.        grees of disappointing results.
  99.  
  100.        First, PSP expects to work with source code files that are lim-
  101.        ited to eighty (80) characters or less per line.  This has a two-
  102.        fold purpose.  An 80-character limit makes the source files eas-
  103.        ier to manipulate on screen while editing.  Also, the limit makes
  104.        the listing fit on a narrow carriage printer.
  105.  
  106.        Next, PSP executes a page break immediately before the reserved
  107.        words (among others) 'FUNCTION' and 'PROCEDURE' (case sensitive),
  108.        if they occur beginning in column one.  This means that comments
  109.        regarding a procedure or function should follow the block they
  110.        describe, if they are to be printed on the same page with the
  111.        related code.
  112.  
  113.        Either comment delimiter pair ('(*', '*)' or '{','}') will be
  114.        properly handled.  However, PSP requires that a comment may not
  115.        extend across multiple lines.  Each physical line of a comment
  116.        must be delimited at both the beginning and ending of each line.
  117.        In addition, PSP assumes that the beginning of a comment
  118.        signifies the end of executable code on a given line.
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.                         Copyright (C) 1988, Lee Lorentz
  129.                                      Page 1
  130.  
  131.  
  132.  
  133.                      Pascal Source Processor Documentation
  134.  
  135.  
  136.  
  137.  
  138.  
  139.                                   ------------
  140.                                   INSTALLATION
  141.                                   ------------
  142.  
  143.        The first step in the installation (and I CAN'T STRESS IT ENOUGH)
  144.        is to make a working copy of the distribution disk and PUT THE
  145.        ORIGINAL AWAY!!!  PSP is not copy protected, and a copy may be
  146.        produced by the standard DOS COPY command (see your DOS manual).
  147.  
  148.        If you will be working from a floppy-based system, your install-
  149.        ation is complete.  If you will be working from a hard disk sys-
  150.        tem, I recommend that you copy the PSP.EXE file into the source
  151.        code sub-directory.  This is only for convenience, as you can
  152.        specify the full file specification of a source file.  If PSP is
  153.        in the same directory as your source file, you need only enter
  154.        the file name.
  155.  
  156.  
  157.  
  158.  
  159.                                    ----------
  160.                                    TO USE PSP
  161.                                    ----------
  162.  
  163.        First, make the source code sub-directory the current directory,
  164.        using the DOS CHDIR command.  Then, from the DOS command line
  165.        type 'PSP' (without the quote marks) and press [RETURN].  A data
  166.        entry screen will then display.
  167.  
  168.        Type in the specification of the source file to be processed.  If
  169.        both PSP and the source file are on the same drive, you need not
  170.        enter the drive.  If they are in the same directory, you need not
  171.        enter the path.  The full file name is required in any case.  If
  172.        PSP cannot find the name entered, the prompt will redisplay.  To
  173.        exit from PSP without processing a file, enter 'END' for a file
  174.        name.
  175.  
  176.        The prompt will move down to the destination selection.  There
  177.        are three numbered choices displayed.  To make a selection, just
  178.        press the number and processing will begin.  It is not necessary
  179.        to press [RETURN].  You will notice that selection one is con-
  180.        tained within square brackets ('[1]').  The square brackets indi-
  181.        cate that this is a default response.  If you just press [RETURN]
  182.        selection one will be assumed.  Selection 1 sends the output dir-
  183.        ectly to the printer (using LPT1:).  Selection 2 sends the output
  184.        to the screen.  Selection 3 sends the output to a text file on
  185.        disk.  If you choose selection 3, an additional prompt will ap-
  186.        pear for the output file name.  I recommend that a suffix of .PRN
  187.        be used for the text output files on disk.  Again, even though
  188.        the prompt doesn't suggest it, a full file specification can be
  189.        entered.
  190.  
  191.  
  192.  
  193.  
  194.                         Copyright (C) 1988, Lee Lorentz
  195.                                      Page 2
  196.  
  197.  
  198.  
  199.                      Pascal Source Processor Documentation
  200.  
  201.        Once the above prompts have been answered, processing begins.  As
  202.        each step in the process begins, an advisory message appears on
  203.        the screen.  The processing steps are:
  204.             Scanning source file line
  205.             Printing banner page
  206.             Parsing line
  207.             Sorting
  208.             Printing table of contents page
  209.             Printing source code listing page
  210.        The Scanning and Parsing lines are updated with the line number
  211.        from the source code file as processing proceeds.  The last three
  212.        Printing lines are updated with the page number as processing
  213.        continues.  PSP returns to the DOS prompt when printing is com-
  214.        plete.
  215.  
  216.  
  217.                                ------------------
  218.                                OUTPUT DESCRIPTION
  219.                                ------------------
  220.  
  221.        The output of PSP is produced in four main sections.  Each of
  222.        these is described in more detail in the paragraphs below.  These
  223.        sections are 1) Banner Page, 2) Table of Contents, 3) Source
  224.        Listing, and 4) Symbol Cross Reference.
  225.  
  226.        Banner Page
  227.        The banner page provides summary information about the process.
  228.        At the top left and right corners are the run time and date.
  229.        Centered below on the page is the file name (stripped of any path
  230.        description), in enlarged and boldface print.  This is followed
  231.        by the line count from the source file, and the source file's
  232.        date and time stamp from the directory entry.  This helps to keep
  233.        track of what version of your program is represented by your
  234.        listing.
  235.  
  236.        Table of Contents
  237.        The table of contents provides a listing of the first line of
  238.        each function and procedure declared in your source file.  It is
  239.        case insensitive, and includes the line number of the declaration
  240.        within your source file.  The line number is printed in 10-pitch
  241.        (pica) spacing, and the declaration line is printed in 12-pitch
  242.        (elite).  This is how PSP can put a full 80-character line of
  243.        source on a 8" wide sheet.
  244.  
  245.        Source Listing
  246.        The source listing is printed next.  Again, the line number is
  247.        printed in 10-pitch (pica) spacing, and the declaration line is
  248.        printed in 12-pitch (elite).  The page break scheme is fairly
  249.        simple.  When one of 'TYPE', 'CONST', 'VAR', 'FUNCTION', or 'PRO-
  250.        CEDURE' (case sensitive) is found beginning in column one of the
  251.        source listing, a page break is executed before printing the sym-
  252.        bol.  This is why comments relating to a function or procedure
  253.        should follow the declaration.  PSP attempts to keep one function
  254.        or procedure per page.  This may seem a waste of paper, but dur-
  255.        ing the development process, it provides 'white space' on each
  256.        page which provides a working area for handwritten notes.
  257.  
  258.  
  259.  
  260.                         Copyright (C) 1988, Lee Lorentz
  261.                                      Page 3
  262.  
  263.  
  264.  
  265.                      Pascal Source Processor Documentation
  266.  
  267.  
  268.        Symbol Cross Reference
  269.        The symbol cross reference is printed next.  The symbols are
  270.        printed alone on a line, indented four spaces from the left
  271.        margin in 10-pitch and double-strike mode.  The line number(s)
  272.        where the symbol was encountered are printed next, in 12-pitch.
  273.        Hexadecimal constants are printed first (prefixed with a '$'),
  274.        followed by symbols beginning with a capital letter, followed
  275.        finally by symbols beginning with a lower case letter.  The final
  276.        page of the symbol cross reference ends with a page footing with
  277.        no following header.  This leaves the printer set at it's top of
  278.        form position, ready for the next print job.
  279.  
  280.  
  281.  
  282.  
  283.                                   ------------
  284.                                   REGISTRATION
  285.                                   ------------
  286.  
  287.        PSP is distributed under the Shareware concept.  This means that
  288.        you are encouraged to pass copies to your friends and associates.
  289.        However, it is NOT public domain.  If you find that PSP is of use
  290.        to you, a contribution of $25.00 would be greatly appreciated.
  291.        Registration also includes telephone support.  To help keep the
  292.        cost of quality software down, fill in the registration form
  293.        below and send it with your contribution to:
  294.  
  295.             Lee Lorentz
  296.             3205 Harbor Lane North
  297.             Plymouth, MN  55447
  298.             (612) 557-1308
  299.  
  300.  
  301.            Company            ______________________________________
  302.  
  303.            Name               ______________________________________
  304.  
  305.            Address            ______________________________________
  306.  
  307.            City, State, Zip   ______________________________________
  308.  
  309.            Telephone          (     ) ______________________________
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.                         Copyright (C) 1988, Lee Lorentz
  327.                                      Page 4
  328.  
  329.  
  330.  
  331.