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/