7.15 Menu formatting

There are two possibilities for menu formatting:

• format the whole menu in a preformatted environment, like in Formatting of complex formats (@example, @display…);
• format the menu in table with more specialized formatting for each part of the menu;

The simple formatting is used if $SIMPLE_MENU is true, otherwise the format with tables is used (this is the default).

To understand how the formatting of menus is controlled, the different parts of a menu are first described, then how to control the formatting of each of these parts, for each possible formatting.

7.15.1 The structure of a menu

In texi2html, a menu is considered to be composed of 2 parts, the menu entries and the menu comments. Menu entries are further divided in an entry link and optionnaly an entry description. The entry link consists in a node name and an optionnal menu entry name.

A menu entry begins with ‘*’ at the beginning of the line. It begins with the entry link, followed by the description. The description spans until the next menu entry, or some text begining at the first character of a line or an empty line, not contained within a command block which begun in the description. An empty line or a line with text at the first character starts a menu comment, which spans until the next menu entry.

Here is an illustration of these rules:

@menu
* entry name: node name.        description begins
   description continues
* another menu entry::
   description begins
                    description continues

   A menu comment, after an empty line

* node::                        description begins
A menu comment. The line starts at the first character

* last entry::         description begins @emph{text
of the description, even if the line begins at the first character,
because we are in @emph}.
@end menu

7.15.2 The formatting of the different menu components

Three function references are associated with the formatting of the different parts of a menu:

Function Reference: $link menu_link $section \%state $href $node $name $ending

$section is the section name corresponding with the link, $href is the link hypertextual reference. $href may be absent. \%state holds informations about the current context. The only key which could be of interest is preformatted, true if the context is a preformatted context. See section Three contexts for expansions: preformatted, normal and string. $node is the node name, $name is the name of the node. $ending is the text ending the link entry, in general ‘::’ followed by some spaces.

Function Reference: $description menu_description $description_text \%state $element_text

$description_text is the text of the menu description. \%state should be used similarly than for the menu link. $element_text is the heading of the element associated with the node.

Function Reference: $menu_comment menu_comment $text

$text is the text of the menu comment. It is always in a preformatted environment.

Another function reference corresponds with a special case. It is used when a menu entry appears within another block command, to avoid the possibilities of invalid HTML production. In that case the menu description and menu comments are not formatted specially, but treated like normal text.

Function Reference: $link simple_menu_link $link_text $href $node $name $ending

$link_text is the text corresponding with the link name, $href is the link hypertextual reference. $node is the node name, $name is the name of the node, and $ending is the text ending the link entry.

7.15.3 Simple menu formatting in a preformatted environment

If the menu is to be formatted in a single preformatted environment, an entry for ‘menu’ should be added to the $complex_format_map hash reference (see section Formatting of complex formats (@example, @display…)). In the default case, if the user didn't add an entry himself, a very simple entry is used, with:

$complex_format_map->{'menu'} = { 'begin' => q{''} , 'end' => q{''},
    'pre_style' => "$MENU_PRE_STYLE", 'class' => 'menu-preformatted' };

7.15.4 The formatting of the menu in a table

In the default case, the name of the section corresponding with the node is used instead of the node name. If $NODE_NAME_IN_MENU is true, however, node names are used. If $AVOID_MENU_REDUNDANCY is true and menu entry equal menu description the description isn't printed. This is the default. Likewise, if node or section name equal entry name, do not print entry name.

A symbol, $MENU_SYMBOL is put at the beginning of menu entries when the node name is used. The default is ‘•’. If $UNNUMBERED_SYMBOL_IN_MENU is true it is also put at the beginning of unnumbered section names. This is not done by default.

The menu comments are considered to be preformatted text. The style associated with this preformatted text is determined by $MENU_PRE_STYLE. Default is ‘font-family: serif’. The css class associated with menu comments is menu-comments.

The following function reference controls the formatting of a wole menu in that case:

Function Reference: $menu menu $menu_components_text

$menu_components_text is the formatted menu components text, obtained as explained above.

Doku-Base