Appendix C. LaTeX Software and User Group Information
The files and packages that are described in this book are available in most TeX distributions, such as the TeX Live DVD or CD-ROM (provided with this book), or on the CTAN DVD of DANTE. The newest versions can also be directly downloaded from the web. The aim of this appendix is to provide you with the necessary information to obtain current releases of these DVDs (CD-ROMs are available on demand) and to give hints on how to locate and get the files you need directly from the Internet.
C.1. Getting help
While we certainly hope that your questions have been answered in this book, we know that this cannot be the case for all questions. For questions related to specific packages discussed in the book, it can be helpful to read the original documentation provided with the package. Appendix C.4 suggests ways to find that documentation on your system.
Very valuable resources are the existing FAQ documents. The most important ones are the UK-TUG FAQ by Robin Fairbairns available at http://www.tex.ac.uk/faq (or http://faq.tug.org) and the DANTE FAQ by Bernd Raichle et al. available at http://www.dante.de/faq/de-tex-faq (in German). Robin’s FAQ is also available in HTML format on the CD-ROM in the directory /texmf/doc/html/faq/index.html. However, as both documents are constantly being developed further, it is best to access the on-line versions if possible.
If precomposed answers are not enough, several news groups are devoted to general TeX and LaTeX questions: news://comp.text.tex is perhaps the most important one, with usually more than 100 messages posted each day. Many of the authors mentioned in this book are regular contributors on the news groups and help with answering questions and requests. Thus, there is a vast amount of helpful material on the web that can be conveniently searched using any search engine that indexes news entries.
If you post to any of these news groups, please adhere to basic netiquette. The community is friendly but sometimes direct and expects you to have done some research of your own first (e.g., read the FAQ first and searched the archived news) and not ask questions that have been answered several hundred times before. You should perhaps read Eric Raymond’s “How To Ask Questions The Smart Way”, available at http://www.catb.org/~esr/faqs/smart-questions.html, as a starter. Also, if applicable, provide a minimal and usable example of your problem that allows others to easily reproduce the symptoms you experience—this will save others time and might get you a faster reply.
C.2. How to get those TeX files?
A useful entry point to the TeX world is the TeX Users Group home page (http://www.tug.org; see Figure C.1). From there you can reach most information sources about TeX and friends available worldwide.
In particular, from the TeX Users Group home page you can go to one of the CTAN (Comprehensive TeX Archive Network) nodes. CTAN is a collaborative effort initiated in 1992 by the TeX Users Group Technical Working Group on TeX Archive Guidelines originally coordinated by George Greenwade, building on earlier work of Peter Abbott (see [61] for the historical background), and currently maintained by Jim Hefferon, Robin Fairbairns, Rainer Schöpf, and Reinhard Zierke (spring 2004). Its main aim is to provide easy access to up-to-date copies of all versions of TeX, LaTeX, METAFONT, and ancillary programs and their associated files.
Presently, there are three backbone machines that act as FTP servers: in the United Kingdom (cam.ctan.org), in Germany (dante.ctan.org), and in the United States (tug.ctan.org). These these sites are mirrored worldwide and all have a Web interface (see Figure C.2).
The material on CTAN is regularly (currently on a yearly basis) made available on a DVD (if needed, the corresponding material is available on several CD-ROMs that can be obtained on demand from one of the TeX User Groups, see below). One is the TeX Live distribution ([157]; see also www.tug.org/texlive), which provides a “runnable” version of TeX for various platforms. TeX Live CD-ROMs have been developed since 1996 through a collaboration between the TeX Users Group (TUG; United States) and the TeX user groups of the Czech Republic, France, Germany, India, Netherlands, Poland, Slovakia, and the United Kingdom, amongst others. These user groups distribute the TeX Live DVD to their members, so you should contact them directly (their addresses are given in Section C.5).
Another distribution is prepared by the German-speaking TeX user group DANTE (see Section C.5) and contains on a DVD an image of the complete CTAN file tree (more than 4GB of data). Much like the TeX Live DVD, this DANTE CTAN DVD is distributed by most user groups to their members. Thus, the same procedure as for TeX Live should be used if you are interested in getting a copy.
C.3. Using CTAN
In the previous section we described the TeX Live and DANTE CTAN DVD (formerly CD-ROM) sets. Obtaining the latest version of these CD-ROMs is an optimal way for getting access to recent versions of LaTeX software.
Nevertheless, for readers with an Internet connection, it makes sense to query one of the CTAN nodes every now and then to see whether one of the LaTeX components you need has been updated. In particular, on the TeX Users Group home page there is an area which gives a list of the latest updates available on CTAN (see Figure C.2, bottom oval). If you find updates, you can download the latest version of the given package directly from a CTAN archive (see Section C.3.2 of how this can be done).
Although network connections get faster all the time, it is often wise to connect to a site that is not too distant geographically from your location (consult the web page http://www.tug.org/tex-archive/CTAN.sites for a list of mirror sites for the CTAN nodes).
C.3.1. Using the TeX file catalogue
A catalogue of TeX- and LaTeX-related packages maintained by Graham Williams can be consulted at http://datamining.csiro.au/tex/catalogue.html. The catalogue is also directly reachable from the TeX Users Group home page (see the second oval in Figure C.1).
Moreover, the TeX catalogue is directly searchable from the CTAN interface (e.g., http://www.tug.org/ctan.html). In Figure C.2 we show how, after typing the string “graphicx” in the “Search Catalogue” area, we get the page shown in the bottom part of that figure. From this second page we can choose directly which of the proposed entries we want to investigate further (left side of the page) or we can follow a link to the associated CTAN directory (right side of the page).
C.3.2. Finding files on the archive and transferring them
Turning back to Figure C.2 we see that an easy way to find a file on CTAN is to use the web interface. Indeed, we merely have to type our search string in the CTAN search area. In this case, we specified the string “graphicx” (top oval in Figure C.2). The search engine returns the list of all files in the CTAN archive matching the given search criterion (see top part of Figure C.3). We can now browse the directory, and decide to recuperate one file. We can also transfer a complete directory by clicking on the link “entire directory” (rightmost oval in Figure C.3), which leads us to the page shown in the bottom part of Figure C.3. Here we are given the choice between a gzipped tar or a zip archive. By right-clicking on one of the two pointers (bottom ovals in Figure C.3) we download the archive in the desired format to our local machine so that we can install the files.
C.3.3. Getting files from the command line
If you know the Internet address of the package that you want to transfer (for instance from a Web search), it is perhaps more convenient to get hold of the archive from the command line, without going through a web interface. In this case you can use FTP or the wget program. The latter program allows you to download non-interactively files from the Web. It supports the HTTP, HTTPS, and FTP protocols. An example follows (commands input by the user are underlined).
Alternatively, you can use the FTP protocol. In this case, we first connect to the CTAN site (ftp.dante.de) and specify ftp as login name. The password must be your e-mail address. As we decided to transfer the graphics package, we first position ourselves in the directory where the file resides (cd tex-archive/macros/LaTeX/required). We have a look at the files in that directory (ls), transfer the zip archive, and close the FTP sesssion (quit).
C.4. Finding the documentation on your TeX system
When you want to use a LaTeX package, it would be nice if you could study the documentation without having to remember where the relevant files are located on your TeX system. Two ways exist to help you in your search: texdoc and its derivative texdoctk.
C.4.1. texdoc—Command-line interface for a search by name
Thomas Esser developed the program texdoc, which is part of the TeX Live distribution. If you know the name of the file describing a package, you can find the relevant documentation files as follows:
The -l option tells texdoc to list only the path to the files that fulfill the selection criterion (in this case, files called pspicture regardless of their extension). If you do not specify the -l option, texdoc will show you the contents of the documentation file (in this case, pspicture.dvi) with the help of the relevant display program (for instance, xdvi or Windvi).
If you do not know the precise name of the file, you can specify the -s option and provide a wildcard-like specification as a search pattern. For instance:
Here we have picked up files that have the string picture in their name—among them the “pspicture” files we found previously.
The texdoc utility is quite useful, but it has a drawback: you must know the name of the file describing the package that you want to use. This is not always just the name of the package itself (as with pspicture in the above examples).
C.4.2. texdoctk—Panel interface for a search by subject
Thomas Ruedas took a somewhat different approach to provide easy access to the documentation for files present on your TeX system. His texdoctk program uses a graphics user interface based on perl and Tk. The program uses a database that groups documentation files present in Thomas Esser’s tetex distribution (TeX Live is based on tetex) into 17 categories, and offers an eighteenth “user’s” category to allow users to add their (local) documentation entries into the database, if needed. As with texdoc, the display or print programs present on the system will be used for viewing (e.g., xdvi, dvips).
Figure C.4 shows how we used the texdoctk system to display the documentation for the pspicture package. In this case we did not have to know the name of the package. In fact, we navigated from the main panel, where we chose the “Graphics” category (1), which opened the “Graphics” menu (lower left), where we selected “Extended picture environment (pspicture)” (2). We then clicked the “View” button (3), which called the .dvi viewer Windvi (4), which displayed the text of the documentation.
On the figure one can see all available documentation categories (note the “Miscellaneous” button in the lower-right corner for special cases) as well as the “Search” and “Help” buttons for more advanced use.
C.5. TeX user groups
TeX users in several countries have set up TeX user groups, mostly based on language affinities. If you need help, you should contact your local user group first, since they might be able to come up with an answer that is most suited to your language-dependent working environment. Below we give some information about groups that have a formal existence (see http://www.tug.org/lugs.html or http://www.servalys.nl/lug/ for up-to-date and more complete lists). They can help you obtain TeX-related material on CD-ROMs or other publications.
