An Annotated TeX Source

Mahesh wanted to see the annotated source of the TeX document that generated the output shown here. There are two components in the source:  (1) document source, let us call it as test.tex, (2) a custom configuration for TeX4ht, let us call it as my.cfg.

Document Source

documentclass[a4paper]{article}

\usepackage{lettrine}
\usepackage{lipsum,shortvrb}
\usepackage[utf8]{inputenc}

\MakeShortVerb{|}
\def\hlink#1#2{\Tg<a href="#1">#2\Tg</a>}

\begin{document}

\title{Taming TeX4ht to Support Lettrine Package}

\author{\hlink{http://www.cvr.cc}{\textsc{cv radhakrishnan}},
        \Tg<small>\hlink{http://www.river-valley.com}{River Valley},
        Trivandrum, \textsc{india}\Tg</small>}

\maketitle

\lettrine{T}{his code} has kindly been contributed by
\hlink{http://www.raphink.info/}{Rapha"el Pinson} and is
\hlink{https://github.com/cc-translators/sagesse/blob/master/lettrine.4ht}
{available here}. The original code was slightly modified to fit
into the scheme of TeX4ht.  Rapha"el had provided eight hooks to
re\Configure |lettrine| which I'd reduced to seven. All the hooks are
provided below:

\begin{enumerate}
 \item Before |lettrine|
 \item After  |lettrine|
 \item Before lettrine initial character
 \item Between lettrine initial character and lettrine line
 \item After lettrine line
 \item Before lettrine ante
 \item After lettrine ante
\end{enumerate}

\lettrine{F}{urther} hooks have been defined to access initial
character and lettrine line in case we want to \Configure
|lettrine|. |HlettrineChar| and |HlettrineString| can be used to
access the character and line respectively. The screenshot of this
pages as rendered in Firefox is \hlink{lettrine.png}{available here}.

Here is a bit of dummy text to fill in the page. lipsum[5-9]

\end{document}

There is nothing special to explain in the above part. \hlink is a
custom macro with two arguments to cross-link something to a URL. The
packages are popular ones and need no introduction.

Custom Configuration

The custom configuration, my.cfg has two parts — a preamble part and a post preamble part. Preamble area shall consist of three important commands:

  1. \Preamble — beginning of preamble area.
  2. \begin{document} — do not confuse with the begin{document} in your document source.
  3. \EndPreamble — end of preamble area.

\Preamble command shall contain all the options that are to be passed on to TeX4ht. Options can be provided as comma separated strings. All needed TeX packages shall be loaded before Preamble command as shown below, where we have loaded xspace package.

\RequirePackage{xspace}
\Preamble{xhtml,NoFonts,ext=html,charset="utf-8"}

For more details about options, please see this post.

\Configure{PROLOG}{DOCTYPE}
\Configure{VERSION}{}
\Configure{DOCTYPE}{\HCode{<!DOCTYPE html>\Hnewline}}
\Configure{HTML}{\HCode{<html>\Hnewline}}{\HCode{\Hnewline</html>}}
\Configure{@HEAD}{}
\Configure{@HEAD}{\HCode{<meta
         \expandafter\csname a:charset\endcsname/>\Hnewline}}
\Configure{@HEAD}{\HCode{<meta name="generator" content="TeX4ht
         http://www.tug.org/tex4ht/" />\Hnewline}}
\Configure{@HEAD}{\HCode{<link
         rel="stylesheet" type="text/\Css"
         href="\expandafter\csname aa:\CssFile\endcsname" />\Hnewline
    }
}
\Configure{BODY}{\Tg<body>}{\Tg</body>}
\begin{document}
\def\hlink#1#2{\Tg<a href="#1">#2\Tg</a>\xspace}
\EndPreamble

All the configuration items that are processed by TeX4ht at the top of the document source shall be provided before the begin{document} command that appears in the preamble area. All the elements that form part of prolog and <head> element of HTML are the ideal candidates. Thus, PROLOG, VERSION, DOCTYPE, HTML, @HEAD and BODY are re-\Configured as we want them in a different manner. In HTML 5, we do not need DTD, XML version and further several meta part are more simplified, we re\Configure these items in this part of the configuration. You might note that @HEAD is additive, each \Configure{@HEAD} has one argument which will be added to the <head>...</head> part of the HTML. We have inserted character set, link information for .\Css file, meta information relating to generator which is TeX4ht, by re-configuring @HEAD.

\Configure{\textsc}{\Tg<span class="sc">}{\Tg</span>}
\Configure{texttt}{\Tg<span class="tt">}{\Tg</span>}
\Configure{textbf}{\Tg<span class="bf">}{\Tg</span>}
\Css{.sc{font-variant: small-caps;}}
\Css{.bf{font-weight: bold;}}
\Css{small{font-size: .8em;}}
\Css{.tt,.verb{font-family: monospace; white-space: nowrap;
    color: #222; font-size: 85%;}}

The above lines show a few font attributes where we have re\Configured commands like \textsc, textbf, and texttt. The related .\Css declarations have been provided following the font attributes.

\Css{body{margin-top: 2em; margin-bottom: 1em; width: 60%;
    margin-left: auto; margin-right: auto; padding: 3em;
    color: #444; box-shadow: 2px 2px 20px -5px #bfbfbf;
    -webkit-box-shadow: 2px 2px 20px -8px #bfbfbf;
    -moz-box-shadow: 2px 2px 20px -5px #bfbfbf;
    font-family: "EB Garamond";
    font-style: normal;
    font-size: 1em; line-height: 1.3em;
    border: 1px solid #fefeef; }}
\Css{p.indent{ text-indent: 0em }}

The above provides .\Css declarations for <body> element with a soft gray shadow, 60% width of the window, slightly grayed text color, slightly increased line height, 3em padding on all sides, etc. Not a big deal. The text indent has been suppressed through another .\Css declaration, as the indent can interfere with lettrine spacing.

Our custom configuation ends here if you do not want to make use of the free web font, namely, EB Garamond created by Georg Duffner and distributed under OFL font licence. The font can be had from Google or from here. The succeeding lines are .\Css declarations to make use of Garamond and CheshireInitials fonts in your document.

\Css{@font-face{font-family: InitialsFont; font-style: normal;
    src: url/fonts/CheshireInitials.ttf;}}
\Css{@font-face{font-family: "EB Garamond SC"; font-variant: small-caps;
    src: url/fonts/EBGaramond12-SC.ttf;}}
\Css{@font-face{font-family: "EB Garamond"; font-style: normal;
    font-weight: normal; font-variant: normal;
    src: url/fonts/EBGaramond12-Regular.ttf;}}
\Css{@font-face{font-family: "EB Garamond Italic"; font-style: italic;
    font-weight: normal;font-variant: normal;
    src: url/fonts/EBGaramond12-Italic.ttf;}}
\Css{@font-face{font-family: "EB Garamond Bold"; font-style: normal;
    font-weight: bold; font-variant: normal;
    src: url/fonts/EBGaramond12-Bold.ttf;}}
\Css{em, i, .ecti, .ecti1, .thanks, .signature, .dvquote-text,
.dvprayer-text{font-family: "EB Garamond Italic", serif;}}
%
\Css{strong, b, .partToc a, .partToc, .likepartToc a, .likepartToc,
.chapterToc a, .chapterToc, .likechapterToc a, .likechapterToc,
.appendixToc a, .appendixToc, .addchapToc,
.paragraphHead, .likeparagraphHead,
.subparagraphHead, .likesubparagraphHead,
.caption td.id{font-family: "EB Garamond Bold", serif;}}
%
\Css{.small-caps, .booksubtitle, .dvday, .sectionHead,
.dvquote-ref, .dvbox .lettrine-line{font-family: "EB Garamond SC", serif;}}
%
% CheshireInitials for Lettrine character
%
\Css{.lettrine{float: left; font-family: InitialsFont;
    line-height: 1.15; margin-left: -0.1em; padding-bottom: -0.6em;
    margin-bottom: -1em; margin-right: 0.2em;}}

How to run TeX4ht

Save the above sources as test.tex and my.cfg respectively. Following command can be invoked from terminal:

  mzlatex test my ' -cunihtf'

The synatax is

  script <tex-file> <conf-file> '<options-for-t4ht>'

Please note the space between the opening single quote character and -cunihtf which is very important. The sources and latest lettrine.4ht package are available here as a zip archive.

Enjoy the magic!

5 Responses to “An Annotated TeX Source”


  • Thanks very much for the post. A few issues I found on testing, which gives errors with hlatex: there is a %21 character in the code listed. It should be changed to ‘!

    Configure{DOCTYPE}{HCode{<%21DOCTYPE html>Hnewline}}

    There should not be a line break in:

    hlink{https://github.com/cc-translators/sagesse/blob/master/lettrine.4ht}
    {available here}.

    It would actually be very helpful to the novice, if you could provide a direct link at the end of the article to the sample .tex and .cfg files. 

  • Nasser M, Abbasi

    Hello;
    Thanks for this, it is beautiful HTML.
    How does one compile test.tex in the zip file using latex or using pdflatex? Just doing latex test.tex gives errors. I am using texlive 2012 debian version.
    Also, how to change .cfg file to generate HTML where text is justified?
    thanks,
    –Nasser

  • Hi,

    I am using ‘mk4ht oolatex file.tex’ to convert a TeX file to odt. The small caps are not transferred at all, and I wasn’t able to figure out how I could fix that. Is there any way?

    Best regards,
    Philipp

    • Philipp – please post the input file and the invocation to the public mailing list, tex4ht@tug.org. A relatively recent volunteer, Michal Hoftich, has been (amazingly) active in trying to deal with such things.

Leave a Reply