                           A Manual for TPUTOOL

TPUTOOL is a ShareWare program that may be registered through CompuServe
(registration number #479) or directly with the author (se README.1ST).
If you continue to use the program, please register it.


Description:

TPUTOOL accepts a command-line input consisting of a (qualified) filename
and any number of conditional defines.  The tool then parses the indicated
file and all referenced units, include files, link files, etc., collecting
names and relationships.  The only limit is a total file count of not more
than 64 files (to be removed on a later release).

The parser does a lot of syntax checking while parsing.  If a syntax error
is found, a screen message is displayed and parsing is suspended for that
file (although it continues for other members of the tree).  The parser has
been tested on all of my own source files and all of the sample files that
come with TP 6.0.

TPUTOOL is a utility program written especially for developers of large
Turbo-Pascal programs.  TPUTOOL displays the parent-child relationship of
units and permits the user to display statistics and list files

TPUTOOL is written entirely in Turbo-Pascal Version 6. The windowing, while
looking much like TurboVision, is my own homemade version.  I found that
TurboVision is generally best avoided when upgrading existing programs,
although I did use many parts of TurboVision such as the collection and
sorted collection objects!


The files:

TPUTOOL is distributed as a self-extracting zip named TT.EXE.  When expanded,
you will have TPUTOOL.EXE, TPUTOOL.OVR, and a number of *.UIF files.  The UIF
files contain information pertaining to the Borland-supplied units such as
CRT, DOS, SYSTEM, etc.

The TPUTOOL.OVR and the *.UIF files should either be in the current
directory along with TPUTOOL.EXE or made visible by adding the directory in
which they reside to the APPEND path in your AUTOEXEC.BAT file.


The author:

I am retired IBM Senior Engineer-Programmer who started programming in
AutoCoder on an IBM 705 in 1957.  I have written in just about every
language except Lisp over the years.  After I retired from IBM, I formed
JWIrwin Consulting Ltd., providing custom programming services.  I am
currently programming in Forth, C, C++, and Turbo-Pascal.


System requirements:

TPUTOOL requires an 80286 or better machine with a color display (CGA, EGA,
or VGA.  I developed the tool under OS2 2.0 on a 16-mhz PS2-80 and tested it
under OS2 1.3 on a PC-AT upgraded to 33-mhz 80486.

Screen updates are almost instantaneous on my fast machines, but may look a
little ragged on slower machines.  A mouse is supported and is very
desirable, but is not absolutely required.


Directories:

All Pascal source files must be in a single directory and have the .PAS
extension (.INC for include files, .OVR for link files).  TPUTOOL must
either be run in the same directory as the Pascal source files or with a
fully qualified path to that directory.


Program Startup:

Enter
        TPUTOOL <fn> [<def> <def> ...]

     <fn> is a fully qualified path to the base file to be expanded (usually
     the main program).  If you do not provide <fn>, you will be prompted
     for it.  The .PAS suffix is optional; if you do not provide it, the
     program will.

     <def> is a command line conditional symbol.

     Press F1 at most any time for context-sensitive help.


Main display:

The initial display consists of one to four columns of file names.  One file
is highlighted to indicate selection.  All files are color-coded to indicate
the type of file (Program, Unit, Include, etc.).  The base file you supplied
at startup is selected (highlighted in white).


       TPUTOOL         JWIFLASH
       TPUFILE         JWIMOUSE.INC
       TPUINIT         JWIPOPUP
       TPUSCAN         JWIUTIL
       TPUSRCH
       TPUUTIL
       TPUVARS
       ...

    F1-Help  F3-Quit  F4-Config F7-Tree  F8-Details  F10-Identifiers  Print

By using the arrow keys or mouse, move the highlight to the file of
interest, and execute any of the following menu choices by clicking the
mouse on the highlighted number or pressing the indicated function key:

F1 displays context sensitive help.
F4 displays a submenu that allows the user to select screen colors.
F7 or left mouse button displays the files in a tree form
   (see "Tree Display" below).
F8 or right mouse button displays a submenu of details
   (see "Details" below).
F10 displays a list of all public identifiers.

Print is not a PrintScreen.  Rather, it prints an alphabetized list of USUS,
OVERLAY, LINK, and INCLUDE files that make a great index for a book of
listings.

If you are using a mouse, clicking on a filename highlights it.  Clicking
again on the highlighted file causes an action on that file.  Clicking the
left button displays the tree beginning with the selected file.  Clicking
the right button displays a submenu that permits listing the selected file
or displaying a number of statistics for that file.  You must click on the
alphabetic filename and not on the dashed lines or numbers.


Tree display:

The USES tree display is actually two displays, a "right hand" display that
is initially shown, and a "left hand" display.  To move right in the tree,
click on a filename in the righthand column.  To move left in the tree,
click on a filename in the left column.  You must click on the alphabetic
filename and not on the dashed lines or numbers.

The right hand display consists of two columns with the base file on the
left and a sorted list of its USES files on the right.  The base file is
initially highlighted.  Parenthesized numbers indicate the number of
linkages to each file.  For example:

TPUTOOL ---(9)-------+------(15)--- CRT
                     +------(17)--- DOS
                     +------(1)---- PRINTER
                     +------(1)---- TPUINIT ---(4)--->
                     +------(5)---- TPUSHOW ---(6)--->
                     +------(3)---- TPUSTATS --(8)--->
                                       ...
                                       ...

      F1-Help  F3-List  F8-Details  F10-Identifiers  Print


Here, the base file, TPUTOOL, has 9 USES files.  The standard TP files CRT,
DOS, and PRINTER can not be followed further since there is no source to
expand.  The files TPUINIT, TPUSHOW, and TPUSTATS have USES statements and
can be further expanded.  16 files are displayed at a time.  Any remaining
files can be displayed by paging up and down.

The left-hand display consists of two similar colums with the base file on
the right and a list of files with USES statements referencing the base file
on the left.

<--(4)--- TPUINIT ---(4)---+-----(5)--- TPUPOPUP --(7)--->
<--(1)--- TPUFIND ---(7)---+
<--(3)--- TPUSHOW ---(11)--+
            ...
            ...

      F1-Help  F3-List  F8-Details  F10-Identifiers  Print


TPUPOPUP is referenced in the USES statements of 5 files, TPUINIT, TPUFIND,
and TPUSHOW . TPUPOPUP, in turn, has 7 files in its USES statement.

By using the arrow keys or mouse, move the highlight to the file of
interest, and execute any of the following menu choices by clicking the
mouse on the highlighted number or pressing the indicated function key:

F1 displays context sensitive help.
F3 returns to the list display.
F8 displays a submenu of details (see "Details" below).
F10 displays a list of all public identifiers.


If you are using a mouse, clicking on a filename highlights it.  Clicking
again on the highlighted file causes an action on that file.


Public names:

Pressing F10 when the main display or USES tree display is on the screen
displays a window with a list of public names of functions, procedures,
variables, constants, constructors, destructors, types, etc.  Each name is
identified by category and the file in which it is defined is displayed.
The following is copied from an actual run on the TP 6.0 sample program
GENFORM.

const  ALLOWDUPLICATES  (TRUE)                        GENPHONE
const  BUSINESS (numeric)                             GENPHONE
var    COLLECTION (PSORTEDCOLLECTION)                 GENFORM
const  COMPANYWIDTH (numeric)                         GENPHONE
const  DATA (array of TDATAREC)                       GENPHONE
const  DATACOUNT (numeric)                            GENPHONE
const  DATAKEYTYPE (KEYTYPES)                         GENPHONE
var    F (PFORM)                                      GENFORM
const  FEMALE (numeric)                               GENPHONE
var    I (INTEGER)                                    GENFORM
var    KEYTYPES (enumerated)                          DATACOLL
fun    MAKEFORM (PFORM)                               GENPHONE
const  MALE (numeric)                                 GENPHONE
const  NAMEWIDTH (numeric)                            GENPHONE
var    P (POINTER)                                    GENFORM
type   PDATACOLLECTION (ptr to TDATACOLLECTION)       DATACOLL
       more ...

Use the PgUp, PgDn, or up and down arrows to highlight the desired name,
then press Enter to return to the USES tree display with the file containing
that identifier as the anchor file.

Pressing F4 displays a filter selection that allows the user to display
            or block out categories of identifiers.
Pressing F7 displays the source containing the identifier.
Pressing F8 displays the ancestry of the identifier.
Pressing F9 prints a formatted list of all public identifiers.


Duplicate names:

Currently, TPUTOOL shows only the most recent defininition of duplicate
public names.  A later version will mark duplicates and properly handle
local references to them.


Details:

The details menu allows display of file dates and sizes, formatted listing
of source files, and alphabetized display of lists of program items such as
compiler directives and conditional defines.


Printing:

Choosing the "L"ist option from the statistics menu formats and prints the
source file including all nested include files.  Pages are headed with the
program name and page number.

The program is set up to use the Turbo-Pascal "LST" device as the only
printer.  I have an IBM Proprinter II attached and this is the only printer
I have tested the program with.  I used no special control codes, so I
expect that most any printer will work.


Manual:

Use the TP 6.0 sample program "Lister" to print this file to print this file
in pagenated form for use as a manual.  Execute "LISTER README.1ST".


Futures:
In last quarter '92, a new release of TPUTOOL will be available with:
    o  Improve parser with expanded "Lint" checking.
    o  Add duplicate identifier checking and handling
    o  Add user selectable screen colors.                         (rel 1.1)
    o  Add DOS, GRAPH, SYSTEM, and CRT unit identifiers.          (rel 1.1)
    o  Expand object heirarchy display.
    o  Add filter to select identifiers to be displayed           (rel 1.1)
    o  Remove the 64-file limit.
    o  Permit shelling out to DOS.

 In first quarter '93:
    o  release TP for Windows version with graphic trees
    o  Continue parsing after source code errors.
    o  Rerun tree without leaving the program (to capture source changes)


History:
  Release 1.0  11/21/92
    Initial release uploaded to CompuServe

  Release 1.1  11/28/92
    o  Added U_F (Unit Info Files) for DOS, GRAPH, CRT, OVERLAY, and SYSTEM
       identifiers.
    o  Added filter to selectively display identifiers by class.
    o  Added user color configuration.

