NAME
TeX4ht - a system for authoring hypertext with TeX and friends
SYNOPSIS
mk4ht command file [ options1 ] [ options2 ] [ options3 ]
httex|htlatex|httexi file [ options1 ] [ options2 ] [ options3 ]
ht tex|latex file [ t4ht options ]
tex4ht [ -fdir-char ] file[.dvi] [ -ctag-name ] [ -eenv-file ] [
-gbitmap-file-ext ] [ -h(e|f|F|g|s|v|V) ] [ -ihtf-font-dir ] [
-lbookkeeping-file ] [ -P(*|filter) ] [ -ttfm-font-dir ] [ -u10 ] [
-utf8 ] [ -xs ]
t4ht [ -fdir-char ] file[.lg] [ -ctag-name ] [ -dout-dir ] [ -eenv-file
] [ -i ] [ -mmode ] [ -Mmode ] [ -p ] [ -r ] [ -S(*|filter) ] [
-Xfield-content ] [ -.field-content ]
DESCRIPTION
(This manual page was written for the Debian GNU/Linux distribution
because the original program does not have a manual page. Instead, it
is documented in detail at the author's website; see below. Please
refer to that documentation for more details or up to date
information.)
This page documents briefly the portmanteau perl script mk4ht, the more
specific shell scripts httex, htlatex, httexi, and others like them,
the lower level shell script interface ht, and the commands tex4ht and
t4ht that all these scripts invoke. Together these programs constitute
TeX4ht; a highly configurable TeX-based authoring system for producing
hypertext.
TeX4ht interacts with TeX-based applications through a style file
tex4ht.sty and other files which are loaded by this style file, leaving
the processing of the source files to the native TeX compiler. The
output of the TeX compiler is then post-processed by tex4ht and t4ht.
Consequently, TeX4ht can handle most features of TeX-based systems in
general, and of LaTeX in particular.
The shell scripts httex , htlatex and httexi convert TeX (respectively
LaTeX and texinfo) into HTML. Typical user requirements should be
satisfied by these scripts which can generally convert typical TeX
source without requiring any modifications.
To convert from a one of the other dialects of TeX (like ConTeXt), or
to convert into one of the other variants of hypertext (MathML, XML, OO
and so on), it is recommended that you use the perl script mk4ht. Most
common usage of the system can be covered by the appropriate use of
this command with its options.
The shell script ht is a much more elementary script which is provided
for more complicated needs. Its correct use depends on a better
understanding of the system.
All these scripts begin with suitable invocations of tex(1) or latex(1)
or other dialects of TeX as required. The post-processing of the .dvi
output is handled by tex4ht. Anything that cannot be rendered using
HTML (or its chosen hypertext variant), such as the creation of bitmap
images or CSS (Cascade Style Sheet) files is handled by the auxiliary
program t4ht. The method used for generating the images can be
configured.
OPTIONS
The following is only a very brief summary of the main program options.
For more details of the command-line and configuration options, see the
HTML documentation (see below).
Options for httex, htlatex and httexi
httex, htlatex and httexi are shell scripts that can be used to convert
a file in the TeX/LaTeX/texinfo format into HTML. This TeX source file
should be like any other TeX source file normally used to produce a
.dvi file by processing with TeX and friends. The name of such a file
is the mandatory file argument for each script. This is followed by up
to three optional arguments (delimited with quotation marks). These
arguments, which are not required for typical usage, are as follows:
1. The first argument is a list of options for the tex4ht.sty style
file (used with tex or latex), separated with commas. See the
HTML documentation for the list of options available. The .log
file generated by tex/latex also includes summaries of some of
the options available. If not empty, this argument must start
with html or xhtml. Additional options could be mathml or
docbook to indicate appropriate style of output.
2. This argument is used to select tagged sections of tex4ht.env
that specifies the font files (*.htf) to use. This corresponds
to the -c option for the command tex4ht as explained below.
Examples include unicode or mozilla.
3. This argument lists options for the t4ht program as explained
below.
See the HTML documentation for more details and examples.
Similar scripts are available within the directory /usr/share/tex4ht
for generating other kinds of hypertext output. It is also possible to
use the perl script mk4ht as explained below.
Options for mk4ht
mk4ht is a perl script that can be used to convert TeX source files
from numerous dialects of TeX into different hypertext variants. This
script takes two mandatory arguments: the name of the command to run
and the file to run it on. Each possible command is of the form
"<variant><dialect>": so for example xhmlatex denotes a LaTeX source
that needs to be converted to XHTML with MathML extensions. The
possible names for commands can be found by listing the directory
/usr/share/tex4ht. The three optional arguments to mk4ht are identical
to those outlined above for httex, htlatex and httexi. In fact, the
command htlatex foo is identical to mk4ht htlatex foo except that the
former is shorter to type! However, mk4ht can be configured to shorten
the command line as follows.
Each user can create the configuration file mk4ht.cfg or .mk4ht in the
home or working directory to configure commonly used options for mk4ht;
in addition options to clean up temporary files can also be added to
this configuration file. Running the command mk4ht without any
arguments will summarise the use of this user configuration file.
Options for ht
ht is a small shell script that is used to run the tex4ht programs. It
has two compulsory arguments, as follows:
1. The TeX command name to run, usually either tex or latex.
2. The input file name (with or without extension).
It may take any additional options, which will be passed on to the call
to t4ht.
General directory/file search options
Several of the options detailed below relate to setting directory paths
to find particular kinds of files. Note the following when specifying
directories for the programs:
1. There must be no space between the option letter (eg, -t) and
the directory/file name.
2. The directory name must end with a trailing slash (/, or /! -
see below).
3. You can add an exclamation mark (!) to the end of the directory
name, to enable sub-directory searching.
4. Only one directory can be specified at a time. To search
multiple directories, either use the sub-directory searching
facility or repeat the option. (The directory search options
can be repeated as often as required.)
5. When compiled with kpathsea (as in the Debian package), the
path-searching is in part taken over by kpathsea. On a Debian
system see /usr/share/doc/tex4ht/README.kpathsea for more
information on path-searching in a kpathsea-enabled tex4ht.
As well as command-line options, most of these options can (and
normally should) be set in the configuration file tex4ht.env. The
format within this file is similar, but without using a hyphen before
the option letter. See the HTML documentation for more details on the
configuration options available. The file tex4ht.env can be superseded
on a per-directory and/or a per-user basis as explained in the HTML
documentation. On a Debian system see
/usr/share/doc/tex4ht/README.Debian as well.
Options for tex4ht
-ctag-name
Certain lines within the tex4ht.env configuration file can be
marked with tags. These lines (typically htf-font-dir search
lines) will be omitted unless specifically requested by
specifying the tag name on the tex4ht command line. If not
used, a command-line option of -cdefault is assumed. (See the
supplied tex4ht.env file for examples of tagged sections.)
-eenv-file
Specify address of the tex4ht configuration file tex4ht.env.
-gbitmap-file-ext
Set the extension of bitmap images to bitmap-file-ext instead of
the default .png. Note that the extension should begin with a
dot (.). Note also that this option only affects images
generated automatically for symbol fonts, and not images
generated with the \Picture macro of tex4ht.
-he Trace errors and warnings (produces verbose output).
-hg Trace groups
-hs Trace \specials.
-hV Trace search path for tex4ht.env configuration file
-hF Trace search path for .htf font files
-hv Dump contents of found tex4ht.env configuration file to stderr
(for debugging)
-hf Dump contents of each .htf font file found to stderr (for
debugging)
-ihtf-font-dir
Set directory for HTF font files (used by tex4ht) to htf-font-
dir.
-lbookkeeping-file
Specify name of the file listing cache used to speed up filename
lookups (ignored if compiled with kpathsea support)
-Pfilter
Restrict system calls requested in the source (La)TeX files to
utilities whose names have filter as a prefix. Use a single
asterisk as filter to allow any system calls.
-ttfm-font-dir
Set directory for TFM font files to tfm-font-dir (ignored if
compiled with kpathsea support).
-u10 Use base 10 encoding for unicode characters.
-utf8 Use utf-8 encoding for unicode characters.
-xs Use 8.3 (MSDOS style) file names for the generated PNG files.
Options for t4ht
-ctag-name
Certain lines within the tex4ht.env configuration file can be
marked with tags. These lines (typically scripts for post-
processing files) will be omitted unless specifically requested
by specifying the tag name on the tex4ht command line. If not
used, a command-line option of -cdefault is assumed. (See the
supplied tex4ht.env file for examples of tagged sections.)
-dout-dir
Output files to directory out-dir, instead of to the current
directory.
-eenv-file
Specify address of the tex4ht configuration file tex4ht.env.
-i Generate verbose debugging output.
-mmode Create any new output files with access mode as indicated by
mode. The mode should be a numeric mode, as used by the
chmod(1) command.
-Mmode As -m but change all mode of all output files (including reused
bitmaps).
-p Do not convert pictures (ie, images generated with macros like
\Picture, not characters in symbol fonts that will be
automatically converted into a graphic file).
-r Do not resuse existing bitmaps of glyphs (for characters in
symbol fonts etc), but instead generate all bitmaps anew.
-Sfilter
Restrict system calls requested in the source (La)TeX files to
utilities whose names have filter as a prefix. Use a single
asterisk as filter to allow any system calls.
-Xfield-content
Scripts for post-processing of files can be specified in
tex4ht.env. If these scripts refer to a field %%3, content for
that field can be set with this command-line option.
-.field-content
Scripts for post-processing of groups of files with a particular
extension can be specified in tex4ht.env. If these scripts
refer to a field %%2, content for that field can be set with
this command-line option.
FILES
/etc/tex4ht/tex4ht.env
Configuration file for tex4ht. This file is commented within
the file, and some additional notes are in
/usr/share/doc/tex4ht/README.kpathsea on a Debian system.
Further explanation is available in the HTML documentation.
/etc/texmf/texmf.cnf
Global configuration file for all TeX-related programs using the
kpathsea path searching library. The variables TEX4HTINPUTS,
T4HTINPUTS and TEX4HTFONTSET within this file relate to file
searching within tex4ht and t4ht. These variables may also be
set in the environment, outwith /etc/texmf/texmf.cnf.
/usr/share/texmf/tex4ht/ht-fonts/*.htf
Hypertext font files used by tex4ht.
/usr/share/texmf/tex/generic/tex4ht/tex4ht.sty and
/usr/share/texmf/tex/generic/tex4ht/*.4ht
Macro files used by tex or latex when using tex4ht to generate
HTML output.
/usr/share/tex4ht/*
Shell scripts for generating different kinds of hypertext output
from tex or latex sources.
SEE ALSO
The use of the tex4ht macros is documented in the HTML documentation at
the web site given below.
tex(1), latex(1), amstex(1), kpsewhich(1), http://www.cse.ohio-
state.edu/~gurari/TeX4ht/mn.html
BUGS
This manual page is not complete. Users should refer to the HTML
documentation for fuller details of the configuration options and for
details of the use of the tex4ht style files. tex4ht is still a work
in progress, so bug reports and requests are very welcome: contact
Eitan Gurari <gurari@cis.ohio-state.edu>.
AUTHOR
This manual page was originally written by Andrew Gray
<ajpg@debian.org> (and then modified by Kapil Paranjape), for the
Debian GNU/Linux system (but it may be used by others).
The tex4ht programs and macro files were written by Eitan Gurari
<gurari@cis.ohio-state.edu>. The author maintains a home page at
http://www.cse.ohio-state.edu/~gurari/TeX4ht/
5 Apr 2005