RSS Matters

RSS Logo

How to Install LaTeX2HTML on a Windows (32-bit) XP machine

Link to the last RSS article here: Structural Equation Modeling without one of the commercial modeling software packages -- or, how you can use free software to impress your committee and/or colleagues. -- Ed.

By Dr. Jon Starkweather, Research and Statistical Support Consultant

The following article discusses how “I” installed LaTeX2HTML on my work computer, a Windows (32-bit) XP machine. The motivation for me writing this article was to provide others, who may be interested in using LaTeX2HTML, with some guidance on the installation adventure. It was an adventure for me and hopefully, as a result; it will not be an adventure for you. 

First, you will need administrator privileges to alter some aspects of your system’s PATH and to be able to install some of the utilities used by LaTeX2HTML. If you do not understand what I mean by PATH in the previous statement, don’t worry. We’ll cover that. For now, just make sure you have administrator privileges. Second, you will need to have and be able to use WinZip. Third, you may notice I rigidly recommend specific versions of some programs below. This is because, if you have a different version of a program (a good example is Ghostscript), the directory structure and included files may differ from what I used, which then alters the way you configure and install LaTeX2HTML. 

Before we really begin, there are a few points worth noting. All the software mentioned below is freely available; meaning, you can download all the latest versions from the web, from their respective sites (e.g. Strawberry Perl). However; I have provided UNT based links to the exact versions of the software I used and I super-duper-strongly recommend you stick with them. As mentioned above; if you deviate from those versions provided, you very likely will have difficulties configuring and installing LaTeX2HTML. If you are a savvy computer user/administrator, you’ll notice I tend to make some unnecessary steps; meaning I tend to be very cautious. Obviously, you are free to wander in your own direction; I have tried to make this article as user friendly as possible for those who may not be as technically savvy as you. I do not consider myself very technically savvy and that is why I’m so cautious. 

So, we will start from scratch; meaning, with no utilities or MikTeX / LaTeX installed (in the right places!). 

1. Preparation of Utilities & System

1.1. Create C:\textmf

Before starting anything else, first go to the ‘C’ drive and create a new directory or folder called ‘texmf’ which can be thought of as TeX Mainframe or TeX Main File. This will be the directory in which we install all the following programs. The reason for this is because LaTeX2HTML hates spaces in file paths. So we should now have a new folder called textmf and when you double click on it, it should be empty and the address field of Windows Explorer should contain the following C:\textmf as shown below (please note, there is no space between C: and \texmf; the font style used here simply makes it look like there is a space).

Explorer Screen Shot

1.2. proTeXt

ProTeXt is a distribution of MikTeX for Windows which also includes some utilities which make it easier to use TeX (the underlying or raw base of MikTeX, LaTeX, etc.). These utilities are also used by LaTeX2HTML. First, download and review the ProTeXt installation manual. During your review, you should take careful note of how the manual advocates installation to the default location (e.g. on page 8: C:\Program Files\MikTeX 2.8\miktex\bin). However, there are very specific problems with that approach when it comes time to install LaTeX2HTML; primarily the space between “Program” and “Files” (as well as the space between “MikTeX” and “2.8” in that example). The proTeXt installation manual is very easy to follow and very clear, offering a step-by-step guide for installing MikTeX 2.8, TeXnicCenter (the LaTeX editor), Ghostscript 8.71, and GSview 4.9. It also shows how to configure the TeXnicCenter so that you do not have to continuously close and re-open your Adobe to view processed LaTeX documents. However, you should deviate from the manual during the installation of each program so that you install all four programs in C:\texmf as shown below and remove any spaces from the installation directories / paths.

Explorer Screen Shot 2

To install all four programs using the proTeXt distribution and its manual, first create a folder on your desktop named ‘protext’. Then, you will need to download proTeXt.exe to save it to your new ‘protext’ folder on your desktop. Then, double click on the proTeXt.exe to expand it. Once all the files have been expanded, you can simply follow the manual for installing everything – to the non-default location C:\texmf as shown above. A good rule of thumb is to change/replace “Program Files” with texmf when installing each program. For example, the default location for MikTeX (as mentioned above) is C:\Program Files\MikTeX 2.8\miktex\bin but because of the spaces, you should change that to C:\texmf\MikTeX2.8\miktex\bin for your installation. One more note about the proTeXt manual, as good as it is, I found it beneficial to print it and have it in front of me during the installation of each of the four programs. The manual is designed to be an interactive Adobe.pdf, but on my machine, the interactive ‘uninstall’ and ‘install’ buttons did not function properly.

