TeX4ht handles correctly only macros whose logical meanings are directly or indirectly declared in TeX4ht configurations. For instance, without extra configurations, TeX4ht will provide correct translation for
under a user’s definition of the form
but not under a definition of the form
It is highly recommended to leave source LaTeX and TeX files intact, and not introduce TeX4ht configurations there. The configurations should be introduced indirectly in private configuration files. Source files containing just native LaTeX and TeX code permit their compilation to different output formats, including PostScript and PDF, by TeX4ht and other tools.
Packages used by the general LaTeX community typically provide better support than one can expect from tailoring private commands and configurations for such commands. It is also expected to take less effort to learn the features of existing packages than designing new ones. Consequently, one is advised to investigate available resources before committing to work on private features.
The following are some of the more useful underlying commands of TeX4ht.
| 1 | \HCode{...} |
| 2 | \HPage{anchor}content\EndHPage{} |
| 3 | \Link[target-file arguments]{target-loc}{cur-loc}anchor\EndLink |
| 4 | \ifHtml...tex4ht code... \else...non tex4ht code... \fi (or \ifHtml\UnDef...non tex4ht code... \else...tex4ht code... \fi) |
| 5 | \ifOption{...}{true-part}{false-part} |
A non-leading package parameter ‘1’, ‘2’, ‘3’, or ‘4’, in \usepackage, asks for a tree-structured set of files, reflecting on the sectioning of the document to the specified depth. Sequential prev-next links within the hierarchy, instead of the default hierarchical ones, can be requested with the ‘next’ parameter. The parameter ‘sections+’ creates titles for the sectioning commands that link to the tables of contents.
Finer control is possible with the following commands.
| 1 | \CutAt{at-unit,until-unit-1,until-unit-2,...} |
| 2 | \tableofcontents[unit-1,unit-2,...] |
| 3 | \TocAt{at-unit,unit-1,unit-2,...,/until-unit-1,/until-unit-2,...} |
| 4 | \ConfigureToc{unit} {before-mark} {before-title} {before-page-number} {at-end} |
| 5 | \Configure{tableofcontents} {before-toc} {end-of-toc} {after-toc} {before-nonindented-par} {before-indented-par} |
| 6 | \Configure{TocAt} {before-toc} {after-toc} |
| 7 | \Configure{TocAt*} {before-toc} {after-toc} |
| 8 | \Configure{unit} {top} {bottom} {before-title} {after-title} |
| 9 | \Configure{CutAt} {unit} {before-button} {after-button} |
| 10 | \Configure{+CutAt} {unit} {before-button} {after-button} |
| 11 | \NewSection\unit {mark-for-toc} |
| 12 | \Configure{writetoc} {definitions-for-the-writing-environment} |
| 13 | \Configure{crosslinks} {left-delimiter} {right-delimiter} {next} {prev} {prev-tail} {front} {tail} {up} |
| 14 | \Configure{crosslinks+} {before-top-links} {after-top-links} {before-bottom-links} {after-bottob-links} |
Tables with \multicolum entries need a few LaTeX compilations to stabilize.
| 1 | \Configure{table} {before-tbl} {after-tbl} {before-row} {after-row} {before-entry} {after-entry} |
The appearances of lists and \begin-\end environments are configured with the following commands.
| 1 | \ConfigureList{list-name} {before-list} {after-list} {before-label} {after-label} |
| 2 | \ConfigureEnv{environment-name} {before-environment} {after-environment} {before-list} {after-list} |
The next command imports external pictures, and the two commands that follow request pictorial representations for local content. The attributes, and the replacement parameters with their enclosing rectangular brackets, are optional.
| 1 | \Picture[replacement-for-textual-browser]{file-name attributes} |
| 2 | \Picture+[replacement-for-text-browsers]{file-name attributes}content\EndPicture |
| 3 | \Picture*[replacement-for-text-browsers]{file-name attributes}content\EndPicture |
In the default setting, the math environments ‘\(...\)’, and the display math environments ‘\[...\]’ and ‘$$...$$’, request pictorial representations for their content. On the other hand, the math environments ‘$...$’ ask for no special treatment. Simple features like mathematical symbols, subscripts, and superscripts, are translated into html, and more complex entities like roots and fractions are translated into pictures (example).
| 1 | \Configure{[]} {before$$at-start} {at-end$$after},
\Configure{()}{before$at-start}{at-end$after} \Configure{$$}{before}{after}{at-start} \Configure{$}{before}{after}{at-start} |
| 2 | \Configure{SUB}{before}{after} \Configure{SUP}{before}{after} \Configure{SUBSUP}{before}{between}{after} |
| 3 | no_, no^ |
The insertions of code at paragraph breaks are controlled by the following commands.
| 1 | \Configure{HtmlPar} {noindent-P} {indent-P} {from-noindent-P} {from-indent-P} \EndP |
| 2 | \IgnorePar |
| 3 | \ShowPar |
| 4 | \IgnoreIndent |
| 5 | \ShowIndent |
Cascade style sheets attach presentations to the content of hypertext pages, in a manner similar to the way that ‘.sty’ files define the presentations to the content of source LaTeX files. TeX4ht produces a CSS file for each document that is translated to HTML transitional 4.0 code. The following are related commands.
| 1 | \Css{content} |
| 2 | \Css content\EndCss |
| 3 | \CssFile[list-of-css-files]content\EndCssFile |
TeX4ht has an elaborated machinery for handling fonts, through special virtual hypertext fonts stored in ‘.htf’ files. Instead of providing a design for each symbol, as is the case in standard fonts, the virtual fonts provide a content for each symbol. The following commands offer some control, from within the source LaTeX documents, over the content provided to the symbols.
| 1 | \NoFonts |
| 2 | \EndNoFonts |
| 3 | \Configure{htf} {class} {delimiter} {template-1} {template-2} {template-3} {template-4} {template-5} {template-6} {template-7} |
| 4 | \Configure{htf-sty} {class/font} {CSS-instructions} |
The htf fonts might request pictorial representations for symbols. In such cases, the sizes of the pictures depend on the sizes of the TeX fonts in use. Size changes through the \magnification command should be made before loading the tex4ht.sty package.
The design of a virtual hypertext font might take some labor, but it does not require too much sophistication.
A font of TeX may have more than one htf font to map to. The search for a desired version can be regulated within scripts.
Scripts produce the content in verbatim format with no decorations.
| 1 | \ScriptEnv{environment} {prefix} {postfix} |
| 2 | \ScriptCommand{\command} {prefix} {postfix} |
| 3 | \JavaScript...\EndJavaScript |
Much of the look and feel of TeX4ht is achieved through hooks that are introduced and configured with the following commands.
| 1 | \NewConfigure{name}[i]{body} |
| 2 | \Configure{name}{parameter-1}...{parameter-i} |
Block {\begin}...\end environments may also be configured through the \ConfigureEnv command, and lists may also employ the \ConfigureList command.
For help configuring hooks already seeded in the system, compile the source files in use with the ‘info’ option active and review the information in log files. Much of the information in the log files may also be obtained by running ‘xhlatex mktex4ht’ and reviewing the entries in the outcome page ‘mktex4ht.html => index => mktex4ht’.
A compilation starts by opening tex4ht.sty and loading a fraction of its code. The main purpose of this phase is to request the loading of the system at a later time (for instance, upon reaching \begin{document}). The motivation for the late loading is to allow TeX4ht to collect as much information as possible about the environment requested by the source file, and help the system reshape that environment with minimal interference from elsewhere.
The system uses two kinds of (4ht) configuration files. The files of the first kind mainly seed hooks into the macros loaded by the source file (for instance, latex.4ht, fontmath.4ht, and article.4ht). The files of the second kind mainly attach meaning to the hooks (for instance, html4.4ht, unicode.4ht, and mathml.4ht).
Different source files may request the loading of different style files and in different orders. The hook seeding files are loaded in response to the loading of the style files, and in a compatible order. Since the different style files may redefine the syntax and semantics of macros, TeX4t follows a similar route of defining and redefining the hooks and their meanings.
The meaning attaching files are normally requested through option names introduced in the tex4ht.4ht system file. For instance, the mzlatex command refers to the mozilla option name of tex4ht.4ht, and the oolatex command refers to the ooffice option name. The user may add option names, and redefine old ones, within a new file named tex4ht.usr.
A new tex4ht.usr file should group references to *.4ht configuration files under arbitrarily chosen option names. For that purpose, \Configure commands similar to those provided in tex4ht.4ht should be employed.
Variants of the htlatex-like scripts may be produced in the following manner.
It is the ooffice script from tex4ht.4ht, with the added record ‘\Hinclude[*]{myooconfig.4ht}%’.