Next: User Manual Up: LaTeX2HTML Test Document Previous: Special Features Contents Index
This section describes how you can define hypertext entries in your HTML documents from within your LATEX source, as well as other effects available in HTML for which there need be no direct LATEX analog for a printed document. These are implemented as new LATEX commands which have special meaning during the translation by LATEX2HTML into HTML, but are mostly ignored when processed by LATEX.
The new commands described in the sections
below are defined mainly in the html package,
with LATEX definitions in the file html.sty,
which is part of the LATEX2HTML distribution.
It must be included in any LATEX document using these features,
by one of the following methods:
It is not sufficient to load the style file via an \input or
\include command, such as \input html.sty .
This will load the required definitions for LATEX, but will not load
the html.perl package file for LATEX2HTML.
Warning: Some of these features, but not all, are also available with LATEX 2.09.
\begin{rawhtml}
\begin{htmlonly}
\begin{latexonly}
%begin{latexonly}
\begin{imagesonly}
\begin{comment}
\begin{makeimage}
\begin{htmllist}
{htmlonly} say, occurs
on a line by itself with no preceding spaces, <tab>s
or any other characters.
(Otherwise LATEX will not recognise the intended end
of the environment when processing for the .dvi version.)
Similarly there should be nothing on the same line after
the opening environment delimiter, \begin{htmlonly} say.
The following commands are defined for LATEX in html.sty.
Corresponding Perl implementations are either in html.perl
or in the latex2html script itself.
\latextohtml
\htmladdnormallink
\htmladdnormallinkfoot
\htmladdimg
\hyperref
\htmlref
\hypercite
\htmlcite
\externalref
\externalcite
\externallabels
The following commands, also defined for LATEX in html.sty,
are normally used only when creating segmented documents,
see a later page.
\segment
\startdocument
{document} command, unless it is
shielded from LATEX within an htmlonly environment.)
\internal
\htmlhead
\htmlnohead
\segmentcolor
\segmentpagecolor
The following commands are shorthand forms for some of the “conditional” environments
listed above.
\html
\latex
\latexhtml
The following commands implement effects on the HTML pages for which
there is no direct LATEX counterpart. Most of these commands are discussed
in detail in a later section.
\HTMLcode
\htmlrule
\strikeout
\htmlimage
\htmlborder
\tableofchildlinks
\htmlinfo
\htmladdtonavigation
\bodytext
\htmlbody
\htmlbase
\htmltracing{<level>}
\htmltracenv{<level>}
\HTMLset
\HTMLsetenv
{<env-name>}...\end{<env-name>}
markup notation. (Safety features that are available with the usual
\begin...\end mechanism may not always work in the best way
with this alternative style of environment delimiter.
These comments apply to both the LATEX and LATEX2HTML processing.)
\rawhtml...\endrawhtml
\htmlonly...\endhtmlonly
\latexonly...\endlatexonly
\imagesonly...\endimagesonly
\comment...\endcomment
Warning: These `pseudo'-environments are not as reliable as their LATEX counterparts. In particular, the \begin<env-name> and \end<env-name> commands should appear on lines by themselves, preferably with no preceding spaces or <tab> characters. This requirement is analogous to the warning for conditional environments.
\htmladdnormallink{<text>}{<URL>}
\htmladdnormallink[<name>]{<text>}{<URL>}
\htmladdimg{<URL>}
\htmladdimg[<align>]<URL>}
\htmladdnormallinkfoot{<text>}{<URL>}
\htmladdnormallinkfoot[<name>]{<text>}{<URL>}
\htmladdnormallink{<URL>}{http://www.ncsa.uiuc.edu/demoweb/url-primer.html}
The optional argument to \htmladdnormallink allows a name to be specified for the place in the document where the hyperlink occurs. This is done via the NAME="<name>" attribute for the <A ...> anchor tag in HTML . Such a name can be used as the target for a hyperlink using the \htmlref command, described later.
In fact any valid set of “attributes” for the <IMG> tag in HTML
can be specified as the optional <align> parameter. In particular
the WIDTH, HEIGHT and BORDER attributes can be set,
perhaps overriding the natural size of the image.
\~{},
else the ˜ will be interpreted as an accent on the following character.
Note the warning concerning how the environment delimiters should be used in the LATEX source code.
A particularly good use of the rawhtml environment
is in the creation of interactive
electronic forms
from within a LATEX document.
When producing the paper (.dvi) version
of a document the rawhtml environment is ignored.
\begin{rawhtml}
<HR>
<FORM ACTION="http://cbl.leeds.ac.uk/nikos/doc/error.html">
<OL>
<LI> <INPUT TYPE="checkbox" NAME="wp" VALUE="word"> Word for
Windows.
<LI> <INPUT TYPE="checkbox" NAME="wp" VALUE="wp"> Word Perfect.
<LI> <INPUT TYPE="checkbox" NAME="wp" VALUE="latex"> LaTeX.
<LI> Plain Text Editors (Please Specify): <INPUT TYPE="text" NAME="other_ed">
</OL>
So, what do think (comments please): <BR>
<INPUT TYPE="text" SIZE=45 NAME="other_wp">
<INPUT TYPE="submit" VALUE="submit this form but don't expect much!">
</FORM>
<HR>
\end{rawhtml}
The result is shown below.
To insert SGML-style comments into the HTML files, use the rawhtml environment as follows.
\begin{rawhtml}
<!-- this text is treated as a comment
perhaps extending over several lines
-->
\end{rawhtml}
Note the warning concerning how the environment delimiters should be used in the LATEX source code.
\HTMLcodeWhen the <tag> also needs a closing tag (e.g <I>...</I>) the <contents> must be given, enclosed in braces. Both the opening and closing tags then will be placed correctly.[<attribs>]{<tag>}
\HTMLcode[<attribs>]{<tag>}{<contents>}
Warning: In version 97.1 this command was actually called \HTML. However style files may well define \HTML to mean something else, like a styled version of the HTML acronym. So in version 98.1 the name has been changed to \HTMLcode.
If no other definition of \HTML exists, then this command will be defined, to work the same as \HTMLcode.
An important aspect of this is that any of the <tag>, <attribs> and <contents> may be given wholly by expanding a LATEX macro, or may contain arbitrary macros, perhaps including other \HTMLcode commands. The following table was constructed using this feature; its LATEX source follows.
|
|
\newcommand{\myalign}{center}
\newcommand{\mylist}{UL}
\newcommand{\myitem}[2]{\HTMLcode[disc]{LI}{\simpletest{#1}{#2}}}
\newcommand{\simpletest}[2]{%
\HTMLcode{#1}{ a simple test of “#2”,} using \HTMLcode{CODE}{<#1>} .}
\newcommand{\tableopts}{10,border=5}
\newcommand{\tablelist}[4][left]{\HTMLcode[#1]{DIV}{
\HTMLcode[\tableopts]{TABLE}{
\HTMLcode[bottom]{CAPTION}{
#3
}\HTMLcode{TR}{\HTMLcode{TD}{
\HTMLcode{#2}{
#4
}}}
}}\HTMLcode[all]{BR}}
\tablelist[\myalign]{\mylist}{%
\textbf{A listing of the different text styles available in HTML 3.2}}{%
\myitem{B}{bold-face}
\myitem{I}{italics}
\myitem{TT}{teletype-text}
\myitem{U}{underlining}
\HTMLcode[circle]{LI}{\simpletest{STRIKE}{strikeout}}
\myitem{EM}{emphasis style}
\myitem{STRONG}{strong style}
\myitem{CODE}{code style}
\myitem{CITE}{citation style}
\myitem{DFN}{definition style}
\HTMLcode[square]{LI}{\simpletest{SAMP}{sample style}}
\HTMLcode[square]{LI}{\simpletest{KBD}{keyboard style}}
\myitem{VAR}{variable style}}
The above code demonstrates many aspects of the way \HTML commands can be used.
nesting:
macros:
within macros:
attribute values:
\HTMLcode[50\% 3 noshade center]{HR}
attribute names:
newlines:
Some further aspects of the use of this \HTML
command are not apparent from the above example.
invalid <tag> :
required attributes:
valid HTML :
The requirement to produce valid HTML currently rests with the user.This issue will be addressed in forthcoming revisions of LATEX2HTML.
extra attributes and values:
attributes with similar data-types:
This would be useful for example in adding a long description of a multi-media resource in the paper version of a document. Such a description would be redundant in the electronic version, as the user can have direct access to this resource.
Here is an example of the use of the latexonly environment,
used earlier in this manual:
\begin{latexonly}
\begin{figure}
\begin{center}
\fbox{\includegraphics[width=4in]{psfiles/eform}}
\end{center}
\caption{An electronic form. Of course in the online version of this
document the form above would be active.}
\end{figure}
\end{latexonly}
Note the warning concerning how the environment delimiters should be used in the LATEX source code.
Note the warning concerning how the environment delimiters should be used in the LATEX source code.
{...} command causes everything within the braces
to be processed by LATEX, but ignored by LATEX2HTML.
{...} command causes everything within the braces
to be ignored by LATEX and processed by LATEX2HTML.
{...}{...} causes everything
within the first set of braces to be processed exclusively by LATEX,
with the contents of the second set of braces processed solely by LATEX2HTML.
The following example should clarify what happens:
\newcommand{\A}{The letter A.}
\newcommand{\B}{The letter B.}
\begin{latexonly}
\renewcommand{\A}{Not the letter A.}
\renewcommand{\B}{Not the letter B.}
\begin{document}
\A \B
\end{document}
If you process this with LATEX, the result is:
The letter A. Not the letter B.
Note the warning concerning how the environment delimiters should be used in the LATEX source code.
Warning: Be careful when using LATEX commands which alter the values of counters
(e.g. numbered figures or equations) in conditional text, because this may
cause the counter values in the electronic version to lose synchronisation
with the values of the corresponding counters in the LATEX version.
Note the warning concerning how the environment delimiters should be used in the LATEX source code.
One further important use of the makeimage environment is as follows.
If a makeimage environment occurs as a sub-environment within
a figure environment, then an image will not be made of the
figure's contents. Instead, the contents are treated as normal text,
each part being handled as if there were no figure at all,
except that everything is placed within a single cell of a
<TABLE>...</TABLE> construction in HTML 3.2.
The contents of any \caption
commands are placed between <CAPTION>...</CAPTION> tags
for the <TABLE>.
Normally an image of the entire contents of the figure would be
placed within the single cell of the <TABLE>.
Now images are made of any subparts of those figure's contents
that really need it, in particular the makeimage sub-environments.
An empty makeimage sub-environment does not generate an image of itself,
yet still it inhibits an image being made of the whole figure.
These comments apply also to table environments.
In a hypertext document however, cross-references can be shown
without any indirection, just by highlighting a relevant piece of text.
This can make a document more readable as it removes unnecessary
information.
{sec:cond}
is defined somewhere within a document,
the command \hyperref, taking 4 arguments,
can be used in that document as follows:
\emph{Is the concept of
\hyperref
% This will be highlighted in the hypertext version
{conditional text} % argument #1
% This will be shown in the printed version
% followed by a numeric reference ...
{conditional text (see Section } % argument #2
% ... followed by this text
{ for more information)} % argument #3
% This is the common label
{sec:cond} % argument #4
a good idea? }
Here is how it will be shown:
Is the concept of conditional text a good idea?
In the printed version what would appear is:
Is the concept of conditional text (see Section 4.2 for more information) a good idea?
\hyperref[ref]{<HTML-text>}{<LaTeX-text>}{<post-LaTeX>}{<label>}
\hyperref{<HTML-text>}{<LaTeX-text>}{<post-LaTeX>}{<label>}
\hyperref[pageref]{<HTML-text>}{<LaTeX-text>}{<post-LaTeX>}{<label>}
\hyperref[page]{<HTML-text>}{<LaTeX-text>}{<post-LaTeX>}{<label>}
\hyperref[noref]{<HTML-text>}{<LaTeX-text>}{<label>}
\hyperref[no]{<HTML-text>}{<LaTeX-text>}{<label>}
The first two are the defaults, where LATEX
uses \ref{<label>}.
With the next two LATEX uses \pageref{<label>},
while with the final two LATEX completely ignores the <label>,
setting just the <LaTeX-text>.
For creating hyperlinks to other documents
using symbolic reference <label>s,
see also the \externalref
command.
The preceding paragraph is an example of the use of the \hyperref[page] option.
Its source code is:
For creating hyperlinks to other documents
using symbolic reference \Meta{label}s,
see also the \Lc{externalref}
\hyperref[page]{command}{command, described on page~}{}{externref}.
which appears in the LATEX typeset version as:
For creating hyperlinks to other documents using symbolic reference <label>s, see also the \externalref command, described on page 31.In fact both \hyperref and the \htmlref command, to be described next, permit textual hyperlinks based on symbolic <label>s from external files.
With \verb|\htmlref| \htmlref{it's easy to make links}{fig:example}.
which produces:
With \htmlref it's easy to make links.In the LATEX typeset version it will appear simply as:
With \htmlref it's easy to make links.
Here is an example of a bibliographic entry for the original
LATEX [1] blue book:
@string{tugURL="\htmladdnormallink
{http://www.tug.org/}{http://www.tug.org}"}
@string{danteURL="\htmladdnormallink
{http://www.dante.de/}{http://www.dante.de}"}
@book{lamp:latex,
title = "LaTeX User's Guide \& Reference Manual, 2nd edition",
year = 1994 ,
author = "Leslie Lamport",
Publisher = "Addison--Wesley Publishing Company, Inc.",
note = "Online information on {\TeX} and {\LaTeX} is available at "
# tugURL # " and " # danteURL }
See the bibliography for how this will appear.
\bibliography{urls,...}.
The natbib package, written for LATEX by Patrick Daly, provides even more flexibility in the way a reference may be cited. All the features of this package are implemented for LATEX2HTML via the natbib.perl file. (Indeed there is even a mode whereby natbib handles the Harvard style of citation. This requires loading also the nharvard package.)
Thanks... to Martin Wilck for the bulk of the work
in producing this extension, and to Ross Moore for
necessary adjustments to allow it to work correctly with the
document segmentation strategy.
\hypercite[int]{<HTML-text>}{<LaTeX-text>}{<opt-LaTeX>}{<label>}
\hypercite[cite]{<HTML-text>}{<LaTeX-text>}{<opt-LaTeX>}{<label>}
\hypercite{<HTML-text>}{<LaTeX-text>}{<opt-LaTeX>}{<label>}
\hyperciteThe first three forms are equivalent; LATEX uses \cite[nocite]{<HTML-text>}{<LaTeX-text>}{<label>}
\hypercite[no]{<HTML-text>}{<LaTeX-text>}{<label>}
\hypercite[ext]{<HTML-text>}{<LaTeX-text>}{<label>}
[<opt-LaTeX>]<label> ,
after placing the <LaTeX-text>.
Note that {<opt-LaTeX>} must be specified,
even if empty `{}'.
Similarly the latter three forms are equivalent,
with LATEX using \nocite{<label>} ,
to force the particular reference to appear on the bibliography page,
even though no explicit marker is placed at this point.
(Thus there is no need for an optional <opt-LaTeX> argument.)
Within the HTML version a hyperlink is produced when the <HTML-text>
is not empty. External label files are also searched,
in order to match the symbolic <label>, see also
\externalcite.
commands described in the \LaTeX{} \htmlcite{blue book}{lamp:latex},
...
as well as many other \LaTeX{} constructions, such as are described in
the \LaTeX{} \hypercite{\emph{Companion}}{\emph{Companion}}{}{goossens:latex}
and \LaTeX{} \hypercite{\emph{Graphics Companion} (e.g. \Xy-pic)}%
{\emph{Graphics Companion}}{\Xy-pic}{goossens:latexGraphics};
which produces:
commands described in the LATEX blue book,whereas in the LATEX typeset version one sees:
...
as well as many other LATEX constructions, such as are described in the LATEX Companion and LATEX Graphics Companion (e.g. XY-pic);
commands described in the LATEX blue book,
...
as well as many other LATEX constructions, such as are described in the LATEX Companion[2] and LATEX Graphics Companion[3, XY-pic];
The \externalcite command provides a similar facility when the bibliography page is “external”; that is, not part of the current document.
\externallabels{<URL to directory of external document>}{<local copy of external document labels.pl file>}
If a symbolic reference made in either of the commands described on the previous page is not defined within the document itself, LATEX2HTML will look for that reference in one of the external files7. After any modifications in an external document (sections added/deleted, segmentation into different physical parts, etc.) a new labels.pl will be generated. If the \externallabels command in another document contains the correct address to an updated copy of the labels.pl file, then the cross-references will be re-aligned after running the local document through the translator.
There is also a mechanism analogous to the
label–ref pairs of LATEX, which can be used only
within a single document.
These labels are called internal labels,
as opposed to the external labels defined above.
They are used extensively with the document segmentation strategy
described later.
Either type of label is defined with a LATEX \label command. Labels can be referenced within a document using a \ref command. When processed by LATEX, each \ref command is replaced by the section number in which the corresponding \label occurred. When processed by the translator, each \ref is replaced by a hypertext link to the place where the corresponding \label occurred.
\externalrefThe argument to \externalref may be any symbolic label defined in the labels.pl file of any of the external documents. Such references to external symbolic labels are then translated into hyper-links pointing to the external document.{<symbolic label in remote document>}
A particularly important use for this is in allowing multiple documents to access information in a common bibliographic listing. For example: all of an author's publications; a comprehensive listing of publications in a particular field; the (perhaps yearly) output of publications from a particular organisation or institution.
Thanks... to Uffe Engberg for suggesting this feature.
Next consider how it could be done with symbolic labels.
First you have to import the labels used in this document
by copying the file labels.pl,
saving it in /tmp/labels.pl say,
then adding anywhere in your document:
\externallabels{http://cbl.leeds.ac.uk/nikos/tex2html/doc/manual}%
{/tmp/labels.pl}
After that you can use the label `crossrefs' defined at the beginning of this
section9 as follows:
\externalref{crossrefs}
This will be translated into the appropriate hyper-link to this page.
If there are any changes in this document and you would like to
bring your document up-to date, you have to copy
labels.pl again
and rerun the translator on your document. Of course if I move the
directory containing the HTML files for this document somewhere else,
then you would have to make a change in the argument of the
\externallabels command to reflect this.
It is obvious that some level of collaboration is required between authors trying to maintain cross-references between different documents. Using symbolic labels makes this a lot easier (especially for documents written by the same author).
The html package, through the LATEX input file html.sty, and its Perl counterpart html.perl, implements several new commands that are intended entirely for effects within the produced HTML files. In LATEX these commands, their arguments, and any optional arguments are completely ignored.
Much variation can be obtained in the horizontal rule that is produced, using extended forms of the \htmlrule command:
\htmlruleWhereas a “break” tag <BR> normally precedes the <HR> generated by the \htmlrule command, this break is omitted when using the \htmlrule* variant.
\htmlrule*
\htmlrule[<attribs>]
\htmlrule*[<attribs>]
Furthermore, the optional argument <attribs> can be used to specify attributes for both the <HR> and <BR> tags. More specifically, <attribs> should be a list of attribute-names and/or key-value pairs <key>=<value> separated by spaces or commas. This list is parsed to extract those attributes applicable to the <HR> tag, and those applicable to the <BR> (with the unstarred variant).
However if this command, or its variant \tableofchildlinks*, occurs within the source code to appear on a particular HTML page, then the child-links table will be placed at that point where the command occurs. Normally a break tag <BR> is inserted to separate the table of child-links from the surrounding text. The \tableofchildlinks* omits this extra break when it would result in too much space above the table.
For example throughout this section of the manual, all subsections in which several explicit commands have been discussed have their child-links table placed at the top of the page, using \tableofchildlinks*. This helps to quickly find the description of how the commands are used.
The variant \htmlinfo* places the information, but leaves out the standard “About this document...” header. Instead the \htmlhead command can be used to place an alternative heading, prior to the \htmlinfo* command. Neither this heading nor the $INFO contents appears in the LATEX typeset version.
Warning: Any previous settings for the <BODY ...> tag
are discarded. Furthermore no checking is done to verify whether the given <options>
indeed contains a list of attributes and values valid for the <BODY ...> tag.
When using \bodytext you are assumed to know precisely what you are doing!
Other packages contain commands which alter the contents of the <BODY ...> tag;
notably the color.perl implementation of LATEX's color package,
and the (prototype) frames package, by Martin Wilck and Ross Moore.
In both these packages the requested information is checked for
validity as an attribute within the <BODY ...> tag.
Warning: This is intended for Perl programmers only.
Use this command at your own risk!
Keeping such a map file up to date manually can be tedious, especially with dynamic documents under revision. An experimental program makemap helps automate this process. This program (which is really a Perl script) takes one mandatory argument and an optional argument. The mandatory argument is the name of a user-map file, defined below. The optional argument is the name of the directory where the HTML map file(s) are to be placed.
The best way of describing how this works is by example.
Suppose a document has two figures designated to
become active image-maps. The first
figure includes a statement like:
\begin{figure}
\htmlimage{map=/cgi-bin/imagemap/BlockDiagram.map,...}
. . .
\end{figure}
The second figure has a line like:
\begin{figure}
\htmlimage{map=/cgi-bin/imagemap/FlowChart.map,...}
. . .
\end{figure}
# # Define the location(s) of the labels.pl file(s): # +report/ <URL> # # Define map #1: # BlockDiagram.map: label1 rect 288,145 397,189 label2 rect 307,225 377,252 label2 default # # Define map #2 # FlowChart.map: label3 circle 150,100 200,100 label4 default
+report states that the symbolic labels
are to be found in the labels.pl contained in the directory
report/, and that its associated URL is as stated. Any number
of external labels.pl files may be so specified.
The block diagram image has two active regions. The first is a rectangle
bounded by corners (288, 145) and (397, 189), while the second is a rectangle
bounded by corners (307, 225) and (377, 252). These coordinates
can be obtained with the aid of a program such as xv.
If the user clicks in the first rectangle,
it will cause a branch to the URL associated
with symbolic label label1 defined in the labels.pl file
found in directory report/. The single active region in the
flow chart figure is a circle centred at (150, 100) and passing through
point (200, 100). Clicking in this region will cause a branch to
symbolic label label3. Labels label2 and label4
will be visited if the user clicks anywhere outside of the explicit
regions. If any labels are not defined in any of the labels.pl
files mentioned, they will be interpreted as URLs without translation.
The HTML image-maps are generated and placed in directory
report/ by invoking the command: makemap report.map report .
For these reasons, program segmentation was developed.
This feature enables the author to subdivide his document
into multiple segments.
Each segment can be processed independently by LATEX2HTML.
Hypertext links between segments can be made symbolically,
with references shared through auxiliary files.
If a single segment changes, only that segment needs to be reprocessed
(unless a label is changed that another segment requires).
Furthermore, the entire document can be processed
without modification by LATEX to obtain the printed version.
The top level segment that LATEX reads is called the parent segment.
The others are called child segments.
Document segmentation does require a little more work on the
part of the author, who will now have to undertake some
of the book-keeping formerly performed by LATEX2HTML.
The following four LATEX extensions carry out segmentation:
\segment{<file>}{<sec-type>}{<heading>}
\internal[<type>]{<prefix>}
internals
contents
sections
figure
table
index
images
\startdocument
{document} and \end{document}
statements are contained in the parent segment only.
It follows that the child segments cannot be processed
separately by LATEX without modification. However they can be
processed separately by LATEX2HTML, provided it is told
where the end of the LATEX preamble is; this is
the function of the \startdocument directive. It
substitutes for \begin{document} in child segments,
but is otherwise ignored by both LATEX and LATEX2HTML.
\htmlhead{<sec-type>}{<heading>}
\htmlnohead
\segmentcolor{<model>}{<color>}
\segmentpagecolor{<model>}{<color>}
The use of the segmenting commands is best illustrated by the example below. You might want to check your segmented document for consistency using the -unsegment command line option.
\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.
\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.
\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}
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}