A Segmentation Example

The best way to illustrate document segmentation is through a simple example. Suppose that a document is to be segmented into one parent and two child segments. Let the parent segment be report.tex, and the the two child segments be sec1.tex and sec2.tex. The latter are translated with filename prefixes of s1 and s2, respectively. This example is included with recent distributions of L^ATEX2HTML, having more prolific comments than are shown here.

The text of report.tex is as follows:

\documentclass{article}          % Must use LaTeX 2e
\usepackage{html,makeidx,color}

\begin{document}                 % The start of the document
\title{A Segmentation Example}
\date{\today}
\maketitle
\tableofcontents
\listoffigures

% Process the child segments:

\segment{sec1}{section}{Section 1 title}
\segment{sec2}{section}{Section 2 title}
\printindex
\end{document}

This file obtains the information necessary to build an index, a table of contents and a list of figures from the child segments. It then proceeds to typeset these.

The first child segment sec1.tex is as follows:

\documentclass{article}
\usepackage{html,color,makeidx}
\input{sec1.ptr}
\internal{s2}
\startdocument
Here is some text.
\subsection{First subsection}
Here is subsection 1\label{first}.
\begin{figure}
\colorbox{red}{Some red text\index{Color text}}
\caption[List of figure caption]{Figure 1 caption}
\end{figure}
Reference\index{Reference} to \ref{second}.

The first thing this child segment does is establish the L^ATEX packages it requires, then loads the counter information that was written by the \segment command that invoked it. Since this segment contains a symbolic reference (second) to the second segment, it must load the internal labels from that segment.

The final segment sec2.tex is as follows:

\documentclass{article}
\usepackage{html,makeidx}
\input{sec2.ptr}
\internal{s1}
\startdocument
Here is another section\label{second}.
Plus another\index{Reference, another} reference\ref{first}.
\begin{figure}
\fbox{The figure}
\caption{The caption}
\end{figure}

This segment needs to load internal labels from the first one, because of the reference to `first'. These circular dependencies (two segments referencing each other) are either not allowed or handled incorrectly by the Unix utility make, without resorting to time stamps and some trickery. A time-stamp is a zero-length file whose only purpose is to record its creation time. Besides evaluating segment interdependence, another function of make is to provide inter-segment navigation information.

A sample Makefile is included in the distribution. This correctly generates the fully-linked document. The first time it is invoked, it runs:

• latex on report.tex twice;
• dvips to generate report.ps;
• latex2html on sec1.tex;
• latex2html on sec2.tex. At this point sec2.html is completely linked, since the labels from the sec1 were available;
• latex2html on sec1.tex to pick up the labels from sec2;
• latex2html on report.tex.

Proper operation of make depends on the fact that L^ATEX2HTML updates its own internal label file only if something in its current program segment causes the labels to change from the previous run. This ensures that L^ATEX2HTML is not run unnecessarily. It is also usual for the information page to be suppressed by specifying -info 0 for all but the top-level document.

In the above example, all segments are built within the same sub-directory report/ of the directory containing the L^ATEX source files. This is achieved simply by using the option -dir report with each. All the images and <prefix><type>.pl files are created and stored within this directory.

Sometimes it is desirable to build one or more segments within separate sub-directories. This is especially so when a segment has a large number of images, or if it is required to be part of more than one combined document. In this case the -dir <dir> options can be different, or omitted entirely. For inter-segment referencing to work, a ``relative path'' must be included as part of the <prefix> with each \internal command; e.g.

\internal[figure]{../sect1/s1}