home *** CD-ROM | disk | FTP | other *** search
/ The C Users' Group Library 1994 August / wc-cdrom-cusersgrouplibrary-1994-08.iso / vol_300 / 345_01 / readme.tlc < prev    next >
Text File  |  1989-07-10  |  8KB  |  183 lines
  1. /* -- remove this header before using file! --
  2. HEADER:        The Last Cross-Referencer;
  3. TITLE:        TLC/TLP - The Last Cross-Referencer;
  4. VERSION:    1.01;
  5.  
  6. DESCRIPTION: "TLC/TLP.
  7.             General Information on use of TLC and TLP";
  8.  
  9. KEYWORDS:    Utility, Cross-reference, C, Pascal, Apple, Macintosh, APW, Aztec;
  10. SYSTEM:        Macintosh MPW, v3.0;
  11. FILENAME:    README.TLC;
  12. WARNINGS:    "Has not yet been ported to MS-DOS.
  13.             Shareware, $20 Check/Money Order suggested.";
  14.  
  15. SEE-ALSO:    TLCHELP.DOC,TLPHELP.DOC;
  16. AUTHORS:    Eduard Schwan;
  17. COMPILERS:    AZTEC C65 v3.2b, APPLEIIGS APW C v1.0, APPLE MACINTOSH MPW C v3.0;
  18. */
  19.  
  20. Copyright (c) 1987-1989, Eduard Schwan Programs [esp] - All rights reserved
  21. TLC (The Last C-Cross-Referencer) and TLP (same, but for Pascal) are
  22. Cross-Reference Generators crafted and shot into the Public Domain by
  23. Eduard Schwan.  The source code and executable program may be freely
  24. distributed as long as the copyright/author notices remain intact, and
  25. it is not used in part or whole as the basis of a commercial product.
  26. Any comments, bug-fixes, or enhancements are welcome.
  27. Also, if you find TLC and it's source code useful, a contribution of
  28. $20 (check/money order) is encouraged!  Hopefully we will all see more
  29. source code distributed!
  30.     Eduard Schwan, 1112 Oceanic Drive, Encinitas, Calif. 92024
  31.  
  32. --------------------------------------------------------------------------
  33.  
  34. A note about the source code:
  35.  
  36. There are really two programs intertwined in this source.  TLC is a C source
  37. cross-referencer, and TLP (a recent addition) is a Pascal source cross-
  38. referencer.  I wanted to put a real parser in here to help identify variable
  39. usage (declaration, reference, assignment), but of course, it was needed
  40. before it was done, and some quickie smarts was inserted instead just to get
  41. it working.  Of course, I have not yet gone back to replace the parser, and
  42. probably never will.. it is good enough for me, and I'm lazy!
  43. Anyway, TLC came first, and all the files named TLCxxxx.C are
  44. needed to compile TLC.  TLP came later as an appendage to TLC.  It uses many
  45. of these TLCxxx files too, and it additionally needs all the TLPxxxx.C files.
  46. The MPW Make files are included here (TLC.MAKE and TLP.MAKE), but a table below
  47. should show you who uses what.
  48. DOCUMENT        NEEDED BY            NEEDED BY            NEEDED BY
  49. FILE            BOTH                TLC                    TLP
  50. ---------        ----------            -----------            -----------
  51. readme.tlc        tlc.ext                tlc.c                tlp.c
  52. tlcHelp.Doc        tlc.h                tlc.make            tlp.make
  53.                 tlccmd.c            tlcgtok.c            tlpgtok.c
  54.                 tlcparm.c            tlcparm.dat            tlpparm.dat
  55.                 tlcparm.h            tlcprocf.c            tlpprocf.c
  56.                 tlcresw.c            tlcresw.dat            tlpresw.dat
  57.                 tlcsetp.c
  58.                 tlcstat.c
  59.                 tlcutil.c
  60.                 tlcxref.c
  61.  
  62. Source code history:
  63.  
  64. TLC was originally written on a 64k Apple II+ in Aztec C65, then ported to
  65. APW C on an Apple IIGS, then to MPW C on an Apple Macintosh II.  I have not
  66. done any regression testing after adding the compiler switches, but it
  67. should still run on a IIGS.  I am sure it has grown far too big for even the
  68. Aztec Interpreted C on the Apple II.  I have not yet ported it to an MS-DOS
  69. machine, but it should go just as smoothly as the other ports.
  70.  
  71. I have not made an effort to group machine-specific functions, but they hopefully
  72. just turned out that way.. all in TLCUTIL.C.  Namely get_time(), get_mem(),
  73. check_user_abort(), and maybe do_form_feed().  Also check out TLC.H thoroughly.
  74. Some interesting constants are hiding in there.
  75.  
  76. This has been a three year (not-so-copious) spare-time effort on my part,
  77. and am hoping that this will be as useful to you as it has been to me.  If you
  78. are interested in porting this to yet another machine, or have comments or
  79. bug reports, or just want to say "hi" or send me money, please feel free to
  80. contact me.  I am on AppleLink (JL.TECH, atten:Eduard Schwan), or at the address
  81. below.
  82.  
  83.     Eduard Schwan
  84.     1112 Oceanic Drive
  85.     Encinitas, California  92024
  86.  
  87. --------------------------------------------------------------------------
  88.  
  89. These are the known bugs/features-to-be-added to
  90. The Last [C/Pascal] Cross-referencer, as of 7/02/89 (v1.01) [esp]:
  91.  
  92.     1:Xref case-sensitivity isn't here yet (do_case_sens/do_xcase_sens).
  93.       That is, one can't have case-sens. ids without having case-sens.
  94.       xref sorting, or vice versa.  DoCaseSens works, but DoXcaseSens
  95.       is ignored.  The way I did the symbol table, it is an icky chore
  96.       and may never show up, but hey, I haven't needed it yet either.
  97.  
  98.     2:Underscore-significance (Pascal) isn't here yet.
  99.       (now it is.. 0.90 beta)
  100.  
  101.     3:Include file handling isn't here yet.  Not only that, but the scanner
  102.       doesn't recognize the <incfile.h> as a string, so "incfile" and "h"
  103.       show up as separate xref'ed identifiers (hmm, could be called a feature?)
  104.     
  105.     4:The full-blown parser isn't here yet, instead some quickie C smarts
  106.       were kludged into the scanner (tlc.gtok.c) to make this useable in
  107.       a "reasonable" time frame.
  108.       (NOTE: as of 1.01, it now looks like a pain to retrofit it in..)
  109.       
  110.     5:The symbol table is 100% memory-resident, and therefore the size of
  111.       the source code you throw at TLC is limited by available heap space.
  112.       Another parameter (DO_BIG_XREF?) should be added that makes tlc/tlp
  113.       call alternate symbol table routines that do disk I/O..
  114.       
  115.     6:The statistics option should print out more interesting stuff someday..
  116.       (v1.00 added a list of file names..)
  117.     
  118.     7:The Macintosh version should be jazzed up with heap-avail displayed
  119.       every once in awhile, and it needs a commando interface for us lazies,
  120.       and the time/date need to be called & stuck into ctime_string in
  121.       tlc.util.c.
  122.       (heapAvail & time/date was just fixed in 0.95 beta, so ??? no longer
  123.       appears for time/date.)
  124.  
  125.     8:An fopen() in MPW C (Macintosh) creates a typeless, creatorless file
  126.       (to be expected, really) which means the output text file (TLC.OUT)
  127.       cannot be read by any text editors.. I could make TLC write to stdout
  128.       & redirect, tell users to type "setfile -t TEXT -c 'MPS ' tlc.out" after
  129.       running TLC in MPW, or find a way to set the TYPE of the file inside TLC.
  130.       C purists would argue that redirecting to stdout is the way it should be
  131.       done, to which I say, "yeah, I should have made it that way in the
  132.       beginning.."  It doesn't look that hard to change, but I am still
  133.       pondering the ramifications..
  134.  
  135.     9:TLC knows what a function declaration is by blindly deciding that any
  136.       identifier followed by an open paren (that is not a #define macro) at
  137.       block level zero is a function decl.  This works 100% of the time when
  138.       the C source code's { } match up.  But the following (avoidable) practice
  139.       will goof up TLC's ability to detect functions beyond this point:
  140.               a = b;
  141.             if (a == 1)
  142.     #ifdef debug_on /* TLC ignores conditional compilation & does it all */
  143.                 {    /* in one.. */
  144.                 b = 3;
  145.     #else
  146.                 {  /* in two.. */
  147.                 b = 4;
  148.     #endif
  149.                 }    /* out two.. but not to one! */
  150.  
  151.       This can be avoided by fully capturing (or not capturing) braces in
  152.       conditionals:
  153.               a = b;
  154.             if (a == 1)
  155.     #ifdef debug_on
  156.                 {    /* in one.. */
  157.                 b = 3;
  158.                 }    /* out one */
  159.     #else
  160.                 {  /* in one again.. */
  161.                 b = 4;
  162.                 }    /* out one */
  163.     #endif
  164.  
  165.     10:Emphasis only works on the xref symbols.  It doesn't yet work for
  166.        function headers, comments, or reserved words in the listing output.
  167.  
  168.     11:I think TLC sometimes forgets a reference or two in BIG xref.s with
  169.        lots of files.  I think I have only seen it happen, but only a couple
  170.        of times, and am tracking it down now.
  171.        (Fairly exhaustive debugging with lotsa xreffed files turned up nothing..
  172.        I am giving up this search until a known repeatable occurrance is found,
  173.        so v1.00 may still have this problem!?)
  174.  
  175.     12:If only a cross-reference is done, a bunch of spaces are put in the
  176.        beginning of the file.  I think TLC.PROCF.C is the culprit, and not
  177.        all output is suppressed..
  178.        (Nope, it was new_page, fixed it with an additional parm. in v1.00)
  179.  
  180.     13:The source file names were changed in v1.00 to names edible by the
  181.        MS-DOS community, just in case portability happens.. All names with
  182.        multiple periods got the 1st period stripped (TLC.PROCF.C => TLCPROCF.C)
  183.