Texi2HTML – Texinfo to HTML v1.82: 6. Fine tuning of the page layout
[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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, or for documents unsplit and without navigation information. 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. The Table of contents and the Overview may also be directly included within the document, not as separate pages (see section Table of contents and Short table of contents).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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

FileNext

Forward element first in the next page (or file)

FilePrev

Backward element first in the previous page (or file)


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.

@LINKS_BUTTONS

These are used for <link> elements if they are output in the headers.

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 argument a boolean true if the navigation panel should be vertical. Should return the formatted button text.

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. The button name and the button description are used in HTML attributes to have a textual description of the icon. The corresponding strings are in %BUTTONS_NAME for the button name and %NAVIGATION_TEXT for the description.

If $USE_ACCESSKEY is set, the accesskey attribute is used in navigation. In that case the %BUTTONS_ACCESSKEY hash is used for the access key.

Similarly, if If $USE_REL_REV is set, the rel attribute is used in navigation. In that case the %BUTTONS_REL hash is used for the rel attribute.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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: $navigation_text print_navigation \@buttons $vertical

\@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. Returns the formatted navigation panel in $navigation_text.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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

If $USE_NODE_TARGET is set, the node anchors are used as target for the section HREF, if there is a node associated to that section.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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 @settitle. If there is no @settitle other possibilities are tried (@title, @shorttitlepage…).

fulltitle_no_texi

fulltitle without texi formatting

fulltitle_texi

fulltitle with texi commands

title

title set by @title.

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_comment

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.

filename

This is a reference on a hash that holds the filenames for special elements. These files may not be used in certain cases, for example the toc element file name may not be relevant if table of contents is not output separately. The keys are

doc

the document file if not split, if split should be the top element file.

top

Top element file name.

toc

Table of contents element file name.

stoc

Overview (also called short table of contents) element file name.

about

About element file name.

foot

Footnotes element file name.

frame

Main frame file.

toc_frame

Table of contents frame file name.

input_file_name

Name of the texinfo manual file given on the command line.

destination_directory

Destination directory for the resulting files.

extension

Extension for the output files.

toc_file

The file name of the table of contents, should always be valid, even when table of contents are output directly in the document.

inline_contents

A reference on a hash containing two key, one for each type of table of contents:

contents

The associated value is a reference on an array containg the line resulting from formatting the table of contents, including a heading and a reference.

shortcontents

The associated value is a reference on an array containg the line resulting from formatting the short table of contents, including a heading and a reference.

today

The date. May be overriden by $DATE.

user

The user running texi2html. Maybe overriden by $USER.

css_import_lines

reference on an array containing the @import lines of CSS files.

css_lines

reference on an array containing the normal lines of CSS files.

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, setcontentsaftertitlepage, setshortcontentsaftertitlepage, frenchspacing. If the command doesn’t have any arg, it will be true is it was set.

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::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.

$Texi2HTML::TITLEPAGE

The title page formatted with special title commands (@author, @title) expanded. See section Formatting of title page.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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: init_out

This function perform the initialization of variables and any other task before document outputting.

In the default case the $BODYTEXT (see section Customizing the page header) and the hashes %NAVIGATION_TEXT, %BUTTONS_NAME (see section Specifying the buttons formatting), %BUTTONS_GOTO (see section Formatting of about text) are initialized. Indeed the initialization of these variables is dependent upon the document language selection. Similarly the encoding variables are set based on the information now available (see section Setting the encodings).

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() 
{
   &$default_init_out();
   $NAVIGATION_TEXT{'Following'} = ' &gt; ';
}

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.7 Customizing the texi2html css lines

If the variable $CSS_LINES is set it is used for the css entries. For example if you don’t want any css entries, set

 
$CSS_LINES = '';

If this variable is undef (as in th edefault case), 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.

Another possiblility is to modify the array corresponding with the array reference $Texi2HTML::THISDOC{'css_import_lines'} that contains the @import lines of CSS files, and similarly it is possible to modify the array corresponding with the array reference $Texi2HTML::THISDOC{'css_lines'} that contains the normal CSS files lines (for details on what corresponds with those different lines, see (texinfo)HTML CSS section ‘HTML CSS’ in GNU Texinfo). The right place to modify these arrays is in a function appearing in the @command_handler_process array (see section Bypassing normal formatting). Later, the CSS lines are allready expanded, by the function reference below.

In th edefault case, the resulting css lines are in $Texi2html::THISDOC{'CSS_LINES'}. It is also possible to change completely the way $Texi2html::THISDOC{'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 variable $Texi2html::THISDOC{'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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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 HTML encoding of the resulting document is defined by $ENCODING_NAME. If the variable isn’t defined, the @documentencoding value is used, or the $OUT_ENCODING value, if set. $ENCODING_NAME may influence the value of $OUT_ENCODING, which corresponds with the encoding used when writing to the resulting files. See section Setting the encodings.

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 value used during document formatting is $Texi2HTML::THISDOC{'DOCUMENT_DESCRIPTION'}.

The <body> element attributes may be set by defining the variable $BODYTEXT. The resulting attributes are in $Texi2HTML::THISDOC{'BODYTEXT'}. If you want to define that variable dynamically, you should use the init_out function reference (see section Preparing the output).

<link> element are used in the header if $USE_LINKS is set. @LINKS_BUTTONS determines which links are used. %BUTTONS_REL determines the link type associated with the rel attribute.

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.9 Customizing the sections

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

Function Reference: $element_header print_element_header $first_in_page $previous_is_top

$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 return $element_header, the current section header.

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 contents.

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.

A user name and a date are collected to be output in the footer. You can change them by defining $USER and $DATE in the initialization file.

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 more control over 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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.11 Special pages formatting

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.11.1 Customizing the content of the special pages

The label for the special elements, except for the Top element is formatted according to the function reference $misc_element_label:

Function Reference: $misc_element_label misc_element_label $identifier $page_name

$identifier is the identifier associated with the special element. $page_name is the special element name. It should return a label that can be used for references to the special element.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.11.1.2 Table of contents and Short table of contents

Two possibilities exist for the formatting of table of contents (and short table of contents). In the default case, the table of contents are in separate elements, at the end of the document if the document is unsplit or in separate files. This is consistent with makeinfo where menus are used for navigation. Another mode may be selected by setting $INLINE_CONTENTS. In that case the table of contents are not output as separate elements but are instead output where the corresponding @-command, for example @contents, is set. This behaviour is more consistent with texi2dvi. If @setcontentsaftertitlepage appears in the document, and even if $INLINE_CONTENTS is set, the table of contents are merged in the title (which isn’t output in the default case, see Formatting of title page).

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. If it is defined and false, no table of contents is done even if there is a @contents command.

$DO_SCONTENTS

If the variable is true a short table of contents is done even if there is no @summarycontents command. If it is defined and false, no short table of contents is done even if there is a @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.

$NO_BULLET_LIST_STYLE

This should contain a css style used for the list style when there is no bullet.

$NO_BULLET_LIST_ATTRIBUTE

This should contain an attribute text used for the list element when there is no bullet. For example it is used in the tables of if they 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.

Another function reference is used to add a heading and a reference, to be used with $INLINE_CONTENTS or merged in the title. Its output is not used when the table of contents are separate elements.

Function Reference: \ @inline_contents_lines inline_contents $filehandle $command $element

This function reference returns a reference on an array holding the lines containing the contents, heading and reference. $filehandle is a reference on the currently opened file if the function is called because a @contents or @shortcontents command was encountered, it is undef otherwise. $command is either ‘contents’ or ‘shortcontents’. $element is a hash reference containing informations about the table of contents context. Relevant keys are:

target

The identifier associated with the table of contents, used for example to do references to the table of contents using href in HTML.

id

The identifier associated with the element, used to do labels. In general the same than the target, but not necessarily.

file

The file name containing the table of contents.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.11.1.5 Formatting of title page

The title page is first formatted using the text appearing in the @titlepage section, and put in $Texi2HTML::TITLEPAGE. The information appearing in @title, @subtitle or @author is then added using the following function reference:

Function Reference: titlepage

This function should complete $Texi2HTML::TITLEPAGE.

In the default case, in this function the table of contents and short table of contents are also added if they are to be output and @setcontentsaftertitlepage or @setshortcontentsaftertitlepage appear in the document (see section Table of contents and Short table of contents).

In the default case the resulting title page output is not used in the document, except if the top node is not associated with any content.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.12 Customizing the file and target names

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. The variable should be undef if no extension is to be added. 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.

Function Reference: $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.

The other is used to customize the file names associated with each element, and the name of the file associated with the special elements.

Function Reference: $file element_file_name \%element $type $docu_name

\%element is undefined for the special elements (about, overview, table of contents, footnotes). Otherwise it 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.

$type is empty for normal elements. For the top element it is ‘top’, for the table of contents it is ‘toc’, for the overview it is ‘stoc’, for the footnotes it is ‘foot’ and for about is ‘about’. If frames are used (see section Page layout related command line options), the function reference is also called for ‘frame’, the frame file name, and ‘toc_frame’ the table of content frame file name. $docu_name is the basename of the texinfo manual. The result is the element or special element file name.

target names

Similarly target and id may be set. The id is placed where the item is located, the target is used to construct references to that item. In general they should be equal, but not always, for example in the default case, the target for a section is the node id. The following function reference, is for target items (nodes, anchors, floats):

Function Reference: ($target,$id) node_target_name \%node, $default_target, $default_id

\%node is the same as in the node_file_name function reference above. $default_target is the target already set (it is also in $node->{'target'}), and $default_id is similarly the id already set.

For element associated with files (which may be nodes), the function reference is:

Function Reference: ($target,$id) element_target_name \%element, $default_target, $default_id

the \%element is the same than in element_file_name, and $default_target and $default_id are the target and id already set.

Placed items (floats, footnotes, index entries, anchors, contents, shortcontents and headings) file and target may also be set. In the default case, they should be rightly set, so be careful when changing them. The following function reference can be used:

Function Reference: ($target, $id, $file) placed_target_file_name \%placed_item, \%element, $default_target, $default_id, $default_file, $context

\%placed_item is a hash reference describing the placed item, in the same vein than above. the \%element is the same than in element_file_name, corresponding with the element containing the placed item. $default_file, default_id and $default_target are the file, id and target already set. $context describes the context, it is empty in the normal cases, and can also be set to ‘footnotes’ if in footnotes, or to ‘no_associated_element’ if the placed item is out of any element (typically in @titlepage, @copying).

For special elements, the %misc_pages_targets hash is used to set the target and id. The possibilities for the keys are ‘Overview’, ‘Contents’, ‘Footnotes’ and ‘About’.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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 finalization.

Function Reference: index_summary_file_begin $index_name $is_printed $manual_name

$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. $manual_name is the manual basename.

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

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. $manual_name is the manual basename.

Function Reference: index_summary_file_end $index_name $is_printed $manual_name

$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. $manual_name is the manual basename.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by Derek Price on January 5, 2009 using texi2html 1.82.

Derek Price, CVS developer and technical editor of Essential CVS (Essentials line from O'Reilly Press) , and others offer consulting services and training through Ximbiot.