texinfo (7.1)
This is texi2any_api.info, produced by texi2any version 7.1 from
texi2any_api.texi.
This manual is for GNU Texinfo ‘texi2any’ program output adaptation
using customization files (version 7.1, 11 September 2023).
Copyright © 2013-2023 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, no Front-Cover Texts, and
no Back-Cover Texts. A copy of the license is included in the
section entitled "GNU Free Documentation License" in the Texinfo
manual.
INFO-DIR-SECTION Texinfo documentation system
START-INFO-DIR-ENTRY
* texi2any customization: (texi2any_api).
Customizing texi2any output
END-INFO-DIR-ENTRY
File: texi2any_api.info, Node: Top, Next: Overview, Up: (dir)
GNU Texinfo ‘texi2any’ Output Customization
*******************************************
* Menu:
* Overview::
* Loading Init Files::
* Init File Basics::
* Simple formatting customization::
* Simple headers customizations::
* User Defined Functions::
* Customizing Output-Related Names::
* Init File Calling at Different Stages::
* User Defined Functions in Conversion::
* Mandatory Conversion Function Calls::
* Basic Formatting Customization::
* Dynamic Conversion Information::
* Translations Output and Customization::
* Directions, Links, Labels and Files::
* Customizing Footnotes, Tables of Contents and About::
* Customizing HTML Footers, Headers and Navigation Panels::
* Heading Commands and Tree Elements Formatting::
* Beginning and Ending Files::
* Titlepage, CSS and Redirection Files::
* Specific Functions for Specific Elements::
* Functions Index::
* Variables Index::
* General Index::
-- The Detailed Node Listing --
Init File Basics
* Init File Namespace::
* Managing Customization Variables::
* Init File Loading Error Reporting::
Managing Customization Variables
* Setting Main Program String Variables::
* Modifying Main Program Array Variables::
* Setting Converter Variables in Main Program::
* Getting Main Program Variables Values::
* Adding Customization Variables::
Simple formatting customization
* Init File Expansion Contexts::
* Simple Customization for Commands Without Arguments::
* Simple Customization for Simple Commands with Braces::
* Simple Customization of Accent Commands::
* Simple Customization of Containers::
* Simple Customization of CSS::
Simple headers customizations
* Output Element Units::
* Directions::
* Direction Strings Customization::
* Simple Navigation Panel Customization::
Directions
* Element Direction Information Type::
* Direction Strings::
User Defined Functions
* User Defined Functions are Registered::
* Converter Object and Conversion Functions::
* Texinfo Tree Elements in User Defined Functions::
* Encoding and Decoding File Path Strings::
* Setting the Context for Conversion::
* Conversion Customization Variables::
* Conversion General Information::
Converter Object and Conversion Functions
* Texinfo Tree Conversion Functions::
* Error Reporting in User Defined Functions::
Encoding and Decoding File Path Strings
* Encoding File Path Strings::
* Decoding File Path Strings::
Customizing Output-Related Names
* File: Customizing Output File Names.
* Target: Customizing Output Target Names.
* External Node: Customizing External Node Output Names.
* Special Elements: Customizing Special Elements Output Names.
User Defined Functions in Conversion
* Tree Element Conversion Functions::
* Formatting Functions::
Tree Element Conversion Functions
* Command Tree Element Opening Functions::
* Command Tree Element Conversion Functions::
* Type Tree Element Opening Functions::
* Type Tree Element Conversion Functions::
Formatting Functions
* Specific formating Functions::
Mandatory Conversion Function Calls
* Protection of URLs::
* Formatting HTML Element with Classes::
* Closing Lone HTML Element::
* Substituting Non Breaking Space::
* Conversion in String Context::
* Conversion in Preformatted Context::
* Text Formatting Context::
Dynamic Conversion Information
* Dynamic Converter Formatting Information::
* Opening and Closing Sectioning Commands Extent::
* Setting Up Content for the Next Text Container::
* Associating Information to an Output File::
* Shared Conversion State::
Translations Output and Customization
* Internationalization of Strings Function::
* Translated Strings Customization::
* Translation Contexts::
Directions, Links, Labels and Files
* Getting Direction Strings::
* Target Commands Links, Texts and Associated Commands::
* Other Links, Headings and Associated Information for Special Elements::
* Elements and Links for Directions::
* Element Counters in Files::
Customizing Footnotes, Tables of Contents and About
* Special Elements Information Customization::
* Customizing Footnotes::
* Contents and Short Table of Contents Customization::
* About Element Customization::
* Special Element Body Formatting Functions::
Customizing HTML Footers, Headers and Navigation Panels
* Navigation Panel and Navigation Header Formatting::
* Element Header and Footer Formatting::
Beginning and Ending Files
* Customizing HTML File Beginning::
* Customizing HTML File End::
Titlepage, CSS and Redirection Files
* HTML Title Page Customization::
* Customizing CSS::
* Customizing Node Redirection Pages::
File: texi2any_api.info, Node: Overview, Next: Loading Init Files, Prev: Top, Up: Top
1 Overview
**********
Warning: All of this information, with the exception of
command-line options and search directories associated with command
line options (*note Loading Init Files::), may become obsolete in a
future Texinfo release. Right now, the "API" described in this
chapter is immature, so we must keep open the possibility of
incompatible, possibly major, changes. Of course we try to avoid
incompatible changes, but it is not a promise.
This manual describes how to customize the ‘texi2any’ HTML output.
Although some of the features here can technically be used with other
output formats, it's not especially useful to do so, so we'll write the
documentation as if HTML were the target format. Most of the
customizations are only available for HTML.
The conversion of Texinfo to HTML is done in two steps. After
reading command-line options and init files, input Texinfo code is
parsed into a Texinfo Perl tree and information is gathered on the
document structure. This first step can only be customized to a certain
extent, by using the command-line options and setting customization
variables. The Texinfo Perl tree describes a Texinfo document in a
structured way which makes it easy to go through the tree and format
@-commands and other containers.
The second step is the “conversion” step done in a converter. The
HTML converter takes a Texinfo Perl tree as input and transforms it to
HTML. The code that is used to go through the tree cannot be
customized, but the conversion of tree elements can be fully customized.
File: texi2any_api.info, Node: Loading Init Files, Next: Init File Basics, Prev: Overview, Up: Top
2 Loading Initialization Files and Search Paths
***********************************************
Warning: The ‘texi2any-config.pm’ file related paths and even the
use of ‘texi2any-config.pm’ files is not definitive.
You can write so-called “initialization files”, or “init files” for
short, to modify almost every aspect of output formatting. The program
loads init files named ‘texi2any-config.pm’ each time it is run. Those
files are looked for in the following directories:
‘DATADIR/texi2any/’
(where DATADIR is the system data directory specified at
compile-time, e.g., ‘/usr/local/share’)
‘SYSCONFDIR/texi2any/’
(likewise specified at compile time, e.g., ‘/usr/local/etc’)
‘~/.texi2any/’
(where ‘~’ is the current user's home directory)
‘./.texi2any/’
(under the current directory)
‘./’
(the current directory)
All ‘texi2any-config.pm’ files found are loaded, in the above order.
Thus, ‘./texi2any-config.pm’ can override entries in, say,
‘/usr/local/share/makeinfo/texi2any-config.pm’.
However, the most common way to load an initialization file is with
the ‘--init-file’ option, explicitly specifying the file to be loaded.
By default the following directories are searched, in the following
order. Only the first file found is used:
1. The current directory ‘./’;
2. ‘./.texi2any/’ under the current directory;
3. ‘~/.texi2any/’ where ‘~’ is the current user's home directory;
4. ‘SYSCONFDIR/texi2any/’ where SYSCONFDIR is the system configuration
directory specified at compile-time, e.g., ‘/usr/local/etc’;
5. ‘DATADIR/texi2any/’ Where DATADIR is the system data directory
likewise specified at compile time, e.g., ‘/usr/local/share’;
6. ‘./.texinfo/init/’ under the current directory;
7. ‘~/.texinfo/init/’ under the current home directory;
8. ‘SYSCONFDIR/texinfo/init/’ with SYSCONFDIR as above;
9. ‘DATADIR/texinfo/init/’ with DATADIR as above.
10. ‘DATADIR/texinfo/ext/’ with DATADIR as above.
The ‘DATADIR/texinfo/ext/’ directory contains the init files directly
loaded from ‘texi2any’ code. When loaded from ‘texi2any’ code directly,
init files are only searched for in that directory, being considered as
part of the program and not as user customization. Since the directory
is also in the list of directories searched for init files loaded by the
‘--init-file’ option, those init files can also be loaded as regular
user specified init files.
Additional directories may be prepended to the list with the
‘--conf-dir’ option (*note (texinfo)Invoking texi2any::).
File: texi2any_api.info, Node: Init File Basics, Next: Simple formatting customization, Prev: Loading Init Files, Up: Top
3 Init File Basics
******************
Init files are written in Perl, and by convention have extension ‘.init’
or ‘.pm’. Several init files are included in the Texinfo distribution,
and can serve as a good model for writing your own. Another example is
the ‘Texinfo::Convert::HTML’ module which implements almost all the
Texinfo HTML function described in this manual for the conversion to
HTML(1). In ‘Texinfo::Convert::HTML’ the API may not be followed
strictly for performance reasons, in that case there should always be a
‘API info:’ comment which shows what the API conformant code should be.
The Licenses conditions of the diverse files used as example should be
taken into account when reusing code.
* Menu:
* Init File Namespace::
* Managing Customization Variables::
* Init File Loading Error Reporting::
---------- Footnotes ----------
(1) The ‘Texinfo::Convert::HTML’ module also implements the HTML
converter which go through the tree and call user defined functions.
File: texi2any_api.info, Node: Init File Namespace, Next: Managing Customization Variables, Up: Init File Basics
3.1 Init File Namespace
=======================
Initialization file are loaded from the main program in the
‘Texinfo::Config’ namespace. This means that the namespace of the main
program and the namespace of initialization files are distinct, which
minimizes the chance of a name clash.
It is possible to start init files with:
package Texinfo::Config;
It is not required, but it may help some debugging tools determine in
which namespace the code is run.
In the ‘Texinfo::Config’ namespace, the functions names beginning
with ‘texinfo_’, ‘GNUT_’ and ‘_GNUT_’ are reserved. User defined
functions in init files should never begin with those prefixes.
The HTML converter is not available directly in the init files
namespace, instead it is passed to functions defined in init files that
are registered as functions to be called from the converter. *Note User
Defined Functions::.
File: texi2any_api.info, Node: Managing Customization Variables, Next: Init File Loading Error Reporting, Prev: Init File Namespace, Up: Init File Basics
3.2 Managing Customization Variables
====================================
The basic operations on customization variables are to set and retrieve
their values. New variables can also be added.
The customization variables also valid in the main program out of the
HTML converter are handled differently if they are strings or arrays.
Conversely, customization variables only relevant for the conversion
phase set in the main program are always set like string variables, in
particular by associating array or hash references to customization
variables.
This section describes customization variables set in the main
program. These variables are in general passed to converters. It is
also possible to set customization variables in the converters only, not
in the main program. This is explained later on (*note Conversion
Customization Variables::).
* Menu:
* Setting Main Program String Variables::
* Modifying Main Program Array Variables::
* Setting Converter Variables in Main Program::
* Getting Main Program Variables Values::
* Adding Customization Variables::
File: texi2any_api.info, Node: Setting Main Program String Variables, Next: Modifying Main Program Array Variables, Up: Managing Customization Variables
3.2.1 Setting Main Program String Variables
-------------------------------------------
To set the value of a string customization variable from an
initialization file, use ‘texinfo_set_from_init_file’:
-- Function: texinfo_set_from_init_file ($variable_name,
$variable_value)
$VARIABLE_NAME is a string containing the name of the variable you
want to set, and $VARIABLE_VALUE is the value to which you want to
set it. $VARIABLE_VALUE may be ‘undef’.
For example,
texinfo_set_from_init_file('documentlanguage', 'fr');
overrides the ‘@documentlanguage’ from the document. It would be
overridden by ‘--document-language’ on the command line. Another
example:
texinfo_set_from_init_file('SPLIT', 'chapter');
overrides the default splitting of the document. It would be overridden
by ‘--split’ on the command line.
A final example:
texinfo_set_from_init_file('NO_CSS', 1);
overrides the default value for ‘NO_CSS’. It would be overridden by
‘--set-init-variable NO_CSS=1’ on the command line.
Setting the output format cannot be done by setting the customization
variable ‘TEXINFO_OUTPUT_FORMAT’. This customization variable sets the
output format in the main program, but not from init files as additional
code needs to be run. Instead, the ‘texinfo_set_format_from_init_file’
function should be used:
-- Function: texinfo_set_format_from_init_file ($output_format)
$OUTPUT_FORMAT is the output format; sets the output format,
without overriding formats set from the command line.
Any output format can be set, but since only HTML can be customized,
the main use of ‘texinfo_set_format_from_init_file’ is to set the format
to ‘html’, such that HTML is generated instead of Info in the default
case.
For the customization variables associated with @-commands, see *note
(texinfo)Customization Variables for @-Commands::. For the
customization variables associated with command line options, see *note
(texinfo)Customization Variables and Options::.
File: texi2any_api.info, Node: Modifying Main Program Array Variables, Next: Setting Converter Variables in Main Program, Prev: Setting Main Program String Variables, Up: Managing Customization Variables
3.2.2 Modifying Main Program Array Variables
--------------------------------------------
Warning: The main program customization variables associated with
arrays are not documented.
Customization variables for the main program associated with an array
of values are handled differently. Two functions can be used in init
files, ‘texinfo_add_to_option_list’ to add values to the array and
‘texinfo_remove_from_option_list’ to remove values from the array
associated with the customization variable:
-- Function: texinfo_add_to_option_list ($variable_name,
$variable_values_array_reference)
-- Function: texinfo_remove_from_option_list ($variable_name,
$variable_values_array_reference)
$VARIABLE_NAME is the name of the variable; the values in the array
reference $VARIABLE_VALUES_ARRAY_REFERENCE are added to the list
associated with the variable with ‘texinfo_add_to_option_list’, and
removed with ‘texinfo_remove_from_option_list’.
File: texi2any_api.info, Node: Setting Converter Variables in Main Program, Next: Getting Main Program Variables Values, Prev: Modifying Main Program Array Variables, Up: Managing Customization Variables
3.2.3 Setting Converter Variables in Main Program
-------------------------------------------------
Array and hash references customization variables values relevant in
converters only (not in main program, but in the HTML converter) can be
set through the main program in init files. These variables cannot be
set on the command-line. They are documented in the customization
documentation, not in the main Texinfo manual. Such arrays or hashes
references can be passed through ‘texinfo_set_from_init_file’. For
example:
my @SECTION_BUTTONS =
(
\&singular_banner,
'Back', 'Forward', 'FastBack', 'FastForward',
'Up', 'Top', 'Contents', 'Index', 'About'
);
texinfo_set_from_init_file ('SECTION_BUTTONS', \@SECTION_BUTTONS);
File: texi2any_api.info, Node: Getting Main Program Variables Values, Next: Adding Customization Variables, Prev: Setting Converter Variables in Main Program, Up: Managing Customization Variables
3.2.4 Getting Main Program Variables Values
-------------------------------------------
To get the value of a variable, the function is ‘texinfo_get_conf’:
-- Function: texinfo_get_conf ($variable_name)
$VARIABLE_NAME is the name of the variable; its value (possibly
‘undef’) is returned.
For example:
if (texinfo_get_conf('footnotestyle') eq 'separate') { ... }
File: texi2any_api.info, Node: Adding Customization Variables, Prev: Getting Main Program Variables Values, Up: Managing Customization Variables
3.2.5 Adding Customization Variables
------------------------------------
Trying to set a customization variable that is not known as a valid
customization variable in ‘texi2any’ is an error. It is possible,
however, to add new customization variables from init files. To add a
customization variable, the function is
‘texinfo_add_valid_customization_option’:
-- Function: texinfo_add_valid_customization_option ($variable_name)
$VARIABLE_NAME is added as a valid customization variable name.
The variable value, if set, should also be available in the
converters and therefore in the init file functions registered and
called from the converters.
File: texi2any_api.info, Node: Init File Loading Error Reporting, Prev: Managing Customization Variables, Up: Init File Basics
3.3 Init File Loading Error Reporting
=====================================
If an error or a warning should be emitted when loading an init file,
before the conversion, use ‘texinfo_register_init_loading_error’ for an
error and ‘texinfo_register_init_loading_warning’ for a warning.
-- Function: texinfo_register_init_loading_error ($message)
-- Function: texinfo_register_init_loading_warning ($message)
Cause an error message or a warning message based on $MESSAGE to be
output, taking into account options related to error reporting such
as ‘--force’ or ‘--no-warn’.
Errors or warning emitted from user defined functions should use the
converter (*note Error Reporting in User Defined Functions::).
File: texi2any_api.info, Node: Simple formatting customization, Next: Simple headers customizations, Prev: Init File Basics, Up: Top
4 Simple formatting customization
*********************************
Some change in output formatting can be specified with simple code, not
very different from simple textual configuration information.
* Menu:
* Init File Expansion Contexts::
* Simple Customization for Commands Without Arguments::
* Simple Customization for Simple Commands with Braces::
* Simple Customization of Accent Commands::
* Simple Customization of Containers::
* Simple Customization of CSS::
File: texi2any_api.info, Node: Init File Expansion Contexts, Next: Simple Customization for Commands Without Arguments, Up: Simple formatting customization
4.1 Init File Expansion Contexts: Normal, Preformatted, Code, String, Math
==========================================================================
There are five expansion contexts of interest:
_normal context_
Paragraphs, index entries, tables, ...
_preformatted context_
When spaces between words are kept. For example, within the
‘@display’ (*note (texinfo)@display::) and ‘@example’ environments
(*note (texinfo)@example::), and in menu comments. The
preformatted regions are usually rendered using ‘<pre>’ elements in
HTML.
_code context_
When quotes and minus are kept. In particular ‘---’, ‘``’ and
other similar constructs are not converted to dash and quote
special characters. For example, in ‘@code’ or ‘@option’ commands
(*note (texinfo)Useful Highlighting::).
_math context_
Math (*note ‘@math’: (texinfo)math.). Code or preformatted
specifications are often used for math too. In those cases, there
is no way to separately specify the formatting in math context.
_string context_
When rendering strings without formatting elements, for example in
titles. The string context allows for limited formatting,
typically without any element when producing HTML or XML, so the
value can be used in an attribute. XML entities can be used in
strings.
It is worth mentioning that in some cases, in particular for file
names, plain text can also be used in conversion. There is no
associated context in the converter, so the conversion to plain text is
usually performed by converting a Texinfo elements tree outside of the
main conversion flow.
File: texi2any_api.info, Node: Simple Customization for Commands Without Arguments, Next: Simple Customization for Simple Commands with Braces, Prev: Init File Expansion Contexts, Up: Simple formatting customization
4.2 Simple Customization for Commands Without Arguments
=======================================================
These commands include those whose names are a single nonletter
character, such as ‘@@’, and those with a normal alphabetic name but
whose braces should be empty, such as ‘@TeX{}’ and ‘@AA{}’.
To change the formatting of a command, the functions is
‘texinfo_register_no_arg_command_formatting’:
-- Function: texinfo_register_no_arg_command_formatting ($command_name,
$context, $text, $html_element, $translated_string_converted,
$translated_string_to_convert)
$COMMAND_NAME is the @-command name, without the leading @.
$CONTEXT is ‘normal’, ‘preformatted’ or ‘string’. There is no
separate math context, ‘preformatted’ should be used for math
context. *Note Init File Expansion Contexts::. If $CONTEXT is
‘undef’, the ‘normal’ context is assumed.
The remaining arguments determine the formatting. If $TEXT is set,
the corresponding text is output when the @-command is formatted.
$TEXT can contain HTML elements if needed. If $HTML_ELEMENT is
set, the text is enclosed between the $HTML_ELEMENT element opening
and the element closing. If $TRANSLATED_STRING_CONVERTED is set,
the corresponding text is translated when the document language
changes and used as text. $TRANSLATED_STRING_CONVERTED should
already be HTML. If $TRANSLATED_STRING_TO_CONVERT is set, the
corresponding text is translated when the document language changes
and converted from Texinfo code to HTML. Since the conversion is
done in the appropriate context, $TRANSLATED_STRING_TO_CONVERT
should only be set for the ‘normal’ context. *Note
(texi2any_internals)Texinfo::Translations METHODS::.
It is not required to set values for all the contexts. If
preformatted context output is not set, normal context output is used.
If string context output is not set, preformatted context output is
used.
For example, if you want ‘­’ to be output for ‘@-’ in normal,
preformatted (and math) and string context, call
texinfo_register_no_arg_command_formatting('-', undef, '­');
If you want ‘<small>...</small>’ to be output for ‘@enddots’ in
normal context and ‘...’ to be output in other contexts, call
texinfo_register_no_arg_command_formatting('enddots',
'normal', '...', 'small');
texinfo_register_no_arg_command_formatting('enddots',
'preformatted', '...');
If you want ‘error-->’ to be used for ‘@error’ in every context,
with a translation when the document language changes, call
texinfo_register_no_arg_command_formatting('error', undef, undef, undef,
'error-->');
If you want ‘is the *same* as’ to be used for ‘@equiv’, translated
when the document language changes, and converted from Texinfo to HTML
in the context of the translation, call
texinfo_register_no_arg_command_formatting('equiv', undef, undef, undef,
undef, 'is the @strong{same} as');
*Note Translated Strings Customization:: for customization of
translated strings.
File: texi2any_api.info, Node: Simple Customization for Simple Commands with Braces, Next: Simple Customization of Accent Commands, Prev: Simple Customization for Commands Without Arguments, Up: Simple formatting customization
4.3 Simple Customization for Simple Commands with Braces
========================================================
The formatting of the output produced by "indicator" and font commands
(e.g., ‘@code’, ‘@t’), and other simple commands with arguments (e.g.,
‘@asis’, ‘@clicksequence’, ‘@sup’, ‘@verb’) can be changed with
‘texinfo_register_style_command_formatting’:
-- Function: texinfo_register_style_command_formatting ($command_name,
$html_element, $in_quotes, $context)
$COMMAND_NAME is the @-command name, without the leading @.
$CONTEXT is ‘normal’, ‘preformatted’ or ‘string’. There is no
separate math context, ‘preformatted’ should be used for math
context. *Note Init File Expansion Contexts::. If $CONTEXT is
‘undef’, the ‘normal’ context is assumed.
If $HTML_ELEMENT is set, the argument is enclosed between the
$HTML_ELEMENT element opening and the element closing.
$HTML_ELEMENT is always ignored in ‘string’ context. If $IN_QUOTES
is true, the result is enclosed in quotes associated with
customization variables ‘OPEN_QUOTE_SYMBOL’ and
‘CLOSE_QUOTE_SYMBOL’.
If $HTML_ELEMENT is undefined and $IN_QUOTES is not set, the
formatted argument is output as is.
For example, to set ‘@sansserif{argument}’ to be formatted as
‘<code>ARGUMENT</code>’ in normal and preformatted context, and as a
quoted string in string context, use:
texinfo_register_style_command_formatting('sansserif', 'code', 0,
'normal');
texinfo_register_style_command_formatting('sansserif', 'code', 0,
'preformatted');
texinfo_register_style_command_formatting('sansserif', undef, 1,
'string');
To output the formatted argument of ‘@t’ as is:
foreach my $context ('normal', 'example', string') {
texinfo_register_style_command_formatting ('t', undef,
undef, $context);
}
File: texi2any_api.info, Node: Simple Customization of Accent Commands, Next: Simple Customization of Containers, Prev: Simple Customization for Simple Commands with Braces, Up: Simple formatting customization
4.4 Simple Customization of Accent Commands
===========================================
The formatting of accent commands (‘@'’, ‘@ringaccent’, ‘@dotless’) can
be customized with ‘USE_NUMERIC_ENTITY’. It is also possible to change
how accented commands are converted to named entities. The accent named
entities are obtained by combining a letter to be accented, such as ‘e’
and a postfix based on the accent command name, for example ‘acute’ for
the acute accent ‘@'’. For example, ‘@'e’ is converted to the
‘é’ named entity in the default case.
The association of accent @-command and named entity postfix and the
list of letters that can be prepended can be changed with
‘texinfo_register_accent_command_formatting’:
-- Function: texinfo_register_accent_command_formatting
($accent_command_name, $entity_postfix, $letters)
$ACCENT_COMMAND_NAME is a Texinfo accent formatting @-command name,
$ENTITY_POSTFIX is a string corresponding to the accent command
that is postpended to the letter accent argument. $LETTERS is a
string listing the letters that can be combined with the
$ENTITY_POSTFIX. If $ENTITY_POSTFIX or $LETTERS is an empty
string, numeric entities are used instead of named entities.
For example, with the following code, ‘@dotless{i}’ should be
converted to ‘ı’, and ‘@dotless{j}’ to ‘&jnodot;’. Other letters
than ‘i’ and ‘j’ in argument of ‘@dotless’ should not be combined into a
named entity with that example.
texinfo_register_accent_command_formatting('dotless', 'nodot', 'ij');
File: texi2any_api.info, Node: Simple Customization of Containers, Next: Simple Customization of CSS, Prev: Simple Customization of Accent Commands, Up: Simple formatting customization
4.5 Simple Customization of Containers
======================================
Texinfo tree elements that are not text container nor directly
associated with an @-command can have information set on their
formatting. The first piece of information is whether their contents
should be considered in code context (*note Init File Expansion
Contexts::). The other piece of information is the type of preformatted
environment they are, analogous with the @-command names of ‘@example’
or ‘@display’(1).
The function used is ‘texinfo_register_type_format_info’:
-- Function: texinfo_register_type_format_info ($type, $code_type,
$pre_class_type)
$TYPE is the type of the container. If $CODE_TYPE is set, the
container contents are assumed to be in code context. *Note Init
File Expansion Contexts::. If $PRE_CLASS_TYPE is set, the HTML
‘<pre>’ elements class attribute are based on $PRE_CLASS_TYPE, if
there are such HTML elements output for preformatted content of
$TYPE containers.
For example, to set content appearing in-between node links in
‘@menu’, which is in the ‘menu_comment’ container type to be formatted
in a code context, with preformatted type ‘menu-between’, use:
texinfo_register_type_format_info('menu_comment', 1, 'menu-between');
*Note (texi2any_internals)Texinfo::Parser Types of container
elements::, for a description of container types.
---------- Footnotes ----------
(1) Note that setting the type of preformatted environment does not
make sure that there are preformatted containers used for the formatting
of their contents instead of paragraph containers, since this is
determined in the very first step of parsing the Texinfo code, which
cannot be customized.
File: texi2any_api.info, Node: Simple Customization of CSS, Prev: Simple Customization of Containers, Up: Simple formatting customization
4.6 Simple Customization of CSS Rules and Imports
=================================================
CSS in HTML output can already be modified with command line options
(*note (texinfo)HTML CSS::) and customization options such as ‘NO_CSS’
and ‘INLINE_CSS_STYLE’.
Information on static CSS data used in conversion and some control
over the CSS output is possible. The information is about CSS rules
lines and CSS import lines obtained from parsing ‘--css-include=FILE’
files, as described in *note (texinfo)HTML CSS::, and CSS style rules
associated with HTML elements and class attributes used in the
conversion to HTML. The CSS style rules selectors are, classically,
‘ELEMENT.CLASS’ strings with ELEMENT an HTML element and CLASS an
attribute class associated to that element.
The function used are ‘css_get_info’ to get information and
‘css_add_info’ to modify:
-- Function: $CONVERTER->css_get_info ($specification, $css_info)
-- Function: $CONVERTER->css_add_info ($specification, $css_info,
$css_style)
Those functions can only be used on a converter $CONVERTER, from
functions registered and called with a converter. $SPECIFICATION
is ‘'rules'’ to get information on or set information for CSS rules
lines and ‘'imports'’ to get information on or set information for
CSS import lines. Any other value for $SPECIFICATION corresponds
to CSS style rules associated with HTML elements and class
attributes selectors.
With ‘css_get_info’, if $SPECIFICATION is set to ‘'rules'’ or
‘'imports'’, the corresponding arrays are returned. Otherwise, if
$CSS_INFO is ‘undef’, a hash reference with all the CSS rules
selector as keys and the corresponding rules as values is returned.
If $CSS_INFO is defined, it is considered to be a CSS rule selector
and the corresponding CSS style is returned, or ‘undef’ if not
found.
With ‘css_add_info’, $CSS_INFO is an additional entry added to CSS
rules lines if $SPECIFICATION is set to ‘'rules'’ or an additional
entry added to CSS import lines if $SPECIFICATION is set to
‘'imports'’. Otherwise, $CSS_INFO is a CSS rule selector and the
associated style rule is set to $CSS_STYLE.
Some examples of use:
my @all_included_rules = $converter->css_get_info('rules');
my $all_default_selector_styles = $converter->css_get_info('styles');
my $titlefont_header_style = $converter->css_get_info('styles',
'h1.titlefont');
$converter->css_add_info('styles', 'h1.titlefont', 'text-align:center');
$converter->css_add_info('imports', "\@import \"special.css\";\n");
Note that the CSS selectors and associated style rules that can be
accessed and modified will not necessarily end up in the HTML output.
They are output only if the HTML element and class corresponding to a
selector is seen in the document. *Note Customizing CSS::.
How to run code during the conversion process is described later
(*note Init File Calling at Different Stages::). The simplest way to
use the ‘css_add_info’ function would be to use a function registered
for the ‘structure’ stage:
sub my_function_set_some_css {
my $converter = shift;
$converter->css_add_info('styles', 'h1.titlefont',
'text-align:center');
# ... more calls to $converter->css_add_info();
}
texinfo_register_handler('structure', \&my_function_set_some_css);
*Note Customizing CSS:: for even more control on CSS lines output.
File: texi2any_api.info, Node: Simple headers customizations, Next: User Defined Functions, Prev: Simple formatting customization, Up: Top
5 Simple headers customizations
*******************************
Some customization of navigation panels appearing in header and footers
in output can be specified with simple code. To explain how navigation
panels are customized, we first describe how the document is organized
and which directions are available as the directions is the basis for
navigation panel customization.
* Menu:
* Output Element Units::
* Directions::
* Direction Strings Customization::
* Simple Navigation Panel Customization::
File: texi2any_api.info, Node: Output Element Units, Next: Directions, Up: Simple headers customizations
5.1 Output Element Units
========================
We will call the main unit of output documents a document “unit”, or a
Texinfo tree element “unit”. An element unit's association with output
files is determined by the split options (*note (texinfo)Splitting
Output::). This section describes precisely how these output units
work, with details for customization.
The output elements are:
_Normal document units_
These are normal sections and nodes. Usually a node is associated
with a following sectioning command, while a sectioning command is
associated with a previous node; they both together make up the
element unit. Either the node or the sectioning command is
considered to be the main element component, depending on the
values of the customization variables ‘USE_NODES’ (*note
(texinfo)HTML Customization Variables::).
For example, when generating Info, the nodes are the units; when
generating HTML, either case may happen (*note (texinfo)Two
Paths::).
_Top element_
The top element is the highest element unit in the document
structure. If the document has an ‘@top’ section (*note
(texinfo)@top Command::), it is the element associated with that
section; otherwise, it is the element associated with the
document's ‘@node Top’ (*note (texinfo)The Top Node::). If there
is no ‘@node Top’, the first element in the document is the top
element. The Top element is also a normal element.
_Miscellaneous elements_
The remaining element units are associated with different files if
the document is split, and also if ‘MONOLITHIC’ is not set. There
are four such miscellaneous elements, also called special elements:
1. Table of contents
2. Short table of contents, also called Overview
3. Footnotes page
4. About page
More details:
• The _Table of contents_ should only be formatted if
‘@contents’ is present in the document.
• Similarly the _Short table of contents_ should only appear if
‘@shortcontents’ or ‘@summarycontents’ is present.
• The customization variables ‘contents’ and ‘shortcontents’ may
be set to trigger the output of the respective elements.
• If ‘CONTENTS_OUTPUT_LOCATION’ is set to ‘separate_element’,
the _Table of contents_ and _Short table of contents_ elements
are separate (*note Contents and Short Table of Contents
Customization::). Otherwise the _Table of contents_ and
_Short table of contents_ elements are directly included
within the document, at locations depending on the specific
‘CONTENTS_OUTPUT_LOCATION’ value.
• When generating HTML, the _Footnotes page_ should only be
present if the footnotes appear on a separate page (*note
(texinfo)Footnote Styles::). However, a footnote element is
present if the document is not split.
• The _About page_ shouldn't be present for documents consisting
of only one sectioning element, or for monolithic documents
without navigation information, or if ‘DO_ABOUT’ is not set.
It is common not to have anything but normal element units,
especially in case of monolithic output.
The main component of elements is sections if ‘USE_NODES’ is 0;
conversely, the main component is nodes if ‘USE_NODES’ is set.
When sections are the main components of element units, "isolated"
nodes not directly associated with a sectioning command are associated
with the following sectioning command, while sectioning commands without
nodes constitute element units. Conversely, when nodes are the main
components of elements, isolated sections not associated with nodes are
associated with the previous node, and isolated nodes are element units.
File: texi2any_api.info, Node: Directions, Next: Direction Strings Customization, Prev: Output Element Units, Up: Simple headers customizations
5.2 Directions
==============
A variety of data items, called “element directions”, are associated
with element units. They may be used in the formatting functions,
and/or associated with a button (*note Simple Navigation Panel
Customization::).
Each element direction has a name and a reference to the element unit
they point to, when such an element exists. The element is either a
global element unit (for example, the Top element) or relative to the
current element unit (for example, the next element unit). Such
relative elements are determined with respect to the document structure
defined by the section structuring commands (‘@chapter’,
‘@unnumbered’...) or by the nodes if the node pointers are specified on
‘@node’ lines or in menus (*note (texinfo)Two Paths::).
Here is the list of global element units directions:
_‘ ’_
An empty button.
_Top_
Top element.
_About_
About (help) page.
_Contents_
Table of contents.
_Overview_
Overview: short table of contents.
_Footnotes_
Corresponds to the ‘Footnotes’ element (*note Output Element
Units::).
_Index_
The first element unit with ‘@printindex’.
Here is the list of relative element units directions:
_This_
The current element unit.
_Forward_
Next element unit in reading order.
_First_
First element unit in reading order.
_Last_
Last element unit in reading order.
_Back_
Previous element unit in reading order.
_FastForward_
Next chapter element unit.
_FastBack_
Beginning of this chapter, or previous chapter if the element is a
chapter.
_Next_
Next section element unit at the same level.
_Prev_
Previous section element unit at the same level.
_Up_
Up section.
_SectionNext_
Next element unit in section reading order.
_SectionPrev_
Previous element unit in section reading order.
_SectionUp_
Up in section reading order.
_NodeNext_
Next node element unit.
_NodeForward_
Next node element unit in node reading order.
_NodeBack_
Previous node element unit in node reading order.
_NodePrev_
Previous node element unit.
_NodeUp_
Up node element unit.
Relative direction elements are each associated to a variant, with
‘FirstInFile’ prepended, which points to the direction relative to the
first element in file. For example, ‘FirstInFileNodeNext’ is the next
node element relative to the first element in file. The ‘FirstInFile’
directions are usually used in footers.
* Menu:
* Element Direction Information Type::
* Direction Strings::
File: texi2any_api.info, Node: Element Direction Information Type, Next: Direction Strings, Up: Directions
5.2.1 Element Direction Information Type
----------------------------------------
The element directions also have types of information associated, which
are in general set dynamically depending on the current element unit,
for instance on the element unit whose navigation panel is being
formatted:
‘href’
A string that can be used as an href attribute linking to the
element unit corresponding to the direction.
‘string’
A string representing the direction that can be used in context
where only entities are available (attributes). *Note Init File
Expansion Contexts::.
‘text’
A string representing the direction to be used in contexts with
HTML elements (preformatted and normal contexts). *Note Init File
Expansion Contexts::.
‘tree’
A Texinfo tree element representing the direction.
‘target’
A string representing the target of the direction, typically used
as id attribute in the element unit corresponding to the direction,
and in href attribute.
‘node’
Same as ‘text’, but selecting the node associated with the element
unit direction in priority.
‘section’
Same as ‘text’, but selecting the sectioning command associated
with the element unit direction in priority.
‘text’, ‘tree’ and ‘string’ also have a variant with ‘_nonumber’
prepended, such as ‘text_nonumber’ without sectioning command number in
the representation.
File: texi2any_api.info, Node: Direction Strings, Prev: Element Direction Information Type, Up: Directions
5.2.2 Direction Strings
-----------------------
Directions have strings associated, corresponding to their names,
description or specific HTML keywords:
‘accesskey’
Direction ‘accesskey’ attribute used in navigation.
‘button’
Direction short name typically used for buttons.
‘description’
Description of the direction.
‘example’
Section number corresponding to the example used in the About
special element text.
‘rel’
Direction ‘rel’ attribute used in navigation.
‘text’
Direction text in a few words.
‘button’, ‘description’ and ‘text’ are translated based on the
document language.
The ‘FirstInFile’ direction variants are associated with the same
strings as the direction they are prepended to (*note FirstInFile
direction variant::). For example ‘FirstInFileNodeNext’ is associated
with the same strings as ‘NodeNext’.
File: texi2any_api.info, Node: Direction Strings Customization, Next: Simple Navigation Panel Customization, Prev: Directions, Up: Simple headers customizations
5.3 Direction Strings Customization
===================================
The direction strings can be customized with
‘texinfo_register_direction_string_info’:
-- Function: texinfo_register_direction_string_info ($direction, $type,
$converted_string, $string_to_convert, $context)
$DIRECTION is a direction (*note Directions::), $TYPE is the type
of string (*note Direction Strings::). The other arguments are
optional. $CONTEXT is ‘normal’ or ‘string’. *Note Init File
Expansion Contexts::. If $context is ‘undef’, the ‘normal’ context
is assumed.
$CONVERTED_STRING is the string, already converted to HTML that is
used for the specified context. If the ‘normal’ context
$CONVERTED_STRING only is specified, the same string will be used
for the ‘string’ context.
Alternatively, $STRING_TO_CONVERT can be specified to set the
string to the corresponding Texinfo code after translation and
conversion to HTML. In that case, the context is ignored, as it
will be set at the time of the conversion.
$STRING_TO_CONVERT is ignored for special strings that do not need
to be translated and cannot contain Texinfo @-commands
(‘accesskey’, ‘rel’ and ‘example’). $STRING_TO_CONVERT is also
ignored if $CONVERTED_STRING is set for any context.
File: texi2any_api.info, Node: Simple Navigation Panel Customization, Prev: Direction Strings Customization, Up: Simple headers customizations
5.4 Simple Navigation Panel Customization
=========================================
The “navigation panel” is the line of links (and labels) that typically
appears at the top of each node, so that users can easily get to the
next node, the table of contents, and so on. It can be customized
extensively.
The customization variables ‘VERTICAL_HEAD_NAVIGATION’, ‘ICONS’,
‘HEADERS’, ‘HEADER_IN_TABLE’, ‘USE_ACCESSKEY’, ‘USE_REL_REV’ and
‘WORDS_IN_PAGE’ may be used to change the navigation panel formatting.
*Note (texinfo)HTML Customization Variables::.
Setting ‘ICONS’ is necessary but not sufficient to get icons for
direction buttons since no button image is specified in the default
case. The ‘ACTIVE_ICONS’ and ‘PASSIVE_ICONS’ customization variables
need to be set in addition:
‘ACTIVE_ICONS’
‘PASSIVE_ICONS’
Hash references with element directions as key (*note Directions::)
and button image icons as values. ‘ACTIVE_ICONS’ is used for
directions actually linking to an element, and ‘PASSIVE_ICONS’ are
used if there is no element to link to. The button images are
interpreted as URLs.
Several arrays and hashes enable even more precise control over the
navigation panel buttons and their display. They can be set as
customization variables with ‘texinfo_set_from_init_file’. *Note
Setting Main Program String Variables::.
The following customization variables arrays determine the buttons
present in the various navigation panels:
‘SECTION_BUTTONS’
Specifies the navigation panel buttons present at the beginning of
sectioning elements in the case of section navigation being enabled
or if split at nodes. Specifies the navigation panel buttons
present at the page header if split at section and there is no
section navigation.
‘SECTION_FOOTER_BUTTONS’
‘CHAPTER_FOOTER_BUTTONS’
‘NODE_FOOTER_BUTTONS’
These arrays specify the navigation panel buttons present in the
page footer when the output is split at sections, chapters or
nodes, respectively.
‘CHAPTER_BUTTONS’
Specifies the buttons appearing at the page header if split at
chapters and there is no section navigation.
‘MISC_BUTTONS’
Specifies the buttons appearing at the beginning of special
elements and, if the output is split, at the end of such elements.
‘LINKS_BUTTONS’
Used for ‘<link>’ elements if they are output in the headers.
‘TOP_BUTTONS’
Specifies the buttons used in the top element (*note Output Element
Units::).
Each array specifies which buttons are included, and how they are
displayed. Each array element is associated with a button of the
navigation panel from left to right. The meaning of the array element
values is the following:
_string with an element unit direction_
If icons are not used, the button is a link to the corresponding
element whose text is the ‘text’ direction string (*note Direction
Strings::), surrounded by ‘[’ and ‘]’. If the element direction is
‘ ’, the ‘[’ and ‘]’ are omitted.
If icons are used, the button is an image whose file is determined
by the value associated with the element direction in the
‘ACTIVE_ICONS’ variable hash if the link leads to an element, or in
the ‘PASSIVE_ICONS’ variable hash if there is no element to link
to. If there is a link to the element, the icon links to that
element. The button name and button description are given as HTML
attributes to have a textual description of the icon. The
corresponding strings correspond to the ‘button’ direction string
for the button name and the ‘description’ for a more detailed
description (*note Direction Strings::).
_function reference_
The function is called with one boolean argument, true if the
navigation panel should be vertical. Should return the formatted
button text.
_scalar reference_
The scalar value is printed.
_array reference of length 2_
Here, the first array element should be a an element direction. A
link to the element unit associated with the element direction is
generated. The text of the link depends on the second array
element.
_reference to a text string_
In that case, the corresponding text is used.
_reference to a function_
The functions is called with two arguments, the converter
object and the element direction and should return two
scalars, the link href and text and a boolean set if a
delimiter is needed after that button.
_text string_
The text string is interpreted as an element direction
information type and the corresponding text is used for the
link. *Note Element Direction Information Type::.
For example, if the button array element is
[ 'Next', 'node' ]
Then the button will be a link to the next section with text
based on the name of the node associated with the next section
element unit.
If the customization variable ‘USE_ACCESSKEY’ is set, the ‘accesskey’
attribute is used in navigation. The ‘accesskey’ direction string is
then used for the ‘accesskey’ attributes (*note Direction Strings::).
Similarly, if the ‘USE_REL_REV’ customization variable is set, the
‘rel’ attribute is used in navigation. In that case the ‘rel’ direction
string is used for the ‘rel’ attribute (*note Direction Strings::).
File: texi2any_api.info, Node: User Defined Functions, Next: Customizing Output-Related Names, Prev: Simple headers customizations, Up: Top
6 User Defined Functions
************************
Getting beyond the customization described previously requires writing
some functions and registering those functions such that they are called
for the conversion. This allows dynamic redefinition of functions used
to produce output.
* Menu:
* User Defined Functions are Registered::
* Converter Object and Conversion Functions::
* Texinfo Tree Elements in User Defined Functions::
* Encoding and Decoding File Path Strings::
* Setting the Context for Conversion::
* Conversion Customization Variables::
* Conversion General Information::
File: texi2any_api.info, Node: User Defined Functions are Registered, Next: Converter Object and Conversion Functions, Up: User Defined Functions
6.1 User Defined Functions are Registered
=========================================
User defined functions are always passed as a code reference to a
registering function, together with a string describing what the
function formats. In the following made up example,
‘my_formatting_function’ is passed as a function reference
‘\&my_formatting_function’ to the registering function
‘texinfo_register_command_formatting’, with the string specifying the
formatting done by the function being ‘format_thing’:
sub my_formatting_function {
my $arg1 = shift;
my $arg2 = shift;
# prepare $formatted_text
...
return $formatted_text;
}
texinfo_register_command_formatting ('format_thing', \&my_formatting_function);
As such functions are defined by a reference name associated with a
string we will always use the string in function prototypes. For the
function arguments we will use ‘\@array’ to indicate a reference to an
array (a.k.a. list, in Perl terminology), ‘\%hash’ for a reference to a
hash and ‘\&function’ for a reference on a function.
To illustrate these conventions, here is the prototype for the
function associated with ‘format_thing’:
-- Function Reference: $TEXT format_thing ($ARG1, \@ARG2)
A function reference associated with ‘format_thing’ has a first
argument $ARG1, a second argument a reference to an array \@ARG2,
and returns the formatted text $TEXT.
File: texi2any_api.info, Node: Converter Object and Conversion Functions, Next: Texinfo Tree Elements in User Defined Functions, Prev: User Defined Functions are Registered, Up: User Defined Functions
6.2 Converter Object and Conversion Functions
=============================================
The first argument of most, if not all user defined function is a
converter object. This object gives access to methods to get
information on the conversion context and to methods useful for the
conversion, both as an HTML converter and as a generic
‘Texinfo::Convert::Converter’ (*note
(texi2any_internals)Texinfo::Convert::Converter Helper methods::). The
converter can also be used for error reporting as it is also a
‘Texinfo::Report’ object (*note (texi2any_internals)Texinfo::Report::),
and for in-document strings translation as it is also a
‘Texinfo::Translations’ object (*note
(texi2any_internals)Texinfo::Translations::). *Note Error Reporting in
User Defined Functions:: on error reporting.
* Menu:
* Texinfo Tree Conversion Functions::
* Error Reporting in User Defined Functions::
File: texi2any_api.info, Node: Texinfo Tree Conversion Functions, Next: Error Reporting in User Defined Functions, Up: Converter Object and Conversion Functions
6.2.1 Texinfo Tree Conversion Functions
---------------------------------------
One important converter method that can be used in user defined
functions is ‘convert_tree’ that convert a Texinfo tree rooted at any
element. There is no reason to use that function often, as the
converter already goes through the tree calling reference functions to
convert the elements, but it can be interesting in some cases.
-- Function: $CONVERTED_TEXT = $CONVERTER->convert_tree (\%ELEMENT,
$EXPLANATION)
\%ELEMENT is a Texinfo tree element. $EXPLANATION is optional, it
is a string explaining why the function was called, to help in case
of debugging. The function returns \%ELEMENT converted.
‘convert_tree’ is suitable when the conversion is in the flow of the
Texinfo tree conversion. Sometime, it is better to ignore the
formatting context of the main conversion, for example for the
formatting of a caption, or the formatting of footnotes texts. Another
special case is the case of tree elements being converted more than
once, even if in the flow of the Texinfo tree conversion, for example if
there are multiple ‘@insertcopying’ in a document. A last special case
arise, with formatting done in advance or out of the main conversion.
This is the case, in practice, for sectioning commands or node commands
which may be formatted as directions in navigation panels, menus or
indices, may appear more than once in the document and be converted more
than once, if language changes, for example.
For such cases, the function is ‘convert_tree_new_formatting_context’
which sets the context appropriately.
‘convert_tree_new_formatting_context’ ultimately calls ‘convert_tree’.
-- Function: $CONVERTED_TEXT =
$CONVERTER->convert_tree_new_formatting_context (\%ELEMENT,
$CONTEXT, $MULTIPLE_PASS, $GLOBAL_CONTEXT,
$BLOCK_COMMAND_NAME)
\%ELEMENT is a Texinfo tree element. $CONTEXT is an optional
string describing the new context to be setup to format out of the
main conversion flow. If not defined, the conversion is done in
the main document flow. $MULTIPLE_PASS is an optional string that
marks that the conversion is done more than once. It should be
unique and suitable for inclusion in targets and identifiers.
$GLOBAL_CONTEXT is an optional string that marks that the
formatting may be done in advance, and can be redone.
$BLOCK_COMMAND_NAME is an optional block command name that is used
to initialized the new context. It can be useful, in particular,
to propagate the topmost block command in the new context.
The function returns \%ELEMENT converted, setting the conversion
context according to the arguments.
*Note Setting the Context for Conversion:: on how to set a specific
context for a Texinfo tree conversion.
File: texi2any_api.info, Node: Error Reporting in User Defined Functions, Prev: Texinfo Tree Conversion Functions, Up: Converter Object and Conversion Functions
6.2.2 Error Reporting in User Defined Functions
-----------------------------------------------
To report an error or a warning in a user defined function, use the
methods of ‘Texinfo::Report’ through a converter object (*note Converter
Object and Conversion Functions::).
To report a warning or an error not specific of an element
conversion, use ‘document_warn’ or ‘document_error’:
-- Function: $CONVERTER->document_error ($text, $converter)
-- Function: $CONVERTER->document_warn ($text, $converter)
Register a document-wide error or warning. $TEXT is the error or
warning message. The $CONVERTER object should be given as the
second argument.
To report a warning or an error in element conversion, use
‘line_warn’ or ‘line_error’
-- Function: $CONVERTER->line_error ($text, $converter, $location_info,
$continuation, $silent)
-- Function: $CONVERTER->line_warn ($text, $converter, $location_info,
$continuation, $silent)
Register a warning or an error. $TEXT is the text of the error or
warning. The $CONVERTER object should be given as the second
argument. The optional $LOCATION_INFO holds the information on the
error or warning location. The $LOCATION_INFO reference on hash
may be obtained from Texinfo elements ‘source_info’ keys.
The optional $CONTINUATION argument, if set, conveys that the
message is a continuation of the previous registered message. The
optional $SILENT argument, if set, suppresses the immediate output
of a message if the ‘DEBUG’ customization variable is set.
In general, registering an error does not stop the processing, in
particular it does not stop the main conversion of the Texinfo tree.
Write initialization files as if the conversion always continued after
registering the error.
*Note (texi2any_internals)Texinfo::Report:: for more on
‘Texinfo::Report’.
File: texi2any_api.info, Node: Texinfo Tree Elements in User Defined Functions, Next: Encoding and Decoding File Path Strings, Prev: Converter Object and Conversion Functions, Up: User Defined Functions
6.3 Texinfo Tree Elements in User Defined Functions
===================================================
Many user defined functions used for formatting have Texinfo tree
elements as arguments. The user defined code should never modify the
tree elements. It is possible to reuse Texinfo tree elements
information, but with a copy. For example, the following is ok:
my @contents = @{$element->{'contents'}};
push @contents, {'text' => ' my added text'};
my $result = $converter->convert_tree({'cmdname' => 'strong',
'contents' => \@contents });
The following is not ok:
push @{$element->{'contents'}}, {'text' => ' my added text'};
In addition to the elements obtained after parsing a Texinfo
document, two elements are added, ‘unit’ type elements that correspond
to the normal document units (*note Output Element Units::), and special
elements with type ‘special_element’ that correspond to added special
elements (*note Output Element Units::). These added elements, as well
as nodes and sectioning elements hold information on the document
structure in the ‘structure’ element hash (*note
(texi2any_internals)Texinfo::Structuring METHODS::).
Normal tree unit elements have a ‘unit_command’ key in the ‘extra’
hash that points to the associated ‘@node’ or sectioning @-command
depending on which of nodes or sectioning commands are the main
components of elements. *Note Output Element Units::.
The following keys of the ‘structure’ hash can be interesting:
‘associated_unit’
For sectioning and ‘@node’ @-command elements. The associated tree
unit element.
‘section_childs’
For sectioning commands elements. The children of the sectioning
element in the sectioning tree.
‘section_level’
The level of the section, taking into account ‘@raisesections’ and
‘@lowersections’. Level 0 corresponds to ‘@top’ or ‘@part’ and
level 1 to ‘@chapter’ level sectioning commands. *Note
(texinfo)Raise/lower sections::.
‘unit_filename’
For tree unit elements. The associated file name.
‘unit_next’
For tree unit elements. The next unit element in document order.
‘unit_prev’
For tree unit elements. The previous unit element in document
order.
Detailed information on the tree elements is available in the Texinfo
Parser documentation, in particular a list of types and of information
in the elements ‘extra’ hash (*note (texi2any_internals)Texinfo::Parser
TEXINFO TREE::).
File: texi2any_api.info, Node: Encoding and Decoding File Path Strings, Next: Setting the Context for Conversion, Prev: Texinfo Tree Elements in User Defined Functions, Up: User Defined Functions
6.4 Encoding and Decoding File Path Strings
===========================================
* Menu:
* Encoding File Path Strings::
* Decoding File Path Strings::
File: texi2any_api.info, Node: Encoding File Path Strings, Next: Decoding File Path Strings, Up: Encoding and Decoding File Path Strings
6.4.1 Encoding File Path Strings
--------------------------------
In general, the strings in the customization functions are character
strings. For most purposes, this is right, and the encoding in output
files is taken care of by the converter. Operations on directories and
file names, however, such as the creation of a directory or the opening
of a file require binary strings.
To encode file names consistently with file name encoding used in the
conversion to HTML, there is a function ‘encoded_output_file_name’:
-- Function: ($ENCODED_NAME, $ENCODING) =
$CONVERTER->encoded_output_file_name ($CHARACTER_STRING_NAME)
Encode $CHARACTER_STRING_NAME in the same way as other file name
are encoded in the converter, based on
‘DOC_ENCODING_FOR_OUTPUT_FILE_NAME’, and
‘LOCALE_OUTPUT_FILE_NAME_ENCODING’ or on input file encoding (*note
(texinfo)Other Customization Variables::). Return the encoded name
and the encoding used to encode the name.
There is also a similar function for the input file names encoding,
‘encoded_input_file_name’, which uses ‘DOC_ENCODING_FOR_INPUT_FILE_NAME’
and ‘LOCALE_INPUT_FILE_NAME_ENCODING’ and is less likely to be useful.
When calling external commands, the command line arguments should
also be encoded. To do similarly with other codes, the customization
variable ‘MESSAGE_ENCODING’ should be used. Already encoded file names
may be used. For example
use Encode qw(encode);
....
my ($encoded_file_path, $encoding)
= $converter->encoded_output_file_name($file_name);
my $fh = open($encoded_file_path);
.....
my $call_start = "command --set '$action' ";
my $encoding = $converter->get_conf('MESSAGE_ENCODING');
if (defined($encoding)) {
$encoded_call_start = encode($encoding, $call_start);
} else {
$encoded_call_start = $call_start;
}
my $encoded_call = $encoded_call_start . $encoded_file_path;
my $call = $call_start . $file_name;
if (system($encoded_call)) {
$converter->document_error($converter,
sprintf(__("command did not succeed: %s"),
$call));
}
File: texi2any_api.info, Node: Decoding File Path Strings, Prev: Encoding File Path Strings, Up: Encoding and Decoding File Path Strings
6.4.2 Decoding File Path Strings
--------------------------------
The binary strings that could be accessed correspond to the
customization variables strings or arrays ‘INCLUDE_DIRECTORIES’,
‘CSS_FILES’, ‘MACRO_EXPAND’ and ‘INTERNAL_LINKS’. If they need to be
decoded into character strings, for example to appear in error messages,
it is possible to use the ‘COMMAND_LINE_ENCODING’ customization variable
value as encoding name to mimic how the decoding of these strings from
the command line is done in the main program and in the converters. For
example:
my $macro_expand_fname = $self->get_conf('MACRO_EXPAND');
my $encoding = $self->get_conf('COMMAND_LINE_ENCODING');
if (defined($encoding)) {
$macro_expand_fname = Encode::decode($encoding, $macro_expand_fname);
}
More information on perl and encodings in perlunifaq
(https://perldoc.perl.org/perlunifaq).
File: texi2any_api.info, Node: Setting the Context for Conversion, Next: Conversion Customization Variables, Prev: Encoding and Decoding File Path Strings, Up: User Defined Functions
6.5 Setting the Context for Conversion
======================================
Special container types are recognized by the converter and can be used
to convert a Texinfo tree in a specific context. Those types cannot
appear in a regular Texinfo tree. They can be the type directly
associated with a text element, or the type of a tree root element.
The types are:
‘_code’
In this container, the conversion is done in a code context *Note
Init File Expansion Contexts::.
‘_converted’
In this container, the texts are considered to be already
formatted. This is more likely to be relevant as the type of a
text element.
‘_string’
In this container, the conversion is done in a string context.
*Note Init File Expansion Contexts::.
These contexts are typically used together with converter conversion
functions (*note Converter Object and Conversion Functions::). For
example:
my @contents = @{$element->{'contents'}};
push @contents, {'text' => ' <code>HTML</code> text ',
'type' => '_converted'};
my $result = $converter->convert_tree({'type' => '_code',
'contents' => \@contents });
There is no context for plain text, but the conversion to plain text
can be achieved by using the ‘Texinfo::Text’ converter (*note
(texi2any_internals)Texinfo::Convert::Text::). For example, to convert
the Texinfo tree element $ELEMENT to plain text:
my $plaintext = Texinfo::Convert::Text::convert_to_text($element,
Texinfo::Convert::Text::copy_options_for_convert_text($converter, 1));
File: texi2any_api.info, Node: Conversion Customization Variables, Next: Conversion General Information, Prev: Setting the Context for Conversion, Up: User Defined Functions
6.6 Setting and Getting Conversion Customization Variables
==========================================================
The customization variables values set during the conversion process may
be different from the main program customization variables. The general
rule is that variables set in the main program, in particular from init
files, are passed to the converter. Some variables, however, only
appear in the converter. Some variables are also set in the converter
based on the main program customization variables. Finally, some
variables should be set or reset during conversion, in particular when
converting the tree representing the Texinfo document, when expanding
the tree element corresponding to @-commands associated with
customization variables (*note (texinfo)Customization Variables for
@-Commands::).
The functions described here should be used in user defined
functions, but should not be used out of functions. Conversely, the
similar functions used to set customization variables from init files
without a converter should not be used in functions, but should be used
out of functions in init files (*note Managing Customization
Variables::).
To get the value of a variable in a converter ‘$converter’, the
function is ‘get_conf’:
-- Function: $CONVERTER->get_conf ($variable_name)
$VARIABLE_NAME is the name of the variable; its value in the
converter $CONVERTER (possibly ‘undef’) is returned.
For example:
my $footnotestyle = $converter->get_conf('footnotestyle');
To set a variable in a converter ‘$converter’, the function is
‘set_conf’:
-- Function: $CONVERTER->set_conf ($variable_name, $variable_value)
$VARIABLE_NAME is the name of the variable; its value in the
converter $CONVERTER is set to $VARIABLE_VALUE. The $VARIABLE_NAME
value will not be overidden if it was set from the command line or
from an init file.
For example:
$converter->set_conf('footnotestyle', 'separate');
Some customization variables, in particular those associated with
@-commands, can be reset to the value they had before starting the
conversion. For example, they are reset in order to obtain their value
before the conversion. Thet are also reset to the value they had before
starting the conversion when their value at the end of the preambule or
at the end of the document is needed, but there are no @-commands at
those locations in the Texinfo manual. If a value set by ‘set_conf’ is
intended to be found when the customization variable value is reset,
‘set_conf’ should be called early. For example, when called from a
user-defined function called at different stage, it should be called in
the ‘setup’ stage (*note Init File Calling at Different Stages::).
The values set in converter with ‘set_conf’ will not override
command-line set customization variables, nor variables set early in
init files. This is the expected behaviour, in particular when the
values are set from the document. In the rare cases when overriding the
customization would be needed, the ‘force_conf’ function can be used:
-- Function: $CONVERTER->force_conf ($variable_name, $variable_value)
$VARIABLE_NAME is the name of the variable; its value in the
converter $CONVERTER is set to $VARIABLE_VALUE, overriding any
previous value.
File: texi2any_api.info, Node: Conversion General Information, Prev: Conversion Customization Variables, Up: User Defined Functions
6.7 Conversion General Information
==================================
Some general information is available from the converter.
To determine if an output format such as ‘html’ or ‘tex’ is expanded
(*note (texinfo)Conditional Commands::), use ‘is_format_expanded’:
-- Function: $IS_FORMAT_EXPANDED = $CONVERTER->is_format_expanded
($FORMAT)
Return true if format $FORMAT is expanded, according to
command-line and init file information.
The main method to get information from the converter is ‘get_info’:
-- Function: $INFO = $CONVERTER->get_info ($ITEM)
Return information on $ITEM.
The available information is about:
‘copying_comment’
Text appearing in ‘@copying’ with all the Texinfo commands put into
comments (*note (texinfo)@copying::).
‘current_filename’
The file name of the current document unit being converted.
‘destination_directory’
Destination directory for the output files. It is common to use
that string in directory or file paths with functions requiring
binary strings. In that case the character string needs to be
encoded. *Note Encoding File Path Strings::.
‘document_name’
Base name of the document. It is common to use that string in in
directory or file paths with functions requiring binary strings.
In that case the character string needs to be encoded. *Note
Encoding File Path Strings::.
‘documentdescription_string’
‘@documentdescription’ argument converted in a string context
(*note (texinfo)@documentdescription::). *Note Init File Expansion
Contexts::.
‘floats’
Information on floats. Gathered from the Texinfo parsing result.
*Note Texinfo::Parser::floats_information:
(texi2any_internals)Texinfo::Parser $float_types =
floats_information($parser).
‘global_commands’
Global commands information. Gathered from the Texinfo parsing
result. *Note Texinfo::Parser::global_commands_information:
(texi2any_internals)Texinfo::Parser $commands =
global_commands_information($parser).
‘index_entries’
Information on indices taking into account merged indices. *Note
Texinfo::Structuring::merge_indices:
(texi2any_internals)Texinfo::Structuring $merged_entries =
merge_indices($index_names).
‘index_entries_by_letter’
Index entries sorted by letter. *Note
Texinfo::Structuring::sort_indices:
(texi2any_internals)Texinfo::Structuring ($index_entries_sorted,
$index_entries_sort_strings) = sort_indices($registrar,
$configuration_information, $merged_index_entries,
$sort_by_letter).
‘indices_information’
Information about defined indices, merged indices and index
entries. *Note Texinfo::Parser::indices_information:
(texi2any_internals)Texinfo::Parser $indices_information =
$parser->indices_information().
‘jslicenses’
An hash reference with categories of javascript used in the
document as keys. The corresponding values are also hashes with
file names as keys and with array references as values. The array
references contain information on each of the file licences, with
content
1. licence name
2. license URL
3. file name or source of file
‘labels’
Association of identifiers to label elements. Gathered from the
Texinfo parsing result. *Note Texinfo::Parser::labels_information:
(texi2any_internals)Texinfo::Parser $labels_information,
$targets_list, $nodes_list = labels_information($parser).
‘line_break_element’
HTML line break element, based on ‘<br>’, also taking into account
‘USE_XML_SYNTAX’ customization variable value.
‘non_breaking_space’
Non breaking space, can be ‘ ’, but also a non breaking space
character or the corresponding numeric entity based on
‘ENABLE_ENCODING’ and ‘USE_NUMERIC_ENTITY’ customization variables
values.
‘paragraph_symbol’
Paragraph symbol, can be ‘¶’, but also the corresponding
numeric entity or encoded character based on ‘ENABLE_ENCODING’ and
‘USE_NUMERIC_ENTITY’ customization variables values.
‘title_string’
‘title_tree’
‘simpletitle_tree’
‘simpletitle_command_name’
Some information is deduced from the title commands: “simpletitle”
reflects ‘@settitle’ vs. ‘@shorttitlepage’, and “title” is
constructed by trying all the title-related commands, including
‘@top’ and ‘@titlefont’, in the top element.
‘title_tree’ is a Texinfo tree corresponding to the title,
‘title_string’ is the result of the conversion in a string context
(*note Init File Expansion Contexts::). ‘simpletitle_tree’ is a
Texinfo tree corresponding to the simpletitle, and
‘simpletitle_command_name’ is the @-command name used for the
simpletitle, without the leading @.
‘structuring’
Information on the document structure. Gathered before the
conversion. Two hash keys correspond to interesting information,
‘sectioning_root’ which points to the top level sectioning command
tree element, and ‘sections_list’ which holds the list of the
sectioning commands in the document.
‘title_titlepage’
The formatted title, possibly based on ‘@titlepage’, or on
‘simpletitle_tree’ and similar information, depending on
‘SHOW_TITLE’ and ‘USE_TITLEPAGE_FOR_TITLE’ customization variables
in the default case.
*Note Simple Customization of CSS:: for an explanation on getting
information on CSS.
File: texi2any_api.info, Node: Customizing Output-Related Names, Next: Init File Calling at Different Stages, Prev: User Defined Functions, Up: Top
7 Customizing Output-Related Names
**********************************
It is possible to control both output file names and target identifiers
in detail.
User defined functions customizing file names and targets are
registered with ‘texinfo_register_file_id_setting_function’:
-- Function: texinfo_register_file_id_setting_function ($customized,
\&handler)
$CUSTOMIZED is a string describing what the function should set.
\&HANDLER should be a reference on the user defined function. The
different functions that can be registered have different arguments
and return values.
The different possibilities for the customized information are
explained in the next sections.
For example:
sub my_node_file_name($$$) {
my ($converter, $element, $filename) = @_;
# ....
return $node_file_name
}
texinfo_register_file_id_setting_function('node_file_name',
\&my_node_file_name);
* Menu:
* File: Customizing Output File Names.
* Target: Customizing Output Target Names.
* External Node: Customizing External Node Output Names.
* Special Elements: Customizing Special Elements Output Names.
File: texi2any_api.info, Node: Customizing Output File Names, Next: Customizing Output Target Names, Up: Customizing Output-Related Names
7.1 Customizing Output File Names
=================================
It is possible to specify the output file names with more control than
merely the command line option ‘--output’ (*note (texinfo)Invoking
texi2any::). The ‘PREFIX’ customization variable overrides the base
name of the file given by ‘@setfilename’ or the file name and should not
contain any directory components. To alter intermediate directories,
use the ‘SUBDIR’ customization variable. Finally, the extension may
also be overriden by the customization variable ‘EXTENSION’. This
variable should be ‘undef’ if no extension is to be added.
Furthermore, the customization variables ‘TOP_FILE’ override the
output file name for the top element.
Two function references registered with
‘texinfo_register_file_id_setting_function’ enable further
customization. The first, ‘node_file_name’ is used to customize the
nodes files names.
-- Function Reference: $NODE_FILE node_file_name ($CONVERTER,
\%NODE_ELEMENT, $FILE_NAME)
$CONVERTER is a converter object. \%NODE_ELEMENT is the Texinfo
tree element corresponding to the ‘@node’. $FILE_NAME is the node
file name that has been already set. The function should return
the node file name ($NODE_FILE).
The other function reference, ‘tree_unit_file_name’, is used to
customize the file names associated with each normal element unit (*note
Output Element Units::).
-- Function Reference: ($FILE, $PATH) tree_unit_file_name ($CONVERTER,
\%UNIT_ELEMENT, $FILE_NAME, $FILE_PATH)
$CONVERTER is a converter object. \%UNIT_ELEMENT is the Texinfo
element corresponding to the unit element. $FILE_NAME is the file
name that has been already set. $FILE_PATH is the file path that
has been already set. $FILE_PATH is ‘undef’ if the file is
relative to the output directory, which is the case if the output
is split. The function should return the file name for the unit
element, $FILE, and the file path for the unit element, $PATH,
which should be ‘undef’ if the file path is to be constructed by
putting $FILE in the destination directory.
In the user defined functions, the information that a unit element is
associated with ‘@top’ or ‘@node Top’ or more generally considered to be
the Top element may be determined with
$converter->element_is_tree_unit_top(\%unit_element);
The information on tree elements may be interesting for those
functions (*note Texinfo Tree Elements in User Defined Functions::).
The ‘extra’ key ‘associated_section’ of a node element and
‘associated_node’ of a sectioning command element may also be useful.
The file name associated to a sectioning command is set together with
the target, and is described in the next section.
File: texi2any_api.info, Node: Customizing Output Target Names, Next: Customizing External Node Output Names, Prev: Customizing Output File Names, Up: Customizing Output-Related Names
7.2 Customizing Output Target Names
===================================
Similar to file names, so-called target and id names may be set. The
“id” is placed where the item is located, while the “target” is used to
construct references to that item. The id and target are the same. A
function used to set both target and file name is also described here.
The following function reference is for target items (nodes, anchors,
floats), including for external manuals:
-- Function Reference: $TARGET label_target_name ($CONVERTER,
$NORMALIZED, \@NODE_CONTENTS, $DEFAULT_TARGET)
$CONVERTER is a converter object. $NORMALIZED is the normalized
node name, \@NODE_CONTENTS is a reference on an array containing
the Texinfo tree contents of the command label. $DEFAULT_TARGET is
the target that has been already set. The function should return
the target ($TARGET).
The element corresponding to the label can be found with
‘label_command’ if the label corresponds to an internal reference (*note
Target Commands Links, Texts and Associated Commands::):
my $element;
$element = $converter->label_command($normalized)
if (defined($normalized));
For sectioning commands, in addition to the sectioning command
target, targets for the sectioning command in table of contents and in
short table of contents are needed. The following function reference is
for sectioning command related target and file name:
-- Function Reference: ($TARGET, $TARGET_CONTENTS,
$TARGET_SHORTCONTENTS, $FILE) sectioning_command_target_name
($CONVERTER, \%SECTION_ELEMENT, $DEFAULT_TARGET,
$DEFAULT_TARGET_CONTENTS, $DEFAULT_TARGET_SHORTCONTENTS,
$FILE_NAME)
$CONVERTER is a converter object. \%SECTION_ELEMENT is the Texinfo
element corresponding to the sectioning command.
$DEFAULT_TARGET, $DEFAULT_TARGET_CONTENTS and
$DEFAULT_TARGET_SHORTCONTENTS are the targets that have been
already set for the sectioning element and the sectioning element
in table of contents and in short table of contents. $FILE_NAME is
the file name that has been already set.
The function should return the $TARGET, $TARGET_CONTENTS and
$TARGET_SHORTCONTENTS sectioning element target and sectioning
element in table of contents and in short table of contents
targets, and the file name for the sectioning element ($FILE).
File: texi2any_api.info, Node: Customizing External Node Output Names, Next: Customizing Special Elements Output Names, Prev: Customizing Output Target Names, Up: Customizing Output-Related Names
7.3 Customizing External Node Output Names
==========================================
In the default case references to external nodes are set as described in
the Texinfo manual (*note (texinfo)HTML Xref::). Some customization is
already possible for external manuals URLs as explained in the Texinfo
manual (*note (texinfo)HTML Xref Configuration::), and by setting
‘EXTERNAL_CROSSREF_SPLIT’, ‘EXTERNAL_CROSSREF_EXTENSION’,
‘EXTERNAL_DIR’, ‘TOP_NODE_FILE_TARGET’ or ‘IGNORE_REF_TO_TOP_NODE_UP’
(*note (texinfo)HTML Customization Variables::).
If the external reference is not already ignored because of
‘IGNORE_REF_TO_TOP_NODE_UP’, two function references give full control
over the external node target output names, with
‘external_target_split_name’ if the external target is considered to be
split, and ‘external_target_non_split_name’ if the external target is
non split.
-- Function Reference: ($TARGET, $HOST_DIRECTORY, $FILE_NAME)
external_target_split_name($CONVERTER, $NORMALIZED,
\@NODE_CONTENTS, $DEFAULT_TARGET, $DEFAULT_HOST_DIRECTORY,
$DEFAULT_FILE_NAME)
$CONVERTER is a converter object. $NORMALIZED is the normalized
node name, \@NODE_CONTENTS is a reference on an array containing
the Texinfo tree contents of the external target.
$DEFAULT_TARGET, $DEFAULT_HOST_DIRECTORY and $DEFAULT_FILE_NAME are
the target, host and directory URL part and file name URL part that
have been already set.
The function should return the $TARGET, $HOST_DIRECTORY and
$FILE_NAME URL parts.
-- Function Reference: ($TARGET, $HOST_DIRECTORY_FILE)
external_target_non_split_name($CONVERTER, $NORMALIZED,
\@NODE_CONTENTS, $DEFAULT_TARGET,
$DEFAULT_HOST_DIRECTORY_FILE)
$CONVERTER is a converter object. $NORMALIZED is the normalized
node name, \@NODE_CONTENTS is a reference on an array containing
the Texinfo tree contents of the external target.
$DEFAULT_TARGET is the target and $DEFAULT_HOST_DIRECTORY_FILE is
the host and file name part of the URL that have been already set.
The function should return the $TARGET and $HOST_DIRECTORY_FILE URL
parts.
File: texi2any_api.info, Node: Customizing Special Elements Output Names, Prev: Customizing External Node Output Names, Up: Customizing Output-Related Names
7.4 Customizing Special Elements Output Names
=============================================
For special element units file and target (*note Output Element
Units::), the function reference is:
-- Function Reference: ($TARGET, $FILE)
special_element_target_file_name ($CONVERTER, \%ELEMENT,
$DEFAULT_TARGET, $FILE_NAME)
$CONVERTER is a converter object. \%ELEMENT is the Texinfo element
corresponding to the special element unit. $DEFAULT_TARGET is the
target that has been already set, and $FILE_NAME is the file name
that has been already set. The function should return the $TARGET
and $FILE.
To determine the variety of the special element processed, the
‘extra’ hash ‘special_element_variety’ key can be used. *Note Table
15.1: Special Elements Varieties.
File: texi2any_api.info, Node: Init File Calling at Different Stages, Next: User Defined Functions in Conversion, Prev: Customizing Output-Related Names, Up: Top
8 Init File Calling at Different Stages
***************************************
Arbitrary user-defined functions may be called during conversion. This
could be used, for example, to initialize variables and collect some
@-commands text, and doing clean-up after the Texinfo tree conversion.
There are four places for user defined functions:
‘setup’
Called right after completing main program customization
information with converter specific customization information, but
before anything else is done, including collecting the output files
names and registering the customization variables pre-conversion
values.
‘structure’
Called after setting and determining information on CSS, output
files and directories, document structure and associated
directions, file names, labels and links for nodes, sectioning
commands, special elements, footnotes and index entries.
‘init’
Called after some gathering of global information on the document,
such as titles, copying comment and document description, which
require some conversion of Texinfo, right before the main output
processing. At that point most of the information available from
the converter is set (*note Conversion General Information::).
‘finish’
Called after output generation is finished.
The function used to register a user defined functions is
‘texinfo_register_handler’:
-- Function: texinfo_register_handler ($stage, \&handler, $priority)
$STAGE is one of the stages described just above. \&HANDLER is a
reference on the user defined function. $PRIORITY is an optional
priority class.
To determine the order of user defined functions calls, the
priority classes are sorted, and within a priority class the order
is the order of calling ‘texinfo_register_handler’.
The call of the user defined functions is:
-- Function Reference: $STATUS stage_handler ($CONVERTER, \%TREE,
$STAGE)
$CONVERTER is a converter object. \%TREE is the Texinfo tree root
element. $STAGE is the current stage.
If $STATUS is not 0 it means that an error occured. If $STATUS is
positive, the user defined functions should have registered an
error or warning message, for example with ‘document_error’ (*note
Error Reporting in User Defined Functions::). If $STATUS is
negative, the converter will emit a non specific error message. If
the $STATUS is lower than -‘HANDLER_FATAL_ERROR_LEVEL’ or higher
than ‘HANDLER_FATAL_ERROR_LEVEL’, the processing stops immediately.
Default value for ‘HANDLER_FATAL_ERROR_LEVEL’ is 100.
File: texi2any_api.info, Node: User Defined Functions in Conversion, Next: Mandatory Conversion Function Calls, Prev: Init File Calling at Different Stages, Up: Top
9 User Defined Functions in Conversion
**************************************
Full customization of output is achieved with replacing default
formatting functions with user defined functions. There are two broad
classes of functions, the “conversion” functions used for elements of
the Texinfo tree, and other “formatting” functions with diverse
purposes, including formatting that are not based on tree elements (for
example beginning and end of file formatting).
* Menu:
* Tree Element Conversion Functions::
* Formatting Functions::
File: texi2any_api.info, Node: Tree Element Conversion Functions, Next: Formatting Functions, Up: User Defined Functions in Conversion
9.1 Tree Element Conversion Functions
=====================================
Functions used for tree elements associated with @-commands are
considered separately from functions used for tree elements not
associated with @-commands, which includes containers with a type and
text. There are two functions for each element command or type, one
called when the element is first encountered, and the other called after
formatting the contents of the element. The actual conversion is
usually done after formatting the contents of the element, but it may
sometime be necessary to have some code run when the element is first
encountered.
For @-commands with both a command name and a type, the type is used
as selector for the formating function for ‘def_line’,
‘definfoenclose_command’ and ‘index_entry_command’ types.
* Menu:
* Command Tree Element Opening Functions::
* Command Tree Element Conversion Functions::
* Type Tree Element Opening Functions::
* Type Tree Element Conversion Functions::
File: texi2any_api.info, Node: Command Tree Element Opening Functions, Next: Command Tree Element Conversion Functions, Up: Tree Element Conversion Functions
9.1.1 Command Tree Element Opening Functions
--------------------------------------------
User defined functions called when an @-command element is first
encountered are registered with ‘texinfo_register_command_opening’:
-- Function: texinfo_register_command_opening ($command_name,
\&handler)
$COMMAND_NAME is an @-command name, with the leading @. \&HANDLER
is the user defined function reference.
The call of the user defined functions is:
-- Function Reference: $TEXT command_open ($CONVERTER, $COMMAND_NAME,
\%ELEMENT)
$CONVERTER is a converter object. $COMMAND_NAME is the @-command
name without the @. \%ELEMENT is the Texinfo element.
The $TEXT returned is prepended to the formatting of the @-command.
It is possible to have access to the default opening function
reference. The function used is:
-- Function: \&DEFAULT_COMMAND_OPEN = $CONVERTER->default_command_open
($COMMAND_NAME)
$COMMAND_NAME is the @-command name without the @. Returns the
default opening function reference for $COMMAND_NAME, or ‘undef’ if
there is none.
File: texi2any_api.info, Node: Command Tree Element Conversion Functions, Next: Type Tree Element Opening Functions, Prev: Command Tree Element Opening Functions, Up: Tree Element Conversion Functions
9.1.2 Command Tree Element Conversion Functions
-----------------------------------------------
User defined functions called for an @-command element conversion, after
arguments and contents have been formatted, are registered with
‘texinfo_register_command_formatting’:
-- Function: texinfo_register_command_formatting ($command_name,
\&handler)
$COMMAND_NAME is an @-command name, with the leading @. \&HANDLER
is the user defined function reference.
The call of the user defined functions is:
-- Function Reference: $TEXT command_conversion ($CONVERTER,
$COMMAND_NAME, \%ELEMENT, \@ARGS, $CONTENT)
$CONVERTER is a converter object. $COMMAND_NAME is the @-command
name without the @. \%ELEMENT is the Texinfo element.
\@ARGS, if defined, is a reference on the formatted arguments of
the @-command. Each of the array items correspond to each of the
@-command argument. Each array item is a hash references, with
keys corresponding to possible argument formatting contexts:
‘normal’
Argument formatted in a normal context
‘monospace’
Argument formatted in a context where spaces are kept as is,
as well as quotes and minus characters, for instance in ‘--’
and ‘``’. Both in preformatted and code context. *Note Init
File Expansion Contexts::.
‘monospacestring’
Same as monospace, but in addition in string context. *Note
Init File Expansion Contexts::.
‘monospacetext’
Same as monospace, but in addition the argument is converted
to plain text. *Note Converter Object and Conversion
Functions::.
‘filenametext’
Same as monospacetext, but in addition the document encoding
is used to convert accented letters and special insertion
@-commands to plain text even if ‘ENABLE_ENCODING’ is unset.
‘raw’
Text is kept as is, special HTML characters are not protected.
Appears only as ‘@inlineraw’ second argument.
‘string’
In string context. *Note Init File Expansion Contexts::.
‘tree’
The Texinfo tree element corresponding to the argument. *Note
Texinfo Tree Elements in User Defined Functions::.
‘url’
Similar with filenametext. The difference is that UTF-8
encoding is always used for the conversion of accented and
special insertion @-commands to plain text. This is best for
percent encoding of URLs, which should always be produced from
UTF-8 encoded strings.
The formatted arguments contexts depend on the @-command, there
could be none, for ‘@footnote’ argument which is not directly
converted where the footnote command is, or multiple, for example
for the fourth argument of ‘@image’ which is both available as
‘normal’ and ‘string’.
For example, ‘$args->[0]->{'normal'}’ is the first argument
converted in normal context.
$CONTENT is the @-command formatted contents. It corresponds to
the contents of block @-commands, and to Texinfo code following
‘@node’, sectioning commands, ‘@tab’ and ‘@item’ in ‘@enumerate’
and ‘@itemize’. $CONTENT can be ‘undef’ or the empty string.
The $TEXT returned is the result of the @-command conversion.
To call a conversion function from user defined code, the function
reference should first be retrieved using ‘command_conversion’:
-- Function: \&COMMAND_CONVERSION = $CONVERTER->command_conversion
($COMMAND_NAME)
$COMMAND_NAME is the @-command name without the @. Returns the
conversion function reference for $COMMAND_NAME, or ‘undef’ if
there is none, which should only be the case for @-commands ignored
in HTML not defined by the user.
for example, to call the conversion function for the ‘@tab’
@-command, passing arguments that may correspond to another @-command:
&{$converter->command_conversion('tab')}($converter, $cmdname,
$command, $args, $content);
It is possible to have access to the default conversion function
reference. The function used is:
-- Function: \&DEFAULT_COMMAND_CONVERSION =
$CONVERTER->default_command_conversion ($COMMAND_NAME)
$COMMAND_NAME is the @-command name without the @. Returns the
default conversion function reference for $COMMAND_NAME, or ‘undef’
if there is none, which should only be the case for @-commands
ignored in HTML.
File: texi2any_api.info, Node: Type Tree Element Opening Functions, Next: Type Tree Element Conversion Functions, Prev: Command Tree Element Conversion Functions, Up: Tree Element Conversion Functions
9.1.3 Type Tree Element Opening Functions
-----------------------------------------
User defined functions called when an element without @-command with a
container type is first encountered are registered with
‘texinfo_register_type_opening’:
-- Function: texinfo_register_type_opening ($type, \&handler)
$TYPE is the element type. \&HANDLER is the user defined function
reference.
The call of the user defined functions is:
-- Function Reference: $TEXT type_open ($CONVERTER, $TYPE, \%ELEMENT)
$CONVERTER is a converter object. $TYPE is the element type.
\%ELEMENT is the Texinfo element.
The $TEXT returned is prepended to the formatting of the type
container.
It is possible to have access to the default opening function
reference. The function used is:
-- Function: \&DEFAULT_TYPE_OPEN = $CONVERTER->default_type_open
($TYPE)
$COMMAND_NAME is the element type. Returns the default opening
function reference for $TYPE, or ‘undef’ if there is none.
File: texi2any_api.info, Node: Type Tree Element Conversion Functions, Prev: Type Tree Element Opening Functions, Up: Tree Element Conversion Functions
9.1.4 Type Tree Element Conversion Functions
--------------------------------------------
User defined functions called for the conversion of an element without
@-command with text or a container type are registered with
‘texinfo_register_type_formatting’. For containers, the user defined
function is called after conversion of the content.
-- Function: texinfo_register_type_formatting ($type, \&handler)
$TYPE is the element type. \&HANDLER is the user defined function
reference.
The call of the user defined functions is:
-- Function Reference: $TEXT type_conversion ($CONVERTER, $TYPE,
\%ELEMENT, $CONTENT)
$CONVERTER is a converter object. $TYPE is the element type.
\%ELEMENT is the Texinfo element. $CONTENT is text for elements
associated with text, or the formatted contents for other elements.
$CONTENT can be ‘undef’ or the empty string.
The $TEXT returned is the result of the @-command conversion.
To call a conversion function from user defined code, the function
reference should first be retrieved using ‘type_conversion’:
-- Function: \&TYPE_CONVERSION = $CONVERTER->type_conversion ($TYPE)
$TYPE is the element type. Returns the conversion function
reference for $TYPE, or ‘undef’ if there is none, which should only
be the case for types ignored in HTML not defined by the user.
It is possible to have access to the default conversion function
reference. The function used is:
-- Function: \&DEFAULT_TYPE_CONVERSION =
$CONVERTER->default_type_conversion ($TYPE)
$TYPE is the element type. Returns the default conversion function
reference for $TYPE, or ‘undef’ if there is none, which should only
be the case for types ignored in HTML.
File: texi2any_api.info, Node: Formatting Functions, Prev: Tree Element Conversion Functions, Up: User Defined Functions in Conversion
9.2 Formatting Functions
========================
Most formatting functions are specific, with specific arguments, and a
specific item formatted.
User defined functions associated with the formatting of special
elements body (*note Output Element Units::) are handled separately.
The formatting functions are often called from function that can be
replaced by a user defined function, therefore these functions may not
be called if the replacement functions do not keep a similar operation.
* Menu:
* Specific formating Functions::
File: texi2any_api.info, Node: Specific formating Functions, Up: Formatting Functions
9.2.1 Specific formating Functions
----------------------------------
User defined formatting functions are registered with
‘texinfo_register_formatting_function’:
-- Function: texinfo_register_formatting_function ($formatted,
\&handler)
$FORMATTED is a string describing the formatting function.
\&HANDLER is the user defined function reference.
To call a formatting function from user defined code, the function
reference should first be retrieved using ‘formatting_function’:
-- Function: \&FORMATTING_FUNCTION = $CONVERTER->formatting_function
($FORMATTED)
$FORMATTED is a string describing the formatting function. Returns
the associated formatting function reference.
It is possible to have access to the default formatting function
reference. The function used is:
-- Function: \&DEFAULT_FORMATTING_FUNCTION =
$CONVERTER->default_formatting_function ($FORMATTED)
$FORMATTED is a string describing the formatting function. Returns
the default formatting function reference.
The string that should be used to register or call each of the
formatting functions and the call of the formatting functions are
documented in the following sections of the manual, depending on where
they are relevant.
File: texi2any_api.info, Node: Mandatory Conversion Function Calls, Next: Basic Formatting Customization, Prev: User Defined Functions in Conversion, Up: Top
10 Mandatory Conversion Function Calls
**************************************
There are several conventions and constraints that user defined code
should abide to, in order to comply with customization option values,
and also to have information correctly registered in the converter.
* Menu:
* Protection of URLs::
* Formatting HTML Element with Classes::
* Closing Lone HTML Element::
* Substituting Non Breaking Space::
* Conversion in String Context::
* Conversion in Preformatted Context::
* Text Formatting Context::
File: texi2any_api.info, Node: Protection of URLs, Next: Formatting HTML Element with Classes, Up: Mandatory Conversion Function Calls
10.1 Protection of URLs
=======================
URLs need to be "percent-encoded" to protect non-ASCII characters,
spaces and other ASCII characters. Percent-encoding also allows to have
characters be interpreted as part of a path and not as characters with a
special role in URLs. For example, ‘?’ has a special role in URLs as it
starts a query string. To have it considered as part of a file path,
instead of a marker of the beginning of a query, it needs to be percent
encoded.
To protect a whole URL, in which characters with a special role in
URL are left as is, use ‘url_protect_url_text’. To protect file path in
URL, including characters with a special role in URLs, use
‘url_protect_file_text’.
-- Function: $PROTECTED_URL =
$CONVERTER->url_protect_url_text($INPUT_STRING)
Percent-encode $INPUT_STRING, leaving as is all the characters with
a special role in URLs, such as ‘:’, ‘/’, ‘?’, ‘&’, ‘#’ or ‘%’ (and
a few other). HTML reserved characters and form feeds protected
are also protected as entities (*note ‘format_protect_text’: Basic
Formatting Customization.). This is typically used on complete
URLs pointing to diverse internet resources, such as the ‘@url’ URL
argument.
for example
return $self->html_attribute_class('a', [$cmdname])
.' href="'.$self->url_protect_url_text($url)."\">$text</a>";
-- Function: $PROTECTED_PATH =
$CONVERTER->url_protect_file_text($INPUT_STRING)
Percent-encode $INPUT_STRING leaving as is character appearing in
file paths only, such as ‘/’, ‘.’, ‘-’ or ‘_’. All the other
characters that can be percent-protected are protected, including
characters with a special role in URLs. For example, ‘?’, ‘&’ and
‘%’ are percent-protected. HTML reserved characters and form feeds
protected are also protected as entities (*note
‘format_protect_text’: Basic Formatting Customization.). This is
typically used on file names corresponding to actual files, used in
the path portion of an URL, such as the image file path in
‘@image’.
For example
$self->html_attribute_class('img', [$cmdname])
. ' src="'.$self->url_protect_file_text($image_file)."\");
File: texi2any_api.info, Node: Formatting HTML Element with Classes, Next: Closing Lone HTML Element, Prev: Protection of URLs, Up: Mandatory Conversion Function Calls
10.2 Formatting HTML Element with Classes
=========================================
Opening an HTML element with one or more classes should always be done
through ‘html_attribute_class’:
-- Function: $ELEMENT_OPEN = $CONVERTER->html_attribute_class
($HTML_ELEMENT, \@CLASSES)
Formats the beginning of an HTML element $HTML_ELEMENT. \@CLASSES
is the list of classes for this element. The element opening
returned does not include the end of element symbol ‘>’ such that
it is possible to add more attributes.
If the HTML element is ‘span’, an empty string is returned if there
is also no attribute.
If ‘NO_CSS’ is set, no attribute is set for the element. Otherwise
a ‘class’ attribute is set based on \@CLASSES . If
‘INLINE_CSS_STYLE’ is set, a CSS style attribute based on CSS
element class rules is also added. Otherwise the information that
the element class was seen is registered by the converter.
Examples of use:
my $open = $converter->html_attribute_class('span', ['category-def']);
$category_result = $open.'>'.$category_result.'</span>'
if ($open ne '');
my $result = $converter->html_attribute_class('em', [$cmdname, 'jax_p'])
. '>' . $content . '</em>';
File: texi2any_api.info, Node: Closing Lone HTML Element, Next: Substituting Non Breaking Space, Prev: Formatting HTML Element with Classes, Up: Mandatory Conversion Function Calls
10.3 Closing Lone HTML Element
==============================
HTML elements with an opening element, but no closing element, such as
‘<img>’ or ‘<link>’ should be closed by calling
‘close_html_lone_element’:
-- Function: $HTML_ELEMENT = $CONVERTER->close_html_lone_element
($UNCLOSED_ELEMENT)
Close the $UNCLOSED_ELEMENT, which can contain attributes, by
prepending ‘>’ or ‘/>’ depending on the ‘USE_XML_SYNTAX’
customization variable value.
Examples of use:
$description = $converter->close_html_lone_element(
"<meta name=\"description\" content=\"$description\"");
File: texi2any_api.info, Node: Substituting Non Breaking Space, Next: Conversion in String Context, Prev: Closing Lone HTML Element, Up: Mandatory Conversion Function Calls
10.4 Substituting Non Breaking Space
====================================
If a ‘ ’ can appear in formatted code, the corresponding text
should be in a call to ‘substitute_html_non_breaking_space’, to take
into account ‘ENABLE_ENCODING’ and ‘USE_NUMERIC_ENTITY’ customization
variables:
-- Function: $SUBSTITUTED_TEXT =
$CONVERTER->substitute_html_non_breaking_space
($FORMATTED_TEXT)
Substitute ‘ ’ according to customization variables values.
This is not needed if the ‘non_breaking_space’ information is taken
from the general information (*note Conversion General Information::).
File: texi2any_api.info, Node: Conversion in String Context, Next: Conversion in Preformatted Context, Prev: Substituting Non Breaking Space, Up: Mandatory Conversion Function Calls
10.5 Conversion in String Context
=================================
Conversion and formatting functions should check if in string context to
avoid using HTML elements in formatting when in string context. *Note
Init File Expansion Contexts::.
To determine if in string context, the functions is ‘in_string’:
-- Function: $IN_STRING = $CONVERTER->in_string ()
Return true if in string context.
Example of use:
if ($converter->in_string()) {
return "$mail_string ($text)";
} else {
return $converter->html_attribute_class('a', [$cmdname])
." href=\"mailto:$mail_string\">$text</a>";
}
File: texi2any_api.info, Node: Conversion in Preformatted Context, Next: Text Formatting Context, Prev: Conversion in String Context, Up: Mandatory Conversion Function Calls
10.6 Conversion in Preformatted Context
=======================================
Conversion and formatting functions should test if in preformatted
context to convert accordingly. *Note Init File Expansion Contexts::.
To determine if in preformatted context, the functions is
‘in_preformatted’:
-- Function: $IN_PREFORMATTED = $CONVERTER->in_preformatted ()
Return true if in preformatted context.
If in preformatted context, it is possible to get preformatted
@-commands and preformatted types nesting with
‘preformatted_classes_stack’:
-- Function: @PREFORMATTED_NESTING =
$CONVERTER->preformatted_classes_stack ()
Returns an array containing the block preformatted @-commands such
as ‘@example’, ‘@display’ or ‘@menu’ names without the leading @
and the HTML attribute class preformatted container names, in order
of appearance.
The ‘%Texinfo::Commands::preformatted_code_commands’ hash can be used
to determine if a preformatted command is to be formatted as code (*note
(texi2any_internals)Texinfo::Commands %preformatted_code_commands::).
my @pre_classes = $converter->preformatted_classes_stack();
foreach my $pre_class (@pre_classes) {
if ($Texinfo::Commands::preformatted_code_commands{$pre_class}) {
$result = '<code>' .$result. '</code>';
last;
}
}
*Note Simple Customization of Containers:: on customizing containers
preformatted class.
File: texi2any_api.info, Node: Text Formatting Context, Prev: Conversion in Preformatted Context, Up: Mandatory Conversion Function Calls
10.7 Text Formatting Context
============================
Formatting of text requires to use additional informative functions on
specific contexts only relevant for text. User defined functions should
convert the text according to the context.
Each context is associated with a function:
_code_
-- Function: $IN_CODE = $CONVERTER->in_code ()
Return true if in code context. *Note Init File Expansion
Contexts::.
_math_
-- Function: $IN_MATH = $CONVERTER->in_math ()
Return true if in math context. *Note Init File Expansion
Contexts::.
_raw_
-- Function: $IN_RAW = $CONVERTER->in_raw ()
Return true if in raw format, in ‘@inlineraw’ or in ‘@html’.
In such a context, text should be kept as is and special HTML
characters should not be protected.
_verbatim_
-- Function: $IN_VERBATIM = $CONVERTER->in_verbatim ()
Return true if in verbatim context, corresponding to ‘@verb’
and ‘@verbatim’. In general, HTML characters should be
protected in this context.
_upper-case_
-- Function: $IN_UPPER_CASE = $CONVERTER->in_upper_case ()
Return true if in upper-case context, corresponding to ‘@sc’.
_non-breakable space_
-- Function: $IN_NON_BREAKABLE_SPACE =
$CONVERTER->in_non_breakable_space ()
Return true if in context where line breaks are forbidden,
corresponding to ‘@w’.
_space protected_
-- Function: $IN_SPACE_PROTECTED = $CONVERTER->in_space_protected
()
Return true if in context where space and newline characters
are kept, corresponding to ‘@verb’.
File: texi2any_api.info, Node: Basic Formatting Customization, Next: Dynamic Conversion Information, Prev: Mandatory Conversion Function Calls, Up: Top
11 Basic Formatting Customization
*********************************
The following formatting functions references handle basic formatting
and are called from diverse formatting and conversion functions. *Note
Specific formating Functions:: for information on how to register and
get the functions references.
All the functions take a converter object as their first argument.
‘format_button_icon_img’
Called for an active direction, if ‘ICONS’ is set, when formatting
the navigation panel (*note Simple Navigation Panel
Customization::).
-- Function Reference: $TEXT format_button_icon_img ($CONVERTER,
$BUTTON, $ICON, $NAME)
$BUTTON is a button name, typically obtained from the ‘button’
direction string (*note Direction Strings::). $ICON is an
image file name to be used as icon. $NAME is the direction
heading, typically formatted in string context. *Note Init
File Expansion Contexts::.
Returns a formatted icon image.
‘format_comment’
-- Function Reference: $TEXT format_comment ($CONVERTER,
$INPUT_TEXT)
Return $INPUT_TEXT in a comment.
*Note Texinfo::Convert::Converter::xml_comment:
(texi2any_internals)Texinfo::Convert::Converter $comment =
$converter->xml_comment($text).
‘format_heading_text’
-- Function Reference: $TEXT format_heading_text ($CONVERTER,
$COMMAND_NAME, \@CLASSES, $INPUT_TEXT, $LEVEL, $ID,
\%ELEMENT, $TARGET)
Returns a heading formatted using $INPUT_TEXT as heading text,
$LEVEL as heading level, \@CLASSES for a class attribute.
$COMMAND_NAME gives an information on the @-command the
heading is associated to and can be ‘undef’, for instance for
special elements headings.
$ID is an optional identifier, and \%ELEMENT is an optional
Texinfo tree element associated with the heading. $TARGET is
the id of the element this heading is referring to.
In the default case, if the $TARGET or $ID are specified, a
copiable anchor will be generated and injected into the
heading. In the case both are specified, $ID is preferred
over $TARGET, as it is closer to the element the user sees the
anchor on.
This function reference can be called for ‘@node’ and sectioning
commands, heading commands, tree units, special elements and title
@-commands.
A formatted headings is, in the default case, like
‘<h2>$INPUT_TEXT</h2>’ for a $LEVEL 2 heading.
‘format_program_string’
-- Function Reference: $TEXT format_program_string ($CONVERTER)
This function reference should return the formatted program
string.
‘format_protect_text’
-- Function Reference: $TEXT format_protect_text ($CONVERTER,
$INPUT_TEXT)
Return $INPUT_TEXT with HTML reserved characters and form
feeds protected.
For performance reasons, this function reference may not be
called everywhere text is protected. For those cases, the
calling function should also be redefined to call
‘&{$self->formatting_function('format_protect_text')}(...)’
instead of another function(1).
*Note Texinfo::Convert::Converter::xml_protect_text:
(texi2any_internals)Texinfo::Convert::Converter $protected_text =
$converter->xml_protect_text($text).
‘format_separate_anchor’
This function reference is called if there is not another HTML
element to add an identifier attribute to.
-- Function Reference: $TEXT format_separate_anchor ($CONVERTER,
$ID, $CLASS)
ID is the identifier. $CLASS is an optional class to be used
in an HTML class attribute.
Return an anchor with identifier $ID.
---------- Footnotes ----------
(1) The function called is actually the function referenced as
‘$self->formatting_function('format_protect_text')’ in the default case,
but it is called directly to avoid an indirection
File: texi2any_api.info, Node: Dynamic Conversion Information, Next: Translations Output and Customization, Prev: Basic Formatting Customization, Up: Top
12 Dynamic Conversion Information
*********************************
Dynamic formatting information on the conversion can be obtained from
the converter.
For advanced customization, it is also often necessary to pass
information during conversion between different formatting functions or
between different calls of the same function.
The information is often useful for the formatting of paragraph and
preformatted containers and @-commands such as ‘@abbr’, ‘@footnote’,
‘@node’, sectioning commands, ‘@quotation’ and ‘@float’.
* Menu:
* Dynamic Converter Formatting Information::
* Opening and Closing Sectioning Commands Extent::
* Setting Up Content for the Next Text Container::
* Associating Information to an Output File::
* Shared Conversion State::
File: texi2any_api.info, Node: Dynamic Converter Formatting Information, Next: Opening and Closing Sectioning Commands Extent, Up: Dynamic Conversion Information
12.1 Dynamic Converter Formatting Information
=============================================
To get the current paragraph and preformatted number, use
‘paragraph_number’ or ‘preformatted_number’:
-- Function: $NUMBER = $CONVERTER->paragraph_number ()
-- Function: $NUMBER = $CONVERTER->preformatted_number ()
Return the current paragraph or preformatted container number in
the current formatting context.
To get the topmost block @-command being converted, use
‘top_block_command’:
-- Function: $COMMAND_NAME = $CONVERTER->top_block_command ()
Return the most recent block @-command seen in the current
formatting context.
To get the text filling and alignement context, determined by
‘@flushleft’ or ‘@center’, use ‘in_align’:
-- Function: $ALIGN_CONTEXT = $CONVERTER->in_align ()
If the alignment context is the default alignement context, return
‘undef’. Otherwise, returns the command name of the alignment
context.
To determine if the conversion is in a context converted multiple
times, use ‘in_multi_expanded’:
-- Function: $MULTI_EXPANDED_CONTEXT_INFORMATION =
$CONVERTER->in_multi_expanded ()
Return a string representing the multiple expanded context, or
‘undef’ if not in a multiple expanded context.
To get the location of an image file, use
‘html_image_file_location_name’:
-- Function: ($IMAGE_FILE, $IMAGE_BASEFILE, $IMAGE_EXTENSION,
$IMAGE_PATH, $IMAGE_PATH_ENCODING) =
$CONVERTER->html_image_file_location_name ($COMMAND_NAME,
\%ELEMENT, \@ARGS)
$COMMAND_NAME, \%ELEMENT and \@ARGS should be the arguments of an
‘@image’ @-command formatting (*note Command Tree Element
Conversion Functions::).
The return values gives information on the image file if found, or
fallback values. $IMAGE_FILE is the relative image file name. It
is the file name used in formatting of the ‘@image’ command in the
default case. $IMAGE_BASEFILE is the base file name of the image,
without extension, corresponding to the ‘@image’ @-command first
argument. $IMAGE_EXTENSION is the image file extension (without a
leading dot). $IMAGE_PATH is the path to the actual image file,
‘undef’ if no file was found. $IMAGE_PATH is returned as a binary
string, the other strings returned are character strings.
$IMAGE_PATH_ENCODING is the encoding used to encode the image path
to a binary string.
*Note Conversion in Preformatted Context:: for information on getting
preformatted commands and container types nesting information.
File: texi2any_api.info, Node: Opening and Closing Sectioning Commands Extent, Next: Setting Up Content for the Next Text Container, Prev: Dynamic Converter Formatting Information, Up: Dynamic Conversion Information
12.2 Opening and Closing Sectioning Commands Extent
===================================================
In the default formatting, when a sectioning command is encountered, a
‘<div>’ element is opened for the extent of the sectioning command
including its children sectioning commands. This extent need to be
closed at different places, for instance when another sectioning command
is reached, at the end of a file, or at the end of the document.
The user defined formatting function should take care of registering
and closing opened section levels. In the default code, registering is
done in the sectioning commands conversion function only.
The function for registering opened section extent is
‘register_opened_section_level’:
-- Function: $CONVERTER->register_opened_section_level ($level,
$closing_text)
$LEVEL is the sectioning command level. It is typically obtained
with ‘section->{'structure'}->{'section_level'}’ (*note Texinfo
Tree Elements in User Defined Functions::). $CLOSING_TEXT is the
text that should be output when the section level $LEVEL is closed.
The function for closing registered section extents is
‘close_registered_sections_level’:
-- Function: @CLOSING_TEXTS =
$CONVERTER->close_registered_sections_level ($LEVEL)
$LEVEL is the sectioning command level. Opened section are closed
down to section level $LEVEL. The closing texts are returned in
the @CLOSING_TEXTS array in order.
Example of use:
my $level = $opening_section->{'structure'}->{'section_level'};
$result
.= join('', $converter->close_registered_sections_level($level));
$converter->register_opened_section_level($level, "</div>\n");
File: texi2any_api.info, Node: Setting Up Content for the Next Text Container, Next: Associating Information to an Output File, Prev: Opening and Closing Sectioning Commands Extent, Up: Dynamic Conversion Information
12.3 Setting Up Content for the Next Text Container
===================================================
Text is mainly output in two “inline” text containers, ‘paragraph’ for
text in paragraph and ‘preformatted’ for text in preformatted
environments. The Texinfo code parsing makes sure that it is the case,
to simplify conversion to formats which allow text only in specific
environments such as HTML.
Formatted text may also be prepared based on information from Texinfo
elements tree while out of the inline containers. For that case,
functions allow to register pending inline formatted content, and get
the content to be prepended in inline text containers.
Pending formatted content text is registered with
‘register_pending_formatted_inline_content’:
-- Function: $CONVERTER->register_pending_formatted_inline_content
($category, $content)
$CONTENT is the formatted content to be registered and output in
the next inline container. $CATEGORY is a indicator of the source
of the formatted inline content, mostly used to cancel registered
content if no inline container was seen.
Pending formatted content can (and should) be cancelled when it is
known that there is no suitable inline container to be used to output
the text. The function is ‘cancel_pending_formatted_inline_content’:
-- Function: $CANCELLED_CONTENT =
$CONVERTER->cancel_pending_formatted_inline_content
($CATEGORY)
Cancel the first $CATEGORY pending formatted content text found.
Returns ‘undef’ if nothing was cancelled, and the cancelled content
otherwise.
Pending formatted content is gathered by calling
‘get_pending_formatted_inline_content’. In the default case, this is
done in inline containers opening code (*note Type Tree Element Opening
Functions::).
-- Function: $CONTENT =
$CONVERTER->get_pending_formatted_inline_content ()
Returns the concatenated pending content.
The inline containers get the content when they are opened, but are
converted after the formatting of their contents. Two additional
functions allow to associate pending content to an element,
‘associate_pending_formatted_inline_content’, and get the associated
content, ‘get_associated_formatted_inline_content’.
‘associate_pending_formatted_inline_content’ is normally called in
inline container opening code, right after
‘get_pending_formatted_inline_content’, while
‘get_associated_formatted_inline_content’ is called in the inline
container conversion function (*note Type Tree Element Conversion
Functions::).
-- Function: $CONVERTER->associate_pending_formatted_inline_content
(\%element, $content)
Associate $CONTENT to the Texinfo tree element \%ELEMENT.
-- Function: $CONTENT =
$CONVERTER->get_associated_formatted_inline_content
(\%ELEMENT)
Get $CONTENT associated to the Texinfo tree element \%ELEMENT.
File: texi2any_api.info, Node: Associating Information to an Output File, Next: Shared Conversion State, Prev: Setting Up Content for the Next Text Container, Up: Dynamic Conversion Information
12.4 Associating Information to an Output File
==============================================
To be able to retrieve information associated to the current file, in
general for the file begin or end formatting,
‘register_file_information’ can be used to associate information, and
‘get_file_information’ to retrieve that information.
-- Function: $CONVERTER->register_file_information ($key, $value)
Associate the current output file name file to the key $KEY, itself
associated to the value $VALUE.
-- Function: $VALUE = $CONVERTER->get_file_information ($KEY,
$FILE_NAME)
Return the value associated to the key $KEY and file name
$FILE_NAME.
File: texi2any_api.info, Node: Shared Conversion State, Prev: Associating Information to an Output File, Up: Dynamic Conversion Information
12.5 Shared Conversion State
============================
For information shared among formatting functions without involving the
converter, the function ‘shared_conversion_state’ can be used both for
initialization of shared information and to share information:
-- Function: $REFERENCE = $CONVERTER->shared_conversion_state ($NAME,
$INITIALIZATION)
Return the reference $REFERENCE associated with $NAME.
$INITIALIZATION is only read the first time $NAME is seen and sets
up the reference that will be reused afterwards. If
$INITIALIZATION is a scalar (string or integer, for example), a
reference on a scalar is returned, the associated value being set
to $INITIALIZATION. Otherwise, $INITIALIZATION should be a
reference on a hash or on an array.
The converter is used to hold the information, but does not use nor
write.
Examples of use:
my $explained_commands_hash
= $converter->shared_conversion_state('explained_commands', {});
$explained_commands_hash->{'key'} = 'value';
my $foot_num_reference
= $converter->shared_conversion_state('footnote_number', 0);
${$foot_num_reference}++;
File: texi2any_api.info, Node: Translations Output and Customization, Next: Directions, Links, Labels and Files, Prev: Dynamic Conversion Information, Up: Top
13 Translations Output and Customization
****************************************
Translated strings can be specified in customization functions, for
@-commands without arguments (*note Simple Customization for Commands
Without Arguments::), for direction strings (*note Direction Strings
Customization::) and for specific elements headings such as footnotes,
contents or about (*note Special Elements Information Customization::).
Translated strings can also be inserted in the output in user-defined
customization functions, by using specific functions for
internationalization of strings, ‘gdt’ or ‘pgdt’.
It is possible to customize the translated strings, in order to
change the translations of the strings translated in the default case.
If new translated strings are added, it is even required to use
translated strings customization to add translations for the added
strings.
*Note (texinfo)Internationalization of Document Strings:: for
additional information on the default case.
* Menu:
* Internationalization of Strings Function::
* Translated Strings Customization::
* Translation Contexts::
File: texi2any_api.info, Node: Internationalization of Strings Function, Next: Translated Strings Customization, Up: Translations Output and Customization
13.1 Internationalization of Strings Function
=============================================
The subroutines ‘gdt’ or ‘pgdt’, are used for translated strings:
-- Function: $TRANSLATED_TREE = $CONVERTER->gdt ($STRING,
\%VARIABLES_HASH, $TRANSLATION_CONTEXT, $MODE)
-- Function: $TRANSLATED_TREE = $CONVERTER->pgdt ($TRANSLATION_CONTEXT,
$STRING, \%VARIABLES_HASH, $MODE)
$STRING is the string to be translated, \%VARIABLES_HASH is a hash
reference holding the variable parts of the translated string.
$TRANSLATION_CONTEXT is an optional translation context that limits
the search of the translated string to that context (*note
(gettext)Contexts::). The result returned is a perl Texinfo tree
in the default case.
$MODE is an optional string which may modify how the function
behaves. The possible values are:
‘translated_text’
In that case the string is not considered to be Texinfo, a
plain string that is returned after translation and
substitution. The substitutions may only be strings in that
case.
If called as ‘pgdt’, $TRANSLATION_CONTEXT is not optional and is
the first argument.
When the string is expanded as Texinfo, and converted to a Texinfo
tree in perl, the arguments are substituted; for example, ‘{arg_name}’
is replaced by the corresponding actual argument, which should be
Texinfo perl trees, Texinfo perl tree contents arrays or strings.
In the following example, ‘{date}’, ‘{program_homepage}’ and
‘{program}’ are the arguments of the string. Since they are used in
‘@uref’, their order in the formatted output depends on the formatting
and is not predictable. ‘{date}’, ‘{program_homepage}’ and ‘{program}’
are substituted after the expansion, which means that they should
already be Texinfo perl trees, Texinfo perl tree contents. A string is
turned into a Texinfo text element without type, with the string as
‘text’.
$converter->gdt('Generated @emph{@today{}} using '
.'@uref{{program_homepage}, @emph{{program}}}.',
{ 'program_homepage' => $converter->get_conf('PACKAGE_URL'),
'program' => { 'text' => $converter->get_conf('PROGRAM') }}));
In the example, the ‘$converter->get_conf('PACKAGE_URL')’ string is
turned into ‘{ 'text' => $converter->get_conf('PACKAGE_URL') }’.
An example of combining conversion with translation:
$converter->convert_tree($converter->gdt(
'{explained_string} ({explanation})',
{'explained_string' => {'type' => '_converted',
'text' => $result},
'explanation' => {'type' => '_converted',
'text' => $explanation_result}}),
"convert explained $cmdname");
In the default case, the ‘gdt’ function from the
‘Texinfo::Translations’ module is used for translated strings. It is
possible to use a user-defined function instead as seen next. *Note
(texi2any_internals)Texinfo::Translations:: for more on
‘Texinfo::Translations’.
In ‘texi2any’ code, ‘gdt’ is also used to mark translated strings for
tools extracting translatable strings to produce template files. ‘pgdt’
is used to mark translated string with a translation context associated.
File: texi2any_api.info, Node: Translated Strings Customization, Next: Translation Contexts, Prev: Internationalization of Strings Function, Up: Translations Output and Customization
13.2 Translated Strings Customization
=====================================
To customize strings translations, register the
‘format_translate_string’ function reference:
-- Function Reference: $TRANSLATED_TREE format_translate_string
($CONVERTER, $STRING, $LANG, \%VARIABLES_HASH,
$TRANSLATION_CONTEXT, $MODE)
$STRING is the string to be translated, $LANG is the language.
$TRANSLATION_CONTEXT is an optional translation context. $MODE is
an optional string which should modify how the function behaves.
The result returned should be a perl Texinfo tree in the default
case, or a string if $MODE is set to ‘translated_text’. The result
returned may also be ‘undef’, in which case the translation is done
as if the function reference had not been defined.
*Note Internationalization of Strings Function:: for more
information on strings translations function arguments.
The ‘replace_convert_substrings’ method of ‘Texinfo::Translations’
can be used to substitute \%VARIABLES_HASH and return a Texinfo
tree based on a translated string, taking into account $MODE (*note
Texinfo::Translations replace_convert_substrings:
(texi2any_internals)Texinfo::Translations $tree =
$object->replace_convert_substrings($translated_string,
$replaced_substrings, $mode).).
This function reference is not set in the default case, in the
default case the ‘gdt’ method from the ‘Texinfo::Translations’ module is
called (*note Internationalization of Strings Function::). *Note
Specific formating Functions:: for information on how to register and
get the function reference.
Here is an example with new translated strings added and definition
of ‘format_translate_string’ to translate the strings:
texinfo_register_no_arg_command_formatting('error', undef, undef,
undef, 'error-->');
my %translations = (
'fr' => {
'error-->' => {'' => 'erreur-->',},
# ...
},
'de' => {
'error-->' => {'' => 'Fehler-->',},
# ...
}
# ...
);
sub my_format_translate_string($$$;$$$)
{
my ($self, $string, $lang, $replaced_substrings,
$translation_context, $type) = @_;
$translation_context = '' if (!defined($translation_context));
if (exists($translations{$lang})
and exists($translations{$lang}->{$string})
and exists($translations{$lang}->{$string}
->{$translation_context})) {
my $translation = $translations{$lang}->{$string}
->{$translation_context};
return $self->replace_convert_substrings($translation,
$replaced_substrings, $type);
}
return undef;
}
texinfo_register_formatting_function('format_translate_string',
\&my_format_translate_string);
File: texi2any_api.info, Node: Translation Contexts, Prev: Translated Strings Customization, Up: Translations Output and Customization
13.3 Translation Contexts
=========================
Translation contexts may be set to avoid ambiguities for translated
strings, in particular when the strings are short (*note
(gettext)Contexts::). Translation contexts are set for translated
direction strings (*note Direction Strings::) and for special elements
headings (*note Special Elements Information Customization::).
For direction strings, the translation context is based on the
direction name (*note Directions::), with ‘direction’ prepended and
another string prepended, depending on the type of string:
‘button’
‘button label’ is prepended
‘description’
‘description’ is prepended
‘text’
‘string’ is prepended
For example, the ‘Top’ direction ‘button’ direction string
translation context is ‘Top direction button label’.
As an exception, the ‘This’ direction has ‘(current section)’
prepended to have a more explicit translation context. The ‘This’
direction ‘text’ direction string translation context is thus ‘This
(current section) direction string’.
For special element headings, the translation context is obtained by
prepending ‘section heading’ to the special element variety (*note Table
15.1: Special Elements Varieties.). For example, the ‘footnotes’
special element variety heading translation context is ‘footnotes
section heading’.
Here is an example, which could be used with the same function
registered as ‘format_translate_string’ as in the example above:
texinfo_register_direction_string_info('Forward', 'text', undef,
'Forward');
texinfo_register_special_element_info('heading', 'contents',
'The @emph{Table of Contents}');
my %translations = (
'fr' => {
'The @emph{Table of Contents}' => {'contents section heading'
=> '@result{} La @emph{Table des mati@`eres}',},
'Forward' => {'Forward direction string'
=> 'Vers l\'avant @result{}',},
}
...
);
Other translated strings may also be associated with translation
contexts. The translation template file
‘po_document/texinfo_document.pot’ in the source directory of Texinfo
contains the translated strings appearing in all the output formats.
File: texi2any_api.info, Node: Directions, Links, Labels and Files, Next: Customizing Footnotes, Tables of Contents and About, Prev: Translations Output and Customization, Up: Top
14 Directions, Links, Labels and Files
**************************************
Navigation headers, navigation panels, end or beginning of files,
‘@xref’ and similar @-commands output, ‘@menu’, ‘@node’, sectioning
commands, ‘@printindex’ and ‘@listoffloats’ formatting requires
directions, links, labels and files information.
* Menu:
* Getting Direction Strings::
* Target Commands Links, Texts and Associated Commands::
* Other Links, Headings and Associated Information for Special Elements::
* Elements and Links for Directions::
* Element Counters in Files::
File: texi2any_api.info, Node: Getting Direction Strings, Next: Target Commands Links, Texts and Associated Commands, Up: Directions, Links, Labels and Files
14.1 Getting Direction Strings
==============================
To get direction strings, use ‘direction_string’:
-- Function: $STRING = $CONVERTER->direction_string ($DIRECTION,
$STRING_TYPE, $CONTEXT)
Retrieve the $DIRECTION (*note Directions::) string of type
$STRING_TYPE (*note Direction Strings::). $CONTEXT is ‘normal’ or
‘string’. *Note Init File Expansion Contexts::. If $CONTEXT is
‘undef’, the ‘normal’ context is assumed. The string will be
translated if needed.
File: texi2any_api.info, Node: Target Commands Links, Texts and Associated Commands, Next: Other Links, Headings and Associated Information for Special Elements, Prev: Getting Direction Strings, Up: Directions, Links, Labels and Files
14.2 Target Commands Links, Texts and Associated Commands
=========================================================
Target @-commands are @-commands that are associated with an identifier
and can be linked to. They corresponds first to @-commands with unique
identifier used as labels, ‘@node’, ‘@anchor’ and ‘@float’. Sectioning
commands, index entries and footnotes are also associated to targets.
To get the unique Texinfo tree element corresponding to a label, use
‘label_command’:
-- Function: \%ELEMENT = $CONVERTER->label_command ($LABEL)
Return the element in the tree that $LABEL refers to.
To get the identifier, file name and href of tree elements that may
be used as link target, use ‘command_id’, ‘command_filename’ and
‘command_href’:
-- Function: $IDENTIFIER = $CONVERTER->command_id (\%TARGET_ELEMENT)
Returns the id specific of the \%TARGET_ELEMENT tree element.
-- Function: $FILE_NAME = $CONVERTER->command_filename
(\%TARGET_ELEMENT)
Returns the file name of the \%TARGET_ELEMENT tree element.
-- Function: $HREF = $CONVERTER->command_href (\%TARGET_ELEMENT,
$SOURCE_FILENAME, $SOURCE_COMMAND, $SPECIFIED_TARGET)
Return string for linking to \%TARGET_ELEMENT with ‘<a href>’.
$SOURCE_FILENAME is the file the link comes from. If not set, the
current file name is used. $SOURCE_COMMAND is an optional
argument, the @-command the link comes from. It is only used for
messages. $SPECIFIED_TARGET is an optional identifier that
overrides the target identifier if set.
To get the text of tree elements that may be used as link
description, use ‘command_text’:
-- Function: $RESULT = $CONVERTER->command_text (\%TARGET_ELEMENT,
$TYPE)
Return the information to be used for a hyperlink to
\%TARGET_ELEMENT. The information returned depends on $TYPE:
_text_
Return text.
_tree_
Return a Texinfo elements tree.
_tree_nonumber_
Return a Texinfo elements tree representing text without a
chapter number being included.
_string_
Return text in string context. *Note Init File Expansion
Contexts::.
To get the top level element and the tree unit element associated to
any Texinfo tree element, use ‘get_element_root_command_element’:
-- Function: \%TOP_LEVEL_ELEMENT, \%ELEMENT_UNIT =
$CONVERTER->get_element_root_command_element (\%ELEMENT)
Return the top level element and tree element unit a Texinfo tree
\%ELEMENT is in (*note Texinfo Tree Elements in User Defined
Functions::). Both the top level element and the tree element unit
may be undefined, depending on how the converter is called and on
the Texinfo tree. The top level element returned is also
determined by the customization variable ‘USE_NODES’. If
‘USE_NODES’ is set the ‘@node’ is preferred, otherwise the
sectioning command is preferred.
To obtain the top level command element associated with the target
element, either a ‘@node’ or a sectioning element, use
‘command_root_element_command’:
-- Function: \%TOP_LEVEL_ELEMENT =
$CONVERTER->command_root_element_command (\%TARGET_ELEMENT)
Return the top level element \%TARGET_ELEMENT is in.
To get the node element associated with the target element, use
‘command_node’:
-- Function: \%NODE_ELEMENT = $CONVERTER->command_node
(\%TARGET_ELEMENT)
Return the node element associated with \%TARGET_ELEMENT.
File: texi2any_api.info, Node: Other Links, Headings and Associated Information for Special Elements, Next: Elements and Links for Directions, Prev: Target Commands Links, Texts and Associated Commands, Up: Directions, Links, Labels and Files
14.3 Other Links, Headings and Associated Information for Special Elements
==========================================================================
To get the id of a footnote in the main document, use
‘footnote_location_target’:
-- Function: $TARGET = $CONVERTER->footnote_location_target
(\%FOOTNOTE_ELEMENT)
Return the id for the location of the footnote \%FOOTNOTE_ELEMENT
in the main document (where the footnote number or symbol appears).
To get an href to link to a footnote location in the main document,
use ‘footnote_location_href’:
-- Function: $HREF = $CONVERTER->footnote_location_href
(\%FOOTNOTE_ELEMENT, $SOURCE_FILENAME, $SPECIFIED_TARGET,
$TARGET_FILENAME)
Return string for linking to \%FOOTNOTE_ELEMENT location in the
main document with ‘<a href>’. $SOURCE_FILENAME is the file the
link comes from. If not set, the current file name is used.
$SPECIFIED_TARGET is an optional identifier that overrides the
target identifier if set. $TARGET_FILENAME is an optional file
name that overrides the file name href part if set.
*Note Target Commands Links, Texts and Associated Commands:: to get
link information for the location where footnote text is output.
To get id and link href of sectioning commands in table of contents
and short table of contents, use ‘command_contents_target’ and
‘command_contents_href’:
-- Function: $TARGET = $CONVERTER->command_contents_target
(\%SECTIONING_ELEMENT, $CONTENTS_OR_SHORTCONTENTS)
Returns the id for the location of \%SECTIONING_ELEMENT sectioning
element in the table of contents, if $CONTENTS_OR_SHORTCONTENTS is
‘contents’, or in the short table of contents, if
$CONTENTS_OR_SHORTCONTENTS is set to ‘shortcontents’ or
‘summarycontents’.
-- Function: $HREF = $CONVERTER->command_contents_href
(\%SECTIONING_ELEMENT, $CONTENTS_OR_SHORTCONTENTS,
$SOURCE_FILENAME)
Return string for linking to the \%SECTIONING_ELEMENT sectioning
element location in the table of contents, if
$CONTENTS_OR_SHORTCONTENTS is ‘contents’ or in the short table of
contents, if $CONTENTS_OR_SHORTCONTENTS is set to ‘shortcontents’
or ‘summarycontents’. $SOURCE_FILENAME is the file the link comes
from. If not set, the current file name is used.
To determine if a tree unit element is the top element, use
‘element_is_tree_unit_top’:
-- Function: $IS_TREE_UNIT_TOP = $CONVERTER->element_is_tree_unit_top
(\%ELEMENT)
Returns true if the \%ELEMENT Texinfo tree element is the tree unit
Top element (*note Output Element Units::) and is either associated
with the ‘@top’ sectioning command or with the ‘Top’ ‘@node’.
To get information on the special element variety associated with an
@-command command name, use ‘command_name_special_element_information’:
-- Function: ($SPECIAL_ELEMENT_VARIETY, \%SPECIAL_ELEMENT, $CLASS_BASE,
$SPECIAL_ELEMENT_DIRECTION) =
$CONVERTER->command_name_special_element_information
($COMMAND_NAME)
$COMMAND_NAME is an @-command name without the leading @. If the
$COMMAND_NAME is not associated with a special element, returns
‘undef’. Otherwise, return the $SPECIAL_ELEMENT_VARIETY (*note
Table 15.1: Special Elements Varieties.), the \%SPECIAL_ELEMENT
texinfo tree unit, a $CLASS_BASE string for HTML class attribute
and the $SPECIAL_ELEMENT_DIRECTION direction corresponding to that
special elements (*note Directions::).
In the current setup, special elements are associated with
‘@contents’, ‘@shortcontents’ and ‘@summarycontents’ and with
‘@footnote’.
File: texi2any_api.info, Node: Elements and Links for Directions, Next: Element Counters in Files, Prev: Other Links, Headings and Associated Information for Special Elements, Up: Directions, Links, Labels and Files
14.4 Elements and Links for Directions
======================================
*Note Directions:: for the list of directions.
To get the Texinfo tree unit special element associated with a
special element direction, such as ‘About’ or ‘Contents’, use
‘special_direction_element’:
-- Function: \%SPECIAL_ELEMENT = $CONVERTER->special_direction_element
($DIRECTION)
Return the special element associated with direction $DIRECTION, or
‘undef’ if the direction is not a special element direction or the
special element is not output.
To get the Texinfo tree unit element associated with other global
element directions, such as ‘Top’ or ‘Index’, use
‘global_direction_element’:
-- Function: \%ELEMENT = $CONVERTER->global_direction_element
($DIRECTION)
Return the Texinfo tree unit element corresponding to direction
$DIRECTION, or ‘undef’ if the direction is not a global direction.
To get link information for relative and global directions, use
‘from_element_direction’:
-- Function: $RESULT = $CONVERTER->from_element_direction ($DIRECTION,
$TYPE, $SOURCE_ELEMENT, $SOURCE_FILENAME, $SOURCE_COMMAND)
Return a string for linking to $DIRECTION, or the information to be
used for a hyperlink to $DIRECTION, depending on $TYPE. The
possible values for $TYPE are described in *note Element Direction
Information Type::.
$SOURCE_ELEMENT is the tree unit element the link comes from. If
not set, the current tree unit element is used. $SOURCE_FILENAME
is the file the link comes from. If not set, the current file name
is used. $SOURCE_COMMAND is an optional argument, the @-command
the link comes from. It is only used for messages.
File: texi2any_api.info, Node: Element Counters in Files, Prev: Elements and Links for Directions, Up: Directions, Links, Labels and Files
14.5 Element Counters in Files
==============================
The position of the tree unit element being formatted in its file or the
total number of elements output to a file is interesting, for instance
to format end of files, decide which navigation header or footer is
needed and whether a rule should be output.
To get information on tree elements unit counter in files, use
‘count_elements_in_filename’:
-- Function: $COUNT = $CONVERTER->count_elements_in_filename
($SPECIFICATION, $FILE_NAME)
Return tree unit element counter for $FILE_NAME, or ‘undef’ if the
counter does not exist. The counter returned depends on
$SPECIFICATION:
_current_
Return the number of unit elements associated with $FILE_NAME
having already been processed.
_remaining_
Return the number of unit elements associated with $FILE_NAME
that remains to be processed.
_total_
Return the total number of element units associated with the
file.
File: texi2any_api.info, Node: Customizing Footnotes, Tables of Contents and About, Next: Customizing HTML Footers, Headers and Navigation Panels, Prev: Directions, Links, Labels and Files, Up: Top
15 Customizing Footnotes, Tables of Contents and About
******************************************************
Some customization is specific for the different cases, especially when
the formatting is not done in a separate document unit (*note Output
Element Units::), but some customization is relevant for all the special
elements. The formatting of special elements bodies is handled the same
for all the special elements, when formatted as separate elements. To
specify a special element in those contexts, the special elements
varieties are used, as described in *note Table 15.1: Special Elements
Varieties.
Special Element Special Element Variety
----------------------------------------------------
Table of contents ‘contents’
Short table of contents ‘shortcontents’
Footnotes ‘footnotes’
About ‘about’
Table 15.1: Association of special elements names with their special
element variety
The variety of special elements is in the element ‘extra’ hash
‘special_element_variety’ key.
* Menu:
* Special Elements Information Customization::
* Customizing Footnotes::
* Contents and Short Table of Contents Customization::
* About Element Customization::
* Special Element Body Formatting Functions::
File: texi2any_api.info, Node: Special Elements Information Customization, Next: Customizing Footnotes, Up: Customizing Footnotes, Tables of Contents and About
15.1 Special Elements Information Customization
===============================================
The following items are common to all the special elements:
‘class’
String for special element HTML class attributes.
‘direction’
Direction corresponding to the special element. *Note
Directions::.
‘heading’
Special element heading Texinfo code.
‘heading_tree’
Special element heading Texinfo tree.
‘order’
Index determining the sorting order of special elements.
‘file_string’
File string portion prepended to the special element file names,
such as ‘_toc’.
‘target’
A string representing the target of the special element, typically
used as id attribute and in href attribute.
The heading string is set with ‘heading’, and should be a Texinfo
code string. ‘heading_tree’ cannot be set directly, but can be
retrieved. It is determined from ‘heading’ after translation and
conversion to a Texinfo tree.
To set the information, use ‘texinfo_register_special_element_info’
in an init file:
-- Function: texinfo_register_special_element_info ($item_type,
$special_element_variety, $value)
Set $ITEM_TYPE information for the special element variety
$SPECIAL_ELEMENT_VARIETY to $VALUE. $VALUE may be ‘undef’, or an
empty string, but only ‘heading’ and ‘target’ should be set to that
value as a non-empty value is needed for the other items for
formatting.
To retrieve the information for formatting, use
‘special_element_info’:
-- Function: $LIST_OR_VALUE = $CONVERTER->special_element_info
($ITEM_TYPE, $SPECIAL_ELEMENT_VARIETY)
$ITEM_TYPE is the type of information to be retrieved as described
above. If $SPECIAL_ELEMENT_VARIETY is ‘undef’, the list of the
special elements varieties with information for the $ITEM_TYPE is
returned. If $SPECIAL_ELEMENT_VARIETY is a special element
variety, the corresponding value is returned.
The value returned is translated and converted to a Texinfo tree
for ‘heading_tree’.
File: texi2any_api.info, Node: Customizing Footnotes, Next: Contents and Short Table of Contents Customization, Prev: Special Elements Information Customization, Up: Customizing Footnotes, Tables of Contents and About
15.2 Customizing Footnotes
==========================
‘NUMBER_FOOTNOTES’ and ‘NO_NUMBER_FOOTNOTE_SYMBOL’ customization
variables can be used to change the footnotes formatting. Redefinition
of ‘@footnote’ conversion reference and footnote formatting references
is needed for further customization.
‘@footnote’ @-commands appearing in the Texinfo elements tree are
converted like any other elements associated with @-commands (*note
Command Tree Element Conversion Functions::). It is therefore possible
to redefine their formatting by registering a user defined function.
To pass information on footnotes between the conversion function
processing the ‘@footnote’ command at the location they appear in the
document and the functions formatting their argument elsewhere, two
functions are available: ‘register_footnote’ to be called where they
appear in the document, and ‘get_pending_footnotes’ to be called where
they are formatted.
-- Function: $CONVERTER->register_footnote (\%element, $footnote_id,
$foot_in_doc_id, $number_in_doc, $footnote_location_filename,
$multi_expanded_region)
\%ELEMENT is the footnote texinfo tree element. $FOOTNOTE_ID is
the identifier for the location where the footnote arguments are
expanded. $FOOT_IN_DOC_ID is the identifier for the location where
the footnote appears in the document. $NUMBER_IN_DOC is the symbol
used to format the footnote in the document.
$FOOTNOTE_LOCATION_FILENAME is the filename of the tree unit
element of the footnote in the document. If the footnote appears
in a region that is expanded multiple times, the information on the
expansion is $MULTI_EXPANDED_REGION (*note Dynamic Converter
Formatting Information::).
‘register_footnote’ is normally called in the ‘@footnote’ @-command
conversion function reference. The default conversion function also
call ‘command_href’ to link to the location where the footnote text will
be expanded (*note Target Commands Links, Texts and Associated
Commands::).
-- Function: @PENDING_FOOTNOTES_INFORMATION =
$CONVERTER->get_pending_footnotes ()
Returns in @PENDING_FOOTNOTES_INFORMATION the information gathered
in ‘register_footnote’. Each of the array element in
@PENDING_FOOTNOTES_INFORMATION is an array reference containing the
arguments of ‘register_footnote’ in the same order.
The formatting of footnotes content is done by the
‘format_footnotes_sequence’ formatting reference (*note Specific
formating Functions::):
-- Function Reference: $FOOTNOTES_SEQUENCE format_footnotes_sequence
($CONVERTER)
Formats and returns the footnotes that need to be formatted. This
function normally calls ‘get_pending_footnotes’. The default
function also calls ‘footnote_location_href’ (*note Other Links,
Headings and Associated Information for Special Elements::) to link
to the location in the document where the footnote appeared.
If footnotes are in a separate element unit (*note Output Element
Units::), the default footnote special element body formatting function
calls ‘format_footnotes_sequence’ (*note Special Element Body Formatting
Functions::).
If the footnotes are not in a separate element unit, or there is no
separate element because there is only one tree unit element or no tree
unit element, the ‘format_footnotes_segment’ formatting reference is
called when pending footnotes need to be formatted. This function
reference can be replaced by a user defined function.
-- Function Reference: $FOOTNOTES_SEGMENT format_footnotes_segment
($CONVERTER)
Returns the footnotes formatted. In the default case, the function
reference calls ‘format_footnotes_sequence’ and also sets up a
header with ‘format_heading_text’ (*note Basic Formatting
Customization::), using the customization variables
‘FOOTNOTE_END_HEADER_LEVEL’ and the special ‘footnotes’ element
‘heading’ information (*note Special Elements Information
Customization::).
File: texi2any_api.info, Node: Contents and Short Table of Contents Customization, Next: About Element Customization, Prev: Customizing Footnotes, Up: Customizing Footnotes, Tables of Contents and About
15.3 Contents and Short Table of Contents Customization
=======================================================
To begin with, the table of contents and short table of contents can be
made to appear at different locations in the document.
By default, the customization variable ‘CONTENTS_OUTPUT_LOCATION’ is
set to ‘after_top’, specifying that the tables of contents are output at
the end of the ‘@top’ section, to have the main location for navigation
in the whole document early on. This is in line with ‘FORMAT_MENU’ set
to ‘sectiontoc’ with sectioning command being used in HTML for
navigation rather than menus.
If ‘CONTENTS_OUTPUT_LOCATION’ is set to ‘inline’, the tables of
content are output where the corresponding @-command, for example
‘@contents’, is set. This behavior is consistent with ‘texi2dvi’.
If ‘CONTENTS_OUTPUT_LOCATION’ is set to ‘separate_element’, the
tables of contents are output in separate elements, either at the end of
the document if the output is unsplit or in separate files if not. This
makes sense when menus are used for navigation with ‘FORMAT_MENU’ set to
‘menu’.
If ‘CONTENTS_OUTPUT_LOCATION’ is set to ‘after_title’ the tables of
contents are merged into the title material, which in turn is not output
by default; *note HTML Title Page Customization::.
Next, the following variables allow for some useful control of the
formatting of table of contents and short table of contents:
‘BEFORE_TOC_LINES’
Inserted before the table of contents text.
‘AFTER_TOC_LINES’
Inserted after the table of contents text.
‘BEFORE_SHORT_TOC_LINES’
Inserted before the short table of contents text.
‘AFTER_SHORT_TOC_LINES’
Inserted after the short table of contents text.
Additional customization variables ‘SHORT_TOC_LINK_TO_TOC’ and
‘NUMBER_SECTIONS’ can be used to change the formatting of table of
contents.
Finally, the following function reference provides even more control
over the table of contents and short table of contents formatting
reference:
-- Function Reference: $TOC_RESULT format_contents ($CONVERTER,
$COMMAND_NAME, \%ELEMENT, $FILENAME)
$COMMAND_NAME is the @-command name without leading @, should be
‘contents’, ‘shortcontents’ or ‘summarycontents’. \%ELEMENT is
optional. It corresponds to the $COMMAND_NAME Texinfo tree
element, but it is only set if ‘format_contents’ is called from a
Texinfo tree element conversion, and not as a special element body
formatting. $FILENAME is optional and should correspond to the
filename where the formatting happens, for links.
In the default function, structuring information is used to format
the table of contents (*note Conversion General Information::), and
‘command_contents_href’ (*note Other Links, Headings and Associated
Information for Special Elements::) and ‘command_href’ (*note
Target Commands Links, Texts and Associated Commands::) are used
for links. If $FILENAME is unset, the current file name is used,
using ‘$converter->get_info('current_filename')’.
Return formatted table of contents or short table of contents.
If contents are in a separate element unit (*note Output Element
Units::), the default contents and shortcontents special element body
formatting function calls ‘format_contents’ (*note Special Element Body
Formatting Functions::). Otherwise, ‘format_contents’ is called in the
conversion of heading @-command, in title page formatting, and in
‘@contents’ conversion function, depending on the
‘CONTENTS_OUTPUT_LOCATION’ value.
File: texi2any_api.info, Node: About Element Customization, Next: Special Element Body Formatting Functions, Prev: Contents and Short Table of Contents Customization, Up: Customizing Footnotes, Tables of Contents and About
15.4 About Element Customization
================================
The default About element has an explanation of the buttons used in the
document, controlled by ‘SECTION_BUTTONS’. The formatting of this is
influenced by the ‘text’, ‘description’ and ‘example’ direction strings
(*note Direction Strings::) and by ‘ACTIVE_ICONS’ (*note Simple
Navigation Panel Customization::).
‘PROGRAM_NAME_IN_ABOUT’ can also be used to change the beginning of
the About element formatting.
If the above is not enough and you want to control exactly the
formatting of the about element, the ‘about’ special element body
reference function may be overridden (*note Special Element Body
Formatting Functions::).
File: texi2any_api.info, Node: Special Element Body Formatting Functions, Prev: About Element Customization, Up: Customizing Footnotes, Tables of Contents and About
15.5 Special Element Body Formatting Functions
==============================================
In addition to the formatting possibilities available with the default
special element formatting presented previously, it is also possible to
control completely how a separate special element is formatted.
To register body formating user defined functions for special element
(*note Output Element Units::), the special elements varieties are used,
as described in *note Table 15.1: Special Elements Varieties. Special
element body formatting user defined functions are registered with
‘texinfo_register_formatting_special_element_body’:
-- Function: texinfo_register_formatting_special_element_body
($special_element_variety, \&handler)
$SPECIAL_ELEMENT_VARIETY is the element variety (*note Table 15.1:
Special Elements Varieties.). \&HANDLER is the user defined
function reference.
The call of the user defined functions is:
-- Function Reference: $TEXT special_element_body ($CONVERTER,
$SPECIAL_ELEMENT_VARIETY, \%ELEMENT)
$CONVERTER is a converter object. $SPECIAL_ELEMENT_VARIETY is the
element variety. \%ELEMENT is the Texinfo element.
The $TEXT returned is the formatted special element body.
To call a special element body formatting function from user defined
code, the function reference should first be retrieved using
‘special_element_body_formatting’:
-- Function: \&SPECIAL_ELEMENT_BODY_FORMATTING =
$CONVERTER->special_element_body_formatting
($SPECIAL_ELEMENT_VARIETY)
$SPECIAL_ELEMENT_VARIETY is the special element variety. Returns
the conversion function reference for $VARIETY, or ‘undef’ if there
is none, which should not happen for the special elements described
in this manual.
For example:
my $footnotes_element_body
= &{$converter->special_element_body_formatting('footnotes')}(
$converter, 'footnotes', $element);
It is possible to have access to the default conversion function
reference. The function used is:
-- Function: \&DEFAULT_SPECIAL_ELEMENT_BODY_FORMATTING =
$CONVERTER->defaults_special_element_body_formatting
($SPECIAL_ELEMENT_VARIETY)
$SPECIAL_ELEMENT_VARIETY is the special element variety. Returns
the default conversion function reference for
$SPECIAL_ELEMENT_VARIETY, or ‘undef’ if there is none, which should
not happen for the special elements described in this manual.
*Note Customizing Footnotes:: for more on footnotes formatting.
*Note Contents and Short Table of Contents Customization:: for more on
the ‘contents’ and ‘shortcontents’ formatting. *Note About Element
Customization:: for more on the ‘about’ special element body formatting.
File: texi2any_api.info, Node: Customizing HTML Footers, Headers and Navigation Panels, Next: Heading Commands and Tree Elements Formatting, Prev: Customizing Footnotes, Tables of Contents and About, Up: Top
16 Customizing HTML Footers, Headers and Navigation Panels
**********************************************************
‘texi2any’ provides for customization of the HTML page headers, footers,
and navigation panel. (These are unrelated to the headings and
"footings" produced in TeX output; *note Page Headings:
(texinfo)Headings.)
In the event that your needs are not met by changing the navigation
buttons (*note Simple Navigation Panel Customization::), you can
completely control the formatting of navigation panels by redefining
function references. *Note Specific formating Functions:: for
information on how to register the function references.
In a nutshell, element header and footer formatting function
determines the button directions list to use and calls navigation header
formatting. The navigation header formatting adds some formatting if
needed, but mostly calls the navigation panel formatting. The
navigation panel can call buttons formatting.
* Menu:
* Navigation Panel and Navigation Header Formatting::
* Element Header and Footer Formatting::
File: texi2any_api.info, Node: Navigation Panel and Navigation Header Formatting, Next: Element Header and Footer Formatting, Up: Customizing HTML Footers, Headers and Navigation Panels
16.1 Navigation Panel and Navigation Header Formatting
======================================================
All the formatting functions take a converter object as first argument.
The overall display of navigation panels is controlled via this
function reference, ‘format_navigation_header’:
-- Function Reference: $NAVIGATION_TEXT format_navigation_header
($CONVERTER, \@BUTTONS, $COMMAND_NAME, \%ELEMENT)
\@BUTTONS is an array reference holding the specification of the
buttons for the navigation panel (*note Simple Navigation Panel
Customization::). \%ELEMENT is the element in which the navigation
header is formatted. $COMMAND_NAME is the associated command
(sectioning command or ‘@node’). It may be ‘undef’ for special
elements.
Returns the formatted navigation header and panel. The navigation
panel itself can be formatted with a call to
‘&{$self->formatting_function('format_navigation_panel')}’.
The customization variable ‘VERTICAL_HEAD_NAVIGATION’ should be
relevant.
The navigation panel display is controlled via
‘format_navigation_panel’:
-- Function Reference: $NAVIGATION_TEXT format_navigation_panel
($CONVERTER, \@BUTTONS, $COMMAND_NAME, \%ELEMENT, $VERTICAL)
\@BUTTONS is an array reference holding the specification of the
buttons for that navigation panel. \%ELEMENT is the element in
which the navigation header is formatted. $COMMAND_NAME is the
associated command (sectioning command or ‘@node’). It may be
‘undef’ for special elements. $VERTICAL is true if the navigation
panel should be vertical.
Returns the formatted navigation panel in $NAVIGATION_TEXT. The
buttons in the navigation panel can be formatted with a call to
‘&{$self->formatting_function('format_button')}’.
The function reference ‘format_button’ does the formatting of one
button:
-- Function Reference: $FORMATTED_BUTTON format_button ($CONVERTER,
$BUTTON, $SOURCE_COMMAND)
$BUTTON holds the specification of the button (*note Buttons
Display::). $SOURCE_COMMAND is an optional argument, the @-command
the link comes from.
Returns the formatted result in $FORMATTED_BUTTON.
The buttons images can be formatted with ‘format_button_icon_img’
(*note Basic Formatting Customization::).
Customization information described in *note Simple Navigation
Panel Customization:: such as ‘BUTTONS_TEXT’, ‘BUTTONS_NAME’,
‘BUTTONS_GOTO’, ‘USE_ACCESSKEY’, ‘USE_REL_REV’ and ‘BUTTONS_REL’
can be relevant for the formatting of a button.
File: texi2any_api.info, Node: Element Header and Footer Formatting, Prev: Navigation Panel and Navigation Header Formatting, Up: Customizing HTML Footers, Headers and Navigation Panels
16.2 Element Header and Footer Formatting
=========================================
All the formatting functions take a converter object as first argument.
By default, the function associated with ‘format_element_header’
formats the header and navigation panel of a tree unit element.
-- Function Reference: $FORMATTED_HEADER format_element_header
($CONVERTER, $COMMAND_NAME, \%ELEMENT, \%TREE_UNIT_ELEMENT)
\%ELEMENT is the element in which the navigation header is
formatted (sectioning command, ‘@node’ or special element).
$COMMAND_NAME is the associated command name. It may be ‘undef’
for special elements. \%TREE_UNIT_ELEMENT is the associated tree
unit element (*note Texinfo Tree Elements in User Defined
Functions::).
Returns the formatted navigation header and panel.
In the default code, the function reference select a buttons list
(*note Simple Navigation Panel Customization::). The navigation
header can then be formatted with a call to
‘&{$self->formatting_function('format_navigation_header')}’. It is
also possible to format directly the navigation panel, depending on
customization variables values and location in file.
Similarly, the function associated with ‘format_element_footer’
formats the footer and navigation panel of a tree unit element.
-- Function Reference: $FORMATTED_FOOTER format_element_footer
($CONVERTER, $TREE_UNIT_TYPE, \%TREE_UNIT_ELEMENT, $CONTENT,
$COMMAND)
\%TREE_UNIT_ELEMENT is the tree unit element element in which the
navigation footer is formatted. $TREE_UNIT_TYPE is the associated
type. $CONTENT is the formatted element content. $COMMAND is an
optional argument, the @-command associated with the
\%TREE_UNIT_ELEMENT.
Returns the formatted navigation footer and panel.
In the default code, the function reference select a buttons list
(*note Simple Navigation Panel Customization::). The navigation
header can then be formatted with a call to
‘&{$self->formatting_function('format_navigation_header')}’.
Many customization variables may be interesting for the footer
formatting, such as ‘SPLIT’, ‘HEADERS’, ‘DEFAULT_RULE’, ‘BIG_RULE’,
‘WORDS_IN_PAGE’ or ‘PROGRAM_NAME_IN_FOOTER’.
File: texi2any_api.info, Node: Heading Commands and Tree Elements Formatting, Next: Beginning and Ending Files, Prev: Customizing HTML Footers, Headers and Navigation Panels, Up: Top
17 Heading Commands and Tree Elements Formatting
************************************************
The customization variables ‘CONTENTS_OUTPUT_LOCATION’,
‘CHAPTER_HEADER_LEVEL’, ‘TOC_LINKS’, ‘USE_NEXT_HEADING_FOR_LONE_NODE’
and ‘FORMAT_MENU’ may be used to change the sectioning commands
conversion. *Note (texinfo)HTML Customization Variables::.
‘@node’ and sectioning default conversion function call
‘format_heading_text’ (*note Basic Formatting Customization::) and
‘format_element_header’ (*note Element Header and Footer Formatting::),
as well as functions opening and closing sectioning commands extent
(*note Opening and Closing Sectioning Commands Extent::). The ‘@node’
and sectioning elements are formatted like any other elements associated
with @-commands. The corresponding function references can therefore be
replaced by user defined functions for a precise control of conversion
(*Note Command Tree Element Conversion Functions::).
Tree unit elements default conversion involves calling the formatting
reference ‘format_element_footer’ (*note Element Header and Footer
Formatting::). The conversion for these elements with type ‘unit’ can
be be replaced by user defined functions for a precise control of
conversion (*note Type Tree Element Conversion Functions::).
Special elements conversion is achieved by calling
‘special_element_body_formatting’ (*note Special Element Body Formatting
Functions::), ‘format_navigation_header’ (*note Navigation Panel and
Navigation Header Formatting::), ‘format_heading_text’ (*note Basic
Formatting Customization::) and ‘format_element_footer’ (*note Element
Header and Footer Formatting::). The conversion for these elements with
type ‘special_element_type’ can be be replaced by user defined functions
for a precise control of conversion (*note Type Tree Element Conversion
Functions::).
File: texi2any_api.info, Node: Beginning and Ending Files, Next: Titlepage, CSS and Redirection Files, Prev: Heading Commands and Tree Elements Formatting, Up: Top
18 Beginning and Ending Files
*****************************
The end of file (footers) formatting function reference is called from
the converter after all the element units in the file have been
converted. The beginning of file (headers) formatting function
reference is called right after the footers formatting function
reference.
*Note Specific formating Functions:: for information on how to
register and get the functions references.
* Menu:
* Customizing HTML File Beginning::
* Customizing HTML File End::
File: texi2any_api.info, Node: Customizing HTML File Beginning, Next: Customizing HTML File End, Up: Beginning and Ending Files
18.1 Customizing HTML File Beginning
====================================
You can set the variable ‘DOCTYPE’ to replace the default. the
‘DOCTYPE’ is output at the very beginning of each output file.
You can define the variable ‘EXTRA_HEAD’ to add text within the
‘<head>’ HTML element. Similarly, the value of ‘AFTER_BODY_OPEN’ is
added just after ‘<body>’ is output. These variables are empty by
default.
The ‘<body>’ element attributes may be set by defining the
customization variable ‘BODYTEXT’.
By default, the encoding name from ‘ENCODING_NAME’ is used. If this
variable is not defined, it is automatically determined.
A date is output in the header if ‘DATE_IN_HEADER’ is set.
The description from ‘@documentdescription’ (or a value set as a
customization variable) is used in the header (*note
(texinfo)@documentdescription::).
‘<link>’ elements are used in the header if ‘USE_LINKS’ is set, in
which case ‘LINKS_BUTTONS’ determines which links are used and
‘BUTTONS_REL’ determines the link type associated with the ‘rel’
attribute. *Note Simple Navigation Panel Customization::.
You can set ‘HTML_ROOT_ELEMENT_ATTRIBUTES’ to add attributes to the
‘<html>’ element.
The customization variables ‘SECTION_NAME_IN_TITLE’,
‘PACKAGE_AND_VERSION’, ‘PACKAGE_URL’ and other similar variables,
‘HTML_MATH’ and ‘INFO_JS_DIR’ may also be used to change the page header
formatting. *Note (texinfo)HTML Customization Variables::.
The following function references give full control over the page
header formatting done at the top of each HTML output file.
-- Function Reference: $FILE_BEGIN format_begin_file ($CONVERTER,
$FILENAME, \%TREE_UNIT_ELEMENT)
$FILENAME is the name of the file output. \%TREE_UNIT_ELEMENT is
the first tree unit element of the file. This function should
print the page header, in HTML, including the ‘<body>’ element.
File: texi2any_api.info, Node: Customizing HTML File End, Prev: Customizing HTML File Beginning, Up: Beginning and Ending Files
18.2 Customizing HTML File End
==============================
You can define the variable ‘PRE_BODY_CLOSE’ to add text just before the
HTML ‘</body>’ element. Nothing is added by default.
If ‘PROGRAM_NAME_IN_FOOTER’ is set, the date and name of the program
that generated the output are output in the footer.
The customization variables ‘JS_WEBLABELS’ and ‘JS_WEBLABELS_FILE’
are also used in the page footer formatting. *Note (texinfo)HTML
Customization Variables::.
The ‘format_end_file’ function reference give full control over the
page footer formatting done at the bottom of each HTML output file.
-- Function Reference: $FILE_END format_end_file ($CONVERTER,
$FILENAME, \%TREE_UNIT_ELEMENT)
$FILENAME is the name of the file output. \%TREE_UNIT_ELEMENT is
the last output unit of the file. This function should print the
page footer, including the ‘</body>’ element.
File: texi2any_api.info, Node: Titlepage, CSS and Redirection Files, Next: Specific Functions for Specific Elements, Prev: Beginning and Ending Files, Up: Top
19 Titlepage, CSS and Redirection Files
***************************************
* Menu:
* HTML Title Page Customization::
* Customizing CSS::
* Customizing Node Redirection Pages::
File: texi2any_api.info, Node: HTML Title Page Customization, Next: Customizing CSS, Up: Titlepage, CSS and Redirection Files
19.1 HTML Title Page Customization
==================================
If ‘SHOW_TITLE’ is not set, no title is output. ‘SHOW_TITLE’ is ‘undef’
in the default case. If ‘undef’, ‘SHOW_TITLE’ is set if
‘NO_TOP_NODE_OUTPUT’ is set. The "title page" is used to format the
HTML title if ‘USE_TITLEPAGE_FOR_TITLE’ is set, otherwise the
‘simpletitle’ is used. ‘USE_TITLEPAGE_FOR_TITLE’ is set in the default
case. *Note (texinfo)HTML Customization Variables::.
The following functions references provides full control on the title
and "title page" formatting:
-- Function Reference: $TITLE_TITLEPAGE format_title_titlepage
($CONVERTER)
Returns the formatted title or "title page" text.
In the default case, return nothing if ‘SHOW_TITLE’ is not set,
return the output of ‘format_titlepage’ if
‘USE_TITLEPAGE_FOR_TITLE’ is set, and otherwise output a simple
title based on ‘simpletitle’.
-- Function Reference: $TITLE_PAGE format_titlepage ($CONVERTER)
Returns the formatted "title page" text.
In the default case, the ‘@titlepage’ is used if found in global
information, otherwise ‘simpletitle’ is used (*note Conversion
General Information::).
File: texi2any_api.info, Node: Customizing CSS, Next: Customizing Node Redirection Pages, Prev: HTML Title Page Customization, Up: Titlepage, CSS and Redirection Files
19.2 Customizing the CSS lines
==============================
*Note Simple Customization of CSS:: for information on CSS
customization.
The CSS ELEMENT.CLASS that appeared in a file, gathered through
‘html_attribute_class’ calls (*note Formatting HTML Element with
Classes::) are available through the ‘html_get_css_elements_classes’
function:
-- Function: @CSS_ELEMENT_CLASSES =
$CONVERTER->html_get_css_elements_classes ($FILE_NAME)
Returns an array containing ‘element.class’ pairs of elements and
classes appearing in $FILE_NAME.
It is possible to change completely how CSS lines are generated by
redefining the following function reference:
-- Function Reference: $CSS_LINES format_css_lines ($CONVERTER,
$FILE_NAME)
This function returns the CSS lines and ‘<script>’ HTML element for
$FILE_NAME.
In the default case, the function reference uses ‘CSS_REFS’
corresponding to command-line ‘--css-ref’,
‘html_get_css_elements_classes’ and ‘css_get_info’ (*note Simple
Customization of CSS::) to determine the CSS lines.
File: texi2any_api.info, Node: Customizing Node Redirection Pages, Prev: Customizing CSS, Up: Titlepage, CSS and Redirection Files
19.3 Customizing Node Redirection Pages
=======================================
Node redirection pages are output if ‘NODE_FILES’ is set (*note
(texinfo)Invoking texi2any::).
It is possible to change completely how node redirection pages are
generated by redefining the following function reference:
-- Function Reference: $NODE_REDIRECTION_FILE_CONTENT
format_node_redirection_page ($CONVERTER, \%ELEMENT)
\%ELEMENT is a node element needing a redirection page. A
redirection page is needed if the node file name is not the file
name expected for HTML cross manual references (*note (texinfo)HTML
Xref::).
Returns the content of the node redirection file.
File: texi2any_api.info, Node: Specific Functions for Specific Elements, Next: Functions Index, Prev: Titlepage, CSS and Redirection Files, Up: Top
Appendix A Specific Functions for Specific Elements
***************************************************
Links on Texinfo perl modules functions or descriptions of functions
that can be used for specific elements formatting:
‘@today’
*Note Texinfo::Convert::Utils::expand_today:
(texi2any_internals)Texinfo::Convert::Utils $tree =
expand_today($converter).
‘@verbatiminclude’
*Note Texinfo::Convert::Utils::expand_verbatiminclude:
(texi2any_internals)Texinfo::Convert::Utils $tree =
expand_verbatiminclude($registrar, $configuration_information,
$verbatiminclude).
‘@def*’ @-commands
*Note Texinfo::Convert::Utils::definition_arguments_content:
(texi2any_internals)Texinfo::Convert::Utils $arguments =
definition_arguments_content($element). *Note
Texinfo::Convert::Utils::definition_category_tree:
(texi2any_internals)Texinfo::Convert::Utils $tree =
definition_category_tree($converter, $def_line).
‘@float’
*Note Texinfo::Convert::Converter::float_name_caption:
(texi2any_internals)Texinfo::Convert::Converter ($caption,
$prepended) = $converter->float_name_caption ($float). Can be
called as ‘$converter->float_name_caption’.
accent @-commands
*Note Texinfo::Convert::Converter::xml_accent:
(texi2any_internals)Texinfo::Convert::Converter $result =
xml_accent($text, $accent_command, $in_upper_case,
$use_numeric_entities). Can be called as ‘$converter->xml_accent’.
*Note Texinfo::Convert::Converter::xml_numeric_entity_accent:
(texi2any_internals)Texinfo::Convert::Converter $result =
xml_numeric_entity_accent($accent_command_name, $text).
*Note Texinfo::Convert::Converter::convert_accents:
(texi2any_internals)Texinfo::Convert::Converter $result =
$converter->convert_accents($accent_command, \&format_accents,
$in_upper_case).
text element
*Note
Texinfo::Convert::Converter::xml_format_text_with_numeric_entities:
(texi2any_internals)Texinfo::Convert::Converter $formatted_text =
$converter->xml_format_text_with_numeric_entities($text). Can be
called as ‘$converter->xml_format_text_with_numeric_entities’.
‘@item’ in ‘@table’ and similar @-commands
*Note Texinfo::Convert::Converter::table_item_content_tree:
(texi2any_internals)Texinfo::Convert::Converter $table_item_tree =
$converter->table_item_content_tree($element, $contents). Can be
called as ‘$converter->table_item_content_tree’.
‘@*index’ ‘@subentry’
*Note Texinfo::Convert::Converter::comma_index_subentries_tree:
(texi2any_internals)Texinfo::Convert::Converter $contents_array
$converter->comma_index_subentries_tree($entry). Can be called as
‘$converter->comma_index_subentries_tree’.
global informative commands (‘@contents’, ‘@footnotestyle’ ...)
*Note Texinfo::Common::set_informative_command_value:
(texi2any_internals)Texinfo::Common
set_informative_command_value($configuration_information,
$element).
heading commands, such as ‘@subheading’
*Note Texinfo::Common::section_level:
(texi2any_internals)Texinfo::Common $level =
section_level($section). This function would work for sectioning
commands too, but for sectioning commands,
‘section->{'structure'}->{'section_level'}’ can also be used.
*Note Texinfo Tree Elements in User Defined Functions::.
sectioning commands
*Note Texinfo::Structuring::section_level_adjusted_command_name:
(texi2any_internals)Texinfo::Structuring $command_name =
section_level_adjusted_command_name($element).
‘@itemize’
‘@itemize’ normally have an @-command as argument. If, instead,
the argument is some Texinfo code,
‘html_convert_css_string_for_list_mark’ can be used to convert that
argument to text usable in CSS style specifications.
-- Function: $TEXT_FOR_CSS =
$CONVERTER->html_convert_css_string_for_list_mark
(\%ELEMENT, $EXPLANATION)
\%ELEMENT is the Texinfo element that is converted to CSS
text. In general, it is ‘$itemize->{'args'}->[0]’, with
‘$itemize’ an ‘@itemize’ Texinfo tree element. $EXPLANATION
is an optional string describing what is being done that can
be useful for debugging.
Returns \%ELEMENT formatted as text suitable for CSS.
The ‘Texinfo::Convert::NodeNameNormalization’ converter, used for
normalization of labels, exports functions that can be used on Texinfo
elements trees to obtain strings that are unique and can be used in
attributes. *Note
(texi2any_internals)Texinfo::Convert::NodeNameNormalization::.
File: texi2any_api.info, Node: Functions Index, Next: Variables Index, Prev: Specific Functions for Specific Elements, Up: Top
Appendix B Functions Index
**************************
[index ]
* Menu:
* $CONVERTER->associate_pending_formatted_inline_content: Setting Up Content for the Next Text Container.
(line 59)
* $CONVERTER->cancel_pending_formatted_inline_content: Setting Up Content for the Next Text Container.
(line 31)
* $CONVERTER->close_html_lone_element: Closing Lone HTML Element.
(line 10)
* $CONVERTER->close_registered_sections_level: Opening and Closing Sectioning Commands Extent.
(line 29)
* $CONVERTER->command_contents_href: Other Links, Headings and Associated Information for Special Elements.
(line 42)
* $CONVERTER->command_contents_target: Other Links, Headings and Associated Information for Special Elements.
(line 34)
* $CONVERTER->command_conversion: Command Tree Element Conversion Functions.
(line 86)
* $CONVERTER->command_filename: Target Commands Links, Texts and Associated Commands.
(line 24)
* $CONVERTER->command_href: Target Commands Links, Texts and Associated Commands.
(line 28)
* $CONVERTER->command_id: Target Commands Links, Texts and Associated Commands.
(line 21)
* $CONVERTER->command_name_special_element_information: Other Links, Headings and Associated Information for Special Elements.
(line 64)
* $CONVERTER->command_node: Target Commands Links, Texts and Associated Commands.
(line 84)
* $CONVERTER->command_root_element_command: Target Commands Links, Texts and Associated Commands.
(line 77)
* $CONVERTER->command_text: Target Commands Links, Texts and Associated Commands.
(line 40)
* $CONVERTER->convert_tree: Texinfo Tree Conversion Functions.
(line 12)
* $CONVERTER->convert_tree_new_formatting_context: Texinfo Tree Conversion Functions.
(line 35)
* $CONVERTER->count_elements_in_filename: Element Counters in Files.
(line 14)
* $CONVERTER->css_add_info: Simple Customization of CSS.
(line 23)
* $CONVERTER->css_get_info: Simple Customization of CSS.
(line 22)
* $CONVERTER->default_command_conversion: Command Tree Element Conversion Functions.
(line 101)
* $CONVERTER->default_command_open: Command Tree Element Opening Functions.
(line 25)
* $CONVERTER->default_formatting_function: Specific formating Functions.
(line 25)
* $CONVERTER->default_type_conversion: Type Tree Element Conversion Functions.
(line 37)
* $CONVERTER->default_type_open: Type Tree Element Opening Functions.
(line 25)
* $CONVERTER->defaults_special_element_body_formatting: Special Element Body Formatting Functions.
(line 50)
* $CONVERTER->direction_string: Getting Direction Strings.
(line 8)
* $CONVERTER->document_error: Error Reporting in User Defined Functions.
(line 13)
* $CONVERTER->document_warn: Error Reporting in User Defined Functions.
(line 14)
* $CONVERTER->element_is_tree_unit_top: Other Links, Headings and Associated Information for Special Elements.
(line 55)
* $CONVERTER->encoded_output_file_name: Encoding File Path Strings.
(line 15)
* $CONVERTER->footnote_location_href: Other Links, Headings and Associated Information for Special Elements.
(line 17)
* $CONVERTER->footnote_location_target: Other Links, Headings and Associated Information for Special Elements.
(line 9)
* $CONVERTER->force_conf: Conversion Customization Variables.
(line 67)
* $CONVERTER->formatting_function: Specific formating Functions.
(line 17)
* $CONVERTER->from_element_direction: Elements and Links for Directions.
(line 30)
* $CONVERTER->gdt: Internationalization of Strings Function.
(line 8)
* $CONVERTER->get_associated_formatted_inline_content: Setting Up Content for the Next Text Container.
(line 63)
* $CONVERTER->get_conf: Conversion Customization Variables.
(line 28)
* $CONVERTER->get_element_root_command_element: Target Commands Links, Texts and Associated Commands.
(line 62)
* $CONVERTER->get_file_information: Associating Information to an Output File.
(line 15)
* $CONVERTER->get_info: Conversion General Information.
(line 18)
* $CONVERTER->get_pending_footnotes: Customizing Footnotes.
(line 43)
* $CONVERTER->get_pending_formatted_inline_content: Setting Up Content for the Next Text Container.
(line 43)
* $CONVERTER->global_direction_element: Elements and Links for Directions.
(line 22)
* $CONVERTER->html_attribute_class: Formatting HTML Element with Classes.
(line 9)
* $CONVERTER->html_convert_css_string_for_list_mark: Specific Functions for Specific Elements.
(line 94)
* $CONVERTER->html_get_css_elements_classes: Customizing CSS. (line 14)
* $CONVERTER->html_image_file_location_name: Dynamic Converter Formatting Information.
(line 38)
* $CONVERTER->in_align: Dynamic Converter Formatting Information.
(line 23)
* $CONVERTER->in_code: Text Formatting Context.
(line 14)
* $CONVERTER->in_math: Text Formatting Context.
(line 20)
* $CONVERTER->in_multi_expanded: Dynamic Converter Formatting Information.
(line 30)
* $CONVERTER->in_non_breakable_space: Text Formatting Context.
(line 45)
* $CONVERTER->in_preformatted: Conversion in Preformatted Context.
(line 12)
* $CONVERTER->in_raw: Text Formatting Context.
(line 26)
* $CONVERTER->in_space_protected: Text Formatting Context.
(line 52)
* $CONVERTER->in_string: Conversion in String Context.
(line 12)
* $CONVERTER->in_upper_case: Text Formatting Context.
(line 40)
* $CONVERTER->in_verbatim: Text Formatting Context.
(line 33)
* $CONVERTER->is_format_expanded: Conversion General Information.
(line 11)
* $CONVERTER->label_command: Target Commands Links, Texts and Associated Commands.
(line 14)
* $CONVERTER->line_error: Error Reporting in User Defined Functions.
(line 21)
* $CONVERTER->line_warn: Error Reporting in User Defined Functions.
(line 23)
* $CONVERTER->paragraph_number: Dynamic Converter Formatting Information.
(line 9)
* $CONVERTER->pgdt: Internationalization of Strings Function.
(line 10)
* $CONVERTER->preformatted_classes_stack: Conversion in Preformatted Context.
(line 19)
* $CONVERTER->preformatted_number: Dynamic Converter Formatting Information.
(line 10)
* $CONVERTER->register_file_information: Associating Information to an Output File.
(line 11)
* $CONVERTER->register_footnote: Customizing Footnotes.
(line 23)
* $CONVERTER->register_opened_section_level: Opening and Closing Sectioning Commands Extent.
(line 19)
* $CONVERTER->register_pending_formatted_inline_content: Setting Up Content for the Next Text Container.
(line 20)
* $CONVERTER->set_conf: Conversion Customization Variables.
(line 39)
* $CONVERTER->shared_conversion_state: Shared Conversion State.
(line 10)
* $CONVERTER->special_direction_element: Elements and Links for Directions.
(line 12)
* $CONVERTER->special_element_body_formatting: Special Element Body Formatting Functions.
(line 34)
* $CONVERTER->special_element_info: Special Elements Information Customization.
(line 51)
* $CONVERTER->substitute_html_non_breaking_space: Substituting Non Breaking Space.
(line 11)
* $CONVERTER->top_block_command: Dynamic Converter Formatting Information.
(line 16)
* $CONVERTER->type_conversion: Type Tree Element Conversion Functions.
(line 29)
* $CONVERTER->url_protect_file_text($INPUT_STRING): Protection of URLs.
(line 33)
* $CONVERTER->url_protect_url_text($INPUT_STRING): Protection of URLs.
(line 19)
* command_conversion: Command Tree Element Conversion Functions.
(line 16)
* command_open: Command Tree Element Opening Functions.
(line 16)
* external_target_non_split_name($CONVERTER,: Customizing External Node Output Names.
(line 36)
* external_target_split_name($CONVERTER,: Customizing External Node Output Names.
(line 21)
* format_begin_file: Customizing HTML File Beginning.
(line 42)
* format_button: Navigation Panel and Navigation Header Formatting.
(line 46)
* format_button_icon_img: Basic Formatting Customization.
(line 19)
* format_comment: Basic Formatting Customization.
(line 31)
* format_contents: Contents and Short Table of Contents Customization.
(line 53)
* format_css_lines: Customizing CSS. (line 22)
* format_element_footer: Element Header and Footer Formatting.
(line 32)
* format_element_header: Element Header and Footer Formatting.
(line 11)
* format_end_file: Customizing HTML File End.
(line 19)
* format_footnotes_segment: Customizing Footnotes.
(line 73)
* format_footnotes_sequence: Customizing Footnotes.
(line 54)
* format_heading_text: Basic Formatting Customization.
(line 41)
* format_navigation_header: Navigation Panel and Navigation Header Formatting.
(line 11)
* format_navigation_panel: Navigation Panel and Navigation Header Formatting.
(line 30)
* format_node_redirection_page: Customizing Node Redirection Pages.
(line 12)
* format_program_string: Basic Formatting Customization.
(line 69)
* format_protect_text: Basic Formatting Customization.
(line 74)
* format_separate_anchor: Basic Formatting Customization.
(line 93)
* format_thing: User Defined Functions are Registered.
(line 33)
* format_title_titlepage: HTML Title Page Customization.
(line 16)
* format_titlepage: HTML Title Page Customization.
(line 25)
* format_translate_string: Translated Strings Customization.
(line 9)
* label_target_name: Customizing Output Target Names.
(line 14)
* node_file_name: Customizing Output File Names.
(line 23)
* sectioning_command_target_name: Customizing Output Target Names.
(line 34)
* special_element_body: Special Element Body Formatting Functions.
(line 23)
* special_element_target_file_name: Customizing Special Elements Output Names.
(line 9)
* stage_handler: Init File Calling at Different Stages.
(line 48)
* texinfo_add_to_option_list: Modifying Main Program Array Variables.
(line 15)
* texinfo_add_valid_customization_option: Adding Customization Variables.
(line 12)
* texinfo_get_conf: Getting Main Program Variables Values.
(line 8)
* texinfo_register_accent_command_formatting: Simple Customization of Accent Commands.
(line 18)
* texinfo_register_command_formatting: Command Tree Element Conversion Functions.
(line 10)
* texinfo_register_command_opening: Command Tree Element Opening Functions.
(line 9)
* texinfo_register_direction_string_info: Direction Strings Customization.
(line 9)
* texinfo_register_file_id_setting_function: Customizing Output-Related Names.
(line 12)
* texinfo_register_formatting_function: Specific formating Functions.
(line 9)
* texinfo_register_formatting_special_element_body: Special Element Body Formatting Functions.
(line 16)
* texinfo_register_handler: Init File Calling at Different Stages.
(line 37)
* texinfo_register_init_loading_error: Init File Loading Error Reporting.
(line 10)
* texinfo_register_init_loading_warning: Init File Loading Error Reporting.
(line 11)
* texinfo_register_no_arg_command_formatting: Simple Customization for Commands Without Arguments.
(line 13)
* texinfo_register_special_element_info: Special Elements Information Customization.
(line 40)
* texinfo_register_style_command_formatting: Simple Customization for Simple Commands with Braces.
(line 11)
* texinfo_register_type_format_info: Simple Customization of Containers.
(line 16)
* texinfo_register_type_formatting: Type Tree Element Conversion Functions.
(line 11)
* texinfo_register_type_opening: Type Tree Element Opening Functions.
(line 10)
* texinfo_remove_from_option_list: Modifying Main Program Array Variables.
(line 17)
* texinfo_set_format_from_init_file: Setting Main Program String Variables.
(line 41)
* texinfo_set_from_init_file: Setting Main Program String Variables.
(line 9)
* tree_unit_file_name: Customizing Output File Names.
(line 34)
* type_conversion: Type Tree Element Conversion Functions.
(line 17)
* type_open: Type Tree Element Opening Functions.
(line 16)
File: texi2any_api.info, Node: Variables Index, Next: General Index, Prev: Functions Index, Up: Top
Appendix C Variables Index
**************************
[index ]
* Menu:
* ACTIVE_ICONS: Simple Navigation Panel Customization.
(line 21)
* ACTIVE_ICONS <1>: Simple Navigation Panel Customization.
(line 77)
* AFTER_BODY_OPEN: Customizing HTML File Beginning.
(line 9)
* AFTER_SHORT_TOC_LINES: Contents and Short Table of Contents Customization.
(line 42)
* AFTER_TOC_LINES: Contents and Short Table of Contents Customization.
(line 36)
* BEFORE_SHORT_TOC_LINES: Contents and Short Table of Contents Customization.
(line 39)
* BEFORE_TOC_LINES: Contents and Short Table of Contents Customization.
(line 33)
* BODYTEXT: Customizing HTML File Beginning.
(line 14)
* BUTTONS_REL, in file beginning: Customizing HTML File Beginning.
(line 26)
* CHAPTER_BUTTONS: Simple Navigation Panel Customization.
(line 51)
* CHAPTER_FOOTER_BUTTONS: Simple Navigation Panel Customization.
(line 45)
* CONTENTS_OUTPUT_LOCATION: Contents and Short Table of Contents Customization.
(line 9)
* CONTENTS_OUTPUT_LOCATION, Elements: Output Element Units. (line 57)
* DATE_IN_HEADER: Customizing HTML File Beginning.
(line 20)
* DOCTYPE: Customizing HTML File Beginning.
(line 6)
* ENCODING_NAME: Customizing HTML File Beginning.
(line 17)
* EXTENSION: Customizing Output File Names.
(line 6)
* EXTRA_HEAD: Customizing HTML File Beginning.
(line 9)
* HTML_ROOT_ELEMENT_ATTRIBUTES: Customizing HTML File Beginning.
(line 31)
* LINKS_BUTTONS: Simple Navigation Panel Customization.
(line 59)
* LINKS_BUTTONS, in file beginning: Customizing HTML File Beginning.
(line 26)
* MISC_BUTTONS: Simple Navigation Panel Customization.
(line 55)
* NODE_FOOTER_BUTTONS: Simple Navigation Panel Customization.
(line 46)
* PASSIVE_ICONS: Simple Navigation Panel Customization.
(line 22)
* PASSIVE_ICONS <1>: Simple Navigation Panel Customization.
(line 77)
* PRE_BODY_CLOSE: Customizing HTML File End.
(line 6)
* PREFIX: Customizing Output File Names.
(line 6)
* PROGRAM_NAME_IN_ABOUT: About Element Customization.
(line 12)
* PROGRAM_NAME_IN_FOOTER: Customizing HTML File End.
(line 9)
* SECTION_BUTTONS: Simple Navigation Panel Customization.
(line 37)
* SECTION_FOOTER_BUTTONS: Simple Navigation Panel Customization.
(line 44)
* SUBDIR: Customizing Output File Names.
(line 6)
* texinfo_document Gettext domain: Internationalization of Strings Function.
(line 6)
* TOP_BUTTONS: Simple Navigation Panel Customization.
(line 62)
* TOP_FILE: Customizing Output File Names.
(line 15)
* USE_NODES: Output Element Units. (line 77)
File: texi2any_api.info, Node: General Index, Prev: Variables Index, Up: Top
Appendix D General Index
************************
[index ]
* Menu:
* --init-file: Loading Init Files. (line 34)
* </body> tag, outputting: Customizing HTML File End.
(line 22)
* <body> tag, attributes of: Customizing HTML File Beginning.
(line 14)
* <body> tag, outputting: Customizing HTML File Beginning.
(line 44)
* <head> block, adding to: Customizing HTML File Beginning.
(line 9)
* About element, customizing: About Element Customization.
(line 6)
* About page, output element unit: Output Element Units.
(line 38)
* Accent command named entities: Simple Customization of Accent Commands.
(line 6)
* Accent commands, customizing HTML for: Simple Customization of Accent Commands.
(line 6)
* accesskey navigation: Simple Navigation Panel Customization.
(line 123)
* Button specification, navigation panel: Simple Navigation Panel Customization.
(line 29)
* Calling functions at different stages: Init File Calling at Different Stages.
(line 6)
* Commands without arguments, customizing HTML for: Simple Customization for Commands Without Arguments.
(line 6)
* Contents, customizing elements: Contents and Short Table of Contents Customization.
(line 6)
* Contexts for expansion in init files: Init File Expansion Contexts.
(line 6)
* CSS customization: Simple Customization of CSS.
(line 6)
* Customization of about element: About Element Customization.
(line 6)
* Customization of tables of contents elements: Contents and Short Table of Contents Customization.
(line 6)
* Customization variables, adding: Adding Customization Variables.
(line 6)
* Customization variables, setting and getting: Managing Customization Variables.
(line 6)
* Customizing CSS: Simple Customization of CSS.
(line 6)
* Customizing HTML page footers: Customizing HTML File End.
(line 6)
* Customizing HTML page headers: Element Header and Footer Formatting.
(line 6)
* Customizing output file names: Customizing Output File Names.
(line 6)
* Customizing output target names: Customizing Output Target Names.
(line 6)
* Date, in header: Customizing HTML File Beginning.
(line 20)
* Direction information type: Element Direction Information Type.
(line 6)
* Direction strings: Direction Strings. (line 9)
* Direction strings, getting: Getting Direction Strings.
(line 6)
* Directions: Directions. (line 6)
* Document description, in HTML output: Customizing HTML File Beginning.
(line 22)
* Document structure: Texinfo Tree Elements in User Defined Functions.
(line 36)
* Document units: Output Element Units.
(line 6)
* Element directions: Directions. (line 6)
* Elements, main unit of output documents: Output Element Units.
(line 6)
* Encoding, in HTML output: Customizing HTML File Beginning.
(line 17)
* Error reporting, conversion: Error Reporting in User Defined Functions.
(line 6)
* Error reporting, loading: Init File Loading Error Reporting.
(line 6)
* Expansion contexts, for init files: Init File Expansion Contexts.
(line 6)
* FirstInFile direction variant: Directions. (line 101)
* Footer, customizing for HTML: Customizing HTML File End.
(line 6)
* Footnotes, output element unit: Output Element Units.
(line 38)
* Formatting functions, for navigation panel: Navigation Panel and Navigation Header Formatting.
(line 6)
* Functions, calling at different stages: Init File Calling at Different Stages.
(line 6)
* Headers, customizing for HTML: Element Header and Footer Formatting.
(line 6)
* HTML customization for accent commands: Simple Customization of Accent Commands.
(line 6)
* HTML customization for commands without arguments: Simple Customization for Commands Without Arguments.
(line 6)
* HTML customization for simple commands: Simple Customization for Simple Commands with Braces.
(line 6)
* Icons, in navigation buttons: Simple Navigation Panel Customization.
(line 77)
* Id names, customizing: Customizing Output Target Names.
(line 6)
* Init file basics: Init File Basics. (line 6)
* Init file calling functions at different stages: Init File Calling at Different Stages.
(line 6)
* Init file expansion contexts: Init File Expansion Contexts.
(line 6)
* Init file namespace: Init File Namespace. (line 6)
* Initialization files, loading: Loading Init Files. (line 6)
* Insertion commands, customizing HTML for: Simple Customization for Commands Without Arguments.
(line 6)
* Links information: Directions. (line 6)
* Loading init files: Loading Init Files. (line 6)
* Math expansion context: Init File Expansion Contexts.
(line 25)
* Namespace, for init files: Init File Namespace. (line 6)
* Navigation panel button specification: Simple Navigation Panel Customization.
(line 29)
* Navigation panel formatting functions: Navigation Panel and Navigation Header Formatting.
(line 6)
* Navigation panel, simple customization of: Simple Navigation Panel Customization.
(line 6)
* Normal document units: Output Element Units.
(line 15)
* Normal expansion context: Init File Expansion Contexts.
(line 9)
* Output element unit directions: Directions. (line 6)
* Output elements: Output Element Units.
(line 6)
* Output elements, defined: Output Element Units.
(line 12)
* Output file names, customizing: Customizing Output File Names.
(line 6)
* Overview element, customizing: Contents and Short Table of Contents Customization.
(line 6)
* Overview, output element unit: Output Element Units.
(line 38)
* Perl namespaces, for init files: Init File Namespace. (line 6)
* Perl, language for init files: Init File Basics. (line 6)
* Preformatted expansion context: Init File Expansion Contexts.
(line 12)
* rel navigation: Simple Navigation Panel Customization.
(line 127)
* Search paths, for initialization files: Loading Init Files. (line 6)
* Short table of contents element, customizing: Contents and Short Table of Contents Customization.
(line 6)
* Short table of contents, output element unit: Output Element Units.
(line 38)
* Simple commands, customizing HTML for: Simple Customization for Simple Commands with Braces.
(line 6)
* Simple Customization, of navigation panel: Simple Navigation Panel Customization.
(line 6)
* Special Elements file names, customizing: Customizing Special Elements Output Names.
(line 6)
* Special Elements id names, customizing: Customizing Special Elements Output Names.
(line 6)
* Special Elements target names, customizing: Customizing Special Elements Output Names.
(line 6)
* String expansion context: Init File Expansion Contexts.
(line 30)
* Style commands, customizing HTML for: Simple Customization for Simple Commands with Braces.
(line 6)
* Table of contents, output element unit: Output Element Units.
(line 38)
* Target names, customizing: Customizing Output Target Names.
(line 6)
* texi2any-config.pm init files loaded: Loading Init Files. (line 6)
* Texinfo tree element units: Output Element Units.
(line 6)
* Texinfo::Report: Error Reporting in User Defined Functions.
(line 6)
* Title page, customization: HTML Title Page Customization.
(line 6)
* Top element: Output Element Units.
(line 28)
* Translated direction strings: Direction Strings. (line 28)
* Type, of direction information: Element Direction Information Type.
(line 6)
* User defined functions, registering: User Defined Functions are Registered.
(line 6)
Tag Table:
Node: Top891
Node: Overview5518
Node: Loading Init Files7216
Node: Init File Basics10054
Ref: Init File Basics-Footnote-111061
Node: Init File Namespace11203
Node: Managing Customization Variables12246
Node: Setting Main Program String Variables13491
Node: Modifying Main Program Array Variables15729
Node: Setting Converter Variables in Main Program16951
Node: Getting Main Program Variables Values17947
Node: Adding Customization Variables18545
Node: Init File Loading Error Reporting19367
Node: Simple formatting customization20242
Node: Init File Expansion Contexts20857
Node: Simple Customization for Commands Without Arguments22713
Node: Simple Customization for Simple Commands with Braces26309
Node: Simple Customization of Accent Commands28687
Node: Simple Customization of Containers30551
Ref: Simple Customization of Containers-Footnote-132232
Node: Simple Customization of CSS32533
Node: Simple headers customizations36353
Node: Output Element Units37010
Node: Directions41081
Ref: FirstInFile direction variant43453
Node: Element Direction Information Type43860
Node: Direction Strings45458
Node: Direction Strings Customization46503
Node: Simple Navigation Panel Customization48052
Ref: Buttons Display51058
Ref: Accesskey and rel Navigation53390
Node: User Defined Functions53848
Node: User Defined Functions are Registered54589
Node: Converter Object and Conversion Functions56227
Node: Texinfo Tree Conversion Functions57347
Node: Error Reporting in User Defined Functions60404
Node: Texinfo Tree Elements in User Defined Functions62516
Node: Encoding and Decoding File Path Strings65331
Node: Encoding File Path Strings65695
Node: Decoding File Path Strings68051
Node: Setting the Context for Conversion69113
Node: Conversion Customization Variables70942
Node: Conversion General Information74493
Node: Customizing Output-Related Names80364
Node: Customizing Output File Names81734
Node: Customizing Output Target Names84743
Node: Customizing External Node Output Names87388
Node: Customizing Special Elements Output Names89827
Node: Init File Calling at Different Stages90815
Node: User Defined Functions in Conversion93683
Node: Tree Element Conversion Functions94404
Node: Command Tree Element Opening Functions95562
Node: Command Tree Element Conversion Functions96866
Node: Type Tree Element Opening Functions101764
Node: Type Tree Element Conversion Functions103004
Node: Formatting Functions104954
Node: Specific formating Functions105639
Node: Mandatory Conversion Function Calls107020
Node: Protection of URLs107712
Node: Formatting HTML Element with Classes110208
Node: Closing Lone HTML Element111686
Node: Substituting Non Breaking Space112512
Node: Conversion in String Context113342
Node: Conversion in Preformatted Context114193
Node: Text Formatting Context115854
Node: Basic Formatting Customization117726
Ref: Basic Formatting Customization-Footnote-1121882
Node: Dynamic Conversion Information122076
Node: Dynamic Converter Formatting Information123026
Node: Opening and Closing Sectioning Commands Extent125860
Node: Setting Up Content for the Next Text Container127833
Node: Associating Information to an Output File131033
Node: Shared Conversion State131921
Node: Translations Output and Customization133260
Node: Internationalization of Strings Function134553
Node: Translated Strings Customization138123
Node: Translation Contexts141467
Node: Directions, Links, Labels and Files144029
Node: Getting Direction Strings144806
Node: Target Commands Links, Texts and Associated Commands145510
Node: Other Links, Headings and Associated Information for Special Elements149353
Node: Elements and Links for Directions153407
Node: Element Counters in Files155423
Node: Customizing Footnotes, Tables of Contents and About156610
Ref: Special Elements Varieties157439
Node: Special Elements Information Customization158118
Node: Customizing Footnotes160427
Node: Contents and Short Table of Contents Customization164813
Node: About Element Customization168759
Node: Special Element Body Formatting Functions169725
Node: Customizing HTML Footers, Headers and Navigation Panels172739
Node: Navigation Panel and Navigation Header Formatting174042
Node: Element Header and Footer Formatting176940
Node: Heading Commands and Tree Elements Formatting179504
Node: Beginning and Ending Files181625
Node: Customizing HTML File Beginning182320
Node: Customizing HTML File End184465
Node: Titlepage, CSS and Redirection Files185546
Node: HTML Title Page Customization185898
Node: Customizing CSS187300
Node: Customizing Node Redirection Pages188606
Node: Specific Functions for Specific Elements189451
Node: Functions Index194426
Node: Variables Index215886
Node: General Index221366
End Tag Table
Local Variables:
coding: utf-8
End:
Browse
Usage
Versions