1.3. Strawberry Perl

Strawberry Perl is a Perl distribution for Windows systems which comes pre-packaged with common tools. Again, on your desktop, create a new folder called ‘latex2html’ which will be the place we download all the utilities which are necessary for LaTeX2HTML to be installed. Next, within our newly created folder (latex2html), we create another new folder called ‘StrawberryPerl’. Next, we can download the installation file for Strawberry Perl (5.12.1.0) by clicking strawberry-perl-5.12.1.0.msi and saving it in our newly created folder. Next, we can install by simply double clicking on the recently downloaded file and following the installation instructions – BUT; remember to install to the C:\textmf directory as shown below. 

Explorer Screen Shot 3

1.4. NetPbm

NetPbm is a package of many (over 200) programs and libraries for rendering and manipulating images. For our purposes, we will need the NetPbm main installation, as well as at least 3 additional libraries. It is recommended a fourth also be installed. To start, back on the desktop, inside our ‘latex2html’ folder, create a new folder inside ‘latex2html’ called ‘Netpbm’. Next, download netpbm-10.27.exe and save it to our newly created ‘Netpbm’ folder. Next, double click on the netpbm-10.27.exe to install it; again making sure to install it to the C:\textmf as shown below. Notice that when installed, NetPbm is actually called GnuWin32 due to this version of NetPbm being specifically for a Windows (32-bit) operating system. 

Explorer Screen Shot 4

1.4.1. NetPbm: libpng Library

Next, we need to get the first of three required libraries to supplement NetPbm. The libpng library is used to manipulate and convert (to and from) png file type. Fortunately, it comes with an installation program. Download libpng-1.2.37-setup.exe and save it to our ‘Netpbm’ folder (inside the ‘latex2html’ folder on the desktop). When you double click that exe file, it should know where to install because it looks for the NetPbm (GnuWin32) directory. However, if it does not recognize that you have installed NetPbm (GnuWin32) at C:\textmf then you must tell the installation program to install to the C:\textmf\GnuWin32 location. 

1.4.2. NetPbm: zlib Library

Next, we need to get the second of three required libraries. The zlib library is a general purpose compression agent. Again, fortunately it comes with an installation program. Download zlib-1.2.3.exe and save it to our ‘Netpbm’ folder (inside the ‘latex2html’ folder on the desktop). When you double click that exe file, it should know where to install because it looks for the NetPbm (GnuWin32) directory. As above, if it does not recognize that you have installed NetPbm (GnuWin32) at C:\textmf\GnuWin32 then you must tell the installation program to install there. 

1.4.3. NetPbm: libgw32c Library

This library is used as a general purpose development tool (obviously for Windows 32-bit systems). Unlike the convenient libraries above, this one does not come with an installation program. However, thankfully it only contains a few folders which will need to be unzipped and placed into the appropriate directories and subdirectories. Download libgw32c-0.4-lib.zip and save it to our ‘Netpbm’ folder (inside the ‘latex2html’ folder on the desktop). Next, right click on the zip file and select “WinZip” and “Extract to here”. You should then see three new folders appear: ‘include’, ‘lib’, and ‘manifest’. First, open ‘include’ and select both folders (glibc & winx), then cut or copy them and paste them into: C:\texmf\GnuWin32\include. Second, return to the desktop, ‘latex2html’, ‘Netpbm’ folder and open ‘lib’. Select the single file (libgw32c.a) and cut or copy it, then paste it into C:\texmf\GnuWin32\lib. Third, return to the desktop, ‘latex2html’, ‘Netpbm’ folder and open ‘manifest’. Select the two files (libgw32c-0.4-lib.mft & libgw32c-0.4-lib.ver) and cut or copy them, then paste them into C:\texmf\GnuWin32\manifest.

