.\" $Id$
.\" Written by Andrew Gray <ajpg@debian.org>, 12 March 1999
.\" Revised Tue, 22 Jun 1999 09:53:47 +0100
.\" Revised Sun, 16 Jul 2000 14:08:07 +0100
.\" Revised Sat,  3 May 2003 22:41:20 +0100
.\" Revised by Kapil Hari Paranjape Tue,  5 Apr 2005 08:51:27 +0530
.\" Revised Thu, 11 Sep 2008 12:40:50 +0530
.\" Further revisions after inclusion in the TeX4ht package.
.TH TEX4HT 1 "3 Feb 2019"
.SH NAME
tex4ht, ht, mk4ht, httex, htlatex, httexi, htcontext, htmex, htxelatex, htxetex, xhlatex, t4ht \- a system for authoring hypertext with TeX and friends
.SH SYNOPSIS
.BR mk4ht
.I command
.I file
.RI "[ " "options1" " ]"
.RI "[ " "options2" " ]"
.RI "[ " "options3" " ]"
.LP
.BR httex | htlatex | httexi
.I file
.RI "[ " "options1" " ]"
.RI "[ " "options2" " ]"
.RI "[ " "options3" " ]"
.LP
.B ht
tex|latex
.IR file " [ " "t4ht options" " ]"
.LP
.B tex4ht
[
.BI \-f dir-char
]
.I file[.dvi]
[
.BI \-c tag-name
] [
.BI \-e env-file
] [
.BI \-g bitmap-file-ext
] [
.BR \-h ( e|f|F|g|s|v|V )
] [
.BI \-i htf-font-dir
] [
.BI \-l bookkeeping-file
] [
.BR \-P ( * | \fIfilter\fP )
] [
.BI \-t tfm-font-dir
] [
.B \-u10
] [
.B \-utf8
] [
.B \-xs
]
.LP
.B t4ht
[
.BI \-f dir-char
]
.I file[.lg]
[
.BI \-c tag-name
] [
.BI \-d out-dir
] [
.BI \-e env-file
] [
.B \-i
] [
.BI \-m mode
] [
.BI \-M mode
] [
.B \-p
] [
.B \-r
] [
.BR \-S ( * | \fIfilter\fP )
] [
.BI \-X field-content
] [
.BI \-. field-content
]
.LP
.SH "DESCRIPTION"
This page briefly documents
the portmanteau perl script
.BR mk4ht ",
the more specific shell scripts
.BR httex ", "htlatex ", "httexi ",
and their siblings, the lower level shell script interface
.BR ht ",
and the commands
.BR tex4ht " and "t4ht "
that all these scripts invoke. Together these programs constitute
TeX4ht: a highly configurable TeX-based authoring system for producing
hypertext documents
.PP
TeX4ht interacts with TeX-based applications through a style file
.I tex4ht.sty
and (many) other files which are loaded by this style file,
leaving the processing of the source files to the native TeX
compiler. The (DVI) output of the TeX compiler is then post-processed by
.BR tex4ht " and "t4ht ".
Consequently, TeX4ht can handle most features of TeX-based systems in
general, and of LaTeX in particular.
.PP
The shell scripts
.BR "httex" , " htlatex " and " httexi
convert TeX, LaTeX, and Texinfo, respectively, into HTML. The
.B xhlatex
script converts TeX to XHTML. The less-commonly used
.B htcontext
and
.B htmex
use the ConTeXt (\fIhttp://contextgarden.net\fR) and MeX dialects of
TeX. The scripts
.B htxetex
and
.B htxelatex
use the XeTeX (\fIhttps://tug.org/xetex\fR) engine for plain TeX and
XeTeX.
.PP
Typical user requirements should be satisfied by these scripts
which can generally convert typical TeX source without requiring
modification.
.PP
To convert from another dialect of TeX or
to convert into one of the other variants of hypertext
(MathML, XML, OpenOffice and so on), it is
recommended
that you use the perl script
.BR mk4ht .
Most common usage of the
system can be covered by the appropriate use of this command with its options.
.PP
The shell script
.B 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.
.PP
All these scripts begin with suitable invocations of
.BR tex (1)
or
.BR latex (1)
or other dialects of TeX as required. The post-processing of the
.I .dvi
output is handled by
.BR "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
.BR "t4ht".
The method used for generating images can be configured.
.PP
.SH 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).
.SS Options for httex, htlatex and httexi
.BR 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
.I .dvi
file by processing with TeX and friends. The name of the TeX source file
is the mandatory file argument for each script. This is followed by up
to three optional arguments (typically delimited with quotation marks
for the shell). These arguments, which are not
required for typical usage, are as follows:
.IP 1.
The first argument is a list of options for the
.I tex4ht.sty
style file (used with tex or latex), separated with commas.
See the HTML documentation for the list of options available. The
.I .log
file generated by tex/latex also includes summaries of some of the options available.
If not empty, this argument must start with
.B html
or
.BR xhtml .
Additional options could be
.B mathml
or
.B docbook
to indicate the desired (sub)style of output.
.IP 2.
This argument is used to select tagged sections of
.I tex4ht.env
that specifies the font files (*.htf) to use. This corresponds to the
.BI \-c
option for the command
.I tex4ht
as explained below. Examples include
.B unicode
or
.BR mozilla .
.IP 3.
This argument lists options for the
.I t4ht
program as explained below.
.LP
See the HTML documentation for more details and examples.
.LP
Similar scripts are
available within the directory
.I /usr/share/tex4ht
for generating other kinds of hypertext output. It is also possible
to use the perl script
.BR mk4ht
as explained below.
.SS Options for mk4ht
.BR 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
.IR 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
.I /usr/share/tex4ht.
The three optional arguments to
.BR mk4ht
are identical to those outlined above for
.BR httex ", "htlatex " and " httexi ".
In fact, the command
.BR htlatex " "foo "
is identical to
.BR mk4ht " "htlatex " "foo "
(except that the former is shorter to type). However,
.BR mk4ht
can be configured to shorten the command line as follows.
.PP
Each user can create the configuration file
.IR mk4ht.cfg
or
.IR .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
.BR mk4ht
without any arguments will summarize the use of this user configuration
file.
.SS Options for ht
.B ht
is a small shell script that is used to run the tex4ht programs.  It has two
required arguments, as follows:
.IP 1.
The TeX command name to run, usually either
.B tex
or
.BR latex .
.IP 2.
The input file name (with or without extension).
.PP
It may take any additional options, which will be passed on to the call to
.BR t4ht .
.SS 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:
.IP 1.
There must be no space between the option letter (eg,
.BR \-t )
and the directory/file name.
.IP 2.
The directory name must end with a trailing slash
.RB ( / ,
or
.B /!
\- see below).
.IP 3.
You can add an exclamation mark
.RB ( ! )
to the end of the directory name, to enable sub-directory searching.
.IP 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.)
.IP 5.
When compiled with
.B kpathsea
(as in the Debian package), the path-searching is in part taken over by
kpathsea.  On a Debian system see
.I /usr/share/doc/tex4ht/README.kpathsea
for more information on path-searching in a kpathsea-enabled tex4ht.
.LP
As well as command-line options, most of these options can (and normally
should) be set in the configuration file
.IR 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
.IR 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
.I /usr/share/doc/tex4ht/README.Debian
as well.
.SS Options for tex4ht
.TP
.BI \-c tag-name
Lines within the
.I tex4ht.env
configuration file can be marked with tags.  These lines (typically
.I htf-font-dir
search lines and scripts for post-processing)
will be omitted unless specifically requested by specifying the tag name on
the tex4ht command line.  If not used, a command-line option of
.BI \-c default
is assumed.  (See the supplied
.I tex4ht.env file
for examples of tagged
sections.)
.TP
.BI \-e env-file
Specify address of the tex4ht configuration file
.IR tex4ht.env .
.TP
.BI \-g bitmap-file-ext
Set the extension of bitmap images to
.I bitmap-file-ext
instead of the default
.IR .png .
Note that the extension should begin with a dot
.RB ( . ).
Note also that this option only affects images generated automatically for
symbol fonts, and not images generated with the
.B \(rsPicture
macro of tex4ht.
.TP
.B \-he
Trace errors and warnings (produces verbose output).
.TP
.B \-hg
Trace groups
.TP
.B \-hs
Trace
.BR \(rsspecial s.
.TP
.B \-hV
Trace search path for
.I tex4ht.env
configuration file
.TP
.B \-hF
Trace search path for
.I .htf
font files
.TP
.B \-hv
Dump contents of found
.I tex4ht.env
to stderr (for debugging)
.TP
.B \-hf
Dump contents of each
.I .htf
font file found to stderr (for debugging)
.TP
.BI \-i htf-font-dir
Set directory for HTF font files (used by tex4ht) to
.IR htf-font-dir .
.TP
.BI \-l bookkeeping-file
Specify name of the file listing cache used to speed up filename lookups
(ignored if compiled with kpathsea support)
.TP
.BI \-P filter
Restrict system calls requested in the source (La)TeX files to utilities whose
names have
.I filter
as a prefix.  Use a single asterisk as
.I filter
to allow any system calls.
.TP
.BI \-t tfm-font-dir
Set directory for TFM font files to
.I tfm-font-dir
(ignored if compiled with kpathsea support).
.TP
.BI \-u10
Use base 10 encoding for Unicode characters.
.TP
.BI \-utf8
Use UTF-8 encoding for Unicode characters.
.TP
.BI \-xs
Use 8.3 (MSDOS style) file names for the generated PNG files.
.SS Options for t4ht
.TP
.BI \-c tag-name
Same as the -c option for tex4ht, see above.
.TP
.BI \-d outdir
Output files to directory
.IR outdir ,
instead of to the current directory.
.TP
.BI \-e env-file
Specify address of the tex4ht configuration file
.IR tex4ht.env .
.TP
.B \-i
Generate verbose debugging output.
.TP
.BI \-m mode
Create any new output files with access mode as indicated by
.IR mode .
The
.I mode
should be a numeric mode, as used by the
.BR chmod (1)
command.
.TP
.BI \-M mode
As
.I -m
but change all mode of all output files (including reused bitmaps).
.TP
.B \-p
Do not convert pictures (i.e., images generated with macros like
.BR \(rsPicture ,
not characters in symbol fonts that will be automatically converted into a
graphic file).
.TP
.B \-r
Do not resuse existing bitmaps of glyphs (for characters in symbol
fonts, etc.), but instead generate all bitmaps anew.
.TP
.BI \-S filter
Restrict system calls requested in the source (La)TeX files to utilities whose
names have
.I filter
as a prefix.  Use a single asterisk as
.I filter
to allow any system calls.
.TP
.BI \-X field-content
Scripts for post-processing of files can be specified in
.IR tex4ht.env .
If these scripts refer to a field %%3, content for that field can be set
with this command-line option.
.TP
.BI \-. field-content
Scripts for post-processing of groups of files with a particular extension can
be specified in
.IR tex4ht.env .
If these scripts refer to a field %%2, content for that field can be set
with this command-line option.
.SH FILES
The locations below are Debian-specific; if you're not on Debian,
consider them as shown for the sake of example. In the original TeX Live
(TL) distribution (\fIhttps://tug.org/texlive\fR), all files are
installed under the TL root, /usr/local/texlive/ by default.
.TP
.I /etc/tex4ht/tex4ht.env
Configuration file for tex4ht.  This file is commented within the file, and
some additional notes are in
.I /usr/share/doc/tex4ht/README.kpathsea
on a Debian system.  Further explanation is available in the HTML
documentation.
.TP
.I /etc/texmf/texmf.cnf
Global configuration file for all TeX-related programs using the kpathsea path
searching library.  The variables
.IR TEX4HTINPUTS ,
.I T4HTINPUTS
and
.I TEX4HTFONTSET
within this file relate to file searching within
.B tex4ht
and
.BR t4ht.
These variables may also be set in the environment, outwith /etc/texmf/texmf.cnf.
.TP
.I /usr/share/texmf/tex4ht/ht-fonts/*.htf
Hypertext font files used by tex4ht.
.TP
.IR /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.
.TP
.I /usr/share/tex4ht/*
Shell scripts for generating different kinds of hypertext output from tex or
latex sources.
.SH "SEE ALSO"
The use of the tex4ht macros is more fully documented in the HTML
documentation at the web site given here.
.PP
.BR tex (1),
.BR latex (1),
.BR kpsewhich (1),
.I https://tug.org/tex4ht
.PP
ConTeXt can output XML directly, which is probably much more useful than
the ConTeXt support in tex4ht, which has not been kept up to date; see
.IR https://wiki.contextgarden.net/XML .
.PP
One of the tex4ht volunteers, Michal Hoftich, has developed an
alternative build approach for tex4ht documents to the myriad shell
scripts described here, and also a converter using tex4ht to produce
ebook formats; see
.IR https://ctan.org/pkg/make4ht " and " https://ctan.org/pkg/tex4ebook .
(They are included in TeX Live.)
.SH BUGS
This manual page is not complete.  Users should refer to the package
documentation for fuller details of the
configuration options and for details of the use of the tex4ht style files.
.B tex4ht
is still a work in progress, so bug reports, patches, discussion, are
all very welcome; the web site has contact information.
.SH AUTHOR
This manual page was originally written by Andrew Gray,
then modified by Kapil Paranjape and others,
for the Debian GNU/Linux system (but it may be used by others).
It is currently maintained as part of the tex4ht package.
.PP
The
.B tex4ht
programs and macro files were originally written by Eitan Gurari. After
his untimely death, maintainership passed to volunteers (more help is
welcome). The tex4ht home page is
.IR https://tug.org/tex4ht .