up

Configurations

Background

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

Recommendations

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.

Low-Level Features

The following are some of the more useful underlying commands of TeX4ht.

Sectioning and Tables of Contents

A non-leading command line argument ‘1’, ‘2’, ‘3’, or ‘4’ 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.

Tables

Tables with \multicolum entries need a few LaTeX compilations to stabilize.

Lists and Environments

The appearances of lists and \begin-\end environments are configured with the following commands.

Pictures

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.

Mathematical Formulas

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).

Paragraphs

The insertions of code at paragraph breaks are controlled by the following commands.

Cascade Style Sheets (CSS)

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.

Fonts

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.

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

Scripts produce the content in verbatim format with no decorations.

Configurable Hooks

Much of the look and feel of TeX4ht is achieved through hooks that are introduced and configured with the following commands.

Block environments \begin…\end may also be configured through the \ConfigureEnv command. 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.4ht’ and reviewing the entries in the outcome page ‘mktex4ht.html => index => mktex4ht’.

As an example, the footer is placed on these HTML pages using the @/BODY hook, like this (inside \Preamble…\EndPreamble):

General Configuration Files

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.

1. Adjust the latex (tex, texi) command of a given script to use a desired option name, and rename the new script.
2. Make sure the tex4ht and t4ht commands receive appropriate switches in the new script. (These commands show the available options when invoked without parameters.)

The definition of new meaning assigning configuration files can be considerable simplified by relying on literate programming and the file mktex4t.4ht. For additional information, compile this file into a hypertext document, visit the ‘index’ page, and from there reach into the ‘mktex4ht’ page.

Generated August 24, 2020 - tex4ht home page