home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 10 Tools
/
10-Tools.zip
/
tlc10.zip
/
TLC.DOC
< prev
next >
Wrap
Text File
|
1993-06-24
|
9KB
|
243 lines
------------
INTRODUCTION
------------
TLC is a utility that creates a formatted listing, optionally with a
cross-reference, from a given set of C source files. The format and
content of the listing can be controlled by various command-line
switches and directives in the C files. I wrote it for two reasons.
First, most C compilers do not provide a listing capability. Second,
all the third-party C listers I looked at didn't quite provide the
mix of form and functionality I wanted. Some were overkill, while
others did little more than add line numbers to the source code. So
I decided to write my own. This program is continually evolving. I
want it to be useful to as wide an audience as possible. If you
would like to see a feature added, please contact me. All requests
will be given serious consideration. Also, all bug reports are
welcome.
Tom Lowery
Internet: tlowery@pascal.acm.org
Now for the yucky legal stuff...
----------------------
LICENSE AND DISCLAIMER
----------------------
TLC is Copyright 1993 by Tom Lowery. All rights reserved.
This program is free software; you may use it and redistribute it
without restriction. You may not, however, sell, lease, license, or
in any other way charge others a fee for the use of this software, or
modify the software or documentation. A nominal fee may be charged
to cover copying or media costs. The software documentation,
including License and Disclaimer, must remain intact with all
distributed copies.
Because this software is free, it is distributed WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.
------------
INSTALLATION
------------
TLC is distributed with the following files:
TLC.CFG - Configuration file
TLC.DOC - This file
TLC.DOS - DOS version of the executable
TLC.OS2 - OS/2 version of the executable (32-bit)
Copy these files into a directory that is listed in your PATH
variable. Then rename TLC.DOS to TLC.EXE if you are running a DOS
system. Or rename TLC.OS2 to TLC.EXE if you are running OS/2. You
can rename them both to TLC.EXE if you regularly run both operating
systems. But, of course, they must reside in different directories
or you must rename one of the files, eg. TLC-OS2.EXE. Make sure that
a copy of TLC.CFG resides in the same directory as any TLC
executable. A description of this file is given below.
-------------------
RUNNING THE PROGRAM
-------------------
The syntax for using TLC is as follows:
tlc [options] sourcefile [sourcefile ...]
'sourcefile' can be a filename, a wildcard name, or a response file
which contains the names of the files to process. Prepend '@' to the
beginning of a filename to denote it as a response file. The files
listed in the response file should be one per line, eg.
main.c
func1.c
func2.c
library.h
'options' is one or more of the following:
-c Show the copyright notice and operating license.
-h Show the help text. Running TLC without arguments produces
the same result.
-l Set the maximum number of lines for each page. This includes
the header and blank lines put into the listing by TLC. The
default is 60 lines per page.
-n Do not include entirely numeric tokens in the cross ref.
This has no effect unless -x is used also.
-o Send output to a file. Output goes to stdout by default,
which in turn defaults to the screen. For example, either
tlc -ooutput.lst input1.c OR tlc input1.c > output.lst
writes a listing of input1.c to output.lst.
-w Set the maximum number of characters per line for each page.
This includes the line numbers put into the listing by TLC.
The default is 132 characters per line. If a line is longer
than the width setting, it is truncated. If width is set to
a number smaller than 132, an 80-character-wide, 3 line
header is used. Otherwise, a 132-character-wide, 2 line
header is used.
-x Append a cross reference to the listing. Each entry in the
cross reference lists the token along with each line in each
file where it is found.
-----------------
SOURCE DIRECTIVES
-----------------
Four directives exist to set header information in the listing:
#pragma edit (string)
Allows the setting of an edit number for the file. The edit
value has no default, and will appear as spaces if not set.
It is limited to 4 characters and is reset for each input
file.
#pragma module (string)
Sets the module name for the current file. By default, the
module name shown in the header is the first 8 characters of
the base file name. If more than 8 characters are given in
'string', only the first 8 are used. The module name is
reset for each input file.
#pragma subtitle (string)
Sets the listing subtitle. By default, the subtitle is the
last function definition appearing on the current page, so
long as the ANSI standard method is used for function
declaration. For example, if the current page looks like
this:
int func_a (int a, float b, char *c) {
.
.
.
}
void func_b (int a, int b) {
.
.
.
}
the subtitle will default to "func_b". If a subtitle is set
via #pragma subtitle, it will stay in effect until another
#pragma subtitle is seen, or the end of the file is found.
The subtitle is limited to 40 characters.
#pragma title (string)
Sets the listing title. There is no default title. If this
directive is not used, the header will contain spaces in this
field. The title is limited to 40 characters, and is reset
to a null string for each input file.
The double quote character, ", may be used to enclose the string
argument for each pragma. It is not required, and if present, is not
displayed.
----------------------
THE CONFIGURATION FILE
----------------------
The configuration file, TLC.CFG, exists to set default options. TLC
will first look for the configuration file in the current directory.
If it does not find it there, it will look in the same directory
where TLC.EXE resides. If TLC.CFG does not exist there, it stops
looking. When no configuration file is found, it uses default
settings.
The format of the configuration file is as follows:
[configuration directive 1]
argument 1
.
.
.
argument n
[configuration directive 2]
etc.
Right now, the only configuration directive supported is [Keywords].
The arguments below [Keywords] represent the list of tokens that
should not appear in the cross reference. For example, most people
do not want C keywords to appear in the cross reference. The
configuration file distributed with the program contains all the ANSI
C keywords, as well as the standard preprocessor directives. To
change what appears in the cross reference, simply change this list.
The list does not have to be sorted in any particular order. The
default setting is to include all tokens in the cross reference, for
example if TLC.CFG is not found.
----------------
REVISION HISTORY
----------------
Version 1.00 Beta 19-Apr-93
- Initial release
Version 1.10 Beta 27-Apr-93
- Added wildcard spec and response file handling
- Changed order of tokens in cross reference to be more
"alphabetic"
- Added handling of C++ comment characters to denote comments
- Fixed tokenizing of #include filenames in the cross reference
Version 1.11 Beta 30-Apr-93
- Fixed bug to allow response files to have blank lines
- Changed definition of include file to be anything on the same
line as "#include" that falls within double quotes or '<' and
'>'
Version 1.0B4 09-May-93
- Adopted new version convention of Major.Minor[B#]. This is the
fourth release of the 1.0 beta. When the first non-beta release
appears, the B will disappear.
- Made memory allocation more efficient by requesting 32K chunks
at a time from the OS and distributing it in small pieces,
instead of requesting each small piece from the OS.
- Fixed bug of not closing input files after they are read.
- Added -n option, which excludes numeric tokens from the cross
refererence.
Version 1.0 24-Jun-93
- First public release
- Minor cleanups from 1.0B4