up

## Conﬁgurations

∙ Background ∙ Recommendations ∙ Low-Level Features ∙ Sectioning and Tables of Contents ∙ Tables ∙ Lists and Environments ∙ Pictures ∙ Mathematical Formulas ∙ Paragraphs ∙ Cascade Style Sheets (CSS) ∙ Fonts ∙ Scripts ∙ Conﬁgurable Hooks ∙ General Conﬁguration Files

## Background

TeX4ht handles correctly only macros whose logical meanings are directly or indirectly declared in TeX4ht conﬁgurations. For instance, without extra conﬁgurations, TeX4ht will provide correct translation for

\divide{a}{b}

under a user’s deﬁnition of the form

\def\divide#1#2{{#1\over #2}}

but not under a deﬁnition of the form

\def\divide#1#2{\vbox{\hbox{$#1$}\hrule\hbox{$#2$}}}

## Recommendations

It is highly recommended to leave source LaTeX and TeX ﬁles intact, and not introduce TeX4ht conﬁgurations there. The conﬁgurations should be introduced indirectly in private conﬁguration ﬁles. Source ﬁles 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 conﬁgurations 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.

1 | \HCode{...}
2 | \HPage{anchor}content\EndHPage{}
3 | \Link[target-ﬁle 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}

## Sectioning and Tables of Contents

A non-leading package parameter ‘1’, ‘2’, ‘3’, or ‘4’, in \usepackage, asks for a tree-structured set of ﬁles, reﬂecting on the sectioning of the document to the speciﬁed 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} {deﬁnitions-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

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}

## Lists and Environments

The appearances of lists and \begin-\end environments are conﬁgured 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}

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

1 | \Picture[replacement-for-textual-browser]{ﬁle-name attributes}
2 | \Picture+[replacement-for-text-browsers]{ﬁle-name attributes}content\EndPicture
3 | \Picture*[replacement-for-text-browsers]{ﬁle-name attributes}content\EndPicture

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

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ˆ

## Paragraphs

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 (CSS)

Cascade style sheets attach presentations to the content of hypertext pages, in a manner similar to the way that ‘.sty’ ﬁles deﬁne the presentations to the content of source LaTeX ﬁles. TeX4ht produces a CSS ﬁle 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-ﬁles]content\EndCssFile

## Fonts

TeX4ht has an elaborated machinery for handling fonts, through special virtual hypertext fonts stored in ‘.htf’ ﬁles. 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

Scripts produce the content in verbatim format with no decorations.

1 | \ScriptEnv{environment} {preﬁx} {postﬁx}
2 | \ScriptCommand{\command} {preﬁx} {postﬁx}
3 | \JavaScript...\EndJavaScript

## Conﬁgurable Hooks

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

1 | \NewConfigure{name}[i]{body}
2 | \Configure{name}{parameter-1}...{parameter-i}

Block {\begin}…\end environments may also be conﬁgured through the \ConfigureEnv command, and lists may also employ the \ConfigureList command.

For help conﬁguring hooks already seeded in the system, compile the source ﬁles in use with the ‘info’ option active and review the information in log ﬁles. Much of the information in the log ﬁles may also be obtained by running ‘xhlatex mktex4ht.4ht’ and reviewing the entries in the outcome page ‘mktex4ht.html => index => mktex4ht’.

## General Conﬁguration 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 ﬁle, and help the system reshape that environment with minimal interference from elsewhere.

The system uses two kinds of (4ht) conﬁguration ﬁles. The ﬁles of the ﬁrst kind mainly seed hooks into the macros loaded by the source ﬁle (for instance, latex.4ht, fontmath.4ht, and article.4ht). The ﬁles of the second kind mainly attach meaning to the hooks (for instance, html4.4ht, unicode.4ht, and mathml.4ht).

Different source ﬁles may request the loading of different style ﬁles and in different orders. The hook seeding ﬁles are loaded in response to the loading of the style ﬁles, and in a compatible order. Since the different style ﬁles may redeﬁne the syntax and semantics of macros, TeX4t follows a similar route of deﬁning and redeﬁning the hooks and their meanings.

The meaning attaching ﬁles are normally requested through option names introduced in the tex4ht.4ht system ﬁle. 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 redeﬁne old ones, within a new ﬁle named tex4ht.usr.

A new tex4ht.usr ﬁle should group references to *.4ht conﬁguration ﬁles 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 deﬁnition of new meaning assigning conﬁguration ﬁles can be considerable simpliﬁed by relying on literate programming and the ﬁle mktex4t.4ht. For additional information, compile this ﬁle into a hypertext document, visit the ‘index’ page, and from there reach into the ‘mktex4ht’ page.

Example

1. Add a conﬁguration ﬁle myooconfig.4ht with the following content.
   \exit:ifnot{jurabib}
   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   \ConfigureHinput{jurabib}
   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   \def\jbNoLink#1#2{}
   \Configure{jblink}{\jbNoLink}{}
   \Configure{jbanchor}{\jbNoLink}{}
   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   \endinput\empty\empty\empty\empty\empty\empty
   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   \endinput

2. Add to tex4ht.usr the following script.
   \Configure{myooffice}{%
   \:CheckOption{info}\if:Option
   \Hinclude[*]{infoht4.4ht}\fi
   \:CheckOption{info}\if:Option
   \Hinclude[*]{infomml.4ht}\fi
   \Hinclude[*]{ooffice.4ht}%
   \Hinclude[*]{unicode.4ht}%
   \Hinclude[*]{mathml.4ht}%
   \Hinclude[*]{ooffice-mml.4ht}%
   \Hinclude[*]{myooconfig.4ht}%
   }

   It is the ooffice script from tex4ht.4ht, with the added record ‘\Hinclude[*]{myooconfig.4ht}%’.

3. Invoke the compilations with a variant of the following form of the oolatex command.
   htlatex filename "xhtml,myooffice" "ooffice/! -cmozhtf" "-coo"