----------------------------- 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 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 filename2 ... last_filename TeXlist emits no prompts of any kind. Just type in one filename at a time, followed by 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 =====================