6. Fine tuning of the page layout

Some features of the page layout might be specified with command line options, the corresponding variables are described in Page layout related command line options. Fine tuning of the page layout may be achieved with redefinition of other variables and function references in the initialization files.

6.1 The different categories of pages and sectioning elements

The following sectioning elements can be associated with pages:

Normal elements

These are normal sections or nodes. Their association with pages is determined by the splitting of the document. See section Specifying where to split the generated document.

Top element

The top element is the higher element in the document structure. If there is a @top section it is the element associated with that section. Otherwise it is the element associated with the @node Top. If there is no @node Top the first element is the top element.

The top element is formatted differently than a normal element if there is a @top section or the @node Top isn't associated with a sectioning command.

Misc elements

These elements are associated with pages if the document is split. There are four misc elements:

1. Table of contents
2. Short table of contents, also called Overview
3. Footnotes page
4. About page

The About page shouldn't be present for documents consisting in only one sectioning element. The Footnote page should only be present if the footnotes appear on a separated page (see section Page layout related command line options), however a footnote element is present if the document isn't split. The Table of contents should only be formatted if @contents is present in the document. Similarly the Overview should only appear if @shortcontents or @summarycontents is present.

6.2 Page layout and navigation panel overview

A page is broken up in three parts. A page header, the sections and a page footer. A common element in the page layout is a navigation panel with icons or text linking to other sections or pages. Another common element is a rule, separating sections or footer. The navigation panel and the rules may be part of the sections or part of headers or footers. You may use the variables $SMALL_RULE, $DEFAULT_RULE, $MIDDLE_RULE and $BIG_RULE for rules of different sizes. The defaults are

$SMALL_RULE = '<hr size="1">';
$DEFAULT_RULE = '<hr>';
$MIDDLE_RULE = '<hr size="2">';
$BIG_RULE = '<hr size="6">';

In the header some important meta data may be defined, like the title or style information, and textual informations may be present in comments. All this doesn't appear directly in the displayed HTML, though.

The page layout is mainly controlled by functions, the precise functions called depending on the document splitting. The navigation panel, however, can be customized with variables.

Element labels

There are 19 items associated with elements. Each of these is associated with a name and a reference to the element they represent, when such an element exists. The element is either a global element or an element relative to the current element. The relative elements are found with respect with the document structure defined by the section structuring commands (@chapter, @unnumbered…) or by the nodes (in that case the node directions are specified on node line or in menu organization). These items are called element labels. They may be associated with a button (see section Specifying the buttons formatting), and used in the formatting functions (see section Main program variables and usefull functions).

Here is the list:

