diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/texlist/README |
Initial commit
Diffstat (limited to 'support/texlist/README')
-rw-r--r-- | support/texlist/README | 143 |
1 files changed, 143 insertions, 0 deletions
diff --git a/support/texlist/README b/support/texlist/README new file mode 100644 index 0000000000..72782cb9b6 --- /dev/null +++ b/support/texlist/README @@ -0,0 +1,143 @@ + + ----------------------------- + 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 ===================== |