Next: Hypertext Links in Bibliographic Up: Document Segmentation Previous: Document Segmentation

### 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 the version 96.1 distribution of LaTeX2HTML, with more prolific comments than are shown here.

The text of report.tex is given below:

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

\internal[figure]{s1}            % Include internal information
\internal[figure]{s2}            % from children
\internal[sections]{s1}
\internal[sections]{s2}
\internal[contents]{s1}
\internal[contents]{s2}
\internal[index]{s1}
\internal[index]{s2}

\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 and typesets these.

The first child segment, sec1.tex is shown below:

\documentclass{article}
\usepackage{html,color,makeidx}
\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 LaTeX 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 shown below:

\documentclass{article}
\usepackage{html,makeidx}
\internal{s1}
\startdocument
Here's 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 intersegment navigation information.

A sample makefile is included in the distribution which 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 sec2 were available.
• LaTeX2HTML on sec1.tex to pick up the labels from sec1;
• LaTeX2HTML on report.tex.

Proper operation of make depends on the fact that LaTeX2HTML 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 LaTeX2HTML is not run unnecessarily. It is also important that the information page be supressed by specifying -into "" on all but the last program segment.

Next: Hypertext Links in Bibliographic Up: Document Segmentation Previous: Document Segmentation

Tim Love
Thu Mar 14 11:15:46 GMT 1996