tex4ht: indexentries/structure of the .ind-file

Question

Running htlatex 2 times with a makeindex command in-between delivers a working .ind file but with page numbers as linktags in the corresponding .html output which make no sense for users visting the web page.

How can I exchange/addto the info in the LNK-section of the corresponding .ind for a self-chosen text ?

Or where can I find infos about the structure of the .ind or/and the corresponding .4dx-file ?

P.S. My goal is exchanging the page numbers(s) for a (sub)section entry of the LaTeX source to imitate the index structure O'Reilly is using in its E-Books.

Answer 1

I've created new project, helpers4ht, which will be collection of various packages for simplification of tex4ht usage. These packages are possible to include in the .cfg file. First package is indexing4ht, for working with indexes.

Place files indexing4ht.4ht and indexing4ht.sty in your working directory and add \RequirePackage{indexing4ht} to the .cfg file, before \Preamble command. For example:

\usepackage{indexing4ht}
\Preamble{xhtml,3}
\begin{document}
\EndPreamble

in this example, 3 option is used to break sections into standalone html files

Now some sample document, sample.tex:

\documentclass{article}

\usepackage[xindy,noautomatic]{imakeidx}
\makeindex
\makeindex[name=names]
\begin{document}
\section{Hello world}
\index{section}
\subsection{first}

\index[names]{Einstein, Albert}
\index{hello}\index{world}

\subsection{second}
\index[names]{Knuth, Donald}
\index{hello}
\index{not world}
\subsubsection{sub sub section}
\index{hello|definition}
\index{Latex@\LaTeX}
\index{uff|see{hello}}
\index{off|seealso{hello}}
\index{Some bold@\textbf{Some bold}}
\printindex
\printindex[names]
\end{document}

only imakeidx package is supported at the moment, because it provides easy method for index writing customization. Note that two different indices are used, default for keywords, and names. Also see and seealso attributes are used.

Now we can compile the document with

htlatex sample cfgfilename

three important files will be created, sample.idx, names.idx and sample.xdy. sample.xdy is configuration file for xindy index processor. makeindex isn't supported.

When you look at names.idx:

\indexentry{Einstein, Albert}{1.1}
\indexentry{Knuth, Donald}{1.2}

you can see that section numbers are used instead of page numbers. This is default configuration, but it can be configured to use different locations than section numbers, for example paragraphs or link back to \index commands.

Now we need to process .idx files with xindy:

xindy -L english -C utf8 -M sample sample.idx
xindy -L english -C utf8 -M sample names.idx

resulting names.ind:

\begin{theindex}
  \providecommand*\lettergroupDefault[1]{}
  \providecommand*\lettergroup[1]{%
      \par\textbf{#1}\par
      \nopagebreak
  }

  \lettergroup{E}
  \item \idxkeyword{Einstein, Albert}, \idxlocator{1.1}

  \indexspace

  \lettergroup{K}
  \item \idxkeyword{Knuth, Donald}, \idxlocator{1.2}

\end{theindex}

you can see that \idxkeyword and \idxlocator commands are used, these are used for cross-referencing.

Because commands in index entries were used in our samples, we need to take care of them, because they would cause problems in cross-reference handling. The problematic ones are these:

\index{Latex@\LaTeX}
\index{Some bold@\textbf{Some bold}}

Package gettitlestring is used for cleaning of index entries, we need to provide configuration for used commands in the .cfg file:

\usepackage{indexing4ht}
\Preamble{xhtml,3}
\GetTitleStringDisableCommands{%
\renewcommand\textbf[1]{#1}%
\renewcommand\LaTeX{LaTeX}
}
\begin{document}
\EndPreamble

see contents of \GetTitleStringDisableCommands. Definition for each command used in index entry names should be placed here.

Now compile with

htlatex sample cfgfilename

resulting main index:

links on section numbers point back to sections where index entry was saved. note that see and seealso attributes produce links to referenced index entries.