1.4.4. (OPTIONAL) NetPbm: jpeg Library

This library is used to render and manipulate jpeg files. Jpeg is extremely popular and LaTeX2HTML uses jpeg files when converting several LaTeX environments (e.g. R script from the relax package). Therefore, it is strongly recommended you also install this library. It does have an installation program, so it’s very easy to do. Download jpeg-6b-4.exe and save it to our ‘Netpbm’ folder (inside the ‘latex2html’ folder on the desktop). When you double click that exe file, it should know where to install because it looks for the NetPbm (GnuWin32) directory. As above, if it does not recognize that you have installed NetPbm (GnuWin32) at C:\textmf then you must tell the installation program to install there.

1.5. Setting the PATH & Environment Variable

This step involves making sure Windows kept up with us while installing all the preceding programs and utilities. We will also need to create a new Environment Variable. To view (and edit if necessary) the PATH, we need to go to the advanced system properties. There are a few ways to do this but one way is; get to the Windows Control Panel, then double click the System icon, then click the Advanced tab (marked below left with a red rectangle). Next, click on Environment Variables (marked below right with a red rectangle). 

System Properties Screen 1 System Properties Screen 2

In the System variables box, scroll down through the variables until you see Path (as marked below with a red rectangle). We need to make sure Windows recognizes the location of each of the programs we have installed.

Environment Variables 

So, double click on the Path variable and slowly review each path listed. Each path listed is separated by a semicolon (;). There may be many unfamiliar paths listed, but make sure the following paths are also listed:C:\texmf\MikTeX2.8\miktex\bin;C:\texmf\strawberry\c\bin;C:\texmf\strawberry\perl\site\bin;C:\texmf\strawberry\perl\bin;C:\texmf\gs\gs8.71\bin;C:\texmf\GnuWin32\bin;

Notice, there are no spaces in the entire PATH; the font used here simply makes it look like spaces are present. The order is not important, but each of the entries listed above should be listed in your path. If one is missing, type it in. If you added to the PATH, then you need to click OK; if you did not add to the path, simply click Cancel. Now, we need to add a new System variable. Click on the New button (marked with a red rectangle below left). The new variable name you should type is: RGBDEF

and the new variable value you should type is:

C:\texmf\l2h\styles\rgb.tex

Note, just after C:\texmf\ is lowercase L then a number 2 then a lower case H which is an abbreviation of LaTeX2HTML (l2h); also notice there is no space between C: and \tex….again, the font simply makes it look like a space is there. When finished, you should have that variable listed (shown below right with a red rectangle). You might have noticed there is no such directory or files located at that value. Don’t worry, it will be created when we configure and install LaTeX2HTML. 

Environment Variables Environment Variables 2

Make sure to click OK to ensure the changes are saved. These changes are necessary so that when we set the preferences for configuration and installation of LaTeX2HTML, it will properly recognize these programs and utilities, and thus configure without errors (fingers crossed!).

2. LaTeX2HTML

2.1. Create Necessary Directories 

Now, we will create two directories (or folders) which will be used later in this adventure. The first folder we create will be used once we have successfully installed LaTeX2HTML. The folder will be a temporary folder in which LaTeX2HTML stores some images and code while generating HTML from a TeX file. So, return to C:\texmf and create a new folder there named ‘TEMP’. Next, we will create a folder which will be the location of the installed LaTeX2HTML program. Again, return to C:\texmf and create a new folder there named ‘l2h’, which is ‘lowercase L number 2 lowercase H’. This will be the folder we install to. Now, your C:\texmf folder should have the same contents as displayed below:

texmf

Now, we are ready to download the installation file(s) for LaTeX2HTML.

2.2. Get LaTeX2HTML

