        **********************************************************
        * This document is a mechanical convertion from the      *
        * HTML version. If possible, please obtain that version, *
        * or the DVI version.                                    *
        **********************************************************

---- TeX4ht: the DOS port ----

Gertjan Klein
April 3, 1997

1 Introduction
2 Files in the distribution
3 Other required utilities
4 Graphics translation
5 Setup
5.1 The batch files
5.2 The TeX4ht environment file
5.3 emTeX
5.3.1 Adding a Metafont mode
5.3.2 Other configuration files
6 Use
6.1 The test files
6.2 Normal use
6.3 Port-specific details

6.4 Problems

--- 1 Introduction ---

This documentation contains installation instructions for the DOS port
of the utility TeX4ht. TeX4ht, written by Eitan Gurari, is a
(La)TeX-based system for authoring HTML. This port is created by Gertjan
Klein.

The utility uses a style file (TeX4ht.sty) to create a special `.dvi '
file that can be converted to HTML by the program TeX4ht.exe. This
program also creates a `.ivd ' file that contains all items that can't
be converted to HTML directly; these can then be converted to `.gif '
files.

--- 2 Files in the distribution ---

The DOS port of TeX4ht consists of the following files:

# tex4ht.sty The style file to include in your (La)TeX source.

# 2htm.bat The batch file that converts the `.dvi ' file to HTML,
  creates the `.ivd ' file, and converts it to `.gif ' file(s).

# convert.bat This batch file converts a specific picture in the
  `.ivd ' file to `.gif '. It is called from a temporary batch file that
  is created during the conversion and shouldn't be used directly.

# tex4ht.exe The program that converts the `.dvi ' file to HTML
  file(s), and creates the `.ivd ' file; it is called by 2htm.bat. It
  creates a `.lg ' file that contains instructions for creating the
  `.gif ' files, if any.

# t.com A utility to simultaneously direct program output to the
  screen and to a file. It is called by 2htm.bat to duplicate all screen
  output to a log file.

# readme.{htm,dvi,txt} The documentation for this port in several
  formats.

# tex4ht.env Contains configuration information for TeX4ht.

# *.htf Contain font information for TeX4ht.

# htm.mf A mode definition to add to emTeX's local.mf.

# htm.cnf A configuration file for emTeX for automatic font
  generation at the right resolution.

# htm.cfg A configuration file for dvips, informing it of the
  correct location of fonts, and the Metafont mode to use.

# autocrop.cfg A configuration file for the program display,
  instructing it to crop the bitmaps and convert them to `.gif '.

# test.tex, ht.bat These two files can be used to test your (La)TeX
  and TeX4ht. Test.tex is a file that can be used to test pure TeX as
  well as LaTeX installations. Ht.bat is the batch file required to
  extract all source files from test.tex.

--- 3 Other required utilities ---

TeX4ht is an universal utility, and isn't bound to any particular TeX
distribution and/or other utilities. These installation instructions,
however, are written to use one specific set of programs. People that
wish to use other programs are hopefully able to extract the information
they require from these instructions. Also note that you'll need at
least a 386 or higher computer for the creation of bitmaps, as some of
the programs used are DOS-extended and require this.

Below you'll find a list of the programs this port uses to get the
conversion to work. Note that each of these programs must be set up
appropriately according to their installation instructions: please read
their manuals!

