Here we assume the simplest possible configuration for building a HTML document from LaTeXtoHTML: We assume a single (and reasonably short) "file.tex" source file.
The process to create the HTML document is thus:
latex file.tex
This is done by:
latex2html file.tex
Running LaTeX2HTML creates a NEW DIRECTORY (with name file
where file.tex
is the name of
the source file), located below the directory where the source file is.
The HTML files are created in this new directory.
If the source file does not content any LaTeX2HTML specific command, the appearance of the obtained HTML document will be very "basic": The only HTML-like feature will be the fact that sections, subsections etc... will be accessible by clicking in the Table of Contents. After that, refinements as the creation of hyperlinks inside the test itself must be introduced as specific LaTeX2HTML commands.
The behaviour of LaTeX2HTML for a given document can be customized by copying the
".latex2html-init" file into the same directory as the "file.tex" file and
by modifying its content. This file is originally located in the
$LATEX2HTMLDIR
directory.
The preferences for running LaTeX2HTML will then be taken
from this version then from "$HOME
" and from "$LATEX2HTMLDIR
"
versions by decreasing order of priority.
Here we only discuss about the control of the navigation for the hyperlinks automatically generated by LaTeX2HTML (i.e. among the hyperlinks discussed above, only those which concern the sectionning of the document).
Usually, the document is divided into entities (e.g. chapters, sections, ...)
organised as a hierarchy (or a tree). When running LaTeX2HTML, the HTML version
of the document will be also divided into several files or nodes.
However, the default behaviour of LaTeX2HTML
is to generate one "HTML page" for each smallest entity of the document.
Physically, each page is put in a node file "node##.HTML
" where "##
" is an integer.
This can be VERY UNCOMFORTABLE for the reader if these entities are too short
or too long. Fortunately, the default behaviour of LaTeX2HTML can be
modified (customized) to achieve a easily readble documentation.
The way the Electronic document appears at screen is QUITE IMPORTANT for its "readability" and this is why this section should be red carefully.
There are in fact two levels of splitting, which can be controlled separately:
Let us explain these two level in more detail now.
As mentionned above, the default behaviour of
LaTeX2HTML is to generate a separate file node.html
(or "node" or "HTML-page")
for each smallest entity of the document.
The practice shows that an optimal length for a HTML documentation page
is approximately a few paper-pages. Hence if a smallest entity is only
a few paper-lines long or a hundred paper-pages long, the result
at screen will be very uncomfortable. In the first case the feeling is of a boring
documentation for which you have to click twenty time to have an interesting
(but tiny) piece of information. In the second case, you don't need to click too much
but you may become lost inside a non-hierarchised huge page.
The ideal situation should then be that each entity of the same level shoud have approximately the same size, and that the smallest entity should be some paper-pages long. But for pre-existing documentation, this is not necessarily true, and often there are too small entities in the text. In this case, the best solution is to customize the behaviour of LaTeX2HTML in order that it stops the splitting of the document into entities from a given level of sub-entities.
This is achieved by the setting the variable $MAX_SPLIT_DEPTH
to the
right value in the ".latex2html-init" file.
If this variable is set to 0 or 1 , a single page will be made for the whole "Document".
If set to 2 , a single page per "Part".
If set to 3 , a single page per "Chapter".
If set to 4 , a single page per "Section".
If set to 5 , a single page per "Subsection".
If set to 6 , a single page per "Subsubsection".
If set to 7 , a single page per "Paragraph".
If set to 8 , a single page per "Subparagraph".
The default value is 8, which most often results in a too much splitted document. For a documentation which only has no Parts and Chapter, but only sections, subsections, etc..., the best value should be 4 (for a short documentation of 10-20 paper-pages) or 5 (long documentation of 50-100 paper-pages).
Now, the document is assumed to be splitted in reasonably sized HTML pages. Each page can now contain sub-entities (e.g., if each page contains a section, it may also contain several subsection, and many subsubsections...). LaTeX2HTML then put at the top of each page a list of the sub-entities of this page, in highlighted text clickable for direct access inside the page itself. This list can be viewed as a mini "Table of Content" or "mini ToC" for the current HTML page.
The deepness to which this "mini ToC" should be displayed
can be specified through the "link-splitting" variable $MAX_LINK_DEPTH
.
If this variable is set to 1, the "mini ToC" will show only direct sub-entities, if it is set to 2 the depth will be 2 and so on.
The default value is 4, but a smaller value like 1 or 2 is much better for the reader.