-----------------------------
                       TeXlist Readme File
                  -----------------------------

                          John Forkosh
            forkosh@panix.com   www.panix.com/~forkosh


INTRODUCTION
-----------------------------------------------------------------
     TeXlist is yet another utility using LaTeX2e to facilitate
the generation of program listings (or listings of any ascii text
files).  It's a C program that generates a "standalone" latex
document that's then run against LaTeX2e to produce a .dvi file.
     By "standalone" I mean that TeXlist's output isn't intended
to be incorporated within another LaTeX document, though you could
manually strip off the preamble, etc, and then use it that way.
     TeXlist is hereby GPL'ed; see the copyright information below.


TABLE-OF-CONTENTS
-----------------------------------------------------------------
texlist.zip    gnu zipped distribution of TeXlist containing...
00README       this file (no other documentation is available)
texlist.c      TeXlist program and all required functions
texlist        Linux elf executable
texlist.sun    Solaris executable
texlist.exe    MS-DOS executable (won't run from a Windows DOS box)
Note: the two source files (00README and texlist.c) use Unix
line termination, i.e., linefeeds (without carriage returns)
signal line endings.


QUICK-START INSTRUCTIONS
-----------------------------------------------------------------
TeXlist works like a Unix filter.  It reads filenames from stdin
until it sees an empty line or eof, and it writes a stream of
characters to stdout comprising a LaTeX2e document that prints
a nicely-formatted listing containing all those files.

You'd typically redirect both stdin and stdout, as per the
following example:
     cd your_project_directory
     ls *.c > tocfile
     texlist <tocfile >listing.tex
     latex listing
The resulting listing.dvi file can now be run against dvi2ps and
printed, or whatever.

Note that the preceding example assumes
     ls *.c > tocfile
generates tocfile containing one filename per line.  You can also
use your favorite editor to create a custom tocfile, or to modify
the one created by ls, etc.

For just a few random files, you can run TeXlist without
redirecting stdin at all:
     texlist >listing.tex
and then manually enter
     filename1<Enter>
     filename2<Enter>
     ...
     last_filename<Enter>
     <Enter>
TeXlist emits no prompts of any kind.  Just type in one filename
at a time, followed by <Enter> on an empty line to end the program
and return you to the shell.

If you list more than one file, the last page(s) of the listing
contain a table of contents.  It's generated at the end, once
all the page numbers are known.  After printing, you can manually
move the toc to the top.


COMPILING THE SOURCE CODE
-----------------------------------------------------------------
I've comnpiled and run TeXlist under Linux using gcc, under Solaris,
and under DOS using an old Zortech compiler with a 32-bit DOS extender.
The same source compiles and executes under all environments without
any changes whatsoever (except, of course, for the cr/lf conversion
required for DOS).  Note that Zortech's extender won't run under a
Windows DOS box, so you'll need to re-compile to use it in that fashion.

If one of the precompiled executables isn't suitable for you, then
     cc -DTESTDRIVE texlist.c -o texlist
under Unix, or do whatever works under your OS.  Note the -DTESTDRIVE
switch which compiles the stub main() program needed for linking.

The source code is fairly well documented.  There are several other
compile-time switches and #define'd adjustable constants that may be
of interest to you.


HISTORY AND COPYRIGHT
-----------------------------------------------------------------
TeXlist is provided as GPL copyrighted source, and released with
no official support of any kind whatsoever.  I wrote various
components of TeXlist between 1974 and 1996, originally for my own
internal purposes, and for the proprietary use of some of my clients.

Obviously, the earlier components were written for purposes entirely
unrelated to their use in TeXlist.  So, as per the GPL, I, the author,
retain the right to keep secret any other programs I've derived from
TeXlist's source.  You, however, as per the GPL, must make public
your source for all derived works (particularly enhancements, etc).
For example, you can't use my banner() in your non-GPL'ed program.
And, of course, I won't use your enhancements in any proprietary
work of my own.

As per the above, and as per all other GPL provisions, I'm now
releasing TeXlist under the GPL.  Anyone who finds TeXlist's design
and/or implementation worth pursuing, under the GPL, is encouraged
to do so.


WARNINGS
-----------------------------------------------------------------
TeXlist uses LaTeX's verbatim environment (replacing tabs with
spaces).  Therefore, files to be listed may not contain the string
\end{verbatim}.  I don't suppose it's likely your files will.
But the first thing you might try is running TeXlist against its
own source.  To do so, I usually make a temporary copy and change
that "end" to "e n d".  You can leave \begin{verbatim}, directly
above it, alone.

Each typeset page generates an underfull hbox warning.  Some
gentle reader may want to look at my \newcommand{\ulsection}
to see what's causing the complaint.  The .dvi output is fine.


CONCLUDING REMARKS
-----------------------------------------------------------------
I hope you find TeXlist useful.  If so, a contribution to your
country's TeX Users Group, or to the GNU project, is suggested,
especially if you're a company that's currently profitable.

If you also like TeXlist's source, I'm an independent contractor
incorporated in the US as John Forkosh Associates, Inc.  A resume
is at www.panix.com/~forkosh/ or email forkosh@panix.com (if you're
in New York, the NY Metro edition of ComputerUser carries my
print ad).
====================== END-OF-FILE 00README =====================