# Where possible, TeX4ht uses emTeX's output driver dvidot to
  directly create bitmaps. emTeX is available from CTAN (Comprehensive
  TeX Archive Network); the two CTAN sites are ftp.dante.de and
  ftp.tex.ac.uk. A list of mirrors can be found in the file
  CTAN/tex-archive/CTAN.sites. The emTeX directory is CTAN/tex-
  archive/systems/msdos/emtex.

  Emtex comes with an installation program that installs the
  distribution and sets it up for use. This program behaves rather badly
  in a number of aspects. It insists on adding two directories to the
  PATH environment variable, and it won't work properly with 4DOS (an
  alternative command processor - if you don't have it, don't worry
  about it. If you do have it, switch to a command.com prompt before
  running the install program). Nevertheless, those with system
  administration anxiety may want to try it. To use it, get install.exe,
  install.ovl and install.dat.

  For a minimum TeX setup you'll need at least: INSTALL.ENG, README.ENG,
  HELP.ENG, (please read these files!), first.zip, emxrsx.zip,
  tex4b.zip, fontcm.zip, dvid16g1.zip, dvid16g2.zip, mf4b.zip, and
  mfjob12d.zip.

  In addition, if you want to use LaTeX, you'll need l2base.zip,
  l2input.zip, fontltx.zip, and probably l2tools.zip. Note that these
  lists are the minimum required; you'll probably want some or all of
  the other files too. Please read the documentation in emtex\doc !

# To crop the figures and convert the bitmaps to GIF file format,
  the program display is used. This is actually a graphics viewer, but
  it contains batch conversion options. Its home site is
  ftp://NCTUCCCA.edu.tw/Graphics/Display?ENGLISH; as this site is a bit
  difficult to reach you may want to try one of the SimTel mirrors, e.g.
  ftp://ftp.cdrom.com/pub/simtelnet/msdos/graphics/. Get disp189a.zip;
  (disp189b.zip contains driver sources and fonts; you don't need them
  for TeX4ht). Please note that the file contains a directory structure;
  if you use pkunzip, use the -d switch to unpack the files, e.g.:

      md \apps\disp
      cd \apps\disp
      pkunzip -d \temp\disp189a

  After unpacking, read the files readme.1st and install, and run the
  install.exe program.

# Finally, to make the figures transparant, you'll need
  giftrans.exe; it's home site is
  ftp://ftp.rz.uni-karlsruhe.de/pub/net/www/tools/giftrans/. Place this
  program in a directory in your path, or give it a directory of it's
  own. You may also want to download the documentation.

If you can't use the emTeX output driver directly, e.g. because you
included postscript figures in your drawing, an alternative is to use
postscript as an intermediary. In addition to the above, the following
programs are then needed:

# Dvips converts `.dvi ' files to postscript, including a bitmap
  version of the used fonts. There is a version compiled especially for
  emTeX available: CTAN/tex- archive/systems/msdos/emtex/dvips/. You'll
  need dvips.doc, dvipsfnt.zip, and dvipsini.zip. The file dvips.doc
  contains instructions for installation and use.

