Bijlage U The LATEX2HTML translator: An Overview 61 The LATEX2HTML translator: An Overview Herbert W. Swan [email protected] LATEX2HTML is, as its name implies, a translator which If you are using SDBM or GDBM, use must use Perl converts a standard LATEX document into Hypertext version 5. Markup Language (HTML), for incorporation into the LATEX2HTML can translate both LATEX2ε documents, • World-Wide Web. Like LATEX, it is freely available soft- as well as the older LATEX 2.09 documents. However, if ware, supported by highly dedicated volunteers. Unlike you wish to use all of the features of the LATEX2HTML LATEX, it is currently available only on UNIX platforms. translator, you should upgrade your LATEX program it- Complete documentation concerning this software may self to the newer version 2e. be browsed from <http://www-dsed.llnl.gov/ If you want to be able to use LATEX to translate equa- files/programs/unix/latex2html/manual>. • tions, ®gures and arbitrary environments into GIF im- A European mirror is reported at <http://www.rzg. ages for web browsing, you will also need the following mpg.de/rzg/software/latex2html/>.From UNIX utilities available and working: this online document, a PostScript version of the complete dvips version 5.516 or later or dvipsk. It is also rec- document may easily be obtained for hardcopy viewing. • ommended that your installation of dvips permits This article (the one you are reading) represents a conden- users to generate their own fonts through Metafont sation of that more complete documentation. and the MakeTeXPK script. This will cause equa- tions and other GIF text to be much more screen- LAT X2HTML replicates the basic structure of a LAT X E E readable. document as a set of interconnected HTML ®les which can Ghostscript version 2.6.1 or later, with the ppmraw be explored using automatically generated navigation pan- • device driver built in. (To see whether your version els. The cross-references, citations, footnotes, the table-of- of Ghostscript contains this driver, type contents and the lists of ®gures and tables, are also trans- gs lated into hypertext links. Formatting information which devicenames == has equivalent ªtagsº in HTML (lists, quotes, paragraph- quit breaks, type-styles, etc.) is also converted appropriately. The pbmplus or netpbm library. Some of the im- The remaining heavily formatted items such as mathemat- • age ®lters in these libraries are used during the Post- ical equations, pictures or tables are converted to images Script to GIF image conversion (described below). which are placed automatically at the correct positions in If you dislike the white background color of the the ®nal HTML document. • generated inlined images then you should get ei- LATEX2HTML also extends LATEX by supporting arbi- ther the netpbm library (instead of the older pbm- trary hypertext links and symbolic cross-references be- plus) OR install the giftrans ®lter by Andreas tween evolving remote documents. It allows the speci®- Ley <[email protected]>. Ver- cation of conditional text and the inclusion of raw HTML sion 1.10.2 is known to work without problems, but commands. These hyper-media extensions to LATEXare later versions should also be OK. available as new commands and environments from within aLATEX document. Obtaining LATEX2HTML System Requirements One way LATEX2HTML may be obtained is through one Before you consider obtaining LATEX2HTML, you should of the three primary Comprehensive TEX Archive Network ®rst ensure that your UNIX system includes the following (CTAN) sites nearest you. They are located in the United utilities: States <ftp.shsu.edu>, the United Kingdom <ftp. Perl version 4.036 or later. Since LATEX2HTML is tex.ac.uk>, and Germany <ftp.dante.de>.It • written in the Perl language, this utility is essential. can be found under the tex-archive/support/ Since Perl version 5 makes more ef®cient use of dy- latex2html directory. namic memory, it is recommended over version 4. The CTAN version will always be the latest stable revi- Your UNIX system must support some form of keyed sion of LAT X2HTML, currently V96.1-b. However, it • database management system, such as DBM, NDBM, E will not always contain the latest patches submitted by the SDBM, or GDBM. To ®nd out whether your system user community. If you wish to be on the leading edge, supports one of these standards, do a ªman dbm,º etc. Bijlage U The LATEX2HTML translator: An Overview 62 you are better off obtaining the program from <ftp:// Based on recent postings to the LATEX2HTML mailing list www-dsed.llnl.gov/files/programs/unix/ (described below), the top three installation dif®culties that latex2html/sources> (European mirror <ftp: new users encounter are: //ftp.rzg.mpg.de/pub/soft/latex2html/ Image conversion Although LATEX2HTML is able to sources>. This directory will contain all of the recent process ordinary text adequately, it fails to ª®ndº LATEX2HTML releases, including the latest major release, the images to process. One common cause of this 96.1, dated January of 1996. After downloading the ®le problem is that the ppmraw device is not built latex2html-96.1.tar.gz, you will have to un- into Ghostscript. Another cause involves the TEX- zip it with ªgzip -d,º and extract the ®les with ªtar xvf INPUTS environment variable. During normal op- latex2html-96.1.tar.º You should then proceed to down- eration, LATEX2HTML creates a subdirectory un- load the latest revision (currently Rev. e, dated April 8, der the current one to contain the translated HTML 1996), latex2html-96.1.reve.tar.gz. Simply unzip and ex- ®les. It is from this subdirectory that LATEXand tract this ®le on top of the original release ®le for the latest dvips are run during image conversion. If the patches. It will include .diff ®les which will show you TEXINPUTS environment variable that is visible what patches were made since the previous major release. to these programs does not include ª..º, then im- age conversion will fail. At some sites, ªlatexº and ªdvipsº are really scripts which set TEXINPUTS Installation and some other environment variables and call te Once the LATEX2HTML source ®les are obtained, installa- actual programs. If this is the case, the the user tion consists of: including ª..º in his or her TEXINPUTS will not 1. Editing the Perl scripts, to tell the system where the perl solve the problem. translator resides; Database problems Sometimes LATEX2HTML will sim- 2. Editing the latex2html.config script to tell ply die if the Perl interface to the UNIX database LATEX2HTML where the necessary UNIX utility pro- routines is not working. In Linux systems, this grams reside; problem is typically solved by uncommenting the 3. Running the install-test script, which mainly veri®es ªuse GDBM Fileº line in the LATEX2HTML and the previous two steps; install-test scripts. On other systems it may be nec- 4. Making local copies of the LATEX2HTML icons so that essary to recompile Perl with the proper database li- they are accessible to your WWW server. The instal- braries. lation variable $ICONSERVER in latex2html.- File globbing failure This problem manifests itself by config must then be set to this location. LATEX2HTML creating only some temporary ®les, but no valid HTML ®les. This problem can be Warnings: If you cannot do that bear in traced to the inability of Perl to locate the csh pro- mind that these icons will have to travel gram. Look for a line similar to ªcsh='csh'ºin from Livermore, California!!! Also note the Perl Config.pm ®le. If it is absent, recon®g- that several more icons were added that ure Perl . were not present in previous versions of LATEX2HTML. Normal Operation 5. Customizing the installation, as necessary. This is ac- A complished by setting various ªinstallation variablesº To use L TEX2HTML simply type: ªlatex2html (described later) in the ®le latex2html.config <®le>.tex.º The ª.texº suf®x is optional and will be sup- Individual users may also override the system-wide plied by the program if omitted by the user. This will cre- con®guration, either globally for all their documents, ate a new directory called <®le> which will contain the for separately for individual documents. generated HTML ®les, some log ®les and possibly some For a ªper userº initialization ®le, copy the ®le images. To view the result use an HTML viewer such as dot.latex2html-init in the home directory of NCSA Mosaic or Netscape Navigator on the main HTML file/file.html any user that wants it, modify it according to her pref- ®le which is . This ®le will contain erences and rename it as .latex2html-init.At navigation links to the other parts of the generated docu- runtime, both the latex2html.config ®le and ment. $HOME/.latex2html-init ®le will be loaded, The LATEX2HTML script includes a short manual which but the latter will take precedence. can be viewed by typing ªnroff -man latex2html.º You can also set up a ªper directoryº initialization ®le If a GIF image (of an equation or a ®gure, etc.) is used by copying a version of .latex2html-init in more than once in the document, it will be generated only each directory you would like it to be effective. An ini- once. Furthermore, on subsequent calls to LAT X2HTML tialization ®le /X/Y/Z/.latex2html-init will E on the same document, most images need not be regener- take precedence over all other initialization ®les if /X/ ated at all, but are recycled from one run to the next. Their Y/Z is the ªcurrent directoryº when LATEX2HTML is names might change, but their contents do not.