` '

An empty button

Top

Top element. The associated name is $TOP_HEADING if that variable is defined. This variable is not set by default.

Contents

Table of contents

About

About (help) page

Overview

Overview, short table of contents

First

First element in reading order

Last

Last element in reading order

Index

The first chapter with @printindex. The associated name is $INDEX_CHAPTER, if the variable is set. This variable is not set by default.

This

The current element

Back

Preceding element in reading order

FastBack

Beginning of this chapter or previous chapter if the element is a chapter

Prev

Previous section on the same level

NodePrev

Previous node

Forward

Next element in reading order

FastForward

Next chapter

Next

Next section on the same level

NodeNext

Next node

Following

Next node in node reading order

Up

Up section

NodeUp

Up node

6.3 Customization of the navigation panels buttons

A lot of customization of the navigation panel may be achieved without redefining functions, with variables redefinition. In case it isn't enough, it is also possible to redefine the function doing the navigation panel formatting.

6.3.1 Controlling the navigation panel panel at a high level

The global formatting of the navigation panels may be changed with the following variables:

$VERTICAL_HEAD_NAVIGATION

A vertical navigation panel will be used for the header navigation panel if this variable is true.

$ICONS

Icons are used instead of textual buttons if this variable is true.

$SECTION_NAVIGATION

If this variable is false there is no section navigation, no navigation panels for the elements within the pages, only at the beginning and the end of the page (see section Page layout related command line options).

6.3.2 Specifying the buttons formatting

Several arrays and hashes enable a precise control on the buttons and their display. The following arrays determine the buttons present in navigation panels:

@SECTION_BUTTONS

This array is used for the navigation panel buttons present at the begining of sectioning elements. If split at node or section they are also used at the page footer, and in the case of section navigation at the page header.

@SECTION_FOOTER_BUTTONS

@NODE_FOOTER_BUTTONS

This array is used for the navigation panel buttons present at the footer of pages when split at node or at section.

If $WORDS_IN_PAGE is set and the output is split at nodes, these buttons are only present if there are more than $WORDS_IN_PAGE words in the sectioning element text. This counting is very rough and include punctuation marks, html elements, numbers. The default is to include the buttons after 300 words.

@CHAPTER_BUTTONS

This array is used for the buttons appearing at the page footer if split at chapter, and at the page header if split at chapter and there is no section navigation.

@MISC_BUTTONS

These buttons appear at the beginning of special and sections and at the end of these section pages if the output is split.

The array specify the buttons displayed in navigation panels, and how the button is displayed. Each element is associated with a button of the navigation panel from left to right. The signification of the array element value is the following:

reference on a function

The function is called with first argument a filehandle reference on the current file and second argument a boolean true if the navigation panel should be vertical.

reference on a scalar

The scalar value is printed. For some possibly usefull scalars, Accessing elements informations.

reference on an array

In this case the first array element should be a reference on text and the second element an element label. In that case a link to the element associated with the element label with the scalar value text is generated.

For example if the buttons array element is

[ 'Next', \$Texi2HTML::NODE{Next} ]

The button will be a link to the next section with text $Texi2HTML::NODE{Next}.

element label

If icons are not used, the button is a link to the corresponding element which text is defined by the value associated with the element label in the %NAVIGATION_TEXT hash, surrounded by `[' and `]'. If the element label is ` ', there is no `[' and `]'. The element of the %NAVIGATION_TEXT hash are defined dynamically, in the init_out function reference (see section Preparing the output).

If icons are used, the button is an image with file determined by the value associated with the element label in the %ACTIVE_ICONS hash if the the link really leads to an element, or in the %PASSIVE_ICONS hash if there is no element to link to. Of course if there is a link to the element the icon links to that element.

6.3.3 Changing the navigation panel formatting

If you are not satisfied with this scheme, it is possible to control exactly the formatting of navigation panels by redefining a function reference. The function controlling the display of navigation panel is associated with the following function reference:

Function Reference: print_navigation $filehandle \@buttons $vertical

$filehandle is the opened filehandle the function should write to. \@buttons is an array reference which should hold the specification of the buttons for that navigation panel. $vertical is true if the navigation panel should be vertical.

6.4 Main program variables and usefull functions

In the functions controlling the page layout some global variables set by the main program are available, with value corresponding with the current layout element.

6.4.1 Accessing elements informations

Four hashes are available, with key the elements labels (as described in Element labels) and values:

%Texi2HTML::NAME

The formatted element name

%Texi2HTML::HREF

The element hypertext reference

%Texi2HTML::NODE

The element node name

%Texi2HTML::NO_TEXI

The element name after removal of texi commands

6.4.2 Accessing global informations

Three kinds of global informations are available, miscalleneous global strings, flags set by @set and special flags and section lines.

Global strings

The %Texi2HTML::THISDOC hash holds some global informations:

fulltitle

title set by @title. If there is no @title other possibilities are tried (@settitle, @shorttitlepage…).

title

title set by @settitle, or fulltitle.

title_no_texi

title without texi formatting

title_texi

title with texi commands

author

Authors list set by @author.

authors

A reference on an array containing each author set by @author.

copying

Text appearing in @copying with all the texinfo commands removed, put in comments.

program

The name and version of texi2html.

program_homepage

Homepage for texi2html.

program_authors

Authors of texi2html.

file_base_name

base name of the texinfo manual file.

destination_directory

Destination directory for the resulting files.

toc_file

The file name of the table of contents.

today

The date.

It also holds the arg of the following commands, associated with the command name: kbdinputstyle, paragraphindent, setchapternewpage, headings, footnotestyle, exampleindent, firstparagraphindent, everyheading, everyfooting, evenheading, evenfooting, oddheading, oddfooting.

Flags

Flags defined by @set may be accessed through the %main::value hash. The key is the flag name, the value is the flag value at the end of the document.

Special flags are set by the main program. They correspond with a texinfo command, like @setfilename, or @settitle, @author… The corresponding flag is the command name with `_' appended, for example, _titlefont corresponds with @titlefont. Like other flags they are available in %main::value.

Section lines

The following array references or arrays holds formatted lines:

$Texi2HTML::THIS_SECTION

Lines of the current element.

$Texi2HTML::THIS_HEADER

Lines of the current element appearing before the element label (anchors).

$Texi2HTML::OVERVIEW

Lines of short table of contents. See section Special pages formatting.

$Texi2HTML::TOC_LINES

Lines of table of contents. See section Special pages formatting.

6.4.3 Function usefull in page formatting

The usefull function is a function used to print an array of lines, which also counts the number of words in the array, if needed.

Function: $words_number main::print_lines $filehandle \@lines_array

$filehandle is the opened filehandle the function should write to. \@lines_array is the array line the function should write to the file. If this argument is omitted, the function uses $Texi2HTML::THIS_SECTION. $words_number is the number of words in the array, only defined if split at nodes and $WORDS_IN_PAGE is defined.

6.5 Preparing the output

After the texinfo file has been parsed, some information is available which can be used to modify some variables and prepare the outputting. For example the document language, the document encoding, values set with @set or @setfilename and other similar @-commands are not known before the texinfo parsing.

The following function reference may be redefined to be called after texinfo processing and before document generation:

Function Reference: $encoding init_out

This function perform the initialization of variables and any other task before document outputting. It returns the encoding used for the output files.

In the default case the $BODYTEXT (see section Customizing the page header) and the hashes %NAVIGATION_TEXT (see section Specifying the buttons formatting) and %BUTTONS_GOTO (see section Formatting of about text) are initialized.

To perform the default initializations and also add more code, you could do as in the following example (save the default function reference and call it in your own function) :

my $default_init_out = $init_out;
$init_out = \&makeinfo_like_init_out;
sub makeinfo_like_init_out() 
{
   my $encoding = &$default_init_out();
   $NAVIGATION_TEXT{'Following'} = ' > ';
   return $encoding;
}

6.6 Finalizing the output

If you want to do some cleaning after the document was generated (close files, write at the end of files and so on), the following function reference may be redefined:

Function Reference: finish_out

This function is called after the document generation.

The default is to do nothing.

6.7 Customizing the texi2html css lines

It is possible to modify the texi2html css lines by modifying the entries or adding to the %css_map hash. Each key is a css selector, the corresponding value is a style string.

The whole css text is in the variable $CSS_LINES. If this variable is defined the variable value is used instead of being constructed using the %css_map entries. For example if you don't want any css entries, set

$CSS_LINES = '';

It is also possible to change completely the way $CSS_LINES are generated by redefining the following function reference:

Function Reference: css_lines \@import_lines \@rule_lines

This function should be used to construct the $CSS_LINES. \@import_lines are the @import lines of the files specified with `--include-css', and \@rule_lines are the css commands lines of these files. See section Customizing the HTML and text style.

6.8 Customizing the page header

It is possible to add lines to the text within the <head> HTML elements, by defining the variable $EXTRA_HEAD. Similarly it is possible to add text just after the <body> element with the variable $AFTER_BODY_OPEN. These variables are empty by default.

The encoding of the texinfo file is defined by $DOCUMENT_ENCODING if no @documentencoding appears in the document. The default is a `en-ascii' encoding. The encoding of the resulting document is defined by $ENCODING. The default is the $DOCUMENT_ENCODING.

The description of the document may be specified in $DOCUMENT_DESCRIPTION. If this variable is undef, the text associated with @documentdescription is used, and if there isn't such test a default description is constructed using the document title and the name of the first section of the file.

The <body> element attributes may be set by defining the variable $BODYTEXT. If you want to define that variable dynamically, you should use the init_out function reference (see section Preparing the output).

The default functions call the function associated with $print_head_navigation to format the navigation panel for the page header. Thus you can control parts of the formatting by redefining the function reference.

Function Reference: print_head_navigation $filehandle \@buttons

$filehandle is the opened filehandle the function should write to. \@buttons is an array reference which should hold the specification of the buttons for the navigation panel.

If you want even more control, you can have full control over the page header formatting by redefining three function references. The function associated with $print_page_head is called for all the pages, and after that, the function associated with $print_chapter_header is called if the document is split at chapters, or the function associated with $print_section_header is called if the document is split at sections.

Function Reference: print_page_head $filehandle

$filehandle is the opened filehandle the function should write to. This function should print the page head, including the <body> element.

Function Reference: print_chapter_header $filehandle

$filehandle is the opened filehandle the function should write to. This function is called if the document is split at chapters, after print_page_head.

Function Reference: print_section_header $filehandle

$filehandle is the opened filehandle the function should write to. This function is called if the document is split at sections, after print_page_head.

6.9 Customizing the sections

The functions associated with the following function references are used for the formatting of sections:

Function Reference: print_section $filehandle $first_in_page $previous_is_top

$filehandle is the opened filehandle the function should write to. $first_in_page is true if this section is the first section in the page. $previous_is_top is true if this section is the section following the Top section. This function should print the current section.

Function Reference: end_section $filehandle $last_element_or_before_top

$filehandle is the opened filehandle the function should write to. $last_element_or_before_top is true if this section precedes the top element or is the last one in page, or before the special elements.

6.10 Customizing the page footer

It is possible to add text just before the </body> element with the variable $PRE_BODY_CLOSE. Nothing is added by default.

The default functions call the function associated with $print_foot_navigation to format the navigation panel for the page footer. Thus you can control parts of the formatting by redefining the function reference.

Function Reference: print_foot_navigation $filehandle \@buttons

$filehandle is the opened filehandle the function should write to. \@buttons is an array reference which should hold the specification of the buttons for the navigation panel.

If you want even more control, you can have full control the page footer formatting by redefining three function references. The function associated with $print_chapter_footer is called if the document is split at chapters, or the function associated with $print_section_footer is called if the document is split at sections. After that the function associated with $print_page_foot is called.

Function Reference: print_page_foot $filehandle

$filehandle is the opened filehandle the function should write to. This function should print the page foot, including the </body> element.

Function Reference: print_chapter_footer $filehandle

$filehandle is the opened filehandle the function should write to. This function is called if the document is split at chapters, before print_page_foot.

Function Reference: print_section_footer $filehandle

$filehandle is the opened filehandle the function should write to. This function is called if the document is split at sections, before print_page_foot.

6.11 Special pages formatting

For the special elements, two things must be formatted: the content and the page layout

6.11.1 Customizing the content of the special pages

6.11.1.1 Top element text formatting

The top element formatting is controlled by three function which also controls the layout of the top element page or section. The associated function references are:

Function Reference: print_Top_header $filehandle $begin_page

$filehandle is the opened filehandle the function should write to. $begin_page is true if the element is the first in a page. This function should begin the Top element. At the time this function is called the top element text hasn't been parsed.

Function Reference: print_Top $filehandle $has_top_heading

$filehandle is the opened filehandle the function should write to. $has_top_heading is true if there is a @heading command or @titlefont command appearing in the Top element text. This function should be used to format the Top element text and navigation panel.

Function Reference: print_Top_footer $filehandle $end_page

$filehandle is the opened filehandle the function should write to. $end_page is true if the element is the last in a page. This function should end the Top element.

6.11.1.2 Table of contents and Short table of contents

Several variables may be used to control the formatting of table of contents and short table of contents:

$DO_CONTENTS

If the variable is true a table of contents is done even if there is no @contents command.

$DO_SCONTENTS

If the variable is true a short table of contents is done even if there is no @summarycontents command.

$BEFORE_OVERVIEW

The variable value is inserted before the short table of contents text.

$AFTER_OVERVIEW

The variable value is inserted after the short table of contents text.

$BEFORE_TOC_LINES

The variable value is inserted before the table of contents text.

$AFTER_TOC_LINES

The variable value is inserted after the table of contents text.

$TOC_LIST_STYLE

This should contain a css style used for the list style if the tables of content are formatted with a list.

$TOC_LIST_ATTRIBUTE

This should contain an attribute text used for the list element if the tables of content are formatted with a list.

More control on the table of contents and short table of contents formatting may be achieved by redefining a function with the following associated function reference:

Function Reference: toc_body \@elements

\@elements is an array reference contining informations about all the elements of the document. Each of the entry of this array is an hash reference which entries correspond with different informations about the element. Interesting keys have the following meaning:

top

true if the element is the top element,

index_page

true if the element is an index page added because of index splitting,

toc_level

level of the element in the table of content. Highest level is 1 for the top element and for chapters, appendix and so on, 2 for section, unnumberedsec and so on...

tocid

label used for reference linking to the element in table of contents,

file

the file containing the element, usefull to do href to that file in case the document is split,

text

text of the element, with section number,

name

text of the element, without section number.

This function doesn't return anything but should fill the array corresponding with the $Texi2HTML::TOC_LINES and $Texi2HTML::OVERVIEW references with the table of contents and short table of contents.

6.11.1.3 Formatting of footnotes text

The footnotes text is allready formatting when @footnote commands are expanded. See section Customizing the footnotes formatting.

6.11.1.4 Formatting of about text

The default about element contains an explaination of the buttons used in the document (@SECTION_BUTTONS, Specifying the buttons formatting) and an example locating the buttons targets in an example. The formatting of this text may be influenced by the following hashes and variables:

$PRE_ABOUT

$AFTER_ABOUT

This variable may be a scalar or a function reference. If it is a scalar, the value is used. If this is a function reference it is expanded and the returned text is used. The text is added before or after the main about text.

%BUTTONS_GOTO

The keys of this hash are element labels (see Element labels). The value is the text associated with the element label in the about text. The element of the hash are defined dynamically, you should in the init_out function reference (see section Preparing the output).

%BUTTONS_EXAMPLE

The keys of this hash are element labels (see Element labels). The value is the text associated with the element label in the about example, typically a section number.

If this is not enough and you want to control exactly the formatting of the about text, you can redefine the function associated with the following function reference:

Function Reference: $about_text print_about

This function should return the about text.

6.11.2 Customizing the layout of the special pages

The formatting of each of the special pages, or section in case the document is not split, is controlled by a function. The associated function reference is called accordingly:

print_Top

print_Top_header

print_Top_footer

Formatting of top element page or section. It is also used for the formatting of the top element text (see section Top element text formatting).

print_Toc

Formatting of table of contents page or section

print_Overview

Formatting of short table of contents page or section

print_About

Formatting of about (help) page or section

print_Footnotes

Formatting of footnotes section or page in case footnotes are on a separated page or the document isn't split.

In the default case, $print_Top calls $print_Top_header for the header and $print_Top_footer for the footer of top element. All the other function call $print_misc which in turn calls $print_misc_header for the headers and $print_misc_footer for the footers.

6.12 Customizing the file names

It is possible to specify the file names with more control than with the command line options (see section Setting output file and directory names). First the extension may be overrided by the variable $EXTENSION value. Two function references enable further customization. One is usefull in case $NODE_FILES is true and it is used to customize the node file name itself and is also used to produce a file name with a redirection leading to the node file.

Function Reference: ($node_file $redirection_node_file) node_file_name $node

$node is a hash reference with the following interesting keys (there are much more keys):

texi

The texinfo node name.

with_section

True if associated with a section.

The result is the node file name $node_file, and the file containing a redirection to the node $redirection_node_file.

The other is usefull if $NODE_FILES isn't true. It is used to customize the file associated with each element.

Function Reference: $file element_file_name $element $is_top $docu_name

$element is a hash reference with the following interesting keys (there are much more keys):

texi

The texinfo element name.

number

The number associated with a section.

doc_nr

A number incremented whenever a new file should begin, based on how the document is split (see section Specifying where to split the generated document).

text

The element text.

name

The element text without section number.

$is_top is true if the element is considered as the top element. $docu_name is the basename of the texinfo manual. The result is the element file name.

6.13 Generation of external files for index entries

Within the document, @printindex commands are expanded as explained in Customizing the formatting of index lists. In case you want to do something special with index entries, outside of the document, you should first set the variable $IDX_SUMMARY true. After that some function reference will be called for each non empty index. For each index there are 3 function references, one called for initialization, one called for each index entry and the last one called for finalazation.

Function Reference: index_summary_file_begin $index_name $is_printed

$index_name is the two letters name for the index. This function is called for each index appearing in the document, before index_summary_file_entry. $is_printed is true if there is a @printindex for that index.

Function Reference: index_summary_file_entry $index_name $entry_text $entry_reference $formatted_entry $texi_entry $entry_element_reference $entry_element_header $is_printed

This function is called for each entry of an index. index_name is the name of the index. $entry_text is the entry in plain text, $formatted_entry is the index entry formatted, $texi_entry is the entry with texinfo commands. $entry_reference is the reference placed at the index entry place, in the form `file#id'. $entry_element_header is the formatted header of the element containing the index entry. entry_element_header is the reference to the beginning of the element containing the index entry, in the form `file#id'. $is_printed is true if there is a @printindex for that index.

Function Reference: index_summary_file_end $index_name $is_printed

$index_name is the two letters name for the index. This function is called for each index appearing in the document, after index_summary_file_entry. $is_printed is true if there is a @printindex for that index.

This document was generated by Derek R. Price on July, 14 2005 using texi2html 1.77.