# Ghostscript converts the created postscript files to bitmaps; look
  in ftp://ftp.cs.wisc.edu/ghost/aladdin/. You'll need at least
  gs403ini.zip, gs403dos.zip and gs403fn1.zip. (A useful WWW page
  concerning ghostscript can be found at
  http://www.cs.wisc.edu/~ghost/index.html). These files also contain a
  directory structure, so (if you use pkzip) use the -d switch again:

      cd \apps
      pkunzip -d \temp\gs403ini
      pkunzip -d \temp\gs403dos
      pkunzip -d \temp\gs403fnt

  This will create the directories \apps\gs4.01 (containing the program
  and it's support files) and \apps\fonts (containing the postscript
  fonts). If you use other directories, you have to adjust 2htm.bat (see
  section 5.1). You may want to read the readme file and the various
  `.txt ' files in the gs4.01 directory.

--- 4 Graphics translation ---

It may not be possible to translate the entire source file to HTML
without resorting to bitmaps. Examples are special characters not
supported by HTML, graphic figures, inserted postscript, etc. There are
two ways to create the required bitmaps:

# The emTeX dvidot driver. This driver is capable to create a bitmap
  directly in several formats; for TeX4ht, PCX is used. An important
  feature of this driver is that it can crop the bitmaps to the nearest
  8-pixel boundary. This means the resulting bitmaps are small, so the
  conversion to `.gif ' format (and cropping of the last rows) will be
  fast. (Cropping is removing all extraneous whitespace on all sides).
  Note that under some circumstances there can be problems with this
  feature; see section 6.4 for more information.

# Dvips and ghostscript. Converting the `.ivd ' file to postscript,
  and then using the postscript interpreter ghostscript to convert to
  bitmaps, allows inclusion of arbitrary postscript figures in the
  source file. Unfortunately, the created bitmaps are initially rather
  large, which makes translation a lot slower.

The created bitmaps will be cropped regardless of the conversion method
used, to ensure minimum size, and at the same time converted to `.gif '
format to minimize file size. A final stage sets the background color to
transparant (taking over the background color used by the browser).

--- 5 Setup ---

To start setting up TeX4ht, begin with placing all files in the
distribution in one directory. The examples assume this directory to be
c:\apps\tex4ht. To make the main batch file, 2htm.bat, accessible from
everywhere, you could place the TeX4ht directory in your executable
search path by changing the path statement in your autoexec.bat; this is
not a very good idea from a system administration point of view, though.
Better would be to move the 2htm.bat file to a directory already in your
search path. The distribution is set up so none of the programs required
by it need to be in your search path; you do need to edit a few files to
set things up, though.

In addition to making the main batch file accessible, you'll have to
make the TeX4ht.sty file accessible to emTeX; either by moving it
somewhere in the emTeX texinput tree, or by updating emTeX's "texinput"
environment variable to include the path to the style file. Take care:
some of emTeX's batch files explicitly set the texinput variable
themselves, overriding what's already there! For example, latex2e.bat
does this. You may want to append ";c:\apps\tex4ht " to the third line
of this file, the one that starts with " set texinput= ". You can then
issue the command " set texinput=c:\apps\tex4ht " from e.g. set_tex.bat
(see below), to make sure emTeX will find TeX4ht.sty.

-- 5.1 The batch files --

The central part of the port is a set of batch files (2htm.bat and
convert.bat). These files call all other programs and utilities. In
order for these to be found, the main batch file (2htm.bat) needs to be
told where they reside, if they are not in your path. At line 15 and
below in this file, you'll find the following:

 :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
 :: Set up environment variables with paths to programs etc. This part
 :: should be configured properly!! See readme.[dvi|txt|htm]!
 ::
 set tex4htdir=c:\apps\tex4ht\
 set displaydir=c:\apps\disp\
 set giftransdir=c:\tools\utils\
 set gsdir=c:\apps\gs4.01\
 set gs_lib=%gsdir%;c:\apps\fonts
 call c:\apps\emtex\bin\set_tex.bat
 :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

The lines starting with the double colons are comments. The other six
you need to adjust to your particular system. The first of those asks
for the directory the TeX4ht files are in. You have to specify this
directory, with a trailing backslash, for proper operation. On the next
two lines the directories where the display program ("displaydir") and
giftrans ("giftransdir") reside can be specified. If these programs are
somewhere in your path, you can make these empty if you want ("set
displaydir=" and "set giftransdir="), or comment-out these lines by
prefixing them with a double colon. Specifying the path explicitly
prevents path searching, though, and hence may speed up loading
slightly. Make sure you don't forget the trailing backslash.

The next line asks for the directory ghostscript is installed in (again:
with trailing backslash). If you'll never use postscript drawings, you
won't need this and the next line, and can make them empty ("set gsdir="
and "set gs_lib="), or comment them out. If you want to use ghostscript,
the gs_lib variable should point to both the directory where ghostscript
is installed, and the directory where the postscript fonts are
installed.

Finally, when installing emTeX, you may have created a batch file that
sets all appropriate environment variables for emTeX (emtexdir,
dvidrvfonts, mfjobopt, etc.), and adds the emtex \ bin directory to your
path. If so, this batch file should be called here to ensure emTeX is
working properly, unless you already set these variables elsewhere (in
which case you can comment-out this line by putting two colons in front
of it). Note that whether you use the installation program or not,
you'll have to manually edit set_tex.bat to reflect your directory setup
if you've installed emTeX anywhere but in the default directories!

The batch file convert.bat needs no modification.

-- 5.2 The TeX4ht environment file --

TeX4ht requires a configuration file, TeX4ht.env, for proper operation.
Of this file, the two top lines need adjusting.

 tc:\apps\emtex\tfm\!
 ic:\apps\tex4ht\

The first line (starting with t) configures the path to the `.tfm ' (TeX
font metrics) files of your distribution; adjust it to your system. The
second line (starting with i) configures the directory TeX4ht searches
for it's `.htf ' files. If either of these lines ends in an exclamation
mark, subdirectories of the specified directory will be searched. The
other lines need no modification.