To begin; back on the desktop, inside our ‘latex2html’ folder, create a new folder inside ‘latex2html’ called ‘zipped_latex2html’. Download latex2html-2008.tar.gz to that new folder (zipped_latex2html). Next, return to C:\texmf and create a new folder there named ‘tmp’. Next, copy the latex2html-2008.tar.gz file to our newly created C:\texmf\tmp folder. Saving a copy on the desktop is a precaution and is not necessary. Next, inside the C:\texmf\tmp folder right click on the latex2html-2008.tar.gz file and select “WinZip” and “Extract to here”. You’ll then see a file named latex2html-2008.tar; right click on it and select “WinZip” and “Extract to here”. You should now see a standard folder named ‘latex2html-2008’. Inside that folder you should see the same folders and files as are displayed below: 

folders and files

If you make any changes to these folders/files; meaning if you edit any of them or run/execute any of them and you receive errors, then your best bet is to simply delete the ‘latex2html-2008’ folder and un-zip the latex2html-2008.tar file again. Yes that may seem a bit ridiculous, but my experience prompts this recommendation. Also note this is not the completed program LaTeX2HTML. We will use files here to install LaTeX2HTML in the C:\texmf\l2h folder we created previously, which is why the parent directory here is ‘tmp’ which is short for temporary. Once satisfactory installation has been completed (not yet); we can delete the entire ‘tmp’ directory/folder and its contents. 

2.3. Edit prefs.pm

Next, we need to edit the preferences file so that when we configure the installation of LaTeX2HTML it does not produce errors (which would necessitate “…your best bet is to simply delete the ‘latex2html-2008’ folder and un-zip the latex2html-2008.tar file again” from above). Fortunately, there is not much we need to edit. Locate the prefs.pm file inside the un-zipped ‘latex2html-2008’ folder and use which ever editor you are most comfortable with to open it. For those who do not have an editor they are most comfortable with; right click on prefs.pm and select open.

prefs.pm

You will be presented with options for opening the file, choose ‘Select the program from a list’ and click OK.

‘Select the program from a list’

Then, find the Notepad program and select it. You may want to un-check the box to “Always use the selected program to open this kind of file”. Then, click the OK button to open the prefs.pm file.

Open With

Once open, you’ll notice pref.pm begins with a (substantial) revision history. We need to scroll down past the revision history to edit two lines.

Edit two lines

The first line we will edit tells the installation where to look for Ghostscript’s executable file and where to look for the NetPbm (GnuWin32) executable file. Find the following line:

$prefs{'EXTRAPATH'} = '';

Here, we will change/replace with:

$prefs{'EXTRAPATH'} = 'C:\texmf\gs\gs8.71\bin;C:\texmf\GnuWin32\bin';

PLEASE, notice; there is no ‘return’ or line break between the = and ‘C:\\text……., the line was broken only because the page on which I’m typing this could not fit it all on one line. In Notepad, it will all be on one line. Below is a screen capture image of what the line should look like in Notepad. Next, we will edit only a few lines below; where you see:

$prefs{'PREFIX'} = '/usr/local';

We need to change/replace with:

$prefs{'PREFIX'} = 'C:\texmf\l2h';

This specifies where we want LaTeX2HTML to be installed. Notice you can use \\ or \ when giving paths. Below is a screen capture image of what the lines should look like in Notepad.

Notepad Screen Capture

Next, click File, then Save, then close Notepad. We should now be ready to begin actually configuring and installing LaTeX2HTML.

2.4. Run config.bat

Now, you’ve just saved and closed prefs.pm and you should be looking at the contents of the folder named ‘latex2html-2008’ located inside the C:\texmf\tmp folder. Next, without closing the folder(s), open a Command Prompt. If you’ve never done that before, click the “Start” menu button and then click Run…then in the “Open” field, type cmd.exe and hit the Enter key or press the OK button.

Select Run Run

This opens a Command Prompt (sometimes referred to as a DOS prompt) which looks like the following image.

Command Prompt

Here, we will navigate to the currently open C:\texmf\tmp\latex2html-2008 folder by typing the following into the Command Prompt:

cd C:\texmf\tmp\latex2html-2008

and press the enter key. The cd (then space) is the command to change directory.

Change directory

