home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / prgramer / tlc / tlc.doc < prev    next >
Encoding:
Text File  |  1993-06-24  |  8.7 KB  |  243 lines
  1. ------------
  2. INTRODUCTION
  3. ------------
  4.  
  5. TLC is a utility that creates a formatted listing, optionally with a
  6. cross-reference, from a given set of C source files.  The format and
  7. content of the listing can be controlled by various command-line
  8. switches and directives in the C files.  I wrote it for two reasons.
  9. First, most C compilers do not provide a listing capability.  Second,
  10. all the third-party C listers I looked at didn't quite provide the
  11. mix of form and functionality I wanted.  Some were overkill, while
  12. others did little more than add line numbers to the source code.  So
  13. I decided to write my own.  This program is continually evolving.  I
  14. want it to be useful to as wide an audience as possible.  If you
  15. would like to see a feature added, please contact me.  All requests
  16. will be given serious consideration.  Also, all bug reports are
  17. welcome.
  18.  
  19. Tom Lowery
  20. Internet: tlowery@pascal.acm.org
  21.  
  22. Now for the yucky legal stuff...
  23.  
  24. ----------------------
  25. LICENSE AND DISCLAIMER
  26. ----------------------
  27.  
  28. TLC is Copyright 1993 by Tom Lowery.  All rights reserved.
  29.  
  30. This program is free software; you may use it and redistribute it
  31. without restriction.  You may not, however, sell, lease, license, or
  32. in any other way charge others a fee for the use of this software, or
  33. modify the software or documentation.  A nominal fee may be charged
  34. to cover copying or media costs.  The software documentation,
  35. including License and Disclaimer, must remain intact with all
  36. distributed copies.
  37.  
  38. Because this software is free, it is distributed WITHOUT ANY
  39. WARRANTY; without even the implied warranty of MERCHANTABILITY or
  40. FITNESS FOR A PARTICULAR PURPOSE.
  41.  
  42.  
  43. ------------
  44. INSTALLATION
  45. ------------
  46.  
  47. TLC is distributed with the following files:
  48.  
  49.     TLC.CFG - Configuration file
  50.     TLC.DOC - This file
  51.     TLC.DOS - DOS version of the executable
  52.     TLC.OS2 - OS/2 version of the executable (32-bit)
  53.  
  54. Copy these files into a directory that is listed in your PATH
  55. variable.  Then rename TLC.DOS to TLC.EXE if you are running a DOS
  56. system.  Or rename TLC.OS2 to TLC.EXE if you are running OS/2.  You
  57. can rename them both to TLC.EXE if you regularly run both operating
  58. systems.  But, of course, they must reside in different directories
  59. or you must rename one of the files, eg. TLC-OS2.EXE.  Make sure that
  60. a copy of TLC.CFG resides in the same directory as any TLC
  61. executable.  A description of this file is given below.
  62.  
  63.  
  64. -------------------
  65. RUNNING THE PROGRAM
  66. -------------------
  67.  
  68. The syntax for using TLC is as follows:
  69.  
  70.     tlc [options] sourcefile [sourcefile ...]
  71.  
  72. 'sourcefile' can be a filename, a wildcard name, or a response file
  73. which contains the names of the files to process.  Prepend '@' to the
  74. beginning of a filename to denote it as a response file.  The files
  75. listed in the response file should be one per line, eg.
  76.  
  77.     main.c
  78.     func1.c
  79.     func2.c
  80.     library.h
  81.  
  82. 'options' is one or more of the following:
  83.  
  84.     -c  Show the copyright notice and operating license.
  85.  
  86.     -h  Show the help text.  Running TLC without arguments produces
  87.         the same result.
  88.  
  89.     -l  Set the maximum number of lines for each page.  This includes
  90.         the header and blank lines put into the listing by TLC.  The
  91.         default is 60 lines per page.
  92.  
  93.     -n    Do not include entirely numeric tokens in the cross ref.
  94.     This has no effect unless -x is used also.
  95.  
  96.     -o  Send output to a file.  Output goes to stdout by default,
  97.         which in turn defaults to the screen.  For example, either
  98.  
  99.             tlc -ooutput.lst input1.c  OR  tlc input1.c > output.lst
  100.  
  101.         writes a listing of input1.c to output.lst.
  102.  
  103.     -w  Set the maximum number of characters per line for each page.
  104.         This includes the line numbers put into the listing by TLC.
  105.         The default is 132 characters per line.  If a line is longer
  106.         than the width setting, it is truncated.  If width is set to
  107.         a number smaller than 132, an 80-character-wide, 3 line
  108.         header is used.  Otherwise, a 132-character-wide, 2 line
  109.         header is used.
  110.  
  111.     -x  Append a cross reference to the listing.  Each entry in the
  112.         cross reference lists the token along with each line in each
  113.         file where it is found.
  114.  
  115.  
  116. -----------------
  117. SOURCE DIRECTIVES
  118. -----------------
  119.  
  120. Four directives exist to set header information in the listing:
  121.  
  122.     #pragma edit (string)
  123.  
  124.         Allows the setting of an edit number for the file.  The edit
  125.         value has no default, and will appear as spaces if not set.
  126.         It is limited to 4 characters and is reset for each input
  127.         file.
  128.  
  129.     #pragma module (string)
  130.  
  131.         Sets the module name for the current file.  By default, the
  132.         module name shown in the header is the first 8 characters of
  133.         the base file name.  If more than 8 characters are given in
  134.         'string', only the first 8 are used.  The module name is
  135.         reset for each input file.
  136.  
  137.     #pragma subtitle (string)
  138.  
  139.         Sets the listing subtitle.  By default, the subtitle is the
  140.         last function definition appearing on the current page, so
  141.     long as the ANSI standard method is used for function
  142.     declaration.  For example, if the current page looks like
  143.     this:
  144.  
  145.             int func_a (int a, float b, char *c) {
  146.                 .
  147.                 .
  148.                 .
  149.                 }
  150.  
  151.             void func_b (int a, int b) {
  152.                 .
  153.                 .
  154.                 .
  155.                 }
  156.  
  157.         the subtitle will default to "func_b".  If a subtitle is set
  158.         via #pragma subtitle, it will stay in effect until another
  159.         #pragma subtitle is seen, or the end of the file is found.
  160.         The subtitle is limited to 40 characters.
  161.  
  162.     #pragma title (string)
  163.  
  164.         Sets the listing title.  There is no default title.  If this
  165.         directive is not used, the header will contain spaces in this
  166.         field.  The title is limited to 40 characters, and is reset
  167.         to a null string for each input file.
  168.  
  169. The double quote character, ", may be used to enclose the string
  170. argument for each pragma.  It is not required, and if present, is not
  171. displayed.
  172.  
  173.  
  174. ----------------------
  175. THE CONFIGURATION FILE
  176. ----------------------
  177.  
  178. The configuration file, TLC.CFG, exists to set default options.  TLC
  179. will first look for the configuration file in the current directory.
  180. If it does not find it there, it will look in the same directory
  181. where TLC.EXE resides.  If TLC.CFG does not exist there, it stops
  182. looking.  When no configuration file is found, it uses default
  183. settings.
  184.  
  185. The format of the configuration file is as follows:
  186.  
  187.     [configuration directive 1]
  188.     argument 1
  189.         .
  190.         .
  191.         .
  192.     argument n
  193.     [configuration directive 2]
  194.  
  195.     etc.
  196.  
  197. Right now, the only configuration directive supported is [Keywords].
  198. The arguments below [Keywords] represent the list of tokens that
  199. should not appear in the cross reference.  For example, most people
  200. do not want C keywords to appear in the cross reference.  The
  201. configuration file distributed with the program contains all the ANSI
  202. C keywords, as well as the standard preprocessor directives.  To
  203. change what appears in the cross reference, simply change this list.
  204. The list does not have to be sorted in any particular order.  The
  205. default setting is to include all tokens in the cross reference, for
  206. example if TLC.CFG is not found.
  207.  
  208.  
  209. ----------------
  210. REVISION HISTORY
  211. ----------------
  212.  
  213. Version 1.00 Beta    19-Apr-93
  214.     - Initial release
  215.  
  216. Version 1.10 Beta    27-Apr-93
  217.     - Added wildcard spec and response file handling
  218.     - Changed order of tokens in cross reference to be more
  219.       "alphabetic"
  220.     - Added handling of C++ comment characters to denote comments
  221.     - Fixed tokenizing of #include filenames in the cross reference
  222.  
  223. Version 1.11 Beta    30-Apr-93
  224.     - Fixed bug to allow response files to have blank lines
  225.     - Changed definition of include file to be anything on the same
  226.       line as "#include" that falls within double quotes or '<' and
  227.       '>'
  228.  
  229. Version 1.0B4        09-May-93
  230.     - Adopted new version convention of Major.Minor[B#].  This is the
  231.       fourth release of the 1.0 beta.  When the first non-beta release
  232.       appears, the B will disappear.
  233.     - Made memory allocation more efficient by requesting 32K chunks
  234.       at a time from the OS and distributing it in small pieces,
  235.       instead of requesting each small piece from the OS.
  236.     - Fixed bug of not closing input files after they are read.
  237.     - Added -n option, which excludes numeric tokens from the cross
  238.       refererence.
  239.  
  240. Version 1.0        24-Jun-93
  241.     - First public release
  242.     - Minor cleanups from 1.0B4
  243.