-- 5.3 emTeX --

For HTML pages that have no pictures in them, emTeX needs no special
configuration for TeX4ht to work with it. If pictures are required, a
special mode must be set up for emTeX to create output bitmaps with a
resolution of around 100 dpi. (Note that e.g. special accented
characters not defined for HTML are also converted to `.gif ' files).
Setting up emTeX this way also needs to be done if dvips and ghostscript
are used, as dvips includes a bitmap version of the used fonts in the
postscript file it creates. The following steps need to be taken to set
up emTeX for 96 dpi output:

- 5.3.1 Adding a Metafont mode -

The default Metafont modes file local.mf has no entry for 96 dpi
resolution. You'll have to add one, and rebuild the Metafont base files.
The file htm.mf contains the following mode:

 % A 96 dpi screen output mode:
 mode_def htm =
  proofing:=0; fontmaking:=1; tracingtitles:=0;
  pixels_per_inch:=96;
  blacker:=.3;
  fillin:=0;
  o_correction:=0;
  enddef;

You should add this mode to your local.mf file (residing in
emtex\mfinput\etc) by, e.g., typing the following commands at the DOS
prompt:

 cd \apps\emtex\mfinput\etc
 copy local.mf + \apps\tex4ht\htm.mf

(Please substitute the appropriate paths). These commands will append
the file htm.mf to your local.mf file. Now the Metafont base file must
be recompiled. Change to the appropriate Metafont base directory (if you
have a 386 or higher processor, this is most likely emtex\bmfbases).
You'll find a log file there for every base file you've compiled; at the
end of the log file you'll find the command with which the base file was
created. For example, on the author's system, the required command to
recompile the plain base file was

 makebas 386 plain -f plain

Please read the documentation in emtex\doc\english\metafont.doc for more
consise information on how to (re-)compile the base file(s).

When running TeX4ht for the first time, if you've used any characters
that HTML doesn't support, Metafont will be called to generate the
appropriate bitmaps at the resolution of 96 dpi. Metafont and the TeX
fonts weren't originally designed to handle such low output resolutions,
and may on occasion spit out error messages. These can safely be
ignored, but by default aren't. To make Metafont continue after
encountering such problems, the switch /i is added to the environment
variable mfjobopts for the duration of the conversion.

- 5.3.2 Other configuration files -

The emTeX dvidot driver needs a configuration file (htm.cnf) to know
what to call Metafont with for the automatic generation of fonts, and
where to store them. As these fonts are generated for 96 dpi, they can't
be taken from or stored with your normal printer fonts. The
configuration file sets things up so the fonts are stored in a
subdirectory called pixel.htm below the texfonts directory.

Dvips also needs a configuration file (htm.cfg) to tell it what mode to
call metafont with, the font location, and what resolution the generated
fonts have. Ghostscript needs no specific configuration file.

Display will have to be told how to convert it's input files. This is
done in the configuration file autocrop.cfg, which tells it to auto-crop
the input files, and output `.gif ' files.

All the above configuration files will be supplied to their programs
with an absolute path (based on the environment variable tex4htdir), and
therefore need not be copied anywhere.

--- 6 Use ---

-- 6.1 The test files --

For extensive instructions on the use of TeX4ht please read the manual
available in compressed form at
ftp://ftp.cis.ohio-state.edu/pub/tex/osu/gurari/TeX4ht/dos/mn-dos.zip.
We'll discuss compilation of the included test file here. The file
test.tex can be used to test TeX as well as LaTeX installations; it will
generate seven examples of the use of TeX4ht, and convert them to HTML.
As all this generates quite a lot of files, you may want to place
test.tex and ht.bat in a separate directory.

The main batch file of the port, 2htm.bat, does not call TeX or LaTeX,
because it does not know which one to run. For the test files, a batch
file is supplied that calls whichever you want to test. The syntax to
create all test files is " ht tex386 test " or " ht latex2e test ".
Here, ` ht ' is the name of the supplied batch file, ` test ' is the
base name of the test.tex file, and ` latex2e ' or ` tex386 ' is the
name with which you normally call TeX or LaTeX. Note that files
generated during the compilation of test.tex also call ht.bat, and
therefore need to know what name you use to call TeX or LaTeX with. The
default is tex386 for TeX, and latex2e for LaTeX. If you want to use a
different name, you will have to change the second line of the file
test.tex; this currently reads:

 \def\CALL{{tex386}{latex2e}}

Change the tex386 to whatever you call TeX with, and latex2e to what you
call LaTeX with.

When you run ht on the test file, you'll see a lot of activity on your
screen; if all goes well, you'll end up with a lot of files, among which
test.htm. This is the main file; from here, you can view the seven
created examples.

-- 6.2 Normal use --

Normal use of the port would consist of calling TeX or LaTeX a few times
(three is probably enough), and then calling 2htm to convert the created
files to HTML/GIF. For example:

 latex exmp
 latex exmp
 latex exmp
 2htm exmp

To use dvips and ghostscript to create the bitmaps (if any are
required), make that last line " 2htm exmp ps ".

-- 6.3 Port-specific details --

Some things to keep in mind:

# During creation of the HTML files, a temporary batch file is
  created in the current directory. This batch file is named after the
  `.dvi ' file that is being processed, prefixed with two $-signs (e.g.,
  test.tex will become $ $ test.bat). Any batchfile with that name that
  already exists will be overwritten without warning. The batchfile will
  be deleted when processing is done.

# All TeX4ht related screen output will be simultaneously saved in a
  log file; this file will have the base name of the `.dvi ' file, with
  an extention of `.hlg ' (e.g., processing of test.dvi will be logged
  in test.hlg). The TeX or LaTeX output will of course be in the normal
  `.log ' file.

# TeX4ht, in principle, can ask for the creation of bitmaps in many
  different formats (`.jpg ', `.png ',...). This port currently only
  supports the `.gif ' file format.

-- 6.4 Problems --

A known problem exists with the use of the emTeX dvidot autocrop
function in combination with the cropping the display program does.
Under some circumstances, too much may be cropped off the picture. There
are two possible solutions for this problem:

# Change in htm.cnf (the configuration file for the dvidot output
  driver) the line that reads +minimize:on to +minimize:off. This
  disables the cropping feature of this driver.

# Use the dvips/ghostscript combination instead, they don't have
  this problem.

The reason the default is to use the minimize feature, is that is
greatly improves translation speed, and gives trouble only in a small
number of cases.

Another problem exists when using the port in a DOS box under Windows
'95, and possibly Windows 3.11: the display program switches a windowed
DOS box to full screen. Restoring the previous setting is a matter of
pressing Alt-Enter. (If you use "EXIT" to leave the full-screen DOS box,
Windows '95 may retain the settings, resulting in the next DOS box you
open also to be full-screen).

I've also had a report of "file creation error" error messages. They are
related to the log (`.hlg ') file. I have not been able to reproduce
them, and they seem to be harmless.

If you encounter any other problems with TeX4ht, you can contact the
author, Eitan Gurari. If you think the problem is related to the DOS
port, you can contact me: Gertjan Klein.
