[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
texinfo ChangeLog doc/texi2oldapi.texi doc/texi...
|
From: |
Patrice Dumas |
|
Subject: |
texinfo ChangeLog doc/texi2oldapi.texi doc/texi... |
|
Date: |
Fri, 30 Sep 2011 19:13:06 +0000 |
CVSROOT: /sources/texinfo
Module name: texinfo
Changes by: Patrice Dumas <pertusus> 11/09/30 19:13:05
Modified files:
. : ChangeLog
doc : texi2oldapi.texi texinfo.txi version.texi
Log message:
* doc/texinfo.txi (texi2any Output Customization),
doc/texi2oldapi.texi: archive the texi2any Output Customization
chapter in texi2oldapi.texi. Reduce the text in texinfo.txi
to what should be stable.
CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texinfo/ChangeLog?cvsroot=texinfo&r1=1.1256&r2=1.1257
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texi2oldapi.texi?cvsroot=texinfo&r1=1.3&r2=1.4
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texinfo.txi?cvsroot=texinfo&r1=1.385&r2=1.386
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/version.texi?cvsroot=texinfo&r1=1.97&r2=1.98
Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/texinfo/texinfo/ChangeLog,v
retrieving revision 1.1256
retrieving revision 1.1257
diff -u -b -r1.1256 -r1.1257
--- ChangeLog 26 Sep 2011 18:47:45 -0000 1.1256
+++ ChangeLog 30 Sep 2011 19:13:04 -0000 1.1257
@@ -1,3 +1,10 @@
+2011-09-30 Patrice Dumas <address@hidden>
+
+ * doc/texinfo.txi (texi2any Output Customization),
+ doc/texi2oldapi.texi: archive the texi2any Output Customization
+ chapter in texi2oldapi.texi. Reduce the text in texinfo.txi
+ to what should be stable.
+
2011-09-26 Karl Berry <address@hidden>
* doc/texinfo.txi (GNU Sample Texts): change example to be
Index: doc/texi2oldapi.texi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/texi2oldapi.texi,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -b -r1.3 -r1.4
--- doc/texi2oldapi.texi 9 Apr 2011 00:10:38 -0000 1.3
+++ doc/texi2oldapi.texi 30 Sep 2011 19:13:04 -0000 1.4
@@ -345,6 +345,2468 @@
@end itemize
address@hidden texi2any Output Customization
address@hidden @command{texi2any} Output Customization
+
address@hidden
address@hidden Warning
+All of this information, with the exception of command-line options
+and search directories (@pxref{Loading Init Files}), may become
+obsolete in a future Texinfo release. Right now, the ``API''
+described in this chapter is immature, badly designed and incomplete,
+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.
address@hidden quotation
address@hidden cartouche
+
+This chapter describes how to customize many aspects of the
address@hidden 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.
+
address@hidden
+* Loading Init Files:: Finding and writing initialization files.
+* Init File Basics:: What init files can contain and do.
+* Output Elements:: The main unit of output documents.
+* Navigation Panel Customization:: Navigation buttons and more.
+* Customizing HTML Page Layout:: Page headers, footers, sections.
+* Customizing Special Elements:: The top, toc, about, etc., elements.
+* Customizing Output-Related Names:: File names and target names.
+* Customizing HTML Headings:: Sectioning commands.
+* Customizing Indices:: Manipulating index entries.
+* Customizing CSS:: CSS customization for HTML.
address@hidden menu
+
+
address@hidden Loading Init Files
address@hidden Loading Initialization Files and Search Paths
+
address@hidden Loading init files
address@hidden Initialization files, loading
address@hidden Search paths, for initialization files
+
address@hidden Config @r{init files loaded}
+
+You can write so-called @dfn{initialization files}, or @dfn{init
+files} for short, to modify almost every aspect of output formatting.
+The program loads init files named @file{Config} each time it is run.
+Those files are looked for in the following directories (where
address@hidden is the name of the program invoked on the command line,
+normally @code{makeinfo} or @code{texi2any}):
+
address@hidden @file
address@hidden @var{datadir}/@var{prog}/
+(where @var{datadir} is the system data directory specified at
+compile-time, e.g., @file{/usr/local/share})
+
address@hidden @var{sysconfdir}/@var{prog}/
+(likewise specified at compile time, e.g., @file{/usr/local/etc})
+
address@hidden ~/address@hidden/
+(where @code{~} is the current user's home directory)
+
address@hidden ./address@hidden/
+(under the current directory)
+
address@hidden ./
+(the current directory)
address@hidden table
+
+All @file{Config} files found are loaded, in the above order. Thus,
address@hidden/Config} can override entries in, say,
address@hidden/usr/local/share/makeinfo/Config}.
+
address@hidden --init-file
+However, the most common way to load an initialization file is with
+the @option{--init-file} option, explicitly specifying the file to be
+loaded. By default the following directories are searched, in the
+following order, where @var{prog} is the name of the program invoked
+on the command line (@command{makeinfo}, @command{texi2any}, etc.).
+Only the first file found is used:
+
address@hidden
address@hidden The current directory @file{./};
+
address@hidden @file{./address@hidden/} under the current directory;
+
address@hidden @file{~/address@hidden/}
+where @code{~} is the current user's home directory;
+
address@hidden @address@hidden/@var{prog}/}
+where @var{sysconfdir} is the system configuration directory
+specified at compile-time, e.g., @file{/usr/local/etc};
+
address@hidden @address@hidden/@var{prog}/}
+Where @var{datadir} is the system data directory likewise specified at
+compile time, e.g., @file{/usr/local/share};
+
address@hidden @file{./.texinfo/init/} under the current directory;
+
address@hidden @file{~/.texinfo/init/} under the current home directory;
+
address@hidden @address@hidden/texinfo/init/} with @var{sysconfdir} as above;
+
address@hidden @address@hidden/texinfo/init/} with @var{datadir} as above.
address@hidden enumerate
+
+Additional directories may be prepended to the list with the
address@hidden option (@pxref{Invoking texi2any}).
+
+
address@hidden Init File Basics
address@hidden Init File Basics
+
address@hidden Init file basics
address@hidden Perl, language for init files
+
+Init files are written in Perl, and by convention have extension
address@hidden or @file{.pm}. Several init files are included in the Texinfo
+distribution (some are crucial components of the program), and can
+serve as a good model for writing your own. In particular, the
address@hidden file is used to set all the defaults for
+Texinfo. Although it is large, it contains many useful examples of
+settings. Smaller examples include @file{utf8.pm},
address@hidden, and plenty more.
+
address@hidden
+* Init File Variables:: Configuration & other variables, function references.
+* Init File Namespaces:: @code{Texi2HTML::Config}, @code{Texi2HTML}, and
@code{main}.
+* Init File Functions:: Redefining functions through references.
+* Setting and Getting Configuration Variables::
+* Init File Global Information:: Accessing document title, file name, etc.
+* Init File Encodings:: Overriding input and output encodings.
+* texi2any's Three Passes:: Macro expansion, document structure, output
+* Init File Calling at Different Stages:: Calling functions at various times.
+* Init File Formatting of Commands:: Overriding default formatting completely.
+* Init File General Block Commands:: Customizing usual environments.
+* Init File Expansion Contexts:: Normal, preformatted, string, math.
+* Internationalization of Strings::
address@hidden menu
+
+
address@hidden Init File Variables
address@hidden Init File Variables
+
address@hidden Initialization file variables
address@hidden Variables, in initialization files
+
+We divide the kinds of variables that can appear in initialization
+files into three general categories:
+
address@hidden @asis
address@hidden configuration variables
address@hidden Configuration variables
+Configuration variables are set and accessed through specific
+functions in initialization files (@address@hidden Configuration
+Variables}).
+
address@hidden scalars, lists and hashes
address@hidden Perl variables
+Normal Perl variables. The order of loading of initialization files
+and of command-line options is important: later changes override
+earlier ones.
+
address@hidden function references
address@hidden Function references
+These allow dynamic redefinition of functions used to produce output.
+
+As such functions are defined by a reference name, we will always use
+the reference name in function prototypes. For the function arguments
+we will use @code{\@@array} to indicate a reference to an array
+(a.k.a.@: list, in Perl terminology) and @code{\%hash} for a reference
+to a hash.
+
+To illustrate these conventions, here is the prototype for the
+function associated with a function reference
address@hidden:
+
address@hidden {Function Reference} $text formatting_function $arg1 \@@arg2
address@hidden has a first argument @var{$arg1},
+a second argument a reference to an array @var{\@@arg2},
+and returns the formatted text @var{$text}.
address@hidden deftypefn
+
+To redefine this function, you would write:
+
address@hidden
+$formatting_function = \&my_formatting_function;
+sub my_formatting_function($ $)
address@hidden
+ my $arg1 = shift;
+ my $arg2 = shift;
+ # prepare $formatted_text
+ ...
+ return $formatted_text;
address@hidden
address@hidden example
address@hidden table
+
+Since the program can process more than one file on the command line,
+you must ensure that you properly initialize the variables used during
+formatting. It is possible to call functions at different stages to
+help with that (@pxref{Init File Calling at Different Stages}).
+
+
address@hidden Init File Namespaces
address@hidden Init File Namespaces
+
address@hidden Init file namespaces
address@hidden Namespaces, for init files
address@hidden Perl namespaces, for init files
+
address@hidden Texi2HTML::Config @r{namespace}
+Initialization file are loaded from the main program via a
address@hidden call in the @code{Texi2HTML::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. The program's own variables are declared with @code{use
+vars}, so that it should be possible to use the @code{use strict}
+pragma in initialization files.
+
address@hidden Texi2HTML @r{namespace}
address@hidden main @r{namespace}
+To avoid accidentally altering the variables in the @code{main}
+namespace, all the global variables which could be of use in init
+files are available in the @code{Texi2HTML} namespace.
+
+The functions of the main program, however, are still in the
address@hidden namespace.
+
+
address@hidden Init File Functions
address@hidden Init File Functions
+
address@hidden Init file functions
address@hidden Functions, overriding in init files
address@hidden Overriding functions in init files
+To redefine a function you must replace the appropriate function
+reference with a reference to your function: write your function, give
+it a name you ensure is unique in the @code{Texi2HTML::Config}
+namespace, and then override the value of the function reference with
+your own. When another function from the main program (or anywhere
+else) calls the reference, your function will be used.
+
+For example, the function reference to the function called when
+handling an anchor is called @code{$anchor}. Thus, to override the
+corresponding function you could write:
+
address@hidden
+# override the function reference:
+$anchor = \&my_anchor_fn;
+
+# define the function to do the work:
+sub my_anchor_fn @{
+# process arguments, return an html anchor
address@hidden
address@hidden example
+
+
address@hidden Setting and Getting Configuration Variables
address@hidden Setting and Getting Configuration Variables
+
address@hidden Configuration variables, setting and getting
+
+The basic operations on configuration variables are to set and
+retrieve their values.
+
+To set the value of a configuration variable from an initialization file,
+you should use @code{set_from_init_file}:
+
address@hidden set_from_init_file ($variable_name, $variable_value)
address@hidden is a string containing the name of the variable
+you want to set, and @var{$variable_value} is the value to which you
+want to set it. @var{$variable_value} may be @samp{undef}.
address@hidden defun
+
+For example,
+
address@hidden
+set_from_init_file('documentlanguage', 'fr');
address@hidden example
+
address@hidden overrides the @code{@@documentlanguage} from the
+document. It would be overridden by @option{--document-language} on
+the command line.
+
+Another example:
+
address@hidden
+set_from_init_file('SPLIT', 'chapter');
address@hidden example
+
address@hidden overrides the default splitting of the document. It would be
+overridden by @option{--split} on the command line.
+
+A final example:
+
address@hidden
+set_from_init_file('NO_CSS', 1);
address@hidden example
+
address@hidden overrides the default value for @code{NO_CSS}. It would be
+overridden by @code{--set-init-variable NO_CSS=1} on the command line.
+
+To get the value of a variable, the function is @code{get_conf}:
+
address@hidden get_conf ($variable_name)
address@hidden is the name of the variable; its value (possibly
address@hidden) is returned.
address@hidden defun
+
+For example:
+
address@hidden
+if (get_conf('footnotestyle') eq 'separate') @{ ... @}
address@hidden example
+
+For the configuration variables associated with @@-commands, see
address@hidden Variables for @@-Commands}. For the configuration
+variables associated with command line options, see @ref{Configuration
+Variables and Options}.
+
+
address@hidden Init File Global Information
address@hidden Init File Global Information
+
address@hidden @ignore
address@hidden FIXME those are still undocumented
address@hidden 'split_level'
address@hidden 'variable_levels' 'variables'
address@hidden do_about
address@hidden 'FH' 'state' 'format_from_command_line'
address@hidden command_stack
address@hidden line_nr
address@hidden %htmlxref
address@hidden %hyphenation
address@hidden @end ignore
+
address@hidden Init files, and global information
address@hidden Global information, in init files
+
+Much global information about the document is available as the basis
+for customization in init files.
+
address@hidden
+* Title String Variables:: @code{@@author}, @code{@@title}, etc.
+* Command Line String Variables:: Input and output file names, etc.
+* Global Document String Variables:: @code{@@copying}, CSS, TOC, etc.
+* Index String Variables:: @code{defindex}, @code{@@synindex}, etc.
+* Init File Flag Values:: @code{@@set} values.
+* Program String Customization:: For the About element and footers.
address@hidden menu
+
address@hidden Title String Variables
address@hidden Title String Variables
+
address@hidden Title string variables
+
+For title-related @@-commands, such as @code{@@title},
address@hidden@@titlefont}, and @code{@@author}, a variety of information is
+available, with diverse formatting.
+
address@hidden@@author} and @code{@@subtitle} are multiline title-related
+commands, since they may appear more than once. Multiline
+title-related commands are associated with strings that are
+constructed by concatenating all the command occurences. They are
+also associated with arrays, and the name of the arrays is constructed
+by appending a @samp{s} to the command name, as in @code{authors}.
+
+Some information is also deduced from the title commands:
address@hidden reflects @code{@@settitle} vs.\
address@hidden@@shorttitlepage}, and @dfn{fulltitle} is constructed by trying
+all the title-related commands, including @code{@@top} and
address@hidden@@titlefont}, in the top element.
+
address@hidden Texi2HTML::THISDOC
+The information associated with @code{@@top}, @code{@@title},
address@hidden@@settitle}, @code{@@shorttitlepage}, @code{@@author},
address@hidden@@subtitle}, @code{simpletitle} and @code{fulltitle} are
+associated with the following keys in the @code{%Texi2HTML::THISDOC}
+hash, where @var{command} is the title @@-command:
+
address@hidden @code
address@hidden @var{command}_texi
+The original Texinfo code.
+
address@hidden @var{command}
+The corresponding text formatted.
+
address@hidden @var{command}_no_texi
+The text formatted as simple plain text.
+
address@hidden @var{command}_simple_format
+The text formatted as a string without formatting elements
+(@pxref{Init File Expansion Contexts}).
+
address@hidden @var{command}_line_nr
+An opaque structure corresponding with the line where the @@-comand
+appeared. Not available for @code{@@titlefont}, multiline
+title-related commands and derived information.
+
address@hidden table
+
+For multiline commands, the following array references are associated
+with the following keys in the @code{%Texi2HTML::THISDOC} hash, where
address@hidden is the title @@-command:
+
address@hidden @code
address@hidden @var{command}s
+Reference to an array containing all lines set by
address@hidden@@@var{command}}, formatted.
+
address@hidden @var{command}s_texi
+Reference to an array containing all the original Texinfo lines.
+
address@hidden @var{command}s_line_nr
+Reference to an array of opaque structures corresponding with the
+line where the @@-command lines appeared.
+
address@hidden table
+
+
address@hidden Command Line String Variables
address@hidden Command Line String Variables
+
address@hidden Command-line string variables
+
+These entries in the @code{%Texi2HTML::THISDOC} hash are related to
+the command-line processing:
+
address@hidden @code
address@hidden destination_directory
+Destination directory for the output files.
+
address@hidden file_base_name
+Base name of the Texinfo input file.
+
address@hidden filename
+This is a reference to a hash that holds the filenames for special
+elements. These files may not be used in certain cases, for example
+the @code{toc} element file name may not be relevant if table of
+contents is not output separately. The keys are:
+
address@hidden @code
address@hidden doc
+If not split, the document file; if split, the top element file.
+
address@hidden top
+Top element file name.
+
address@hidden toc
+Table of contents element file name.
+
address@hidden stoc
+Overview (a.k.a.@: short table of contents) element file name.
+
address@hidden about
+About element file name.
+
address@hidden foot
+Footnotes element file name.
+
address@hidden frame
+Main frame file.
+
address@hidden toc_frame
+Table of contents frame file name.
+
address@hidden table
+
address@hidden input_directory
+Path to the directory containing the Texinfo input file being processed.
+
address@hidden input_file_name
+Name of the Texinfo input file as given on the command line.
+
address@hidden input_file_number
+Number of the Texinfo input file from the command line which is
+currently being processed.
+
address@hidden program
+The name of the command generating the output.
+
address@hidden program_and_version
+The name and version of the command generating the output.
+
address@hidden program_homepage
+Home page of the command generating the output.
+
address@hidden table
+
+
address@hidden Global Document String Variables
address@hidden Global Document String Variables
+
address@hidden Global document strings
+
+These entries in the @code{%Texi2HTML::THISDOC} hash provide other
+global document information.
+
address@hidden @code
address@hidden copying_comment
+Text appearing in @code{@@copying} with all the Texinfo commands
+put into comments (@pxref{copying,,@code{@@copying}}).
+
address@hidden css_import_lines
+Reference to an array containing the @code{@@import} lines of
address@hidden files (@pxref{HTML CSS}).
+
address@hidden css_rule_lines
+Reference to an array containing the normal lines of @acronym{CSS}
+files.
+
address@hidden dircategory_texi
+The Texinfo @code{@@dircategory} argument (@pxref{Installing Dir Entries}).
+
address@hidden dircategory
+The formatted @code{@@dircategory} argument.
+
address@hidden inline_contents
+A reference to a hash containing two keys, one for each type of table
+of contents: @code{contents} and @code{shortcontents}. Each
+associated value is a reference to an array containg the lines
+resulting from formatting the respective type of table of contents,
+including a heading and a reference.
+
address@hidden stoc_file
+The file name of the Overview (short table of contents).
+
address@hidden toc_file
+The file name of the table of contents.
+
address@hidden table
+
+
address@hidden Index String Variables
address@hidden Index String Variables
+
address@hidden Index strings
+
+These entries in the @code{%Texi2HTML::THISDOC} hash provide other
+index-related information.
+
address@hidden @code
address@hidden defindex
address@hidden defcodeindex
+References to arrays holding the corresponding @@-command
+arguments.
+
address@hidden merged_index
+Reference to a hash whose keys are the index names merged in
+the values.
+
address@hidden index_letters_array
address@hidden index_entries_array
address@hidden index_entries_region_array
address@hidden index_entries
address@hidden indices_numbers
address@hidden indices
+References to hashes holding information about the index entries
+and whole indices.
+
address@hidden synindex
address@hidden syncodeindex
+Reference to arrays containing array references with two elements,
+the two arguments of @code{@@synindex}
+(@pxref{synindex,,@code{@@synindex}}).
+
address@hidden table
+
+
address@hidden Init File Flag Values
address@hidden Init File Flag Values
+
address@hidden Init file flag values
address@hidden Flag values, in init files
+
address@hidden @code{@@set} values, in init files
address@hidden %main::value
+Flags defined with @code{@@set} (@pxref{set value})
+may be accessed through the @code{%main::value} hash. The key is the
+flag name, and the value is the flag value.
+
+
address@hidden Program String Customization
address@hidden Program String Customization
+
address@hidden Program string customization
address@hidden Customization of program string
address@hidden PROGRAM_NAME_IN_FOOTER
+
+The following function reference may be used to construct a string
+advertising the program used to generate the output. It may be used
+in the @code{About} element, and in the footers if
address@hidden is set.
+
address@hidden {Function Reference} $program_string_formatted program_string
+This function reference should return the formatted program
+string.
address@hidden deftypefn
+
+
address@hidden Init File Encodings
address@hidden Init File Encodings
+
address@hidden Init file encodings
address@hidden Encodings, in init files
+
+There are four encoding-related variables, which are autodetected
+if not set:
+
address@hidden @code
address@hidden documentencoding
+This configuration variable may be set, overriding any encoding
+set by @code{@@documentencoding} (@pxref{documentencoding,,
address@hidden@@documentencoding}}).
+
address@hidden IN_ENCODING
+The encoding of the Texinfo files may be set independently with this
+variable. If not, then when @code{documentencoding} is set,
address@hidden is also set if the encoding is supported by Perl.
+
address@hidden ENCODING_NAME
+The encoding advertised in output files. If not set, the value of
+this variable is based on the other ENCODING values, and if they are
+all undefined, the variable @code{DEFAULT_ENCODING} is used.
+
address@hidden OUT_ENCODING
+The encoding of the output files. If not set, the value of
address@hidden or @code{IN_ENCODING} is used if one of these
+variables is set.
+
address@hidden vtable
+
+In general, the @code{documentencoding} and @code{IN_ENCODING} are set
+to the appropriate values with no need to override.
address@hidden is set according to @code{ENCODING_NAME}. To
+force a given encoding for the output, it's best to set
address@hidden The default output encoding for Info is ASCII,
+and for other formats is UTF-8.
+
+The values for the encoding related variables are set in the default
address@hidden function reference (@pxref{Output Initialization}).
+
+
address@hidden texi2any's Three Passes
address@hidden @code{texi2any}'s Three Passes: Macro Expansion, Document
Structure, Output
+
address@hidden @code{texi2any's} three passes
address@hidden Passes, of @code{texi2any}
address@hidden Three passes, of @code{texi2any}
+
address@hidden operates in three passes to transform the original
+input to the final output. In address@hidden, the @code{@@macro} calls
+are expanded; in address@hidden, the document structure is gathered; and
+in address@hidden the result is output. In most cases this organization
+does not matter, as output customization is almost always done in
address@hidden Only if you want to do something during an earlier pass
+do you need to consider this, as explained below.
+
+After the Texinfo input file has been parsed, some information is
+available which can be used to modify some variables and prepare for
+the output. For example, even such basic things as the document
+language, the document encoding, values set with @code{@@set} or
address@hidden@@setfilename}, etc., cannot be known before the Texinfo
+parsing.
+
address@hidden Initialization}
address@hidden Output initialization
address@hidden Initialization of output
+The following function reference may be redefined to be called after
+Texinfo processing and before document generation, i.e., for output
+initialization:
+
address@hidden {Function Reference} init_out
+This function performs the initialization of variables and other
+tasks before document output.
address@hidden deffn
+
+By default, the hashes @code{%BUTTONS_NAME} (@pxref{Navigation Panel
+Button Specification}) and @code{%BUTTONS_GOTO} (@pxref{About Element
+Customization}) are initialized. The initialization of these
+variables depends on the document language. Similarly, the encoding
+variables are set based on the information now available (@pxref{Init
+File Encodings}). When generating HTML, aditionally, the
address@hidden hash is initialized.
+
+To perform the default initializations, which are almost surely
+desired, and also add more code, the best way is to save the default
+function reference and then call it in your new function, like this:
+
address@hidden
+my $default_init_out = $init_out;
+$init_out = \&my_init_out;
+sub my_init_out()
address@hidden
+ &$default_init_out();
+ address@hidden'NodeForward'@} = ' > ';
address@hidden
address@hidden example
+
address@hidden Finalization}
address@hidden Output finalization
address@hidden Finalization of output
+At the other end of things, if you want to do some clean-up after the
+document was generated (write at the end of the output files, issue
+messages, @dots{}), the following function reference may be overridden:
+
address@hidden {Function Reference} finish_out
+This function is called after the document generation.
address@hidden deffn
+
+The default is to do nothing.
+
+These function references are mostly redundant with the handlers described
+in the next section (@pxref{Init File Calling at Different Stages}).
+
+
address@hidden Init File Calling at Different Stages
address@hidden Init File Calling at Different Stages
+
address@hidden Init file calling functions at different stages
address@hidden Calling functions at different stages
address@hidden Functions, calling at different stages
+
+Arbitrary user-defined functions may be called between the different
+Texinfo parsing and outputting passes (see previous section). This
+could be used, for example, to initialize variables before collecting
+the @@-commands and their text, expanding them between the collecting
+and expansion phase and doing clean-up after the expansion pass.
+
+There are five places for user defined functions, each associated with
+an array. The function references in each array are called one after
+another. The arrays correspond with the different stages:
+
address@hidden @code
address@hidden @@command_handler_setup
+Called before anything is done, including collecting the output file
+names. The input file names' directories are available.
+
address@hidden @@command_handler_init
+Called as soon as the input file names are known. It may be at
+different moments: before processing anything, right after
address@hidden@@setfilename}, or at the end of address@hidden (after
address@hidden@@macro} and @code{@@include} expansions). At that time the
+information available is essentially just the input file names.
+
address@hidden @@command_handler_names
+Called right after address@hidden, the main input collection. At that
+time all the special @@-commands have been collected as explained
+above, but no output has been produced, and the element (node and
+section) names have not been processed.
+
address@hidden @@command_handler_process
+Called after the element names have been processed, but
+before the main output initialization.
+
address@hidden @@command_handler_output
+Called right before the main output processing, so that more
+information is available, such as the title (@pxref{Init File Global
+Information}).
+
address@hidden @@command_handler_finish
+Called after output generation is finished.
address@hidden vtable
+
+Because these are arrays, you should use @code{push} to add your
+functions to them, like this (a real example from the @LaTeX{}2HTML
+support):
+
address@hidden
+push (@@command_handler_init,
+ \&Texi2HTML::LaTeX2HTML::init);
+push (@@command_handler_process,
+ \&Texi2HTML::LaTeX2HTML::latex2html);
+push (@@command_handler_finish,
+ \&Texi2HTML::LaTeX2HTML::finish);
address@hidden example
+
+For a real-life example, see the @LaTeX{}2HTML support.
+
+
address@hidden Init File Formatting of Commands
address@hidden Init File Formatting of Commands
+
address@hidden Init file formatting of commands
address@hidden Formatting of commands, in init file
address@hidden Commands, custom formatting
+
+It is possible to bypass completely the normal formatting of
+@@-commands with braces and the block commands of ``raw'' input such
+as @code{@@html} and @code{@@tex} (@pxref{Raw Formatter Commands}).
+In these cases the @@-commands and the text within are passed to a
+user-defined function early, right after the document structure
+determination of address@hidden (@pxref{texi2any's Three Passes}).
+Another user-defined function is called during the output expansion
+phase.
+
address@hidden %command_handler
+These user-defined functions are specified as values in the
address@hidden hash, with the key being the command to
+override. The associated value is itself a hash reference, whose keys
+can be @code{'init'} for the function reference called during the
+first pass, and @code{'expand'} during the expansion pass.
+
+Here is an example for an @@-command with braces, @code{math}, used
+for in the @LaTeX{}toHTML support:
+
address@hidden
address@hidden'math'@} =
+ @{ 'init' => \&Texi2HTML::LaTeX2HTML::to_latex,
+ 'expand' => \&Texi2HTML::LaTeX2HTML::do_tex
+ @};
address@hidden example
+
address@hidden Raw region, overriding formatting of
+Handling a raw region @@-command is the same:
+
address@hidden
address@hidden'tex'@} =
+ @{ 'init' => \&Texi2HTML::LaTeX2HTML::to_latex,
+ 'expand' => \&Texi2HTML::LaTeX2HTML::do_tex
address@hidden;
address@hidden example
+
+These function references are called as follows, respectively:
+
address@hidden {Function Reference} $status @
+ address@hidden'$command'@}->@{'init'@} $command $text $count
address@hidden is the @@-command name, @var{$text} is the text
+appearing within the @@-command, and @var{$count} counts how many
+times this @@-command has appeared. @var{$status} is a boolean to return,
+true if the collection was succesful. If it is false, the @@-command
+and the text are discarded.
address@hidden deftypefn
+
address@hidden {Function Reference} $result @
+ address@hidden'$command'@}->@{'expand'@} $command $count \%state $text
address@hidden is the @@-command name, @var{$count} counts how many
+times this @@-command has appeared, and @var{\%state} is a hash
+reference with detailed context information; @var{$text} should be
+empty. @var{$result} is the expanded resulting text.
address@hidden deftypefn
+
+
address@hidden Init File General Block Commands
address@hidden Init File General Block Commands
+
address@hidden Init file general block commands
address@hidden General block commands, in init files
address@hidden Block commands, in init files
+
+A @dfn{general block @@-command} is any @@-command which is paired
+with an @code{@@end @var{cmdname}}, with the exception of those
+@@-commands selecting whether input is processed (such as
address@hidden@@ignore} and @code{@@ifhtml}) and ``raw'' @@-commands (such as
address@hidden@@verbatim} and @code{@@html}).
+
address@hidden {Function Reference} $line begin_format_texi $command $line
\%state
address@hidden is the format command, @var{$line} is the rest of the
+line following the @@-command, and @var{\%state} is a hash reference
+with detailed context information. The function can modify
address@hidden and return something else.
address@hidden deftypefn
+
+By default, this is used to keep track of multitable nesting, and so
+it is linked with multitable formating.
+
address@hidden oldapi @pxref{Multitable Formatting}
+
+
address@hidden Init File Expansion Contexts
address@hidden Init File Expansion Contexts: Normal, Preformatted, String, Math
+
address@hidden Init file expansion contexts
address@hidden Expansion contexts, for init files
address@hidden Contexts for expansion in init files
+
+There are four expansion contexts of interest:
+
address@hidden @emph
address@hidden normal context
address@hidden Normal expansion context
+Paragraphs, index entries, tables, @enddots{}
+
address@hidden preformatted context
address@hidden Preformatted expansion context
+When spaces between words are kept. For example, within the
address@hidden@@display} (@pxref{display,, @code{@@display}}) and
address@hidden@@example} environments (@pxref{example,, @code{@@example}}), and
+in menu comments. The preformatted regions
+are usually rendered using @code{<pre>} elements in HTML.
+
address@hidden oldapi (@pxref{Menu formatting})
+
address@hidden string context
address@hidden String expansion context
+When rendering strings without formatting elements, for example in
+comments (@pxref{Comments}) and titles. We have two string contexts,
+one that produces plain text, and a second that allows for limited
+formatting, typically without any element when producing HTML or XML,
+so the value can be used in an attribute.
+
address@hidden math context
address@hidden Math expansion context
+Math (@pxref{math,, @code{@@math}}).
+
address@hidden table
+
+
address@hidden Internationalization of Strings
address@hidden Internationalization of Strings in the Output Document
+
address@hidden I18n
address@hidden Internationalization of strings in the output document
address@hidden Output documentation, internationalization of
+
address@hidden documentlanguage @r{configuration variable}
address@hidden writes some fixed strings in the generated document
+at various places: for cross references, in page footers, on the help
+page, alternate text for images, and so on. The string chosen depends
+on the value of the configuration variable @code{documentlanguage} at
+the time of the string being output (@pxref{documentlanguage}, for the
+Texinfo command interface).
+
address@hidden libintl-perl @r{Gettext implementation}
+The Gettext framework is used for those strings (@pxref{Top,,,
+gettext, Gettext}). The @code{libintl-perl} package is used as
+the @code{gettext} implementation; more specifically, the pure Perl
+implementation is used, so Texinfo can support consistent behavior
+across all platforms and installations, which would not otherwise be
+possible. @code{libintl-perl} is included in the Texinfo distribution
+and always installed, to be sure that it is available if needed. It
+is also possible to use the system @code{gettext}; currently decided
+at build-time).
+
address@hidden texinfo_document @r{Gettext domain}
+The Gettext domain @samp{texinfo_document} is used for the strings,
+and the subroutine @code{gdt} is used for translated
+strings:
+
address@hidden gdt ($string, \%variables_hash, \%state)
address@hidden is the string to be translated, @var{\%variables_hash}
+is a hash reference holding the variable parts of the translated
+string, and @var{\%state} is a hash reference with detailed context
+information.
address@hidden defun
+
address@hidden Perl format strings for translation
+Translated strings are written as Texinfo, and may include
+@@-commands. In translated strings, the varying parts of the string
+are not usually denoted by @code{%s} and the like, but by
address@hidden@address@hidden (This convention is common for @code{gettext} in
+Perl and is fully supported in GNU Gettext; @pxref{perl-format,, Perl
+Format Strings, gettext, GNU Gettext}.) For example, in the
+following, @address@hidden@}} will be replaced by the section name:
+
address@hidden
+see @address@hidden
address@hidden example
+
+These Perl-style brace format strings are used for two reasons: first,
+changing the order of @code{printf} arguments is only available since
address@hidden; second, and more importantly, the order of the
+argument is unpredictable, since @@-command expansion may lead to
+different orders depending on the output format. The expansion of
+a translation string is done like this:
+
address@hidden
address@hidden First, the string is translated. The locale
+is @var{@@address@hidden@var{@@documentencoding}.
+
address@hidden @code{us-ascii} encoding, and translations
+If the @var{@@documentlanguage} has the form @var{ll_CC}, @var{ll_CC}
+is tried first, and then @var{ll}. If that does not exist, and the
+encoding is not @code{us-ascii}, then @code{us-ascii} is tried. The
+idea is that if there is a @code{us-ascii} encoding, it means that all
+the characters in the charset may be expressed as @@-commands. For
+example, there is a @code{fr.us-ascii} locale that can accommodate any
+encoding, since all the address@hidden characters have associated
+@@-commands. On the other hand, Japanese has only a translation
address@hidden, since there are no @@-commands for Japanese
+characters.
+
address@hidden Next, the args in string are protected. For example,
address@hidden@{ arg_name @}} address@hidden
address@hidden@@address@hidden@} address@hidden
+@@address@hidden@}}
+(this part is skipped if there is nothing to expand).
+
address@hidden Next, the string is expanded as Texinfo.
address@hidden@@address@hidden@}} expands to @address@hidden and
address@hidden@@address@hidden@}} expands to @address@hidden,
+such that in the end one still gets @address@hidden@}} within an
+expanded string (this part is skipped if there is nothing to expand).
+
address@hidden Finally, the arguments are substituted; for
+example, @address@hidden@}} is replace by the corresponding actual
+argument.
+
address@hidden enumerate
+
address@hidden duplicate @r{in @code{%state} hash}
+In the following example, @address@hidden@}}, @address@hidden@}}
+and @address@hidden@}} are the arguments of the string. Since they
+are used in @code{@@uref}, their order is not predictable. The
address@hidden@{'duplicate'=>address@hidden means that the document state
should be used
+when expanding the string. @address@hidden@}},
address@hidden@address@hidden and @address@hidden@}} are substituted
+after the expansion, which means that they should already be
+acceptable output:
+
address@hidden
+gdt('Generated on @@address@hidden@address@hidden@} using
+ @@address@hidden@address@hidden,
@@address@hidden@address@hidden@address@hidden',
+ @{
+ 'date' => $date,
+ 'program_homepage' => $Texi2HTML::address@hidden'program_homepage'@},
+ 'program' => $Texi2HTML::address@hidden'program_and_version'@} @},
+ @{'duplicate'=>1,
+ @});
address@hidden example
+
+This approach is admittedly a bit complicated. Its usefulness is that
+it supports having translations available in different encodings for
+encodings which can be covered by @@-commands, and also specifying how
+the formatting for some commands is done, independently of the output
+format---yet still be language dependent. For example, a
address@hidden@@pxref} translation string may be:
+
address@hidden
+see @address@hidden section address@hidden@}\' in
@@address@hidden@address@hidden@}
address@hidden example
+
address@hidden
+which allows specifying a string independently of the output format,
+but with rich formatting that may be translated appropriately in many
+languages.
+
address@hidden keep_texi @r{in @code{%state} hash}
+Expansion can be prevented by setting the key @code{keep_texi} in the
address@hidden hash.
+
+When an @code{@@documentlanguage} line appears in the document and the
+language was not set on the command line, it is convenient for the
+translations to redefine some variables based on the new language.
+Therefore, Texinfo has a function reference which is called each time
address@hidden@@documentlanguage} is encountered:
+
address@hidden {Function Reference} $translate_names
+Called each time @code{@@documentlanguage} is encountered, if the
+language was not set on the command line. It should be used to
+retranslate strings based on the new language.
address@hidden deffn
+
+
address@hidden Output Elements
address@hidden Output Elements
+
address@hidden Output elements
address@hidden Elements, main unit of output documents
+
+We will call the main unit of output documents an @dfn{element}. An
+element's association with output files is determined by the split
+options (@pxref{Splitting Output}). This section describes precisely
+how these output elements work, with details for customization.
+
address@hidden
+* Defined: Output Elements Defined.
+* Labels: Output Element Labels.
+* Lines: Output Element Lines.
address@hidden menu
+
+
address@hidden Output Elements Defined
address@hidden Output Elements Defined
+
address@hidden Output elements, defined
+
+The output elements are:
+
address@hidden @emph
address@hidden Normal elements
address@hidden Normal elements
+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. Either the node or the sectioning command is considered to
+be the main element component, depending on the values of the
+configuration variables @code{USE_NODES} and @code{USE_SECTIONS}
+(@address@hidden Configuration Variables}).
+
+For example, when generating Info, the nodes are the elements; when
+generating Docbook, sectioning commands are the main element
+component; and when generating HTML, either case may happen
+(@pxref{Two Paths}).
+
address@hidden Top element
address@hidden Top element
+The top element is the highest element in the document structure. If
+the document has an @code{@@top} section (@pxref{makeinfo top}), it is
+the element associated with that section; otherwise, it is the element
+associated with the document's @code{@@node Top} (@pxref{The Top
+Node}). If there is no @code{@@node Top}, the first element in the
+document is the top element.
+
+The top element may end up formatted differently from normal elements
+if there is an @code{@@top} section or the @code{@@node Top} is not
+associated with a sectioning command.
+
address@hidden Miscellaneous elements
address@hidden Table of contents, output element
address@hidden Short table of contents, output element
address@hidden Overview, output element
address@hidden Footnotes, output element
address@hidden About page, output element
+The remaining elements are associated with different files if the
+document is split, and also if @code{MONOLITHIC} is not set. There
+are four such miscellaneous elements:
+
address@hidden
address@hidden Table of contents
address@hidden Short table of contents, also called Overview
address@hidden Footnotes page
address@hidden About page
address@hidden enumerate
+
+More details:
+
address@hidden
address@hidden The @emph{Table of contents} should only be formatted if
address@hidden@@contents} is present in the document.
+
address@hidden Similarly the @emph{Overview} should only appear if
address@hidden@@shortcontents} or @code{@@summarycontents} is present.
+
address@hidden The configuration variables @code{contents} and
address@hidden may be set to trigger the output of the
+respective elements.
+
address@hidden If @code{INLINECONTENTS} is set, the @emph{Table of contents} and
address@hidden elements are directly included within the document,
+rather than as separate pages (@pxref{Contents and Overview Elements
+Customization}).
+
address@hidden When generating HTML, the @emph{Footnotes page} should only
+be present if the footnotes appear on a separate page (@pxref{Footnote
+Styles}). However, a footnote element is present if the document is
+not split.
+
address@hidden The @emph{About page} shouldn't be present for documents
+consisting of only one sectioning element, or for monolithic documents
+without navigation information.
+
address@hidden itemize
address@hidden table
+
+It is common not to have anything but normal elements, especially in
+case of monolithic output. It is usually with HTML output that
+special elements may be present.
+
+The main component of elements is sections if @code{USE_SECTIONS} is
+set or @code{USE_NODES} is set to 0; conversely, the main component is
+nodes if @code{USE_NODES} is set or @code{USE_SECTIONS} is 0. If both
+configuration variables are undefined, heuristics are used, influenced
+by the presence of nodes or sectioning elements in the document: if
+there are no nodes, sectioning elements are preferred and vice versa.
+
+When sections are the main components of elements, ``isolated'' nodes
+not directly associated with a sectioning command are associated with
+the following sectioning command, while sectioning commands without
+nodes constitute an element. 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
+elements.
+
+
address@hidden Output Element Labels
address@hidden Output Element Labels
+
address@hidden Output element labels
address@hidden Element labels
+
+A variety of data items, called @dfn{element labels}, are associated
+with elements. They may be used in the formatting functions, and/or
+associated with a button (@pxref{Navigation Panel Button Specification}).
+
+Each element label has a name and a reference to the element they
+represent, when such an element exists. The element is either a
+global element (for example, the first element) or relative to the
+current element (for example, the next element). Such relative
+elements are determined with respect to the document structure defined
+by the section structuring commands (@code{@@chapter},
address@hidden@@address@hidden) or by the nodes if the node pointers are
+specified on @code{@@node} lines or in menus, as explained above
+(@pxref{Two Paths}).
+
+Here is the list of element labels:
+
address@hidden @emph
address@hidden @samp{@ }
+An empty button.
+
address@hidden Top
+Top element. The associated name is @code{$TOP_HEADING} if that variable is
+defined. This variable is not set by default.
+
address@hidden About
+About (help) page.
+
address@hidden Contents
+Table of contents.
+
address@hidden Overview
+Overview: short table of contents.
+
address@hidden Footnotes
+Corresponds to the @code{Footnotes} element (@pxref{Output Elements
+Defined}).
+
address@hidden Index
+The first chapter with @code{@@printindex}. The associated name is
address@hidden, if the variable is set. This variable is not
+set by default.
+
address@hidden This
+The current element.
+
address@hidden Forward
+Next element in reading order.
+
address@hidden First
+First element in reading order.
+
address@hidden Last
+Last element in reading order.
+
address@hidden Back
+Previous element in reading order.
+
address@hidden FastForward
+Next chapter.
+
address@hidden FastBack
+Beginning of this chapter, or previous chapter if the element is a chapter.
+
address@hidden Next
+Next section at the same level.
+
address@hidden Prev
+Previous section at the same level.
+
address@hidden Up
+Up section.
+
address@hidden SectionNext
+Next in section reading order.
+
address@hidden SectionPrev
+Previous in section reading order.
+
address@hidden SectionUp
+Up in section reading order.
+
address@hidden NodeNext
+Next node.
+
address@hidden NodeForward
+Next node in node reading order.
+
address@hidden NodeBack
+Previous node in node reading order.
+
address@hidden NodePrev
+Previous node.
+
address@hidden NodeUp
+Up node.
+
address@hidden table
+
+The element labels may also be accessed when formatting elements.
+Four hashes are available, with their keys being the elements items,
+and their values as follows:
+
address@hidden @code
address@hidden %Texi2HTML::NAME
+The formatted element name.
+
address@hidden %Texi2HTML::HREF
+The element hypertext reference.
+
address@hidden %Texi2HTML::NODE
+The element node name.
+
address@hidden %Texi2HTML::NO_TEXI
+The element name after removal of texi commands.
+
address@hidden vtable
+
+For example, @code{$Texi2HTML::address@hidden'Back'@}} is the name of the
+previous element in reading order.
+
+
address@hidden Output Element Lines
address@hidden Output Element Lines
+
address@hidden Output elements lines
address@hidden Formatted lines, of output elements
+
+The following array references holds formatted lines relating to
+various output elements.
+
address@hidden @code
address@hidden $Texi2HTML::OVERVIEW
+Lines of the short table of contents. @xref{Contents and Overview
+Elements Customization}.
+
address@hidden $Texi2HTML::THIS_SECTION
+Lines of the current element.
+
address@hidden $Texi2HTML::TITLEPAGE
+The title page formatted. @xref{HTML Title Page Customization}.
+
address@hidden $Texi2HTML::TOC_LINES
+Lines of table of contents. @xref{Contents and Overview Elements
+Customization}.
+
address@hidden vtable
+
+
address@hidden Navigation Panel Customization
address@hidden Navigation Panel Customization
+
address@hidden Customization, of navigation panel
address@hidden Navigation panel, customization of
+
+The @dfn{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.
+
+Considerable customization can done with straightforward variable
+assignments, especially special arrays. The configuration variables
address@hidden, @code{ICONS}, @code{HEADERS},
address@hidden, @code{USE_ACCESSKEY} and @code{USE_REL_REV}
+may be used to change the the navigation panel formatting.
address@hidden@command{texi2any} Configuration Variables}.
+
+In the unusual case that this isn't enough, it is also possible to
+redefine the function doing the navigation panel formatting.
+
address@hidden
+* Buttons: Navigation Panel Button Specification.
+* Functions: Navigation Panel Formatting Functions.
address@hidden menu
+
+
address@hidden Navigation Panel Button Specification
address@hidden Navigation Panel Button Specification
+
address@hidden Navigation panel button specification
address@hidden Button specification, navigation panel
+
+Several arrays and hashes enable precise control over the navigation
+panel buttons and their display. The following arrays determine the
+buttons present in the various navigation panels:
+
address@hidden @code
address@hidden @@SECTION_BUTTONS
+Specifies the navigation panel buttons present at the beginning of
+sectioning elements. If the output is split at nodes or sections,
+they are also used at the page footer, and in the case of section
+navigation being enabled, at the page header.
+
address@hidden @@SECTION_FOOTER_BUTTONS
address@hidden @@NODE_FOOTER_BUTTONS
+These arrays specify the navigation panel buttons present in the page
+footer when the output is split at sections or nodes, respectively.
+
address@hidden WORDS_IN_PAGE
+If @code{WORDS_IN_PAGE} is set and the output is split at nodes, these
+buttons are only included if the sectioning element text has more than
address@hidden words. The word counting is only approximate and
+includes punctuation marks, html elements, numbers. The default is to
+include the buttons for elements larger than 300 words.
+
address@hidden @@CHAPTER_BUTTONS
+Specifies the buttons appearing at the page footer if split at
+chapters, and at the page header if split at chapters and there is no
+section navigation.
+
address@hidden @@MISC_BUTTONS
+Specifies the buttons appearing at the beginning of special elements
+and, if the output is split, at the end of such elements.
+
address@hidden @@LINKS_BUTTONS
+Used for @code{<link>} elements if they are output in the headers.
+
address@hidden @@TOP_BUTTONS
+Specifies the buttons used in the top element (@pxref{Output Elements
+Defined}).
address@hidden vtable
+
+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:
+
address@hidden @emph
address@hidden function reference
+The function is called with one boolean argument, true if the
+navigation panel should be vertical. Should return the formatted
+button text.
+
address@hidden scalar reference
+The scalar value is printed. @xref{Output Element Labels}, for some
+scalars that may be useful here.
+
address@hidden array reference
+Here, the first array element should be a reference to a text string
+and the second element an element label. A link to the element
+associated with the element label with the given text is generated.
+
+For example, if the button array element is
address@hidden
+[ 'Next', \$Texi2HTML::address@hidden@} ]
address@hidden example
+
address@hidden
+Then the button will be a link to the next section with text
address@hidden::address@hidden@}}.
+
address@hidden element label
address@hidden %NAVIGATION_TEXT
address@hidden init_out
+If icons are not used, the button is a link to the corresponding
+element whose text is defined by the value associated with the element
+label in the @code{%NAVIGATION_TEXT} hash, surrounded by @samp{[} and
address@hidden If the element label is @samp{ }, the @samp{[} and @samp{]}
+are omitted. The elements of the @code{%NAVIGATION_TEXT} hash are
+defined dynamically, in the @code{init_out} function reference
+(@pxref{Output Initialization}).
+
address@hidden %ACTIVE_ICONS
address@hidden %BUTTONS_NAME
address@hidden %PASSIVE_ICONS
address@hidden %NAVIGATION_TEXT
address@hidden Icons, in navigation buttons
+If icons are used, the button is an image whose file is determined by
+the value associated with the element label in the
address@hidden hash if the link leads to an element, or in the
address@hidden 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 are
+in @code{%BUTTONS_NAME} for the button name and
address@hidden for the description.
address@hidden table
+
address@hidden %BUTTONS_ACCESSKEY
address@hidden @code{accesskey} navigation
+If the configuration variable @code{USE_ACCESSKEY} is set, the
address@hidden attribute is used in navigation. The
address@hidden hash is then used for the @code{accesskey}
+attributes.
+
address@hidden address@hidden, for navigation}
address@hidden @code{rel} navigation
+Similarly, if the @code{USE_REL_REV} configuration variable is set,
+the @code{rel} attribute is used in navigation. In that case the
address@hidden hash is used for the @code{rel} attribute.
+
+
address@hidden Navigation Panel Formatting Functions
address@hidden Navigation Panel Formatting Functions
+
address@hidden Navigation panel formatting functions
address@hidden Formatting functions, for navigation panel
+
+In the unusual event that your needs are not met by changing the
+navigation buttons (see the previous section), you can completely
+control the formatting of navigation panels by redefining function
+references.
+
+The overall display of navigation panels is controlled via this
+function reference, @code{print_navigation}:
+
address@hidden {Function Reference} $navigation_text print_navigation @
+ \@@buttons $vertical
address@hidden@@buttons} is an array reference holding the specification of
+the buttons for that navigation panel. @var{$vertical} is true if the
+navigation panel should be vertical. Returns the formatted navigation
+panel in @var{$navigation_text}.
address@hidden deftypefn
+
+The function reference @code{button_formatting} does the formatting of
+one button:
+
address@hidden {Function Reference} $formatted_button button_formatting @
+ $button $vertical
address@hidden holds the specification of the button as explained
+above. @var{$vertical} is true if the navigation panel should be
+vertical. Returns the formatted result in @var{$formatted_button}.
address@hidden deftypefn
+
+By default, the function associated with @code{$print_head_navigation}
+formats the navigation panel for the page header.
+
address@hidden {Function Reference} $page_head print_head_navigation @
+ $filehandle \@@buttons $first_in_page $previous_is_top \%element
address@hidden @bullet
address@hidden @var{$filehandle} is the opened filehandle the function should
+write to, if defined. If not defined the function should return the
+formatted page header as a string.
+
address@hidden @var{\@@buttons} is an array reference holding the specification
+of the buttons for the navigation panel.
+
address@hidden @var{$first_in_page} should be set if this is the first
navigation
+panel in the page.
+
address@hidden @var{$previous_is_top} is true if the previous element is the
+top element.
+
address@hidden @var{\%element} is a hash reference with information about
+the element.
address@hidden itemize
address@hidden deftypefn
+
+Similarly, the function associated with @code{$print_foot_navigation}
+formats the navigation panel for the page footer.
+
address@hidden {Function Reference} print_foot_navigation @
+ $filehandle \@@buttons $rule $print_navigation_panel \%element $maybe_in_page
address@hidden @bullet
address@hidden @var{$filehandle}, @var{\@@buttons}, and @var{\%element} are as
above.
+
address@hidden @var{$rule} is a rule that may be used to separate the
navigation panel
+from the preceding text.
+
address@hidden @var{$print_navigation_panel} is a boolean specifying
+whether the navigation panel itself should be printed.
+
address@hidden @var{$maybe_in_page} is set if the present footer is between
+regular elements and the top, or between regular elements and special
+elements, that is, not at the end of a file.
address@hidden itemize
address@hidden deffn
+
+
address@hidden Customizing HTML Page Layout
address@hidden Customizing HTML Page Layout
+
address@hidden provides for customization of the HTML page
+headers, footers, and the section layout in between. (These are
+unrelated to the headings and ``footings'' produced in @TeX{} output;
address@hidden,, Page Headings}.)
+
address@hidden
+* Headers: Customizing HTML Page Headers.
+* Sections: Customizing HTML Section Layout.
+* Footers: Customizing HTML Page Footers.
address@hidden menu
+
+
address@hidden Customizing HTML Page Headers
address@hidden Customizing HTML Page Headers
+
address@hidden Customizing HTML page headers
address@hidden Headers, customizing for HTML
+
+The following three function references give full control over the
+page header formatting done at the top of each HTML output file. The
address@hidden function is called for all pages. After that,
+the @code{$print_chapter_header} function is called if the output is
+split at chapters, or the @code{$print_section_header} function if the
+split at sections.
+
address@hidden {Function Reference} print_page_head $filehandle
address@hidden @code{<body>} tag, outputting
address@hidden is the opened filehandle to which the function
+should write. This function should print the page header, in HTML,
+including the @code{<body>} element.
address@hidden deftypefn
+
address@hidden {Function Reference} print_chapter_header $filehandle \%element
address@hidden is the opened filehandle to which the function
+should write. @var{\%element} is a hash reference with information
+about the element. This function is called if the output is split
+at chapters, after @code{$print_page_head}.
address@hidden deffn
+
address@hidden {Function Reference} print_section_header $filehandle \%element
address@hidden and @var{\%element} are as above. This function is
+called if the output is split at sections, after
address@hidden
address@hidden deffn
+
address@hidden $EXTRA_HEAD
address@hidden $AFTER_BODY_OPEN
address@hidden @code{<head>} block, adding to
+You can define the variable @code{$EXTRA_HEAD} to add text within the
address@hidden<head>} HTML element. Similarly, the value of
address@hidden is added just after @code{<body>} is output.
+These variables are empty by default.
+
address@hidden address@hidden, in customization}
address@hidden @code{<body>} tag, attributes of
+The @code{<body>} element attributes may be set by defining the
+configuration variable @code{BODYTEXT}.
+
address@hidden ENCODING_NAME
address@hidden Encoding, in HTML output
+By default, the encoding name from @code{ENCODING_NAME} is used. If
+this variable is not defined, it is automatically determined
+(@pxref{Init File Encodings}).
+
address@hidden $DATE_IN_HEADER
address@hidden Date, in header
+A date is output in the header if @code{$DATE_IN_HEADER} is set.
+
address@hidden Document description, in HTML output
+The description from @code{@@documentdescription} (or a value set as a
+configuration variable) is used in the header
+(@pxref{documentdescription}).
+
address@hidden @@address@hidden, in customization}
address@hidden address@hidden, in customization}
address@hidden<link>} elements are used in the header if @code{$USE_LINKS} is
+set, in which case @code{@@LINKS_BUTTONS} determines which links are
+used and @code{%BUTTONS_REL} determines the link type associated with
+the @code{rel} attribute. @xref{Navigation Panel Button
+Specification}.
+
+
address@hidden Customizing HTML Section Layout
address@hidden Customizing HTML Section Layout
+
address@hidden Customizing HTML section layout
address@hidden Section layout, customizing for HTML
+
+The following function references are used for the formatting of
+sections in HTML output:
+
address@hidden {Function Reference} print_section $filehandle @
+ $first_in_page $previous_is_top \%element
address@hidden @var
address@hidden $filehandle
+The opened filehandle to which the function should write.
+
address@hidden $first_in_page
+True if this section is the first section in the page.
+
address@hidden $previous_is_top
+True if this section is the section following the top section.
+
address@hidden \%element
+A hash reference with information about the element.
address@hidden table
+
+The function should print the current section contents.
address@hidden deffn
+
address@hidden {Function Reference} end_section $filehandle @
+ $last_element_or_before_top \%element
address@hidden and @var{\%element} are as above.
address@hidden is true if this section precedes the
+top element or is the last one in page, or before the special
+elements.
address@hidden deffn
+
+
address@hidden Customizing HTML Page Footers
address@hidden Customizing HTML Page Footers
+
address@hidden Customizing HTML page footers
address@hidden Footer, customizing for HTML
+
+The following function references give full control over the page
+footer formatting done at the bottom of each HTML output file. The
address@hidden function is called if the output is split
+at chapters, or the @code{$print_section_footer} footer is called if
+split at sections. After that, the @code{$print_page_foot} function
+is called.
+
address@hidden {Function Reference} print_page_foot $filehandle
address@hidden @code{</body>} tag, outputting
address@hidden is the opened filehandle to which the function
+should write. This function should print the page footer, including
+the @code{</body>} element.
address@hidden deffn
+
address@hidden {Function Reference} print_chapter_footer $filehandle \%element
address@hidden is the opened filehandle to which the function
+should write. @var{\%element} is a reference to a hash with
+information about the element. This function is called if the
+output is split at chapters, before @code{$print_page_foot}.
address@hidden deffn
+
address@hidden {Function Reference} print_section_footer $filehandle \%element
address@hidden and @var{\%element} are as above.
+This function is called if the output is split at sections, before
address@hidden
address@hidden deffn
+
address@hidden $PRE_BODY_CLOSE
+You can define the variable @code{$PRE_BODY_CLOSE} to add text just
+before the HTML @code{</body>} element. Nothing is added by default.
+
address@hidden $PROGRAM_NAME_IN_FOOTER
+If @code{$PROGRAM_NAME_IN_FOOTER} is set, the date and name of the
+program that generated the output are output in the footer.
+
+
address@hidden Customizing Special Elements
address@hidden Customizing Special Elements
+
+Various function references allow you to customize both the content
+and layout of the HTML output of the special elements (@pxref{Output
+Elements Defined}).
+
address@hidden
+* Content: Customizing Content of Special Elements.
+* Layout: Customizing Layout of Special Elements.
address@hidden menu
+
+
address@hidden Customizing Content of Special Elements
address@hidden Customizing Content of Special Elements
+
address@hidden Customizing special elements content
address@hidden Special elements content, customizing
address@hidden Content of special elements, customizing
+
+The label for the special elements (@pxref{Output Elements Defined}),
+except for the top element, is formatted according to the function
+reference @code{$misc_element_label}:
+
address@hidden {Function Reference} $misc_element_label misc_element_label @
+ $identifier $page_name
address@hidden is the identifier associated with the special
+element. @var{$page_name} is the special element name. The function
+should return a label that can be used for references to the special
+element.
address@hidden deftypefn
+
+The following sections describe the details for the special elements
+other than footnotes, which are formatted when the @code{@@footnote}
+command is expanded.
+
address@hidden oldapi (@pxref{Customizing HTML Footnotes}).
+
address@hidden
+* Top Element Customization::
+* Contents and Overview Elements Customization::
+* About Element Customization::
+* HTML Title Page Customization::
address@hidden menu
+
+
address@hidden Top Element Customization
address@hidden Top Element Customization
+
address@hidden Customization of top element
address@hidden Top element, customizing
+
+The top element formatting is controlled by three functions which also
+controls the layout of the top element page or section. The associated
+function references are:
+
address@hidden {Function Reference} print_Top_header $filehandle $begin_page
address@hidden is the opened filehandle to which the function
+should write. @var{$begin_page} is true if the element is the first
+in a page. This function should begin the top element. At the time
+this function is called, the top element text has not been parsed.
address@hidden deffn
+
address@hidden {Function Reference} print_Top $filehandle $has_top_heading
\%element
address@hidden is the opened filehandle to which the function
+should write. @var{$has_top_heading} is true if there is a
address@hidden@@heading} command or @code{@@titlefont} command appearing in
+the top element text. @var{\%element} is a hash reference with
+information about the element. This function should be used to format
+the top element text and navigation panel.
address@hidden deffn
+
address@hidden {Function Reference} print_Top_footer $filehandle $end_page
\%element
address@hidden and @var{\%element} are as above. @var{$end_page}
+is true if the element is the last in a page. This function should
+end the top element.
address@hidden deffn
+
+
address@hidden Contents and Overview Elements Customization
address@hidden Contents and Overview Elements Customization
+
address@hidden Customization of tables of contents elements
address@hidden Contents, customizing elements
address@hidden Short table of contents element, customizing
address@hidden Overview element, customizing
+
+To begin with, the table of contents and short table of contents can
+be made to appear at either the beginning (the default) or end of the
+document.
+
address@hidden INLINE_CONTENTS
+By default, the configuration variable
address@hidden is set, specifying that the tables of contents
+are not output as separate elements but instead where the
+corresponding @@-command, for example @code{@@contents}, is set. This
+behavior is consistent with @command{texi2dvi}.
+
+If @code{INLINE_CONTENTS} is not set, 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.
+
address@hidden @@setcontentsaftertitlepage @r{and HTML output}
+If @code{@@setcontentsaftertitlepage} appears in the document, even if
address@hidden is set, the tables of contents are merged into
+the title material, which in turn is not output by default;
address@hidden Title Page Customization}.
+
+Next, the following variables allow for some useful control of the
+formatting of table of contents and short table of contents:
+
address@hidden @code
address@hidden $BEFORE_TOC_LINES
+Inserted before the table of contents text.
+
address@hidden $AFTER_TOC_LINES
+Inserted after the table of contents text.
+
address@hidden $BEFORE_OVERVIEW
+Inserted before the short table of contents text.
+
address@hidden $AFTER_OVERVIEW
+Inserted after the short table of contents text.
+
address@hidden $NO_BULLET_LIST_STYLE
+Expected to contain the CSS style used for the list style when there
+is no bullet.
+
address@hidden $NO_BULLET_LIST_CLASS
+Used for the class associated with the $NO_BULLET_LIST_STYLE CSS
+style.
+
address@hidden $NO_BULLET_LIST_ATTRIBUTE
+Used as attribute text for the list element when there is no bullet.
+It is used in the tables of contents if they are formatted as a list.
address@hidden vtable
+
+Finally, the following function reference provides even more control
+over the table of contents and short table of contents formatting
+reference:
+
address@hidden {Function Reference} toc_body \@@elements
address@hidden@@elements} is an array reference containing information about
+all the elements of the document. Each entry of this array is a hash
+reference, useful keys of which are as follows:
+
address@hidden @code
address@hidden top
+True if the element is the top element.
+
address@hidden index_page
+True if the element is an index page added because of index splitting.
+
address@hidden toc_level
+Level of the element in the table of contents: the highest level is 1
+for the top element and for chapters, appendices, etc., 2 for
+sections, unnumbered sections, etc., and so on.
+
address@hidden tocid
+Label to be used for references linking to this element within the
+table of contents.
+
address@hidden file
+The file containing the element, part of the link if the output is
+split.
+
address@hidden text
+Text of the element, with section number,
+
address@hidden name
+Text of the element, without section number.
address@hidden table
+
address@hidden $Texi2HTML::address@hidden, in customization}
address@hidden $Texi2HTML::address@hidden, in customization}
+This function doesn't return anything. Instead, it should fill the
+array corresponding to the @code{$Texi2HTML::TOC_LINES} and
address@hidden::OVERVIEW} references with the text for the
+respective tables of contents. @xref{Output Element Lines}.
address@hidden deffn
+
+By default, @code{$toc_body} calls two specialized function
+references, one for the contents and the other for the short contents.
+
address@hidden {Function Reference} \@@contents_lines contents @
+ \@@elements $contents_file
address@hidden@@elements} is an array reference as above.
address@hidden is the name of the file containing the table of
+contents. This function should return the formatted table of contents
+lines.
address@hidden deftypefn
+
address@hidden {Function Reference} \@@shortcontents_lines shortcontents @
+ \@@elements $shortcontents_file
address@hidden@@elements} is an array reference as above.
address@hidden is the name of the file containing the table
+of contents. This function should return the formatted overview
+(short table of contents) lines.
address@hidden deftypefn
+
+Another function reference is used to add a heading and a reference,
+to be used with @code{INLINE_CONTENTS} or merged into the title
+material. Its output is not used when the tables of contents are
+separate elements.
+
address@hidden {Function Reference} \@@inline_contents_lines inline_contents @
+ $filehandle $command \%element \@@elements
+Return a reference to an array holding the lines containing the
+contents, heading and reference. @var{$filehandle} is a reference to
+the currently opened file if the function is called because a
address@hidden@@contents} or @code{@@shortcontents} command was encountered,
+and @code{undef} otherwise. @var{$command} is either @samp{contents}
+or @samp{shortcontents}. @var{\%element} is a reference to a hash
+holding information about the element where the contents appeared.
+Relevant keys are:
+
address@hidden @code
address@hidden target
+The identifier associated with the table of contents, used
+to link to the table of contents.
+
address@hidden id
+The identifier associated with the element, used to do labels.
+Usually but not necessarily the same as @code{target}.
+
address@hidden file
+The file name containing the table of contents.
address@hidden table
+
address@hidden@@elements} is an array reference as above.
address@hidden deftypefn
+
+
address@hidden About Element Customization
address@hidden About Element Customization
+
address@hidden Customization of about element
address@hidden About element, customizing
+
+The default About element has an explanation of the buttons used in
+the document (controlled by @code{@@SECTION_BUTTONS};
address@hidden Panel Button Specification}) and an example showing
+the button targets. The formatting of this text may be influenced by
+the following:
+
address@hidden @code
address@hidden $PRE_ABOUT
address@hidden $AFTER_ABOUT
address@hidden $PRE_ABOUT
address@hidden $AFTER_ABOUT
+Each of these variables may be a scalar or a function reference. If a
+scalar, the value is used. If a function reference, it is called and
+the returned text is used. The text is added before or after the main
+About text, respectively.
+
address@hidden %BUTTONS_GOTO
address@hidden %BUTTONS_GOTO
+The keys of this hash are element labels (@pxref{Output Element
+Labels}), and the values are the text associated with each element
+label in the About text. By default, the elements of the hash are
+defined dynamically in the @code{init_out} function reference
+(@pxref{Output Initialization}).
+
address@hidden %BUTTONS_EXAMPLE
address@hidden %BUTTONS_EXAMPLE
+Like @code{%BUTTONS_GOTO}, except the values are the text from the
+About example, typically a section number.
+
address@hidden table
+
+If the above is not enough and you want to control exactly the
+formatting of the about text, the following function reference may be
+overridden:
+
address@hidden {Function Reference} $about_text about_body
+This function returns the about text.
address@hidden deftypefn
+
+
address@hidden HTML Title Page Customization
address@hidden HTML Title Page Customization
+
address@hidden $Texi2HTML::TITLEPAGE
+The HTML title page is first formatted using the text appearing in the
address@hidden@@titlepage} section, and put in the
address@hidden::TITLEPAGE} array reference (@pxref{Output Element
+Lines}). More formatting can be done using the following function
+reference:
+
address@hidden {Function Reference} titlepage \@@titlepage_lines @
+ $text $comment $simple_text
address@hidden@@titlepage_lines} is an array containing the Texinfo lines in
address@hidden@@titlepage}. @var{$text} is the text appearing in
address@hidden@@titlepage}, formatted. @var{$comment} is the text with
+Texinfo markup removed, thus should be simple plain text.
address@hidden is the text formatted in a string context with
+minimal formatting but no elements. This function should complete
address@hidden::TITLEPAGE}.
address@hidden deffn
+
+By default, this function outputs the title if there is no title page,
+and adds the table of contents and short table of contents if they are
+to be output and @code{@@setcontentsaftertitlepage} or
address@hidden@@setshortcontentsaftertitlepage} appear in the document
+(@pxref{Contents and Overview Elements Customization}).
+
address@hidden USE_TITLEPAGE_FOR_TITLE
address@hidden SHOW_TITLE
+The resulting title page output is used in the document if
address@hidden and @code{SHOW_TITLE} are set.
+
+
address@hidden Customizing Layout of Special Elements
address@hidden Customizing Layout of Special Elements
+
address@hidden Customizing special elements layout
address@hidden Special elements layout, customizing
address@hidden Layout of special elements, customizing
+
+The formatting of each of the special elements is controlled by a
+function, as listed in the following table:
+
address@hidden @code
address@hidden print_Top
address@hidden print_Top_header
address@hidden print_Top_footer
+Formatting of the top element. It is also used for the formatting of
+the top element text (@pxref{Top Element Customization}).
+
address@hidden print_Toc
+Formatting of the table of contents element.
+
address@hidden print_Overview
+Formatting of the short table of contents element.
+
address@hidden print_About
+Formatting of about (help) element.
+
address@hidden print_Footnotes
+Formatting of the footnote elements.
address@hidden ftable
+
address@hidden print_misc
address@hidden print_misc_header
address@hidden print_misc_footer
+In the default case, @code{$print_Top} calls @code{$print_Top_header}
+for the header and @code{$print_Top_footer} for the footer of top
+element. All the other functions call @code{$print_misc} which in
+turn calls @code{$print_misc_header} for the headers and
address@hidden for the footers.
+
+
address@hidden Customizing Output-Related Names
address@hidden Customizing Output-Related Names
+
+It is possible to control both output file names and target
+identifiers in detail.
+
address@hidden
+* File: Customizing Output File Names.
+* Target: Customizing Output Target Names.
address@hidden menu
+
address@hidden Customizing Output File Names
address@hidden Customizing Output File Names
+
address@hidden Customizing output file names
address@hidden Output file names, customizing
+
address@hidden PREFIX
address@hidden SUBDIR
address@hidden EXTENSION
+It is possible to specify the output file names with more control than
+merely the command line option @option{--output} (@pxref{Invoking
+texi2any}). The @code{PREFIX} configuration variable overrides the
+base name of the file given by @code{@@setfilename} or the file name
+and should not contain any directory components. To alter
+intermediate directories, use the @code{SUBDIR} configuration
+variable. Finally, The extension may also be overriden by the
+configuration variable @code{EXTENSION}. This variable should be
address@hidden if no extension is to be added.
+
address@hidden TOP_FILE
address@hidden TOC_FILE
+Furthermore, the configuration variables @code{TOP_FILE} and
address@hidden override the output file name for the top and contents
+elements.
+
address@hidden NODE_FILES
+Two function references enable further customization. The first,
address@hidden, is especially useful when @code{NODE_FILES} is
+true; it is used to customize the node file name.
+
address@hidden {Function Reference} $node_file node_file_name \%node $type
address@hidden is a hash reference with the following interesting keys
+(there are many others): the string @code{texi}, for the Texinfo node
+name, and the boolean @code{with_section}, true if associated with a
+section. @var{$type} is @code{top} if the node is the top element.
+The function should return the node file name (@var{$node_file}).
address@hidden deftypefn
+
+The other function reference, @code{element_file_name}, is used to
+customize the file names associated with each element, and the name of
+the file associated with the special elements (@pxref{Output Elements
+Defined}).
+
address@hidden {Function Reference} $file element_file_name @
+ \%element $type $txi_file_name
address@hidden is undefined for the special elements (@pxref{Output
+Elements Defined}), Otherwise, it is a hash reference with the
+following interesting keys (there are many others):
address@hidden @code
address@hidden texi
+The Texinfo element name.
+
address@hidden number
+The number associated with a section.
+
address@hidden doc_nr
+A number incremented whenever a new file should begin, based on how the
+document is split (@pxref{Splitting Output}).
+
address@hidden text
+The element text.
+
address@hidden name
+The element text without section number.
address@hidden table
+
address@hidden is empty for normal elements. For the top element it is
address@hidden; for the table of contents it is @samp{toc}; for the
+overview it is @samp{stoc}; for footnotes it is @samp{foot}; and for
+the about element it is @samp{about}.
+
address@hidden address@hidden, customizing output names of}
+If frames are used, due to the @code{FRAMES} configuration variable,
+the function reference is also called for @samp{frame}, the frame file
+name, and @samp{toc_frame}, the table of contents frame file name.
+
address@hidden is the basename of the Texinfo manual.
+
+The function should return the file name for the element (@var{$file}).
address@hidden deftypefn
+
+
address@hidden Customizing Output Target Names
address@hidden Customizing Output Target Names
+
address@hidden Customizing output target names
address@hidden Target names, customizing
address@hidden Id names, customizing
+
+Similar to file names, so-called target and id names may be set. The
address@hidden is placed where the item is located, while the @dfn{target}
+is used to construct references to that item. Usually, these should
+be the same.
+
address@hidden xx, but not always, for example in the default case, the
address@hidden xx target for a section is the node id.
+
+The following function reference is for target items (nodes, anchors,
+floats):
+
address@hidden {Function Reference} {($target,$id)} node_target_name @
+ \%node $default_target $default_id $type
address@hidden is the same as in the @code{node_file_name} function
+reference in the previous section. @var{$default_target} is the
+target that has been already set (it is also in
address@hidden>@{'target'@}}), and @var{$default_id} is, similarly, the
+id already set. @var{$type} is @code{top} if the node is the top
+node. The function should return a two-element list of the target and
+id names.
address@hidden deftypefn
+
+For elements (@pxref{Output Elements Defined}), the function
+reference is:
+
address@hidden {Function Reference} {($target,$id)} element_target_name @
+ \%element $default_target $default_id
address@hidden is the same as in @code{element_file_name} in the
+previous section, and @var{$default_target}, @var{$default_id}, and
+the return value, are as above.
address@hidden deftypefn
+
+The file, target, and id of ``placed'' items, namely floats,
+footnotes, index entries, anchors, contents, shortcontents and
+headings, may also be set, although the default should be suitable.
+Nevertheless, the following function reference can be used:
+
address@hidden {Function Reference} {($target, $id, $file)} @
+ placed_target_file_name \%placed_item \%element @
+ $default_target $default_id $default_file $context
+
address@hidden is a hash reference describing the placed item, as
+in the above, likewise @var{\%element}. @var{$default_file},
address@hidden and @var{$default_target} are the file, id and target
+already set. @var{$context} describes the context; this is set to
address@hidden if in footnotes, to @samp{no_associated_element} if
+the placed item is outside of any element (e.g., @code{@@titlepage},
address@hidden@@copying}), and is otherwise empty.
address@hidden deftypefn
+
address@hidden %misc_pages_targets
+For special elements, the @code{%misc_pages_targets} hash is used to
+set the target and id. The possibilities for the keys are
address@hidden, @samp{Contents}, @samp{Footnotes} and @samp{About}.
+
+
address@hidden Customizing HTML Headings
address@hidden Customizing HTML Headings
+
address@hidden Headings, customizing HTML
+
+A function reference may be defined to do the formatting of the heading
+text (usually changing font and underlining):
+
address@hidden {Function Reference} $heading_text_formatted heading_text @
+ $command $text $level
address@hidden is the @@-command name associated with the heading.
address@hidden is the heading @@-command argument, formatted.
address@hidden is the level of the heading in the document tree.
address@hidden deftypefn
+
address@hidden heading_text_preformatted
+A similar function reference is available for preformatted context,
address@hidden
+
+A function controls the formatting of element headings,
address@hidden By default its main job is to determine whether the
address@hidden function reference should be called. Normally,
+heading text is not output for a node on its, only for any associated
+sectioning element (@pxref{Two Paths}).
+
address@hidden {Function Reference} $heading_text heading \%element $command @
+ $command_texi_arg $formatted_arg $in_preformatted $one_section @
+ $element_heading
+
address@hidden @var
address@hidden \%element
+A hash reference representing the sectioning element. The
+following keys are of interest:
+
address@hidden @code
address@hidden text
+The heading text.
+
address@hidden text_nonumber
+The heading text without section number.
+
address@hidden node
+True if the sectioning element is a node without an associated
+structuring command.
+
address@hidden level
+The level of the element in the document tree: @samp{0} for
address@hidden@@top}, @samp{1} for @code{@@chapter}, and so on.
+
address@hidden tag_level
+The sectioning element name, with @code{@@raisesections} and
address@hidden@@lowersections} taken into account.
+
address@hidden top
+True if it is the top element.
address@hidden table
+
address@hidden $command
+The heading @@-command.
+
address@hidden $command_texi_arg
+The argument of the @@-command, unformatted.
+
address@hidden $formatted_arg
+The argument of the @@-command, formatted.
+
address@hidden $in_preformatted
+True if in preformatted environment.
+
address@hidden $one_section
+True if there is only one section.
+
address@hidden $element_heading
+True if the heading is the main component of the element.
address@hidden table
address@hidden deftypefn
+
+It is also possible to customize the heading text with section number
+with this function reference (called for headings and nodes):
+
address@hidden {Function Reference} $result_texi heading_texi @
+ $heading_command $heading $number
address@hidden is the sectioning @@-command of that heading.
address@hidden is the Texinfo input for that heading. @var{$number}
+is the heading number classically-computed with dots between numbers,
+and letters for top-level appendix numbering. This function should
+return the Texinfo text corresponding with the numbered heading.
address@hidden deftypefn
+
+The label associated with the heading that can appear before the
+heading itself and even before the navigation panel can be customized
+with this function reference:
+
address@hidden {Function Reference} $element_label element_label @
+ $identifier \%element $command $unformatted_line
address@hidden is the identifier associated with the heading.
address@hidden is the same as above. @var{$command} is the
+@@-command appearing on the line, and @var{$unformatted_line} is the
+line, unformatted.
address@hidden deftypefn
+
+Additionally, for @code{@@node} and sectioning @@-commands, the
+formatting of the label, navigation panel and heading is controlled
+by:
+
address@hidden {Function Reference} $element_heading_text element_heading @
+ \%element $command $command_texi_arg $formatted_arg @
+ $in_preformatted $one_section $element_heading $first_in_page @
+ $is_top $previous_is_top $unformatted_line $element_id $new_element
address@hidden, @var{$command}, @var{$command_texi_arg},
address@hidden, @var{$in_preformatted}, @var{$one_section}, and
address@hidden are as above. For the rest:
+
address@hidden @var
address@hidden $first_in_page
+True if this is the first heading in a page.
+
address@hidden $is_top
+True if the heading is considered as a top element heading.
+
address@hidden $previous_is_top
+True if the previous element was a top element.
+
address@hidden $unformatted_line
+Holds the whole line, unformatted.
+
address@hidden $element_id
+The id of the heading.
+
address@hidden $new_element
+True if the heading is the first of an element.
address@hidden table
address@hidden deftypefn
+
+
address@hidden Customizing Indices
address@hidden Customizing Indices
+
address@hidden Customizing indices
address@hidden Indices, customizing
address@hidden IDX_SUMMARY
+To do something special with index entries outside of the Texinfo
+source document (@pxref{Indices}), you should first set the
+configuration variable @code{IDX_SUMMARY} true. After that, various
+function references will be called for each non-empty index: one for
+initialization, one for each index entry, and one for finalization.
+
+Another way to work with the index (and tables of contents) entries is
+to specify the @option{--internal-links} option and use the resulting
+table; @pxref{Invoking texi2any}.
+
address@hidden {Function Reference} index_summary_file_begin $index_name @
+ $is_printed $manual_name
+This function is called once for each non-empty index used in the
+document, before any calls to @code{index_summary_file_entry}.
+
address@hidden @var
address@hidden $index_name
+The two-letter name of the index.
+
address@hidden $is_printed
+True if this index has a corresponding @code{@@printindex} command.
+
address@hidden $manual_name
+The manual basename.
address@hidden table
address@hidden deffn
+
address@hidden {Function Reference} index_summary_file_entry $index_name @
+ $entry_text $entry_reference $formatted_entry $texi_entry @
+ $entry_element_reference $entry_element_header $is_printed $manual_name
+This function is called for each entry of an index, in sorted order.
+The sorting happens regardless of whether the index is actually printed.
+
address@hidden @var
address@hidden $index_name
+The two-letter name of the index.
+
address@hidden $entry_text
address@hidden $formatted_entry
address@hidden $texi_entry
+The entry in plain text, formatted, and original source, respectively.
+
address@hidden $entry_reference
+The reference used for the index entry, in the form @samp{file#id}.
+
address@hidden $entry_element_reference
+The reference to the beginning of the element containing the index
+entry, also in the form @samp{file#id} (@pxref{Output Elements
+Defined}).
+
address@hidden $entry_element_header
+The formatted header of the element containing the index entry.
+
address@hidden $is_printed
+True if this index has a corresponding @code{@@printindex} command.
+
address@hidden $manual_name
+The manual basename.
address@hidden table
address@hidden deffn
+
address@hidden {Function Reference} index_summary_file_end $index_name
$is_printed @
+ $manual_name
+This function is called once for each non-empty index used in the
+document, after all calls to @code{index_summary_file_entry}. The
+arguments are the same as for @code{index_summary_file_begin}, above.
address@hidden deffn
+
+
address@hidden Customizing CSS
address@hidden Customizing the CSS lines
+
address@hidden Customizing CSS
address@hidden CSS customization
+
address@hidden %css_map
address@hidden INLINE_CSS
address@hidden NO_CSS
+The @code{NO_CSS} configuration option turns off CSS support. Instead
+of CSS lines being output at the beginning of the document, they may
+be added to HTML attributes, if @code{INLINE_CSS} is set.
+
+The configuration variable holds the CSS specification lines when CSS
+is not inline. It is possible to modify the CSS lines by modifying
+the entries or adding to the @code{%css_map} hash. Each key is a CSS
+selector, the corresponding value is a style string.
+
+It is also possible to change completely how CSS lines are generated
+by redefining the following function reference:
+
address@hidden {Function Reference} css_lines \@@import_lines \@@rule_lines
+This function should set the variable @code{CSS_LINES}.
address@hidden@@import_lines} is an array reference holding the
address@hidden@@import} lines of the files specified with
address@hidden @var{\@@rule_lines} is an array reference
+holding the CSS lines of those. files.
address@hidden deffn
+
* Customizing HTML Basic Commands:: Commands with no arguments, images, etc.
* Customizing HTML References:: @code{@@xref}, external node pointers, etc.
Index: doc/texinfo.txi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.385
retrieving revision 1.386
diff -u -b -r1.385 -r1.386
--- doc/texinfo.txi 26 Sep 2011 18:47:45 -0000 1.385
+++ doc/texinfo.txi 30 Sep 2011 19:13:05 -0000 1.386
@@ -1,5 +1,5 @@
\input texinfo.tex @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.385 2011/09/26 18:47:45 karl Exp $
address@hidden $Id: texinfo.txi,v 1.386 2011/09/30 19:13:05 pertusus Exp $
@c Ordinarily, Texinfo files have the extension .texi. But texinfo.texi
@c clashes with texinfo.tex on 8.3 filesystems, so we use texinfo.txi.
@@ -16860,7 +16860,7 @@
@samp{ascii} for Info.
@item DO_ABOUT
-If unset never do an About special element. @xref{Output Elements Defined}.
+If unset never do an About special element. @c @xref{Output Elements Defined}.
@item DOCTYPE
@vindex SystemLiteral
@@ -18802,35 +18802,33 @@
@node texi2any Output Customization
@chapter @command{texi2any} Output Customization
address@hidden
address@hidden Warning
-All of this information, with the exception of command-line options
-and search directories (@pxref{Loading Init Files}), may become
-obsolete in a future Texinfo release. Right now, the ``API''
-described in this chapter is immature, badly designed and incomplete,
-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.
address@hidden quotation
address@hidden cartouche
-
-This chapter describes how to customize many aspects of the
+This chapter describes how to customize
address@hidden many
+some aspects of the
@command{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.
+target format. Besides, most of the customizations are only available
+for HTML.
+
+This part of the manual and the corresponding interfaces are being
+stabilized, and the only parts described are those that should not
+change in the future. Many other aspects of the formatted HTML may already
+be customized, but the interfaces will change and will be documented
+as soon as they are stable.
+
+The HTML converter uses a Texinfo perl tree as input and converts
+it to HTML. The Texinfo perl tree describes a Texinfo document in a
+structured way which makes easy going through the tree and format
+@@-commands and other containers. The code that is used to go
+through the tree cannot be customized, but the conversion of tree
+elements can be fully customized. The tree structure and the customization
+of Texinfo perl tree elements will be described in future versions of the
+manual.
@menu
* Loading Init Files:: Finding and writing initialization files.
* Init File Basics:: What init files can contain and do.
-* Output Elements:: The main unit of output documents.
-* Navigation Panel Customization:: Navigation buttons and more.
-* Customizing HTML Page Layout:: Page headers, footers, sections.
-* Customizing Special Elements:: The top, toc, about, etc., elements.
-* Customizing Output-Related Names:: File names and target names.
-* Customizing HTML Headings:: Sectioning commands.
-* Customizing Indices:: Manipulating index entries.
-* Customizing CSS:: CSS customization for HTML.
@end menu
@@ -18846,22 +18844,20 @@
You can write so-called @dfn{initialization files}, or @dfn{init
files} for short, to modify almost every aspect of output formatting.
The program loads init files named @file{Config} each time it is run.
-Those files are looked for in the following directories (where
address@hidden is the name of the program invoked on the command line,
-normally @code{makeinfo} or @code{texi2any}):
+Those files are looked for in the following directories:
@table @file
address@hidden @var{datadir}/@var{prog}/
address@hidden @var{datadir}/texi2any/
(where @var{datadir} is the system data directory specified at
compile-time, e.g., @file{/usr/local/share})
address@hidden @var{sysconfdir}/@var{prog}/
address@hidden @var{sysconfdir}/texi2any/
(likewise specified at compile time, e.g., @file{/usr/local/etc})
address@hidden ~/address@hidden/
address@hidden ~/.texi2any/
(where @code{~} is the current user's home directory)
address@hidden ./address@hidden/
address@hidden ./.texi2any/
(under the current directory)
@item ./
@@ -18876,23 +18872,24 @@
However, the most common way to load an initialization file is with
the @option{--init-file} option, explicitly specifying the file to be
loaded. By default the following directories are searched, in the
-following order, where @var{prog} is the name of the program invoked
-on the command line (@command{makeinfo}, @command{texi2any}, etc.).
+following order.
address@hidden where @var{prog} is the name of the program invoked
address@hidden on the command line (@command{makeinfo}, @command{texi2any},
etc.).
Only the first file found is used:
@enumerate
@item The current directory @file{./};
address@hidden @file{./address@hidden/} under the current directory;
address@hidden @file{./.texi2any/} under the current directory;
address@hidden @file{~/address@hidden/}
address@hidden @file{~/.texi2any/}
where @code{~} is the current user's home directory;
address@hidden @address@hidden/@var{prog}/}
address@hidden @address@hidden/texi2any/}
where @var{sysconfdir} is the system configuration directory
specified at compile-time, e.g., @file{/usr/local/etc};
address@hidden @address@hidden/@var{prog}/}
address@hidden @address@hidden/texi2any/}
Where @var{datadir} is the system data directory likewise specified at
compile time, e.g., @file{/usr/local/share};
@@ -18916,93 +18913,21 @@
@cindex Perl, language for init files
Init files are written in Perl, and by convention have extension
address@hidden or @file{.pm}. Several init files are included in the Texinfo
-distribution (some are crucial components of the program), and can
-serve as a good model for writing your own. In particular, the
address@hidden file is used to set all the defaults for
-Texinfo. Although it is large, it contains many useful examples of
-settings. Smaller examples include @file{utf8.pm},
address@hidden, and plenty more.
address@hidden or @file{.pm}.
address@hidden Several init files are included in the Texinfo
address@hidden distribution (some are crucial components of the program), and
can
address@hidden serve as a good model for writing your own.
address@hidden Smaller examples include @file{utf8.pm},
address@hidden @file{html32.pm}, and plenty more.
@menu
-* Init File Variables:: Configuration & other variables, function references.
-* Init File Namespaces:: @code{Texi2HTML::Config}, @code{Texi2HTML}, and
@code{main}.
-* Init File Functions:: Redefining functions through references.
+* Init File Namespaces:: @code{Texinfo::Config}.
* Setting and Getting Configuration Variables::
-* Init File Global Information:: Accessing document title, file name, etc.
-* Init File Encodings:: Overriding input and output encodings.
-* texi2any's Three Passes:: Macro expansion, document structure, output
-* Init File Calling at Different Stages:: Calling functions at various times.
-* Init File Formatting of Commands:: Overriding default formatting completely.
-* Init File General Block Commands:: Customizing usual environments.
-* Init File Expansion Contexts:: Normal, preformatted, string, math.
address@hidden * Init File Expansion Contexts:: Normal, preformatted,
string, math.
* Internationalization of Strings::
@end menu
address@hidden Init File Variables
address@hidden Init File Variables
-
address@hidden Initialization file variables
address@hidden Variables, in initialization files
-
-We divide the kinds of variables that can appear in initialization
-files into three general categories:
-
address@hidden @asis
address@hidden configuration variables
address@hidden Configuration variables
-Configuration variables are set and accessed through specific
-functions in initialization files (@address@hidden Configuration
-Variables}).
-
address@hidden scalars, lists and hashes
address@hidden Perl variables
-Normal Perl variables. The order of loading of initialization files
-and of command-line options is important: later changes override
-earlier ones.
-
address@hidden function references
address@hidden Function references
-These allow dynamic redefinition of functions used to produce output.
-
-As such functions are defined by a reference name, we will always use
-the reference name in function prototypes. For the function arguments
-we will use @code{\@@array} to indicate a reference to an array
-(a.k.a.@: list, in Perl terminology) and @code{\%hash} for a reference
-to a hash.
-
-To illustrate these conventions, here is the prototype for the
-function associated with a function reference
address@hidden:
-
address@hidden {Function Reference} $text formatting_function $arg1 \@@arg2
address@hidden has a first argument @var{$arg1},
-a second argument a reference to an array @var{\@@arg2},
-and returns the formatted text @var{$text}.
address@hidden deftypefn
-
-To redefine this function, you would write:
-
address@hidden
-$formatting_function = \&my_formatting_function;
-sub my_formatting_function($ $)
address@hidden
- my $arg1 = shift;
- my $arg2 = shift;
- # prepare $formatted_text
- ...
- return $formatted_text;
address@hidden
address@hidden example
address@hidden table
-
-Since the program can process more than one file on the command line,
-you must ensure that you properly initialize the variables used during
-formatting. It is possible to call functions at different stages to
-help with that (@pxref{Init File Calling at Different Stages}).
-
-
@node Init File Namespaces
@subsection Init File Namespaces
@@ -19010,52 +18935,12 @@
@cindex Namespaces, for init files
@cindex Perl namespaces, for init files
address@hidden Texi2HTML::Config @r{namespace}
address@hidden Texinfo::Config @r{namespace}
Initialization file are loaded from the main program via a
address@hidden call in the @code{Texi2HTML::Config} namespace. This
address@hidden call in the @code{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. The program's own variables are declared with @code{use
-vars}, so that it should be possible to use the @code{use strict}
-pragma in initialization files.
-
address@hidden Texi2HTML @r{namespace}
address@hidden main @r{namespace}
-To avoid accidentally altering the variables in the @code{main}
-namespace, all the global variables which could be of use in init
-files are available in the @code{Texi2HTML} namespace.
-
-The functions of the main program, however, are still in the
address@hidden namespace.
-
-
address@hidden Init File Functions
address@hidden Init File Functions
-
address@hidden Init file functions
address@hidden Functions, overriding in init files
address@hidden Overriding functions in init files
-To redefine a function you must replace the appropriate function
-reference with a reference to your function: write your function, give
-it a name you ensure is unique in the @code{Texi2HTML::Config}
-namespace, and then override the value of the function reference with
-your own. When another function from the main program (or anywhere
-else) calls the reference, your function will be used.
-
-For example, the function reference to the function called when
-handling an anchor is called @code{$anchor}. Thus, to override the
-corresponding function you could write:
-
address@hidden
-# override the function reference:
-$anchor = \&my_anchor_fn;
-
-# define the function to do the work:
-sub my_anchor_fn @{
-# process arguments, return an html anchor
address@hidden
address@hidden example
-
+name clash.
@node Setting and Getting Configuration Variables
@subsection Setting and Getting Configuration Variables
@@ -19121,553 +19006,9 @@
Variables and Options}.
address@hidden Init File Global Information
address@hidden Init File Global Information
-
address@hidden @ignore
address@hidden FIXME those are still undocumented
address@hidden 'split_level'
address@hidden 'variable_levels' 'variables'
address@hidden do_about
address@hidden 'FH' 'state' 'format_from_command_line'
address@hidden command_stack
address@hidden line_nr
address@hidden %htmlxref
address@hidden %hyphenation
address@hidden @end ignore
-
address@hidden Init files, and global information
address@hidden Global information, in init files
-
-Much global information about the document is available as the basis
-for customization in init files.
-
address@hidden
-* Title String Variables:: @code{@@author}, @code{@@title}, etc.
-* Command Line String Variables:: Input and output file names, etc.
-* Global Document String Variables:: @code{@@copying}, CSS, TOC, etc.
-* Index String Variables:: @code{defindex}, @code{@@synindex}, etc.
-* Init File Flag Values:: @code{@@set} values.
-* Program String Customization:: For the About element and footers.
address@hidden menu
-
address@hidden Title String Variables
address@hidden Title String Variables
-
address@hidden Title string variables
-
-For title-related @@-commands, such as @code{@@title},
address@hidden@@titlefont}, and @code{@@author}, a variety of information is
-available, with diverse formatting.
-
address@hidden@@author} and @code{@@subtitle} are multiline title-related
-commands, since they may appear more than once. Multiline
-title-related commands are associated with strings that are
-constructed by concatenating all the command occurences. They are
-also associated with arrays, and the name of the arrays is constructed
-by appending a @samp{s} to the command name, as in @code{authors}.
-
-Some information is also deduced from the title commands:
address@hidden reflects @code{@@settitle} vs.\
address@hidden@@shorttitlepage}, and @dfn{fulltitle} is constructed by trying
-all the title-related commands, including @code{@@top} and
address@hidden@@titlefont}, in the top element.
-
address@hidden Texi2HTML::THISDOC
-The information associated with @code{@@top}, @code{@@title},
address@hidden@@settitle}, @code{@@shorttitlepage}, @code{@@author},
address@hidden@@subtitle}, @code{simpletitle} and @code{fulltitle} are
-associated with the following keys in the @code{%Texi2HTML::THISDOC}
-hash, where @var{command} is the title @@-command:
-
address@hidden @code
address@hidden @var{command}_texi
-The original Texinfo code.
-
address@hidden @var{command}
-The corresponding text formatted.
-
address@hidden @var{command}_no_texi
-The text formatted as simple plain text.
-
address@hidden @var{command}_simple_format
-The text formatted as a string without formatting elements
-(@pxref{Init File Expansion Contexts}).
-
address@hidden @var{command}_line_nr
-An opaque structure corresponding with the line where the @@-comand
-appeared. Not available for @code{@@titlefont}, multiline
-title-related commands and derived information.
-
address@hidden table
-
-For multiline commands, the following array references are associated
-with the following keys in the @code{%Texi2HTML::THISDOC} hash, where
address@hidden is the title @@-command:
-
address@hidden @code
address@hidden @var{command}s
-Reference to an array containing all lines set by
address@hidden@@@var{command}}, formatted.
-
address@hidden @var{command}s_texi
-Reference to an array containing all the original Texinfo lines.
-
address@hidden @var{command}s_line_nr
-Reference to an array of opaque structures corresponding with the
-line where the @@-command lines appeared.
-
address@hidden table
-
-
address@hidden Command Line String Variables
address@hidden Command Line String Variables
-
address@hidden Command-line string variables
-
-These entries in the @code{%Texi2HTML::THISDOC} hash are related to
-the command-line processing:
-
address@hidden @code
address@hidden destination_directory
-Destination directory for the output files.
-
address@hidden file_base_name
-Base name of the Texinfo input file.
-
address@hidden filename
-This is a reference to a hash that holds the filenames for special
-elements. These files may not be used in certain cases, for example
-the @code{toc} element file name may not be relevant if table of
-contents is not output separately. The keys are:
-
address@hidden @code
address@hidden doc
-If not split, the document file; if split, the top element file.
-
address@hidden top
-Top element file name.
-
address@hidden toc
-Table of contents element file name.
-
address@hidden stoc
-Overview (a.k.a.@: short table of contents) element file name.
-
address@hidden about
-About element file name.
-
address@hidden foot
-Footnotes element file name.
-
address@hidden frame
-Main frame file.
-
address@hidden toc_frame
-Table of contents frame file name.
-
address@hidden table
-
address@hidden input_directory
-Path to the directory containing the Texinfo input file being processed.
-
address@hidden input_file_name
-Name of the Texinfo input file as given on the command line.
-
address@hidden input_file_number
-Number of the Texinfo input file from the command line which is
-currently being processed.
-
address@hidden program
-The name of the command generating the output.
-
address@hidden program_and_version
-The name and version of the command generating the output.
-
address@hidden program_homepage
-Home page of the command generating the output.
-
address@hidden table
-
-
address@hidden Global Document String Variables
address@hidden Global Document String Variables
-
address@hidden Global document strings
-
-These entries in the @code{%Texi2HTML::THISDOC} hash provide other
-global document information.
-
address@hidden @code
address@hidden copying_comment
-Text appearing in @code{@@copying} with all the Texinfo commands
-put into comments (@pxref{copying,,@code{@@copying}}).
-
address@hidden css_import_lines
-Reference to an array containing the @code{@@import} lines of
address@hidden files (@pxref{HTML CSS}).
-
address@hidden css_rule_lines
-Reference to an array containing the normal lines of @acronym{CSS}
-files.
-
address@hidden dircategory_texi
-The Texinfo @code{@@dircategory} argument (@pxref{Installing Dir Entries}).
-
address@hidden dircategory
-The formatted @code{@@dircategory} argument.
-
address@hidden inline_contents
-A reference to a hash containing two keys, one for each type of table
-of contents: @code{contents} and @code{shortcontents}. Each
-associated value is a reference to an array containg the lines
-resulting from formatting the respective type of table of contents,
-including a heading and a reference.
-
address@hidden stoc_file
-The file name of the Overview (short table of contents).
-
address@hidden toc_file
-The file name of the table of contents.
-
address@hidden table
-
-
address@hidden Index String Variables
address@hidden Index String Variables
-
address@hidden Index strings
-
-These entries in the @code{%Texi2HTML::THISDOC} hash provide other
-index-related information.
-
address@hidden @code
address@hidden defindex
address@hidden defcodeindex
-References to arrays holding the corresponding @@-command
-arguments.
-
address@hidden merged_index
-Reference to a hash whose keys are the index names merged in
-the values.
-
address@hidden index_letters_array
address@hidden index_entries_array
address@hidden index_entries_region_array
address@hidden index_entries
address@hidden indices_numbers
address@hidden indices
-References to hashes holding information about the index entries
-and whole indices.
-
address@hidden synindex
address@hidden syncodeindex
-Reference to arrays containing array references with two elements,
-the two arguments of @code{@@synindex}
-(@pxref{synindex,,@code{@@synindex}}).
-
address@hidden table
-
-
address@hidden Init File Flag Values
address@hidden Init File Flag Values
-
address@hidden Init file flag values
address@hidden Flag values, in init files
-
address@hidden @code{@@set} values, in init files
address@hidden %main::value
-Flags defined with @code{@@set} (@pxref{set value})
-may be accessed through the @code{%main::value} hash. The key is the
-flag name, and the value is the flag value.
-
-
address@hidden Program String Customization
address@hidden Program String Customization
-
address@hidden Program string customization
address@hidden Customization of program string
address@hidden PROGRAM_NAME_IN_FOOTER
-
-The following function reference may be used to construct a string
-advertising the program used to generate the output. It may be used
-in the @code{About} element, and in the footers if
address@hidden is set.
-
address@hidden {Function Reference} $program_string_formatted program_string
-This function reference should return the formatted program
-string.
address@hidden deftypefn
-
-
address@hidden Init File Encodings
address@hidden Init File Encodings
-
address@hidden Init file encodings
address@hidden Encodings, in init files
-
-There are four encoding-related variables, which are autodetected
-if not set:
-
address@hidden @code
address@hidden documentencoding
-This configuration variable may be set, overriding any encoding
-set by @code{@@documentencoding} (@pxref{documentencoding,,
address@hidden@@documentencoding}}).
-
address@hidden IN_ENCODING
-The encoding of the Texinfo files may be set independently with this
-variable. If not, then when @code{documentencoding} is set,
address@hidden is also set if the encoding is supported by Perl.
-
address@hidden ENCODING_NAME
-The encoding advertised in output files. If not set, the value of
-this variable is based on the other ENCODING values, and if they are
-all undefined, the variable @code{DEFAULT_ENCODING} is used.
-
address@hidden OUT_ENCODING
-The encoding of the output files. If not set, the value of
address@hidden or @code{IN_ENCODING} is used if one of these
-variables is set.
-
address@hidden vtable
-
-In general, the @code{documentencoding} and @code{IN_ENCODING} are set
-to the appropriate values with no need to override.
address@hidden is set according to @code{ENCODING_NAME}. To
-force a given encoding for the output, it's best to set
address@hidden The default output encoding for Info is ASCII,
-and for other formats is UTF-8.
-
-The values for the encoding related variables are set in the default
address@hidden function reference (@pxref{Output Initialization}).
-
-
address@hidden texi2any's Three Passes
address@hidden @code{texi2any}'s Three Passes: Macro Expansion, Document
Structure, Output
-
address@hidden @code{texi2any's} three passes
address@hidden Passes, of @code{texi2any}
address@hidden Three passes, of @code{texi2any}
-
address@hidden operates in three passes to transform the original
-input to the final output. In address@hidden, the @code{@@macro} calls
-are expanded; in address@hidden, the document structure is gathered; and
-in address@hidden the result is output. In most cases this organization
-does not matter, as output customization is almost always done in
address@hidden Only if you want to do something during an earlier pass
-do you need to consider this, as explained below.
-
-After the Texinfo input file has been parsed, some information is
-available which can be used to modify some variables and prepare for
-the output. For example, even such basic things as the document
-language, the document encoding, values set with @code{@@set} or
address@hidden@@setfilename}, etc., cannot be known before the Texinfo
-parsing.
-
address@hidden Initialization}
address@hidden Output initialization
address@hidden Initialization of output
-The following function reference may be redefined to be called after
-Texinfo processing and before document generation, i.e., for output
-initialization:
-
address@hidden {Function Reference} init_out
-This function performs the initialization of variables and other
-tasks before document output.
address@hidden deffn
-
-By default, the hashes @code{%BUTTONS_NAME} (@pxref{Navigation Panel
-Button Specification}) and @code{%BUTTONS_GOTO} (@pxref{About Element
-Customization}) are initialized. The initialization of these
-variables depends on the document language. Similarly, the encoding
-variables are set based on the information now available (@pxref{Init
-File Encodings}). When generating HTML, aditionally, the
address@hidden hash is initialized.
-
-To perform the default initializations, which are almost surely
-desired, and also add more code, the best way is to save the default
-function reference and then call it in your new function, like this:
-
address@hidden
-my $default_init_out = $init_out;
-$init_out = \&my_init_out;
-sub my_init_out()
address@hidden
- &$default_init_out();
- address@hidden'NodeForward'@} = ' > ';
address@hidden
address@hidden example
-
address@hidden Finalization}
address@hidden Output finalization
address@hidden Finalization of output
-At the other end of things, if you want to do some clean-up after the
-document was generated (write at the end of the output files, issue
-messages, @dots{}), the following function reference may be overridden:
-
address@hidden {Function Reference} finish_out
-This function is called after the document generation.
address@hidden deffn
-
-The default is to do nothing.
-
-These function references are mostly redundant with the handlers described
-in the next section (@pxref{Init File Calling at Different Stages}).
-
-
address@hidden Init File Calling at Different Stages
address@hidden Init File Calling at Different Stages
-
address@hidden Init file calling functions at different stages
address@hidden Calling functions at different stages
address@hidden Functions, calling at different stages
-
-Arbitrary user-defined functions may be called between the different
-Texinfo parsing and outputting passes (see previous section). This
-could be used, for example, to initialize variables before collecting
-the @@-commands and their text, expanding them between the collecting
-and expansion phase and doing clean-up after the expansion pass.
-
-There are five places for user defined functions, each associated with
-an array. The function references in each array are called one after
-another. The arrays correspond with the different stages:
-
address@hidden @code
address@hidden @@command_handler_setup
-Called before anything is done, including collecting the output file
-names. The input file names' directories are available.
-
address@hidden @@command_handler_init
-Called as soon as the input file names are known. It may be at
-different moments: before processing anything, right after
address@hidden@@setfilename}, or at the end of address@hidden (after
address@hidden@@macro} and @code{@@include} expansions). At that time the
-information available is essentially just the input file names.
-
address@hidden @@command_handler_names
-Called right after address@hidden, the main input collection. At that
-time all the special @@-commands have been collected as explained
-above, but no output has been produced, and the element (node and
-section) names have not been processed.
-
address@hidden @@command_handler_process
-Called after the element names have been processed, but
-before the main output initialization.
-
address@hidden @@command_handler_output
-Called right before the main output processing, so that more
-information is available, such as the title (@pxref{Init File Global
-Information}).
-
address@hidden @@command_handler_finish
-Called after output generation is finished.
address@hidden vtable
-
-Because these are arrays, you should use @code{push} to add your
-functions to them, like this (a real example from the @LaTeX{}2HTML
-support):
-
address@hidden
-push (@@command_handler_init,
- \&Texi2HTML::LaTeX2HTML::init);
-push (@@command_handler_process,
- \&Texi2HTML::LaTeX2HTML::latex2html);
-push (@@command_handler_finish,
- \&Texi2HTML::LaTeX2HTML::finish);
address@hidden example
-
-For a real-life example, see the @LaTeX{}2HTML support.
-
-
address@hidden Init File Formatting of Commands
address@hidden Init File Formatting of Commands
-
address@hidden Init file formatting of commands
address@hidden Formatting of commands, in init file
address@hidden Commands, custom formatting
-
-It is possible to bypass completely the normal formatting of
-@@-commands with braces and the block commands of ``raw'' input such
-as @code{@@html} and @code{@@tex} (@pxref{Raw Formatter Commands}).
-In these cases the @@-commands and the text within are passed to a
-user-defined function early, right after the document structure
-determination of address@hidden (@pxref{texi2any's Three Passes}).
-Another user-defined function is called during the output expansion
-phase.
-
address@hidden %command_handler
-These user-defined functions are specified as values in the
address@hidden hash, with the key being the command to
-override. The associated value is itself a hash reference, whose keys
-can be @code{'init'} for the function reference called during the
-first pass, and @code{'expand'} during the expansion pass.
-
-Here is an example for an @@-command with braces, @code{math}, used
-for in the @LaTeX{}toHTML support:
-
address@hidden
address@hidden'math'@} =
- @{ 'init' => \&Texi2HTML::LaTeX2HTML::to_latex,
- 'expand' => \&Texi2HTML::LaTeX2HTML::do_tex
- @};
address@hidden example
-
address@hidden Raw region, overriding formatting of
-Handling a raw region @@-command is the same:
-
address@hidden
address@hidden'tex'@} =
- @{ 'init' => \&Texi2HTML::LaTeX2HTML::to_latex,
- 'expand' => \&Texi2HTML::LaTeX2HTML::do_tex
address@hidden;
address@hidden example
-
-These function references are called as follows, respectively:
-
address@hidden {Function Reference} $status @
- address@hidden'$command'@}->@{'init'@} $command $text $count
address@hidden is the @@-command name, @var{$text} is the text
-appearing within the @@-command, and @var{$count} counts how many
-times this @@-command has appeared. @var{$status} is a boolean to return,
-true if the collection was succesful. If it is false, the @@-command
-and the text are discarded.
address@hidden deftypefn
-
address@hidden {Function Reference} $result @
- address@hidden'$command'@}->@{'expand'@} $command $count \%state $text
address@hidden is the @@-command name, @var{$count} counts how many
-times this @@-command has appeared, and @var{\%state} is a hash
-reference with detailed context information; @var{$text} should be
-empty. @var{$result} is the expanded resulting text.
address@hidden deftypefn
-
-
address@hidden Init File General Block Commands
address@hidden Init File General Block Commands
-
address@hidden Init file general block commands
address@hidden General block commands, in init files
address@hidden Block commands, in init files
-
-A @dfn{general block @@-command} is any @@-command which is paired
-with an @code{@@end @var{cmdname}}, with the exception of those
-@@-commands selecting whether input is processed (such as
address@hidden@@ignore} and @code{@@ifhtml}) and ``raw'' @@-commands (such as
address@hidden@@verbatim} and @code{@@html}).
-
address@hidden {Function Reference} $line begin_format_texi $command $line
\%state
address@hidden is the format command, @var{$line} is the rest of the
-line following the @@-command, and @var{\%state} is a hash reference
-with detailed context information. The function can modify
address@hidden and return something else.
address@hidden deftypefn
-
-By default, this is used to keep track of multitable nesting, and so
-it is linked with multitable formating.
-
address@hidden oldapi @pxref{Multitable Formatting}
-
address@hidden
+The following is still true, but right now nothing uses these contexts
+in init files.
@node Init File Expansion Contexts
@subsection Init File Expansion Contexts: Normal, Preformatted, String, Math
@@ -19696,9 +19037,8 @@
@item string context
@cindex String expansion context
When rendering strings without formatting elements, for example in
-comments (@pxref{Comments}) and titles. We have two string contexts,
-one that produces plain text, and a second that allows for limited
-formatting, typically without any element when producing HTML or XML,
+comments (@pxref{Comments}) and titles. In the string context, there
+is limited formatting, typically without any element when producing HTML,
so the value can be used in an attribute.
@item math context
@@ -19706,7 +19046,7 @@
Math (@pxref{math,, @code{@@math}}).
@end table
-
address@hidden ignore
@node Internationalization of Strings
@subsection Internationalization of Strings in the Output Document
@@ -19731,7 +19071,7 @@
across all platforms and installations, which would not otherwise be
possible. @code{libintl-perl} is included in the Texinfo distribution
and always installed, to be sure that it is available if needed. It
-is also possible to use the system @code{gettext}; currently decided
+is also possible to use the system @code{gettext} (currently decided
at build-time).
@vindex texinfo_document @r{Gettext domain}
@@ -19739,11 +19079,11 @@
and the subroutine @code{gdt} is used for translated
strings:
address@hidden gdt ($string, \%variables_hash, \%state)
address@hidden gdt (\%converter, $string, \%variables_hash)
@var{$string} is the string to be translated, @var{\%variables_hash}
is a hash reference holding the variable parts of the translated
-string, and @var{\%state} is a hash reference with detailed context
-information.
+string, and @var{\%converter} is an object which holds the informations
+about the context. The result returned is a perl Texinfo tree.
@end defun
@cindex Perl format strings for translation
@@ -19782,43 +19122,31 @@
@code{ja.utf-8}, since there are no @@-commands for Japanese
characters.
address@hidden Next, the args in string are protected. For example,
address@hidden@{ arg_name @}} address@hidden
address@hidden@@address@hidden@} address@hidden
-@@address@hidden@}}
-(this part is skipped if there is nothing to expand).
-
address@hidden Next, the string is expanded as Texinfo.
address@hidden@@address@hidden@}} expands to @address@hidden and
address@hidden@@address@hidden@}} expands to @address@hidden,
-such that in the end one still gets @address@hidden@}} within an
-expanded string (this part is skipped if there is nothing to expand).
-
address@hidden Finally, the arguments are substituted; for
-example, @address@hidden@}} is replace by the corresponding actual
-argument.
address@hidden Next, the string is expanded as Texinfo, and converted to a
+Texinfo tree in perl.
+The arguments are substituted; for example, @address@hidden@}} is
+replaced by the corresponding actual argument, which should be
+Texinfo perl trees or Texinfo perl tree contents arrays.
@end enumerate
address@hidden duplicate @r{in @code{%state} hash}
In the following example, @address@hidden@}}, @address@hidden@}}
and @address@hidden@}} are the arguments of the string. Since they
-are used in @code{@@uref}, their order is not predictable. The
address@hidden@{'duplicate'=>address@hidden means that the document state
should be used
-when expanding the string. @address@hidden@}},
address@hidden@address@hidden and @address@hidden@}} are substituted
-after the expansion, which means that they should already be
-acceptable output:
+are used in @code{@@uref}, their order is not predictable.
address@hidden@address@hidden, @address@hidden@}} and @address@hidden@}} are
+substituted after the expansion, which means that they should already be
+Texinfo perl trees or Texinfo perl tree contents:
@example
gdt('Generated on @@address@hidden@address@hidden@} using
@@address@hidden@address@hidden,
@@address@hidden@address@hidden@address@hidden',
@{
- 'date' => $date,
- 'program_homepage' => $Texi2HTML::address@hidden'program_homepage'@},
- 'program' => $Texi2HTML::address@hidden'program_and_version'@} @},
- @{'duplicate'=>1,
- @});
+ 'date' => expand_today(\%converter),
+ 'program_homepage'
+ => @{'text' =>
$Texi2HTML::address@hidden'program_homepage'@address@hidden,
+ 'program'
+ => @{'text' =>
$Texi2HTML::address@hidden'program_and_version'@address@hidden @},
+ );
@end example
This approach is admittedly a bit complicated. Its usefulness is that
@@ -19837,1431 +19165,6 @@
but with rich formatting that may be translated appropriately in many
languages.
address@hidden keep_texi @r{in @code{%state} hash}
-Expansion can be prevented by setting the key @code{keep_texi} in the
address@hidden hash.
-
-When an @code{@@documentlanguage} line appears in the document and the
-language was not set on the command line, it is convenient for the
-translations to redefine some variables based on the new language.
-Therefore, Texinfo has a function reference which is called each time
address@hidden@@documentlanguage} is encountered:
-
address@hidden {Function Reference} $translate_names
-Called each time @code{@@documentlanguage} is encountered, if the
-language was not set on the command line. It should be used to
-retranslate strings based on the new language.
address@hidden deffn
-
-
address@hidden Output Elements
address@hidden Output Elements
-
address@hidden Output elements
address@hidden Elements, main unit of output documents
-
-We will call the main unit of output documents an @dfn{element}. An
-element's association with output files is determined by the split
-options (@pxref{Splitting Output}). This section describes precisely
-how these output elements work, with details for customization.
-
address@hidden
-* Defined: Output Elements Defined.
-* Labels: Output Element Labels.
-* Lines: Output Element Lines.
address@hidden menu
-
-
address@hidden Output Elements Defined
address@hidden Output Elements Defined
-
address@hidden Output elements, defined
-
-The output elements are:
-
address@hidden @emph
address@hidden Normal elements
address@hidden Normal elements
-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. Either the node or the sectioning command is considered to
-be the main element component, depending on the values of the
-configuration variables @code{USE_NODES} and @code{USE_SECTIONS}
-(@address@hidden Configuration Variables}).
-
-For example, when generating Info, the nodes are the elements; when
-generating Docbook, sectioning commands are the main element
-component; and when generating HTML, either case may happen
-(@pxref{Two Paths}).
-
address@hidden Top element
address@hidden Top element
-The top element is the highest element in the document structure. If
-the document has an @code{@@top} section (@pxref{makeinfo top}), it is
-the element associated with that section; otherwise, it is the element
-associated with the document's @code{@@node Top} (@pxref{The Top
-Node}). If there is no @code{@@node Top}, the first element in the
-document is the top element.
-
-The top element may end up formatted differently from normal elements
-if there is an @code{@@top} section or the @code{@@node Top} is not
-associated with a sectioning command.
-
address@hidden Miscellaneous elements
address@hidden Table of contents, output element
address@hidden Short table of contents, output element
address@hidden Overview, output element
address@hidden Footnotes, output element
address@hidden About page, output element
-The remaining elements are associated with different files if the
-document is split, and also if @code{MONOLITHIC} is not set. There
-are four such miscellaneous elements:
-
address@hidden
address@hidden Table of contents
address@hidden Short table of contents, also called Overview
address@hidden Footnotes page
address@hidden About page
address@hidden enumerate
-
-More details:
-
address@hidden
address@hidden The @emph{Table of contents} should only be formatted if
address@hidden@@contents} is present in the document.
-
address@hidden Similarly the @emph{Overview} should only appear if
address@hidden@@shortcontents} or @code{@@summarycontents} is present.
-
address@hidden The configuration variables @code{contents} and
address@hidden may be set to trigger the output of the
-respective elements.
-
address@hidden If @code{INLINECONTENTS} is set, the @emph{Table of contents} and
address@hidden elements are directly included within the document,
-rather than as separate pages (@pxref{Contents and Overview Elements
-Customization}).
-
address@hidden When generating HTML, the @emph{Footnotes page} should only
-be present if the footnotes appear on a separate page (@pxref{Footnote
-Styles}). However, a footnote element is present if the document is
-not split.
-
address@hidden The @emph{About page} shouldn't be present for documents
-consisting of only one sectioning element, or for monolithic documents
-without navigation information.
-
address@hidden itemize
address@hidden table
-
-It is common not to have anything but normal elements, especially in
-case of monolithic output. It is usually with HTML output that
-special elements may be present.
-
-The main component of elements is sections if @code{USE_SECTIONS} is
-set or @code{USE_NODES} is set to 0; conversely, the main component is
-nodes if @code{USE_NODES} is set or @code{USE_SECTIONS} is 0. If both
-configuration variables are undefined, heuristics are used, influenced
-by the presence of nodes or sectioning elements in the document: if
-there are no nodes, sectioning elements are preferred and vice versa.
-
-When sections are the main components of elements, ``isolated'' nodes
-not directly associated with a sectioning command are associated with
-the following sectioning command, while sectioning commands without
-nodes constitute an element. 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
-elements.
-
-
address@hidden Output Element Labels
address@hidden Output Element Labels
-
address@hidden Output element labels
address@hidden Element labels
-
-A variety of data items, called @dfn{element labels}, are associated
-with elements. They may be used in the formatting functions, and/or
-associated with a button (@pxref{Navigation Panel Button Specification}).
-
-Each element label has a name and a reference to the element they
-represent, when such an element exists. The element is either a
-global element (for example, the first element) or relative to the
-current element (for example, the next element). Such relative
-elements are determined with respect to the document structure defined
-by the section structuring commands (@code{@@chapter},
address@hidden@@address@hidden) or by the nodes if the node pointers are
-specified on @code{@@node} lines or in menus, as explained above
-(@pxref{Two Paths}).
-
-Here is the list of element labels:
-
address@hidden @emph
address@hidden @samp{@ }
-An empty button.
-
address@hidden Top
-Top element. The associated name is @code{$TOP_HEADING} if that variable is
-defined. This variable is not set by default.
-
address@hidden About
-About (help) page.
-
address@hidden Contents
-Table of contents.
-
address@hidden Overview
-Overview: short table of contents.
-
address@hidden Footnotes
-Corresponds to the @code{Footnotes} element (@pxref{Output Elements
-Defined}).
-
address@hidden Index
-The first chapter with @code{@@printindex}. The associated name is
address@hidden, if the variable is set. This variable is not
-set by default.
-
address@hidden This
-The current element.
-
address@hidden Forward
-Next element in reading order.
-
address@hidden First
-First element in reading order.
-
address@hidden Last
-Last element in reading order.
-
address@hidden Back
-Previous element in reading order.
-
address@hidden FastForward
-Next chapter.
-
address@hidden FastBack
-Beginning of this chapter, or previous chapter if the element is a chapter.
-
address@hidden Next
-Next section at the same level.
-
address@hidden Prev
-Previous section at the same level.
-
address@hidden Up
-Up section.
-
address@hidden SectionNext
-Next in section reading order.
-
address@hidden SectionPrev
-Previous in section reading order.
-
address@hidden SectionUp
-Up in section reading order.
-
address@hidden NodeNext
-Next node.
-
address@hidden NodeForward
-Next node in node reading order.
-
address@hidden NodeBack
-Previous node in node reading order.
-
address@hidden NodePrev
-Previous node.
-
address@hidden NodeUp
-Up node.
-
address@hidden table
-
-The element labels may also be accessed when formatting elements.
-Four hashes are available, with their keys being the elements items,
-and their values as follows:
-
address@hidden @code
address@hidden %Texi2HTML::NAME
-The formatted element name.
-
address@hidden %Texi2HTML::HREF
-The element hypertext reference.
-
address@hidden %Texi2HTML::NODE
-The element node name.
-
address@hidden %Texi2HTML::NO_TEXI
-The element name after removal of texi commands.
-
address@hidden vtable
-
-For example, @code{$Texi2HTML::address@hidden'Back'@}} is the name of the
-previous element in reading order.
-
-
address@hidden Output Element Lines
address@hidden Output Element Lines
-
address@hidden Output elements lines
address@hidden Formatted lines, of output elements
-
-The following array references holds formatted lines relating to
-various output elements.
-
address@hidden @code
address@hidden $Texi2HTML::OVERVIEW
-Lines of the short table of contents. @xref{Contents and Overview
-Elements Customization}.
-
address@hidden $Texi2HTML::THIS_SECTION
-Lines of the current element.
-
address@hidden $Texi2HTML::TITLEPAGE
-The title page formatted. @xref{HTML Title Page Customization}.
-
address@hidden $Texi2HTML::TOC_LINES
-Lines of table of contents. @xref{Contents and Overview Elements
-Customization}.
-
address@hidden vtable
-
-
address@hidden Navigation Panel Customization
address@hidden Navigation Panel Customization
-
address@hidden Customization, of navigation panel
address@hidden Navigation panel, customization of
-
-The @dfn{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.
-
-Considerable customization can done with straightforward variable
-assignments, especially special arrays. The configuration variables
address@hidden, @code{ICONS}, @code{HEADERS},
address@hidden, @code{USE_ACCESSKEY} and @code{USE_REL_REV}
-may be used to change the the navigation panel formatting.
address@hidden@command{texi2any} Configuration Variables}.
-
-In the unusual case that this isn't enough, it is also possible to
-redefine the function doing the navigation panel formatting.
-
address@hidden
-* Buttons: Navigation Panel Button Specification.
-* Functions: Navigation Panel Formatting Functions.
address@hidden menu
-
-
address@hidden Navigation Panel Button Specification
address@hidden Navigation Panel Button Specification
-
address@hidden Navigation panel button specification
address@hidden Button specification, navigation panel
-
-Several arrays and hashes enable precise control over the navigation
-panel buttons and their display. The following arrays determine the
-buttons present in the various navigation panels:
-
address@hidden @code
address@hidden @@SECTION_BUTTONS
-Specifies the navigation panel buttons present at the beginning of
-sectioning elements. If the output is split at nodes or sections,
-they are also used at the page footer, and in the case of section
-navigation being enabled, at the page header.
-
address@hidden @@SECTION_FOOTER_BUTTONS
address@hidden @@NODE_FOOTER_BUTTONS
-These arrays specify the navigation panel buttons present in the page
-footer when the output is split at sections or nodes, respectively.
-
address@hidden WORDS_IN_PAGE
-If @code{WORDS_IN_PAGE} is set and the output is split at nodes, these
-buttons are only included if the sectioning element text has more than
address@hidden words. The word counting is only approximate and
-includes punctuation marks, html elements, numbers. The default is to
-include the buttons for elements larger than 300 words.
-
address@hidden @@CHAPTER_BUTTONS
-Specifies the buttons appearing at the page footer if split at
-chapters, and at the page header if split at chapters and there is no
-section navigation.
-
address@hidden @@MISC_BUTTONS
-Specifies the buttons appearing at the beginning of special elements
-and, if the output is split, at the end of such elements.
-
address@hidden @@LINKS_BUTTONS
-Used for @code{<link>} elements if they are output in the headers.
-
address@hidden @@TOP_BUTTONS
-Specifies the buttons used in the top element (@pxref{Output Elements
-Defined}).
address@hidden vtable
-
-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:
-
address@hidden @emph
address@hidden function reference
-The function is called with one boolean argument, true if the
-navigation panel should be vertical. Should return the formatted
-button text.
-
address@hidden scalar reference
-The scalar value is printed. @xref{Output Element Labels}, for some
-scalars that may be useful here.
-
address@hidden array reference
-Here, the first array element should be a reference to a text string
-and the second element an element label. A link to the element
-associated with the element label with the given text is generated.
-
-For example, if the button array element is
address@hidden
-[ 'Next', \$Texi2HTML::address@hidden@} ]
address@hidden example
-
address@hidden
-Then the button will be a link to the next section with text
address@hidden::address@hidden@}}.
-
address@hidden element label
address@hidden %NAVIGATION_TEXT
address@hidden init_out
-If icons are not used, the button is a link to the corresponding
-element whose text is defined by the value associated with the element
-label in the @code{%NAVIGATION_TEXT} hash, surrounded by @samp{[} and
address@hidden If the element label is @samp{ }, the @samp{[} and @samp{]}
-are omitted. The elements of the @code{%NAVIGATION_TEXT} hash are
-defined dynamically, in the @code{init_out} function reference
-(@pxref{Output Initialization}).
-
address@hidden %ACTIVE_ICONS
address@hidden %BUTTONS_NAME
address@hidden %PASSIVE_ICONS
address@hidden %NAVIGATION_TEXT
address@hidden Icons, in navigation buttons
-If icons are used, the button is an image whose file is determined by
-the value associated with the element label in the
address@hidden hash if the link leads to an element, or in the
address@hidden 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 are
-in @code{%BUTTONS_NAME} for the button name and
address@hidden for the description.
address@hidden table
-
address@hidden %BUTTONS_ACCESSKEY
address@hidden @code{accesskey} navigation
-If the configuration variable @code{USE_ACCESSKEY} is set, the
address@hidden attribute is used in navigation. The
address@hidden hash is then used for the @code{accesskey}
-attributes.
-
address@hidden address@hidden, for navigation}
address@hidden @code{rel} navigation
-Similarly, if the @code{USE_REL_REV} configuration variable is set,
-the @code{rel} attribute is used in navigation. In that case the
address@hidden hash is used for the @code{rel} attribute.
-
-
address@hidden Navigation Panel Formatting Functions
address@hidden Navigation Panel Formatting Functions
-
address@hidden Navigation panel formatting functions
address@hidden Formatting functions, for navigation panel
-
-In the unusual event that your needs are not met by changing the
-navigation buttons (see the previous section), you can completely
-control the formatting of navigation panels by redefining function
-references.
-
-The overall display of navigation panels is controlled via this
-function reference, @code{print_navigation}:
-
address@hidden {Function Reference} $navigation_text print_navigation @
- \@@buttons $vertical
address@hidden@@buttons} is an array reference holding the specification of
-the buttons for that navigation panel. @var{$vertical} is true if the
-navigation panel should be vertical. Returns the formatted navigation
-panel in @var{$navigation_text}.
address@hidden deftypefn
-
-The function reference @code{button_formatting} does the formatting of
-one button:
-
address@hidden {Function Reference} $formatted_button button_formatting @
- $button $vertical
address@hidden holds the specification of the button as explained
-above. @var{$vertical} is true if the navigation panel should be
-vertical. Returns the formatted result in @var{$formatted_button}.
address@hidden deftypefn
-
-By default, the function associated with @code{$print_head_navigation}
-formats the navigation panel for the page header.
-
address@hidden {Function Reference} $page_head print_head_navigation @
- $filehandle \@@buttons $first_in_page $previous_is_top \%element
address@hidden @bullet
address@hidden @var{$filehandle} is the opened filehandle the function should
-write to, if defined. If not defined the function should return the
-formatted page header as a string.
-
address@hidden @var{\@@buttons} is an array reference holding the specification
-of the buttons for the navigation panel.
-
address@hidden @var{$first_in_page} should be set if this is the first
navigation
-panel in the page.
-
address@hidden @var{$previous_is_top} is true if the previous element is the
-top element.
-
address@hidden @var{\%element} is a hash reference with information about
-the element.
address@hidden itemize
address@hidden deftypefn
-
-Similarly, the function associated with @code{$print_foot_navigation}
-formats the navigation panel for the page footer.
-
address@hidden {Function Reference} print_foot_navigation @
- $filehandle \@@buttons $rule $print_navigation_panel \%element $maybe_in_page
address@hidden @bullet
address@hidden @var{$filehandle}, @var{\@@buttons}, and @var{\%element} are as
above.
-
address@hidden @var{$rule} is a rule that may be used to separate the
navigation panel
-from the preceding text.
-
address@hidden @var{$print_navigation_panel} is a boolean specifying
-whether the navigation panel itself should be printed.
-
address@hidden @var{$maybe_in_page} is set if the present footer is between
-regular elements and the top, or between regular elements and special
-elements, that is, not at the end of a file.
address@hidden itemize
address@hidden deffn
-
-
address@hidden Customizing HTML Page Layout
address@hidden Customizing HTML Page Layout
-
address@hidden provides for customization of the HTML page
-headers, footers, and the section layout in between. (These are
-unrelated to the headings and ``footings'' produced in @TeX{} output;
address@hidden,, Page Headings}.)
-
address@hidden
-* Headers: Customizing HTML Page Headers.
-* Sections: Customizing HTML Section Layout.
-* Footers: Customizing HTML Page Footers.
address@hidden menu
-
-
address@hidden Customizing HTML Page Headers
address@hidden Customizing HTML Page Headers
-
address@hidden Customizing HTML page headers
address@hidden Headers, customizing for HTML
-
-The following three function references give full control over the
-page header formatting done at the top of each HTML output file. The
address@hidden function is called for all pages. After that,
-the @code{$print_chapter_header} function is called if the output is
-split at chapters, or the @code{$print_section_header} function if the
-split at sections.
-
address@hidden {Function Reference} print_page_head $filehandle
address@hidden @code{<body>} tag, outputting
address@hidden is the opened filehandle to which the function
-should write. This function should print the page header, in HTML,
-including the @code{<body>} element.
address@hidden deftypefn
-
address@hidden {Function Reference} print_chapter_header $filehandle \%element
address@hidden is the opened filehandle to which the function
-should write. @var{\%element} is a hash reference with information
-about the element. This function is called if the output is split
-at chapters, after @code{$print_page_head}.
address@hidden deffn
-
address@hidden {Function Reference} print_section_header $filehandle \%element
address@hidden and @var{\%element} are as above. This function is
-called if the output is split at sections, after
address@hidden
address@hidden deffn
-
address@hidden $EXTRA_HEAD
address@hidden $AFTER_BODY_OPEN
address@hidden @code{<head>} block, adding to
-You can define the variable @code{$EXTRA_HEAD} to add text within the
address@hidden<head>} HTML element. Similarly, the value of
address@hidden is added just after @code{<body>} is output.
-These variables are empty by default.
-
address@hidden address@hidden, in customization}
address@hidden @code{<body>} tag, attributes of
-The @code{<body>} element attributes may be set by defining the
-configuration variable @code{BODYTEXT}.
-
address@hidden ENCODING_NAME
address@hidden Encoding, in HTML output
-By default, the encoding name from @code{ENCODING_NAME} is used. If
-this variable is not defined, it is automatically determined
-(@pxref{Init File Encodings}).
-
address@hidden $DATE_IN_HEADER
address@hidden Date, in header
-A date is output in the header if @code{$DATE_IN_HEADER} is set.
-
address@hidden Document description, in HTML output
-The description from @code{@@documentdescription} (or a value set as a
-configuration variable) is used in the header
-(@pxref{documentdescription}).
-
address@hidden @@address@hidden, in customization}
address@hidden address@hidden, in customization}
address@hidden<link>} elements are used in the header if @code{$USE_LINKS} is
-set, in which case @code{@@LINKS_BUTTONS} determines which links are
-used and @code{%BUTTONS_REL} determines the link type associated with
-the @code{rel} attribute. @xref{Navigation Panel Button
-Specification}.
-
-
address@hidden Customizing HTML Section Layout
address@hidden Customizing HTML Section Layout
-
address@hidden Customizing HTML section layout
address@hidden Section layout, customizing for HTML
-
-The following function references are used for the formatting of
-sections in HTML output:
-
address@hidden {Function Reference} print_section $filehandle @
- $first_in_page $previous_is_top \%element
address@hidden @var
address@hidden $filehandle
-The opened filehandle to which the function should write.
-
address@hidden $first_in_page
-True if this section is the first section in the page.
-
address@hidden $previous_is_top
-True if this section is the section following the top section.
-
address@hidden \%element
-A hash reference with information about the element.
address@hidden table
-
-The function should print the current section contents.
address@hidden deffn
-
address@hidden {Function Reference} end_section $filehandle @
- $last_element_or_before_top \%element
address@hidden and @var{\%element} are as above.
address@hidden is true if this section precedes the
-top element or is the last one in page, or before the special
-elements.
address@hidden deffn
-
-
address@hidden Customizing HTML Page Footers
address@hidden Customizing HTML Page Footers
-
address@hidden Customizing HTML page footers
address@hidden Footer, customizing for HTML
-
-The following function references give full control over the page
-footer formatting done at the bottom of each HTML output file. The
address@hidden function is called if the output is split
-at chapters, or the @code{$print_section_footer} footer is called if
-split at sections. After that, the @code{$print_page_foot} function
-is called.
-
address@hidden {Function Reference} print_page_foot $filehandle
address@hidden @code{</body>} tag, outputting
address@hidden is the opened filehandle to which the function
-should write. This function should print the page footer, including
-the @code{</body>} element.
address@hidden deffn
-
address@hidden {Function Reference} print_chapter_footer $filehandle \%element
address@hidden is the opened filehandle to which the function
-should write. @var{\%element} is a reference to a hash with
-information about the element. This function is called if the
-output is split at chapters, before @code{$print_page_foot}.
address@hidden deffn
-
address@hidden {Function Reference} print_section_footer $filehandle \%element
address@hidden and @var{\%element} are as above.
-This function is called if the output is split at sections, before
address@hidden
address@hidden deffn
-
address@hidden $PRE_BODY_CLOSE
-You can define the variable @code{$PRE_BODY_CLOSE} to add text just
-before the HTML @code{</body>} element. Nothing is added by default.
-
address@hidden $PROGRAM_NAME_IN_FOOTER
-If @code{$PROGRAM_NAME_IN_FOOTER} is set, the date and name of the
-program that generated the output are output in the footer.
-
-
address@hidden Customizing Special Elements
address@hidden Customizing Special Elements
-
-Various function references allow you to customize both the content
-and layout of the HTML output of the special elements (@pxref{Output
-Elements Defined}).
-
address@hidden
-* Content: Customizing Content of Special Elements.
-* Layout: Customizing Layout of Special Elements.
address@hidden menu
-
-
address@hidden Customizing Content of Special Elements
address@hidden Customizing Content of Special Elements
-
address@hidden Customizing special elements content
address@hidden Special elements content, customizing
address@hidden Content of special elements, customizing
-
-The label for the special elements (@pxref{Output Elements Defined}),
-except for the top element, is formatted according to the function
-reference @code{$misc_element_label}:
-
address@hidden {Function Reference} $misc_element_label misc_element_label @
- $identifier $page_name
address@hidden is the identifier associated with the special
-element. @var{$page_name} is the special element name. The function
-should return a label that can be used for references to the special
-element.
address@hidden deftypefn
-
-The following sections describe the details for the special elements
-other than footnotes, which are formatted when the @code{@@footnote}
-command is expanded.
-
address@hidden oldapi (@pxref{Customizing HTML Footnotes}).
-
address@hidden
-* Top Element Customization::
-* Contents and Overview Elements Customization::
-* About Element Customization::
-* HTML Title Page Customization::
address@hidden menu
-
-
address@hidden Top Element Customization
address@hidden Top Element Customization
-
address@hidden Customization of top element
address@hidden Top element, customizing
-
-The top element formatting is controlled by three functions which also
-controls the layout of the top element page or section. The associated
-function references are:
-
address@hidden {Function Reference} print_Top_header $filehandle $begin_page
address@hidden is the opened filehandle to which the function
-should write. @var{$begin_page} is true if the element is the first
-in a page. This function should begin the top element. At the time
-this function is called, the top element text has not been parsed.
address@hidden deffn
-
address@hidden {Function Reference} print_Top $filehandle $has_top_heading
\%element
address@hidden is the opened filehandle to which the function
-should write. @var{$has_top_heading} is true if there is a
address@hidden@@heading} command or @code{@@titlefont} command appearing in
-the top element text. @var{\%element} is a hash reference with
-information about the element. This function should be used to format
-the top element text and navigation panel.
address@hidden deffn
-
address@hidden {Function Reference} print_Top_footer $filehandle $end_page
\%element
address@hidden and @var{\%element} are as above. @var{$end_page}
-is true if the element is the last in a page. This function should
-end the top element.
address@hidden deffn
-
-
address@hidden Contents and Overview Elements Customization
address@hidden Contents and Overview Elements Customization
-
address@hidden Customization of tables of contents elements
address@hidden Contents, customizing elements
address@hidden Short table of contents element, customizing
address@hidden Overview element, customizing
-
-To begin with, the table of contents and short table of contents can
-be made to appear at either the beginning (the default) or end of the
-document.
-
address@hidden INLINE_CONTENTS
-By default, the configuration variable
address@hidden is set, specifying that the tables of contents
-are not output as separate elements but instead where the
-corresponding @@-command, for example @code{@@contents}, is set. This
-behavior is consistent with @command{texi2dvi}.
-
-If @code{INLINE_CONTENTS} is not set, 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.
-
address@hidden @@setcontentsaftertitlepage @r{and HTML output}
-If @code{@@setcontentsaftertitlepage} appears in the document, even if
address@hidden is set, the tables of contents are merged into
-the title material, which in turn is not output by default;
address@hidden Title Page Customization}.
-
-Next, the following variables allow for some useful control of the
-formatting of table of contents and short table of contents:
-
address@hidden @code
address@hidden $BEFORE_TOC_LINES
-Inserted before the table of contents text.
-
address@hidden $AFTER_TOC_LINES
-Inserted after the table of contents text.
-
address@hidden $BEFORE_OVERVIEW
-Inserted before the short table of contents text.
-
address@hidden $AFTER_OVERVIEW
-Inserted after the short table of contents text.
-
address@hidden $NO_BULLET_LIST_STYLE
-Expected to contain the CSS style used for the list style when there
-is no bullet.
-
address@hidden $NO_BULLET_LIST_CLASS
-Used for the class associated with the $NO_BULLET_LIST_STYLE CSS
-style.
-
address@hidden $NO_BULLET_LIST_ATTRIBUTE
-Used as attribute text for the list element when there is no bullet.
-It is used in the tables of contents if they are formatted as a list.
address@hidden vtable
-
-Finally, the following function reference provides even more control
-over the table of contents and short table of contents formatting
-reference:
-
address@hidden {Function Reference} toc_body \@@elements
address@hidden@@elements} is an array reference containing information about
-all the elements of the document. Each entry of this array is a hash
-reference, useful keys of which are as follows:
-
address@hidden @code
address@hidden top
-True if the element is the top element.
-
address@hidden index_page
-True if the element is an index page added because of index splitting.
-
address@hidden toc_level
-Level of the element in the table of contents: the highest level is 1
-for the top element and for chapters, appendices, etc., 2 for
-sections, unnumbered sections, etc., and so on.
-
address@hidden tocid
-Label to be used for references linking to this element within the
-table of contents.
-
address@hidden file
-The file containing the element, part of the link if the output is
-split.
-
address@hidden text
-Text of the element, with section number,
-
address@hidden name
-Text of the element, without section number.
address@hidden table
-
address@hidden $Texi2HTML::address@hidden, in customization}
address@hidden $Texi2HTML::address@hidden, in customization}
-This function doesn't return anything. Instead, it should fill the
-array corresponding to the @code{$Texi2HTML::TOC_LINES} and
address@hidden::OVERVIEW} references with the text for the
-respective tables of contents. @xref{Output Element Lines}.
address@hidden deffn
-
-By default, @code{$toc_body} calls two specialized function
-references, one for the contents and the other for the short contents.
-
address@hidden {Function Reference} \@@contents_lines contents @
- \@@elements $contents_file
address@hidden@@elements} is an array reference as above.
address@hidden is the name of the file containing the table of
-contents. This function should return the formatted table of contents
-lines.
address@hidden deftypefn
-
address@hidden {Function Reference} \@@shortcontents_lines shortcontents @
- \@@elements $shortcontents_file
address@hidden@@elements} is an array reference as above.
address@hidden is the name of the file containing the table
-of contents. This function should return the formatted overview
-(short table of contents) lines.
address@hidden deftypefn
-
-Another function reference is used to add a heading and a reference,
-to be used with @code{INLINE_CONTENTS} or merged into the title
-material. Its output is not used when the tables of contents are
-separate elements.
-
address@hidden {Function Reference} \@@inline_contents_lines inline_contents @
- $filehandle $command \%element \@@elements
-Return a reference to an array holding the lines containing the
-contents, heading and reference. @var{$filehandle} is a reference to
-the currently opened file if the function is called because a
address@hidden@@contents} or @code{@@shortcontents} command was encountered,
-and @code{undef} otherwise. @var{$command} is either @samp{contents}
-or @samp{shortcontents}. @var{\%element} is a reference to a hash
-holding information about the element where the contents appeared.
-Relevant keys are:
-
address@hidden @code
address@hidden target
-The identifier associated with the table of contents, used
-to link to the table of contents.
-
address@hidden id
-The identifier associated with the element, used to do labels.
-Usually but not necessarily the same as @code{target}.
-
address@hidden file
-The file name containing the table of contents.
address@hidden table
-
address@hidden@@elements} is an array reference as above.
address@hidden deftypefn
-
-
address@hidden About Element Customization
address@hidden About Element Customization
-
address@hidden Customization of about element
address@hidden About element, customizing
-
-The default About element has an explanation of the buttons used in
-the document (controlled by @code{@@SECTION_BUTTONS};
address@hidden Panel Button Specification}) and an example showing
-the button targets. The formatting of this text may be influenced by
-the following:
-
address@hidden @code
address@hidden $PRE_ABOUT
address@hidden $AFTER_ABOUT
address@hidden $PRE_ABOUT
address@hidden $AFTER_ABOUT
-Each of these variables may be a scalar or a function reference. If a
-scalar, the value is used. If a function reference, it is called and
-the returned text is used. The text is added before or after the main
-About text, respectively.
-
address@hidden %BUTTONS_GOTO
address@hidden %BUTTONS_GOTO
-The keys of this hash are element labels (@pxref{Output Element
-Labels}), and the values are the text associated with each element
-label in the About text. By default, the elements of the hash are
-defined dynamically in the @code{init_out} function reference
-(@pxref{Output Initialization}).
-
address@hidden %BUTTONS_EXAMPLE
address@hidden %BUTTONS_EXAMPLE
-Like @code{%BUTTONS_GOTO}, except the values are the text from the
-About example, typically a section number.
-
address@hidden table
-
-If the above is not enough and you want to control exactly the
-formatting of the about text, the following function reference may be
-overridden:
-
address@hidden {Function Reference} $about_text about_body
-This function returns the about text.
address@hidden deftypefn
-
-
address@hidden HTML Title Page Customization
address@hidden HTML Title Page Customization
-
address@hidden $Texi2HTML::TITLEPAGE
-The HTML title page is first formatted using the text appearing in the
address@hidden@@titlepage} section, and put in the
address@hidden::TITLEPAGE} array reference (@pxref{Output Element
-Lines}). More formatting can be done using the following function
-reference:
-
address@hidden {Function Reference} titlepage \@@titlepage_lines @
- $text $comment $simple_text
address@hidden@@titlepage_lines} is an array containing the Texinfo lines in
address@hidden@@titlepage}. @var{$text} is the text appearing in
address@hidden@@titlepage}, formatted. @var{$comment} is the text with
-Texinfo markup removed, thus should be simple plain text.
address@hidden is the text formatted in a string context with
-minimal formatting but no elements. This function should complete
address@hidden::TITLEPAGE}.
address@hidden deffn
-
-By default, this function outputs the title if there is no title page,
-and adds the table of contents and short table of contents if they are
-to be output and @code{@@setcontentsaftertitlepage} or
address@hidden@@setshortcontentsaftertitlepage} appear in the document
-(@pxref{Contents and Overview Elements Customization}).
-
address@hidden USE_TITLEPAGE_FOR_TITLE
address@hidden SHOW_TITLE
-The resulting title page output is used in the document if
address@hidden and @code{SHOW_TITLE} are set.
-
-
address@hidden Customizing Layout of Special Elements
address@hidden Customizing Layout of Special Elements
-
address@hidden Customizing special elements layout
address@hidden Special elements layout, customizing
address@hidden Layout of special elements, customizing
-
-The formatting of each of the special elements is controlled by a
-function, as listed in the following table:
-
address@hidden @code
address@hidden print_Top
address@hidden print_Top_header
address@hidden print_Top_footer
-Formatting of the top element. It is also used for the formatting of
-the top element text (@pxref{Top Element Customization}).
-
address@hidden print_Toc
-Formatting of the table of contents element.
-
address@hidden print_Overview
-Formatting of the short table of contents element.
-
address@hidden print_About
-Formatting of about (help) element.
-
address@hidden print_Footnotes
-Formatting of the footnote elements.
address@hidden ftable
-
address@hidden print_misc
address@hidden print_misc_header
address@hidden print_misc_footer
-In the default case, @code{$print_Top} calls @code{$print_Top_header}
-for the header and @code{$print_Top_footer} for the footer of top
-element. All the other functions call @code{$print_misc} which in
-turn calls @code{$print_misc_header} for the headers and
address@hidden for the footers.
-
-
address@hidden Customizing Output-Related Names
address@hidden Customizing Output-Related Names
-
-It is possible to control both output file names and target
-identifiers in detail.
-
address@hidden
-* File: Customizing Output File Names.
-* Target: Customizing Output Target Names.
address@hidden menu
-
address@hidden Customizing Output File Names
address@hidden Customizing Output File Names
-
address@hidden Customizing output file names
address@hidden Output file names, customizing
-
address@hidden PREFIX
address@hidden SUBDIR
address@hidden EXTENSION
-It is possible to specify the output file names with more control than
-merely the command line option @option{--output} (@pxref{Invoking
-texi2any}). The @code{PREFIX} configuration variable overrides the
-base name of the file given by @code{@@setfilename} or the file name
-and should not contain any directory components. To alter
-intermediate directories, use the @code{SUBDIR} configuration
-variable. Finally, The extension may also be overriden by the
-configuration variable @code{EXTENSION}. This variable should be
address@hidden if no extension is to be added.
-
address@hidden TOP_FILE
address@hidden TOC_FILE
-Furthermore, the configuration variables @code{TOP_FILE} and
address@hidden override the output file name for the top and contents
-elements.
-
address@hidden NODE_FILES
-Two function references enable further customization. The first,
address@hidden, is especially useful when @code{NODE_FILES} is
-true; it is used to customize the node file name.
-
address@hidden {Function Reference} $node_file node_file_name \%node $type
address@hidden is a hash reference with the following interesting keys
-(there are many others): the string @code{texi}, for the Texinfo node
-name, and the boolean @code{with_section}, true if associated with a
-section. @var{$type} is @code{top} if the node is the top element.
-The function should return the node file name (@var{$node_file}).
address@hidden deftypefn
-
-The other function reference, @code{element_file_name}, is used to
-customize the file names associated with each element, and the name of
-the file associated with the special elements (@pxref{Output Elements
-Defined}).
-
address@hidden {Function Reference} $file element_file_name @
- \%element $type $txi_file_name
address@hidden is undefined for the special elements (@pxref{Output
-Elements Defined}), Otherwise, it is a hash reference with the
-following interesting keys (there are many others):
address@hidden @code
address@hidden texi
-The Texinfo element name.
-
address@hidden number
-The number associated with a section.
-
address@hidden doc_nr
-A number incremented whenever a new file should begin, based on how the
-document is split (@pxref{Splitting Output}).
-
address@hidden text
-The element text.
-
address@hidden name
-The element text without section number.
address@hidden table
-
address@hidden is empty for normal elements. For the top element it is
address@hidden; for the table of contents it is @samp{toc}; for the
-overview it is @samp{stoc}; for footnotes it is @samp{foot}; and for
-the about element it is @samp{about}.
-
address@hidden address@hidden, customizing output names of}
-If frames are used, due to the @code{FRAMES} configuration variable,
-the function reference is also called for @samp{frame}, the frame file
-name, and @samp{toc_frame}, the table of contents frame file name.
-
address@hidden is the basename of the Texinfo manual.
-
-The function should return the file name for the element (@var{$file}).
address@hidden deftypefn
-
-
address@hidden Customizing Output Target Names
address@hidden Customizing Output Target Names
-
address@hidden Customizing output target names
address@hidden Target names, customizing
address@hidden Id names, customizing
-
-Similar to file names, so-called target and id names may be set. The
address@hidden is placed where the item is located, while the @dfn{target}
-is used to construct references to that item. Usually, these should
-be the same.
-
address@hidden xx, but not always, for example in the default case, the
address@hidden xx target for a section is the node id.
-
-The following function reference is for target items (nodes, anchors,
-floats):
-
address@hidden {Function Reference} {($target,$id)} node_target_name @
- \%node $default_target $default_id $type
address@hidden is the same as in the @code{node_file_name} function
-reference in the previous section. @var{$default_target} is the
-target that has been already set (it is also in
address@hidden>@{'target'@}}), and @var{$default_id} is, similarly, the
-id already set. @var{$type} is @code{top} if the node is the top
-node. The function should return a two-element list of the target and
-id names.
address@hidden deftypefn
-
-For elements (@pxref{Output Elements Defined}), the function
-reference is:
-
address@hidden {Function Reference} {($target,$id)} element_target_name @
- \%element $default_target $default_id
address@hidden is the same as in @code{element_file_name} in the
-previous section, and @var{$default_target}, @var{$default_id}, and
-the return value, are as above.
address@hidden deftypefn
-
-The file, target, and id of ``placed'' items, namely floats,
-footnotes, index entries, anchors, contents, shortcontents and
-headings, may also be set, although the default should be suitable.
-Nevertheless, the following function reference can be used:
-
address@hidden {Function Reference} {($target, $id, $file)} @
- placed_target_file_name \%placed_item \%element @
- $default_target $default_id $default_file $context
-
address@hidden is a hash reference describing the placed item, as
-in the above, likewise @var{\%element}. @var{$default_file},
address@hidden and @var{$default_target} are the file, id and target
-already set. @var{$context} describes the context; this is set to
address@hidden if in footnotes, to @samp{no_associated_element} if
-the placed item is outside of any element (e.g., @code{@@titlepage},
address@hidden@@copying}), and is otherwise empty.
address@hidden deftypefn
-
address@hidden %misc_pages_targets
-For special elements, the @code{%misc_pages_targets} hash is used to
-set the target and id. The possibilities for the keys are
address@hidden, @samp{Contents}, @samp{Footnotes} and @samp{About}.
-
-
address@hidden Customizing HTML Headings
address@hidden Customizing HTML Headings
-
address@hidden Headings, customizing HTML
-
-A function reference may be defined to do the formatting of the heading
-text (usually changing font and underlining):
-
address@hidden {Function Reference} $heading_text_formatted heading_text @
- $command $text $level
address@hidden is the @@-command name associated with the heading.
address@hidden is the heading @@-command argument, formatted.
address@hidden is the level of the heading in the document tree.
address@hidden deftypefn
-
address@hidden heading_text_preformatted
-A similar function reference is available for preformatted context,
address@hidden
-
-A function controls the formatting of element headings,
address@hidden By default its main job is to determine whether the
address@hidden function reference should be called. Normally,
-heading text is not output for a node on its, only for any associated
-sectioning element (@pxref{Two Paths}).
-
address@hidden {Function Reference} $heading_text heading \%element $command @
- $command_texi_arg $formatted_arg $in_preformatted $one_section @
- $element_heading
-
address@hidden @var
address@hidden \%element
-A hash reference representing the sectioning element. The
-following keys are of interest:
-
address@hidden @code
address@hidden text
-The heading text.
-
address@hidden text_nonumber
-The heading text without section number.
-
address@hidden node
-True if the sectioning element is a node without an associated
-structuring command.
-
address@hidden level
-The level of the element in the document tree: @samp{0} for
address@hidden@@top}, @samp{1} for @code{@@chapter}, and so on.
-
address@hidden tag_level
-The sectioning element name, with @code{@@raisesections} and
address@hidden@@lowersections} taken into account.
-
address@hidden top
-True if it is the top element.
address@hidden table
-
address@hidden $command
-The heading @@-command.
-
address@hidden $command_texi_arg
-The argument of the @@-command, unformatted.
-
address@hidden $formatted_arg
-The argument of the @@-command, formatted.
-
address@hidden $in_preformatted
-True if in preformatted environment.
-
address@hidden $one_section
-True if there is only one section.
-
address@hidden $element_heading
-True if the heading is the main component of the element.
address@hidden table
address@hidden deftypefn
-
-It is also possible to customize the heading text with section number
-with this function reference (called for headings and nodes):
-
address@hidden {Function Reference} $result_texi heading_texi @
- $heading_command $heading $number
address@hidden is the sectioning @@-command of that heading.
address@hidden is the Texinfo input for that heading. @var{$number}
-is the heading number classically-computed with dots between numbers,
-and letters for top-level appendix numbering. This function should
-return the Texinfo text corresponding with the numbered heading.
address@hidden deftypefn
-
-The label associated with the heading that can appear before the
-heading itself and even before the navigation panel can be customized
-with this function reference:
-
address@hidden {Function Reference} $element_label element_label @
- $identifier \%element $command $unformatted_line
address@hidden is the identifier associated with the heading.
address@hidden is the same as above. @var{$command} is the
-@@-command appearing on the line, and @var{$unformatted_line} is the
-line, unformatted.
address@hidden deftypefn
-
-Additionally, for @code{@@node} and sectioning @@-commands, the
-formatting of the label, navigation panel and heading is controlled
-by:
-
address@hidden {Function Reference} $element_heading_text element_heading @
- \%element $command $command_texi_arg $formatted_arg @
- $in_preformatted $one_section $element_heading $first_in_page @
- $is_top $previous_is_top $unformatted_line $element_id $new_element
address@hidden, @var{$command}, @var{$command_texi_arg},
address@hidden, @var{$in_preformatted}, @var{$one_section}, and
address@hidden are as above. For the rest:
-
address@hidden @var
address@hidden $first_in_page
-True if this is the first heading in a page.
-
address@hidden $is_top
-True if the heading is considered as a top element heading.
-
address@hidden $previous_is_top
-True if the previous element was a top element.
-
address@hidden $unformatted_line
-Holds the whole line, unformatted.
-
address@hidden $element_id
-The id of the heading.
-
address@hidden $new_element
-True if the heading is the first of an element.
address@hidden table
address@hidden deftypefn
-
-
address@hidden Customizing Indices
address@hidden Customizing Indices
-
address@hidden Customizing indices
address@hidden Indices, customizing
address@hidden IDX_SUMMARY
-To do something special with index entries outside of the Texinfo
-source document (@pxref{Indices}), you should first set the
-configuration variable @code{IDX_SUMMARY} true. After that, various
-function references will be called for each non-empty index: one for
-initialization, one for each index entry, and one for finalization.
-
-Another way to work with the index (and tables of contents) entries is
-to specify the @option{--internal-links} option and use the resulting
-table; @pxref{Invoking texi2any}.
-
address@hidden {Function Reference} index_summary_file_begin $index_name @
- $is_printed $manual_name
-This function is called once for each non-empty index used in the
-document, before any calls to @code{index_summary_file_entry}.
-
address@hidden @var
address@hidden $index_name
-The two-letter name of the index.
-
address@hidden $is_printed
-True if this index has a corresponding @code{@@printindex} command.
-
address@hidden $manual_name
-The manual basename.
address@hidden table
address@hidden deffn
-
address@hidden {Function Reference} index_summary_file_entry $index_name @
- $entry_text $entry_reference $formatted_entry $texi_entry @
- $entry_element_reference $entry_element_header $is_printed $manual_name
-This function is called for each entry of an index, in sorted order.
-The sorting happens regardless of whether the index is actually printed.
-
address@hidden @var
address@hidden $index_name
-The two-letter name of the index.
-
address@hidden $entry_text
address@hidden $formatted_entry
address@hidden $texi_entry
-The entry in plain text, formatted, and original source, respectively.
-
address@hidden $entry_reference
-The reference used for the index entry, in the form @samp{file#id}.
-
address@hidden $entry_element_reference
-The reference to the beginning of the element containing the index
-entry, also in the form @samp{file#id} (@pxref{Output Elements
-Defined}).
-
address@hidden $entry_element_header
-The formatted header of the element containing the index entry.
-
address@hidden $is_printed
-True if this index has a corresponding @code{@@printindex} command.
-
address@hidden $manual_name
-The manual basename.
address@hidden table
address@hidden deffn
-
address@hidden {Function Reference} index_summary_file_end $index_name
$is_printed @
- $manual_name
-This function is called once for each non-empty index used in the
-document, after all calls to @code{index_summary_file_entry}. The
-arguments are the same as for @code{index_summary_file_begin}, above.
address@hidden deffn
-
-
address@hidden Customizing CSS
address@hidden Customizing the CSS lines
-
address@hidden Customizing CSS
address@hidden CSS customization
-
address@hidden %css_map
address@hidden INLINE_CSS
address@hidden NO_CSS
-The @code{NO_CSS} configuration option turns off CSS support. Instead
-of CSS lines being output at the beginning of the document, they may
-be added to HTML attributes, if @code{INLINE_CSS} is set.
-
-The configuration variable holds the CSS specification lines when CSS
-is not inline. It is possible to modify the CSS lines by modifying
-the entries or adding to the @code{%css_map} hash. Each key is a CSS
-selector, the corresponding value is a style string.
-
-It is also possible to change completely how CSS lines are generated
-by redefining the following function reference:
-
address@hidden {Function Reference} css_lines \@@import_lines \@@rule_lines
-This function should set the variable @code{CSS_LINES}.
address@hidden@@import_lines} is an array reference holding the
address@hidden@@import} lines of the files specified with
address@hidden @var{\@@rule_lines} is an array reference
-holding the CSS lines of those. files.
address@hidden deffn
-
-
@node Command List
@appendix @@-Command List
@cindex Alphabetical @@-command list
@@ -23188,7 +21091,7 @@
(@url{http://www.gnu.org/software/rcs}) version control systems, which
expand it into a string such as:
@example
-$Id: texinfo.txi,v 1.385 2011/09/26 18:47:45 karl Exp $
+$Id: texinfo.txi,v 1.386 2011/09/30 19:13:05 pertusus Exp $
@end example
(This is useful in all sources that use version control, not just manuals.)
You may wish to include the @samp{$Id:} comment in the @code{@@copying}
@@ -23259,7 +21162,7 @@
@verbatim
\input texinfo @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.385 2011/09/26 18:47:45 karl Exp $
address@hidden $Id: texinfo.txi,v 1.386 2011/09/30 19:13:05 pertusus Exp $
@comment %**start of header
@setfilename sample.info
@include version.texi
@@ -23409,8 +21312,8 @@
Most printed manuals contain headings along the top of every page
except the title and copyright pages. Some manuals also contain
-footings. HTML output also supports something like these, but in a
-completely different way: @pxref{Customizing HTML Page Layout}.
+footings. @c HTML output also supports something like these, but in a
address@hidden completely different way: @pxref{Customizing HTML Page Layout}.
Headings and footings have no meaning in Info or the other output
formats.
Index: doc/version.texi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/version.texi,v
retrieving revision 1.97
retrieving revision 1.98
diff -u -b -r1.97 -r1.98
--- doc/version.texi 25 Sep 2011 22:07:05 -0000 1.97
+++ doc/version.texi 30 Sep 2011 19:13:05 -0000 1.98
@@ -1,4 +1,4 @@
address@hidden UPDATED 25 September 2011
address@hidden UPDATED 30 September 2011
@set UPDATED-MONTH September 2011
@set EDITION 4.13
@set VERSION 4.13
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- texinfo ChangeLog doc/texi2oldapi.texi doc/texi...,
Patrice Dumas <=