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

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.

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

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:

id

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

file

The file name containing the 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.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.

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.

Doku-Base