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