summaryrefslogtreecommitdiff
path: root/support/texlist/README
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/texlist/README
Initial commit
Diffstat (limited to 'support/texlist/README')
-rw-r--r--support/texlist/README143
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 =====================