If you are a superstitious person…now is the time to do whatever it is you do. When we execute (or run) the configuration, you will see quite a lot of text displayed, scrolling by in rapid succession on the Command Prompt. Do not worry; when configuration finishes, you can (and need to) scroll back (up) through what has been displayed to check for errors. Below you see a section of a config.log file which is produced when the configuration is run. You’ll notice I marked one spot which occasionally causes an error. Sometimes the configuration fails to find the version number when checking for the version of dvips (and/or Ghostscript). If the configuration fails for any reason, review this document, the sources provided at the end of this document, and use the web (e.g. search Google: latex2html config failure [with the error you had]) to search out the error(s) you had and likely solution(s). Now, take a deep breath and in the Command Prompt, type: config and hit the enter key. 

config log

2.5. Run install.bat

If you’re looking at these words, I assume you had no errors (which should be the case). If there were errors with config.bat you need to correct them prior to continuing here. Unfortunately, we’re not done yet. The config.bat simply configured the installation executable. At this point, some older sources would have you run the test.bat to make sure everything went as planned with config. However, with newer versions (as is the case here), that is unnecessary. Now, we are ready to actually install LaTeX2HTML. When the installation runs, you will see a dizzying amount of text scrolling by in the Command Prompt. That’s what it’s supposed to do; it’s creating several new files and folders. Again, a deep breath…and in the Command Prompt, type install and hit the enter key.

2.6. Remember to update your PATH

Now that you have installed LaTeX2HTML you must now go back to the System Properties as was done in section 1.5 above. As the last ‘official’ installation step you need to edit your PATH to include C:\texmf\l2h\bin; so that the utilities will know you installed LaTeX2HTML in the ‘l2h’ directory. Remember, LaTeX2HTML uses utilities like NetPbm (GnuWin32) and Ghostscript to convert things (e.g. math) from TeX/LaTeX to images because, HTML is not flexible enough to handle many of the things TeX/LaTeX was designed to handle (e.g. math formulas). Therefore, the PATH needs to be accurate so that LaTeX2HTML can communicate with those other programs/utilities and so they can communicate back to LaTeX2HTML. 

3. Post Installation Individual Preference Configuration

There are a great many options and default settings you can change to personalize the way LaTeX2HTML works. Go to the newly installed C:\texmf\l2h directory and you will find a file named l2hconf.pm which you can open in your favorite editor (or Notepad as was done with prefs.pm above). Slowly scrolling down through the file you will see the authors have included comments explaining which lines can be changed to suit the needs of individual users. One change that you should make, if you intend to convert a document with mathematics, is the options line for DVIP (line 136). Simply remove “-Ppdf” in order to convert documents which contain mathematics. Otherwise, the mathematics will contain a large, unsightly black bar below it or to the right of it when converted to HTML. It is recommended that you read the LaTeX2HTML manual before making other changes – so that you will know what those changes do. Each installation of LaTeX2HTML has a TeX file named manual.tex located at C:\texmf\l2h\docs so you supposedly can create a copy of the manual using LaTeX or simply read it in your LaTeX editor (TeXnicCenter). However, many have posted issues with the manual.tex file in various forums / discussions and I myself could not get LaTeX to produce the Adobe.pdf document that is why the version I downloaded is available here

Adobe.pdf and web page versions of this Benchmarks Online (RSS Matters) article are available here.

Until next time, I’ll be in the Grand Canyon at sundown…

References / Resources 

Comprehensive TeX Archive Network
http://www.ctan.org/
 
Leon van Dommelen's comprehensive site for LaTeX2HTML
http://www.eng.fsu.edu/~dommelen/l2hfu/index.html
 
Leon van Dommelen's list of problems (most with solutions) as an appendix to the site above
http://www.eng.fsu.edu/~dommelen/l2hfu/style_a/node10.html
 
Nasser M. Abbasi's very informative notes on installing LaTeX2HTML
http://www.12000.org/my_notes/l2hwin/

Software / Utilities

Get proTeXt latest version (for Windows) here:
http://www.tug.org/protext/
 
Get Strawberry Perl 5.12.1.0 (for Windows) here:
http://strawberryperl.com/
 
Get NetPbm 10.27 (for Windows) here:
http://gnuwin32.sourceforge.net/packages/netpbm.htm
 
Get latex2html (for Windows or anything) here:
http://www.latex2html.org/
http://www.latex2html.org/~latex2ht/current/