Customising the Navigation Panels

The navigation panels are the strips containing ``buttons'' and text that appears at the top and perhaps at the bottom of each generated page and provides hypertext links to other sections of a document. Some of the options and variables that control whether and where it should appear are presented in an earlier section.

A simple mechanism for appending customised buttons to the navigation panel is provided by the command \htmladdtonavigation. This takes one argument which L^ATEX2HTML appends to the navigation panel. For example,

\htmladdtonavigation{\htmladdnormallink
   {\htmladdimg{http://server/mybutton.gif}}{http://server/link}}

will add an active button mybutton.gif pointing to the specified location.

Apart from these facilities it is also possible to specify completely what appears in the navigation panels and in what order. As each section is processed, L^ATEX2HTML assigns relevant information to a number of global variables. These variables are used by the subroutines top_navigation_panel and bottom_navigation_panel, where the navigation panel is constructed as a string consisting of these variables and some formatting information.

These subroutines can be redefined in a system- or user-configuration file (respectively, $LATEX2HTMLDIR/latex2html.config and $HOME/.latex2html-init). Any combination of text, HTML tags, and the variables mentioned below is acceptable.

The control-panel variables are:

Iconic links (buttons):

$UP

Points up to the ``parent'' section;

$NEXT

Points to the next section;

$NEXT_GROUP

Points to the next ``group'' section;

$PREVIOUS

Points to the previous section;

$PREVIOUS_GROUP

Points to the previous ``group'' section;

$CONTENTS

Points to the contents page if there is one;

$INDEX

Points to the index page if there is one.

Textual links (section titles):

$UP_TITLE

Points up to the ``parent'' section;

$NEXT_TITLE

Points to the next section;

$NEXT_GROUP_TITLE

Points to the next ``group'' section;

$PREVIOUS_TITLE

Points to the previous section;

$PREVIOUS_GROUP_TITLE

Points to the previous ``group'' section.

If the corresponding section exists, each iconic button will contain an active link to that section. If the corresponding section does not exist, the button will be inactive. If the section corresponding to a textual link does not exist then the link will be empty.

The ``next group'' and ``previous group'' are rarely used, since it is usually possible to determine which are the next/previous logical pages in a document. However these may be needed occasionally with segmented documents, when the segments have been created with different values for the $MAX_SPLIT_DEPTH variable. This is quite distinct from the segmented document effect in which the first page of one segment may have its `PREVIOUS' button artificially linked to the first page of the previous segment, rather than the last page.

The number of words that appears in each textual link is controlled by the variable $WORDS_IN_NAVIGATION_PANEL_TITLES which may also be changed in the configuration files.

Below is an example of a navigation panel for the bottom of HTML pages. (Note that the ``.'' is Perl's string-concatenation operator and ``#'' signifies a comment.)

sub bot_navigation_panel {
    #  Start with a horizontal rule and descriptive comment
    "<HR>\n" . "<!--Navigation Panel-->".
    # Now add a few buttons, with a space between them
       "$NEXT $UP $PREVIOUS $CONTENTS $INDEX $CUSTOM_BUTTONS" . 
    # Line break    
       "\n<BR>" .       
    # If ``next'' section exists, add its title to the navigation panel
       ($NEXT_TITLE ? "\n<B> Next:</B> $NEXT_TITLE" : undef) .   
    # Similarly with the ``up'' title ...
       ($UP_TITLE ? "\n<B>Up:</B> $UP_TITLE\n" : undef) . 
    # ... and the ``previous'' title
       ($PREVIOUS_TITLE ? "\n<B> Previous:</B> $PREVIOUS_TITLE\n" : undef) . 
}

Note that extra buttons may be included by defining suitable code for the container $CUSTOM_BUTTONS. The use of explicit `newline' (\n) characters is not necessary for the on-screen appearance of the navigation panel within a browser window. However it maintains an orderly organisation within the .html files themselves, which is helpful if any hand-editing is later required, or simply to read their contents. The corresponding subroutine for a navigation-panel at the top of a page need not use the rule <HR>, and would require a break (<BR>) or two at the end, to give some visual separation from the following material.