###
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 LATEX2`HTML`, 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}

    \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 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 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 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 LATEX2`HTML` 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 LATEX2`HTML` 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 LATEX 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}