diff options
Diffstat (limited to 'Build/source/utils/texi2html/doc/texi2html.info-1')
-rw-r--r-- | Build/source/utils/texi2html/doc/texi2html.info-1 | 1299 |
1 files changed, 0 insertions, 1299 deletions
diff --git a/Build/source/utils/texi2html/doc/texi2html.info-1 b/Build/source/utils/texi2html/doc/texi2html.info-1 deleted file mode 100644 index 1b2eaccb006..00000000000 --- a/Build/source/utils/texi2html/doc/texi2html.info-1 +++ /dev/null @@ -1,1299 +0,0 @@ -This is texi2html.info, produced by makeinfo version 4.5 from -texi2html.texi. - -Copyright (C) 1999, 2000, 2001, 2002, 2003 Free -Software Foundation, Inc. - -Portions -of -`texi2html' - Copyright (C) 1999, 2000 Lionel Cons - Copyright (C) 1999, 2000 Karl Berry - Copyright (C) 1999, 2000 Olaf Bachmann - Copyright (C) 2002, 2003 Patrice Dumas - Copyright (C) 2001, 2002, 2003 Derek Price - Copyright (C) many others. - - -Portions -of this -manual - Copyright (C) 1999, 2000 Karl Heinz Marbaise (manual) - Copyright (C) 2003 Patrice Dumas (manual) - Copyright (C) 2003 Derek Price (manual) - Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - - Permission is granted to copy and distribute modified versions of -this manual under the conditions for verbatim copying, provided that -the entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - - Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions, except that this permission notice may be stated in a -translation approved by the Free Software Foundation. -INFO-DIR-SECTION Texinfo documentation system -START-INFO-DIR-ENTRY -* Texi2HTML: (texi2html). Texinfo to HTML Converter. -END-INFO-DIR-ENTRY - - This file, last updated 1 February 2005, documents the `texi2html' -script which converts Texinfo (http://www.texinfo.org) into HTML -(http://w3c.org). This edition is for `texi2html' version 1.76. - -Copyright (C) 1999, 2000, 2001, 2002, 2003 Free -Software Foundation, Inc. - -Portions -of -`texi2html' - Copyright (C) 1999, 2000 Lionel Cons - Copyright (C) 1999, 2000 Karl Berry - Copyright (C) 1999, 2000 Olaf Bachmann - Copyright (C) 2002, 2003 Patrice Dumas - Copyright (C) 2001, 2002, 2003 Derek Price - Copyright (C) many others. - - -Portions -of this -manual - Copyright (C) 1999, 2000 Karl Heinz Marbaise (manual) - Copyright (C) 2003 Patrice Dumas (manual) - Copyright (C) 2003 Derek Price (manual) - Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - - Permission is granted to copy and distribute modified versions of -this manual under the conditions for verbatim copying, provided that -the entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - - Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions, except that this permission notice may be stated in a -translation approved by the Free Software Foundation. - -File: texi2html.info, Node: Top, Next: Overview, Up: (dir) - -Texi2HTML -********* - - This manual, last updated 1 February 2005, describes version 1.76 of -the `texi2html' Perl script which converts Texinfo (*note Texinfo: -(Texinfo)Top.) into HTML. - - Please send bug reports concerning this manual to the Texi2HTML user -discussion list <user@texi2html.cvshome.org>. Please state the exact -version of the manual which contains the bug, as given above. - -Copyright (C) 1999, 2000, 2001, 2002, 2003 Free -Software Foundation, Inc. - -Portions -of -`texi2html' - Copyright (C) 1999, 2000 Lionel Cons - Copyright (C) 1999, 2000 Karl Berry - Copyright (C) 1999, 2000 Olaf Bachmann - Copyright (C) 2002, 2003 Patrice Dumas - Copyright (C) 2001, 2002, 2003 Derek Price - Copyright (C) many others. - - -Portions -of this -manual - Copyright (C) 1999, 2000 Karl Heinz Marbaise (manual) - Copyright (C) 2003 Patrice Dumas (manual) - Copyright (C) 2003 Derek Price (manual) - Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - - Permission is granted to copy and distribute modified versions of -this manual under the conditions for verbatim copying, provided that -the entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - - Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions, except that this permission notice may be stated in a -translation approved by the Free Software Foundation. - *This manual is currently under construction and of course incomplete. ;-)* - -* Menu: - -* Overview:: -* Obtaining texi2html:: - Obtaining a copy of the `texi2html' - source code distribution -* Installation:: Installing `texi2html' -* Invoking texi2html:: Description of the command line options -* Initialization files:: What kind of variables and subroutines appear - in init files and how they are called -* Changing the page layout:: Fine tuning of the page layout -* Customizing HTML:: Fine tuning of the HTML elements - associated with the texinfo constructs -* Internationalization:: Help translating ! -* Indexop:: Command Line Option Index -* Indexvr:: Variable Index -* Indexcp:: Concept Index - - -File: texi2html.info, Node: Overview, Next: Obtaining texi2html, Prev: Top, Up: Top - -Overview -******** - - Texinfo (http://www.texinfo.org) is the official documentation -format of the GNU (http://www.gnu.org) project. It uses a single -source file to produce both online information and printed output. - - It is often desirable to have a way to produce HTML from Texinfo -sources, as GNU-Info files are produced. It is much simpler to run a -converter than it is to rewrite all the documentation in HTML, -especially considering that there is so much Texinfo documentation in -the world. - - Some time ago `makeinfo' wasn't able to produce HTML output format, -but people still wanted documentation in HTML. This was the birthing -hour for `texi2html'. The basic purpose of `texi2html' is to convert -Texinfo documents into HTML. - - Since then, HTML support in `makeinfo' has improved, but `texi2html' -is still stronger in many areas, including the degree to which it -allows customization. With `texi2html', some important aspects of the -resulting HTML files may be specified via command line options, and -configuration files provide an even finer degree of control over the -final output, allowing most every aspect of the final output not -specified in the Texinfo input file to be specified. Configuration -files are written in `perl', like the main program, and anything which -may be specified on the command line may also be specified within a -configuration file. - - For an example of the kind of pages `texi2html' is capable of -producing, have a look at the following sites: the Singular Manual -(http://www.singular.uni-kl.de/Manual/html/), the Cederqvist (CVS -Manual) (http://ccvs.cvshome.org/docs/manual). - -* Menu: - -* whytexi2html:: Why `texi2html' and not `makeinfo'?. - - -File: texi2html.info, Node: whytexi2html, Up: Overview - -Why `texi2html' and not `makeinfo'? -=================================== - - You would like to produce HTML files from your existing Texinfo -files? There are two programs you can use to do this. The first is -`makeinfo' (*note Generating HTML: (texinfo)Generating HTML.). The -second is `texi2html'. - - The design goal of `makeinfo''s HTML output was to produce readable -HTML output. It is now possible to use CSS for HTML customization. -Another possibility is to use intermediate formats, like docbook or -`mekeinfo' XML and XSL stylesheets to customize the resulting document. -Still the output produced by `makeinfo' isn't customizable. - - The current development of `texi2html' tries to provide for -producing the more interesting and sophisticated HTML pages that -today's Internet users have come to expect. The goal behind -`texi2html' is to generate attractive HTML by default but also to allow -users considerable freedom to affect the final style and design of the -output HTML pages. This is achieved via command line options and -flexible configuration files. - - In contrast to the HTML produced by `makeinfo --html' (the -`makeinfo' program is part of the Texinfo distribution), the -`texi2html' program, among other differences, allows for the -customization of the entire page layout, including headers, footers, -style sheets, etc., allows for customization of the low level HTML -formatting, provides for splitting documents at various levels, and -provides for using the `latex2html' program to convert `@tex' sections -of the Texinfo source. - - The focus on HTML is still present but with the help of the -customization files it is now possible to use `texi2html' to produce -other formats as well. `texi2html' may for example be turned into a -texinfo to roff translator with the help of a customization file -provided with the distribution. - - `texi2html' should reasonably convert all Texinfo 4.8 constructs. -If you find it does not, please send a bug report to the -<users@texi2html.cvshome.org> email list. - - -File: texi2html.info, Node: Obtaining texi2html, Next: Installation, Prev: Overview, Up: Top - -Obtaining `texi2html' -********************* - - The latest version of the source code for `texi2html' should be -available from texi2html.cvshome.org (http://texi2html.cvshome.org). - - -File: texi2html.info, Node: Installation, Next: Invoking texi2html, Prev: Obtaining texi2html, Up: Top - -Installation of `texi2html' -*************************** - - To install `texi2html', you must first obtain a copy of the source -distribution. *Note Obtaining texi2html::. - - `texi2html' also requires `perl' version 5.004 or above. The -current version has not been tested extensively on versions of `perl' -below 5.6, however. - - `texi2html' is a standard Automake-based distribution. If you have -a source version, you should run `./configure' to regenerate the -executable `texi2html' file. `./configure' accepts options to select -the installation directory for the `texi2html' file, the default -directories `texi2html' will use to look for configuration files, and -other details. Run `./configure --help' for more information. - - Running `./configure' combines four files into the final `texi2html' -program file: - * `texi2html.pl' contains the base program, - - * `MySimple.pm' handles the command line options, - - * `texi2html.init' is the default configuration file, and - - * `T2h_i18n.pm' is used for internationalization. - - * `translations.pl' contains the translations of the strings used in - documents. - - Running `./configure' also builds the `make' configuration files -(`Makefile's). To make the documentation run `make'. - - `make install' performs the installation to the locations specified -to the `./configure' script. This usually involves placing the actual -`texi2html' file someplace in your path, such as `/usr/local/bin' or -`/usr/bin'. - - Installing `texi2html' in your path should be sufficient to run it. -To use default initialization files, or a configuration file for -LaTeX2HTML when using `latex2html' to convert `@tex' sections (*note -Expanding TeX regions::), install them in the package data directory -specified to configure. This is `/usr/local/share/texi2html/' by -default, but depends on the value of the `--pkgdatadir=DIR' option -passed to the `./configure' script. Files used for strings -customization and internationalization are also searched for in the -`i18n' directory of this directory. *Note Using init files:: for more. - - -File: texi2html.info, Node: Invoking texi2html, Next: Initialization files, Prev: Installation, Up: Top - -Invoking `texi2html' -******************** - - To produce an HTML manual, run `texi2html' with a Texinfo file as an -argument. For example, this manual is created with: - - $ texi2html texi2html.texi - - The behaviour of `texi2html' may be changed with command line -options. These command line options are always associated with -corresponding `perl' variables which may appear in init files, and these -variables are presented in this chapter each time a switch is described. - - Boolean command line switches always have a corresponding negated -switch, obtained by prepending `no' or `no-' to the switch name. For -example `--nomenu' does the reverse of `--menu'. - -* Menu: - -* Splitting output:: The HTML output may be split at - different levels -* Output files:: -* Expansion:: -* Texinfo related options:: -* Page layout options:: Customizing page layout -* Style options:: Customizing the HTML and text style -* Expanding TeX regions:: -* Using init files:: Specifying initialization files for fine tuning - - -File: texi2html.info, Node: Splitting output, Next: Output files, Up: Invoking texi2html - -Specifying where to split the generated document -================================================ - - The HTML manual resulting from the processing of the Texinfo source -may be split into files at different levels. This is specified with the -option `--split' which takes an argument, namely the level of splitting -(variable: `$SPLIT'). This level may be: - -`chapter' - The document is split at `@chapter', `@appendix', or `@unnumbered'. - -`section' - The document is split at the same places as it is using the - `chapter' argument, and also at `@section', `@appendixsec' or - `@unnumberedsec'. - -`node' - The document is split at every sectioning command. It is not - necessarily split at each node, if the `@node' structure doesn't - correspond with the sectioning command structure (see below). - -`none' - The document isn't split. This is the default. - - There are two kinds of commands which may be used to define -sectioning elements in Texinfo: `@node' and the structuring commands -(`@top', `@section', `@appendixsubsec', and so on). A node just -preceding a structuring command is considered to be part of the same -sectioning element as that command. If the `@node Top' isn't -associated with a structuring command it also defines a sectioning -element. - - By default, nodes which aren't associated with a structuring command -are not considered to be sectioning commands. They are always -considered to be part of a sectioning element defined by a structuring -command. It is possible to change this behaviour via the `--use-nodes' -option (variable `$USE_NODES'). In this case, nodes not associated -with structuring commands are also considered to be sectioning commands -defining a sectioning element. - - This default behaviour mimics `texi2dvi' behaviour, which ignores -`@node' commands for the purprose of sectioning, while the second looks -like `makeinfo' behaviour (*note Two Paths: (texinfo)Two Paths.). - - As an illustration, the following table shows how a sample Texinfo -document is divided into sectioning elements when `--use-nodes' is used -and not: - -Texinfo code default case with - `--use-nodes' - @node node1 first element: first element: - @chapter node 1 - node1 text @node node1 @node node1 - @chapter node 1 @chapter node 1 - @node node2 node1 text node1 text - node2 text second - @node node2 element: - @node node3 node2 text - node3 text second @node node2 - @chapter node 3 element: node2 text - chapter text third - @node node3 element: - node3 text - @chapter node 3 @node node3 - chapter text node3 text - @chapter node 3 - chapter text - - -File: texi2html.info, Node: Output files, Next: Expansion, Prev: Splitting output, Up: Invoking texi2html - -Setting output file and directory names -======================================= - - The manual name is constructed by stripping the `.texi', `.txi', -`.texinfo', or `.txinfo' extension from the Texinfo file name. - - By default, `texi2html' generates the manual file in the current -directory if the manual isn't split. A `.html' file extension is -appended to the manual name. - - If the manual is split the files are put in a directory named after -the manual name. The file name is constructed using the manual name as -basename. An underscore followed by a number is appended to the -basename for each files corresponding with sectioning elements, with the -exception of the top element. For the top element there nothing -appended. The files containing special elements pages have an -underscore and a 3 letter code corresponding to their content (`toc' -for table of contents, `abt' for about, `ovr' for overview) appended. -Lastly, an `.html' file extension is appended. - - Thus, if the texinfo file `afile.texi' is processed and split at -chapters into 3 files, the generated files (in directory `afile') will -be: - - afile.html --> `@node Top' or `@top' section - afile_1.html --> Chapter 1 - afile_2.html --> Chapter 2 - afile_toc.html --> Table of Contents - afile_abt.html --> About Page - - This default behavior may be modified by several command line -options. If the output isn't split, the prefix file name may be -overrided by the `--output' command line option (variable `$OUT'). If -the output is split, and `--output' is set, the files are placed in the -directory specified by the argument to the option. - - The basename may be overridden with `--prefix' (variable `$PREFIX'). -If `--short-ext' is given, `.htm' is appended instead of `.html' in -the final step (variable `$SHORTEXTN'). The `--top-file' option -overrides the top element file name (variable `$TOP_FILE'). This can -be used to name the top element file `index.html'. Similarly, -`--toc-file' changes the name of the table of contents file (variable -`$TOC_FILE'). - - Reusing the example above, but this time calling `texi2html' like so: - - $ texi2html -split chapter -prefix manual -short-ext -top-file index.htm -toc-file contents.htm afile.texi - - we get, in `manual': - - index.htm --> `@node Top' or `@top' section - manual_1.htm --> Chapter 1 - manual_2.htm --> Chapter 2 - contents.htm --> Table of Contents - manual_abt.htm --> About Page - - The file names generated by `texi2html' differ from those generated -by `makeinfo'. `makeinfo' uses the node name to construct the file -names while splitting at nodes. It is possible to get the same -behaviour out of `texi2html' by specifying the `--node-files' option -(variable `$NODE_FILES'). If the output isn't split at nodes, -`texi2html' will still output files named after the nodes, without real -content but redirecting to the right file. The default is false for -this option. This trick enables the generated HTML manual to be a -target for the cross-references of other manuals generated by -`makeinfo' or `texi2html'. - - -File: texi2html.info, Node: Expansion, Next: Texinfo related options, Prev: Output files, Up: Invoking texi2html - -Specifying which regions get expanded -===================================== - - The default for `texi2html' is to expand the `@ifhtml', `@html', and -`@menu' regions, all the `@ifnot' regions except `@ifnothtml', and no -other `@if' regions. - - It is possible to expand other regions by setting `--if<region>', -where `<region>' is replaced by the literal name of the region (for -example, `--iftex'). Symetrically, if `--no-if<region>' is specified, -the `<region>' region is ignored. The configuration file array, -`@EXPAND', holds the names of regions which should be expanded. The -only region name present in `@EXPAND' in the default case is `html'. - - If `--nomenu' is set, the `@menu' sections are not expanded -(variable `$SHOW_MENU'). The default is to expand `@menu' sections. - - -File: texi2html.info, Node: Texinfo related options, Next: Page layout options, Prev: Expansion, Up: Invoking texi2html - -Command line options related to Texinfo language features -========================================================= - - Miscalleneous Texinfo related things may be specified via command -line options. - -`--lang=LANG' - Sets the document language similar to the Texinfo directive, - `@documentlanguage LANG' (variable `$LANG'). The default is `en', - that is, use the english language strings. - -`-DVAR' - Sets VAR. Equivalent to, `@set VAR 1', in Texinfo. - -`-UVAR' - Clears VAR. Equivalent to, `@clear VAR', in Texinfo. - -`-PDIR' - Prepend DIR to the list of directories to search for `@include' - files (the associated array is `@PREPEND_DIRS', empty in the - default case). - -`-IDIR' - Append DIR to the list of directories to search for `@include' - files (the associated array is `@INCLUDE_DIRS', empty in the - default case). - - The include files are always searched for in the current directory. - - -File: texi2html.info, Node: Page layout options, Next: Style options, Prev: Texinfo related options, Up: Invoking texi2html - -Page layout related command line options -======================================== - - If the `--frames' option is specified, HTML frames are used. A file -describing the frame layout is generated, and the document page is -associated with a frame where the short table of content appears -(variable `$FRAMES'). The default is not to use frames. - - It is also possible to suppress the section navigation panel with -`--nosec-nav' (variable `$SECTION_NAVIGATION', the default is to output -all the navigation panels), and to specify whether footnotes should -appear at the foot of the same page which contains the reference to the -note or on a separate page with `--separated-footnotes' (variable -`$SEPARATED_FOOTNOTES'). The default is to have separated footnotes. - - -File: texi2html.info, Node: Style options, Next: Expanding TeX regions, Prev: Page layout options, Up: Invoking texi2html - -Customizing the HTML and text style -=================================== - - Miscalleneous style changes may be achieved with command line -options. - -`--doctype=DTD' -`--frameset-doctype=DTD' - You can specify the document DTD by setting these options. - `--frameset-doctype' applies to the file describing the frames when - frames are used (corresponding variables are `$DOCTYPE' and - `$FRAMESET_DOCTYPE'). - - The default for the document doctype is: - <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd"> - And for the frameset doctype: - <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html401/frameset.dtd"> - -`--iso' - If this option is set, ISO8859 entities are used for some special - symbols, like Copyright (C) (variable `$USE_ISO'). It is the - default. - -`--css-include=FILE' - This command line switch provides for the inclusion of an external - Cascading Style Sheet (CSS) file. More than one file may be - specified, and `-' stands for the standard input (array - `@CSS_FILES'). - - The option use is the same than for `makeinfo' and is described - extensively in *Note HTML CSS: (texinfo)HTML CSS. Briefly, the - CSS `@import' lines from the external file CSS file are pasted - before the `texi2html' CSS rules, and the external file CSS rules - are pasted after the `texi2html' CSS rules. - -`--html-xref-prefix=PATH' - This option sets the base directory for external HTML texinfo - manuals (variable `$EXTERNAL_DIR'). Defaults to `../'. - -`--def-table' - If this option is set, HTML tables are used to format definition - commands, rather than HTML definition tables (variable - `$DEF_TABLE'). Default is false. - -`--short-ref' - If this option is set, cross-references are given without section - numbers (variable `$SHORT_REF'). Default is false. - -`--number' - If this option is set, sections are numbered (variable - `$NUMBER_SECTIONS'). This is the default. - -`--toc-links' - If this option is set, links from headings to TOC entries are - created (variable `$TOC_LINKS'). Default is false. - - -File: texi2html.info, Node: Expanding TeX regions, Next: Using init files, Prev: Style options, Up: Invoking texi2html - -Expanding `@tex' and `@math' regions using LaTeX2HTML -===================================================== - - It is possible to use LaTeX2HTML (http://www.latex2html.org/) to -process `@tex' regions and `@math{}' commands. This is an attractive -way to display mathematical constructs in the HTML manual. The `--l2h' -option activates this feature (variable $L2H). It is usually desirable -to expand `@tex' sections when this option is specified (*note -Expansion::). The default is not to use this feature. - - The `--l2h-l2h=PROGRAM' option enables changing the name/location of -the LaTeX2HTML program processing TeX regions (variable `$L2H_L2H'). -The default is `latex2html'. - - `--l2h-tmp' sets the directory used for temporary files, this name -shouldn't contain a dot `.' (variable is `$L2H_TMP'). Defaults to the -current dir. - - The file specified by `--l2h-file' is used as LaTeX2HTML init file. -It is searched at the same places than init files (*note Using init -files::), and the default is `l2h.init'. - - -File: texi2html.info, Node: Using init files, Prev: Expanding TeX regions, Up: Invoking texi2html - -Use initialization files for fine tuning -======================================== - - Initialization variables are read first from -`/usr/local/share/texi2html/Config' (the exact location being -changeable with the `--pkgdatadir=dir' option of the `configure' -script, see *Note Installation::), `/usr/local/etc/texi2html/Config' -(the exact location being changeable with the `--sysconfdir=dir' option -of the `configure' script, see *Note Installation::), from `./Config' -then from `$HOME/.texi2html/Config'. Any command-line option can -override the corresponding option set in init file, and the option -`--init-file' specifies an init file to be loaded, with later settings -overriding earlier ones. - - The init files specified with `--init-file' are searched first in -the current directory, then in the `$HOME/.texi2html/' directory, in -the `/usr/local/etc/texi2html/' directory and lastly in the -`/usr/local/share/texi2html/' directory. - - A file is also included based on the language selected, by `$LANG', -`--lang' or `@documentlanguage'. If no language was selected `en' is -considered to be the language. All the files with name the language -name in `/usr/local/share/texi2html/i18n/', -`/usr/local/etc/texi2html/i18n/', `$HOME/.texi2html/i18n/' and then -`./i18n/' are included. - - The default initialization options are defined in the -`texi2html.init' file contained in the `texi2html' distribution (which -gets included near the beginning of the `texi2html' script that gets -installed). - - To customize `texi2html' it is best if you copy the appropriate -sections from the `texi2html.init' contents into an appropriate local -initialization file, make the necessary changes there, and then have -`texi2html' read this initialization file by one of the means described -above. - - -File: texi2html.info, Node: Initialization files, Next: Changing the page layout, Prev: Invoking texi2html, Up: Top - -Overview of initialization files content and loading -**************************************************** - - The initialization files are `perl' files, read as explained in -*Note Using init files::. You don't need to know much of `perl' to do -some simple changes in variable values, however, to be able to really -take advantage of all the features of the initialization file, a good -knowledge of `perl' is required. - - In initialization file two kind of variables appear. These are normal -variables (including arrays and hashes) and references on functions. -The later permits the dynamic redefinition of functions used to produce -the HTML manual. You should be able to change the value of some normal -variables without a deep knowledge of `perl', by looking at the -existing examples. The possible mistakes in that case could be omitted -`;', and bad quoting. - - Initialization file are loaded from the main program by the mean of -a `require', while in the `Texi2HTML::Config' namespace. This means -that the namespace of the main program and the namespace of -inititalization files are distinct, which ensures that no name clash -should happen. The variables are declared with the `our' specifier, -such that it should be possible to use the `use strict' pragma in the -initialization file code. - - To avoid messing with the variables in the `main' namespace all the -global variables which could be of use in the init files are in the -`Texi2HTML' namespace. Notice that the functions of the main program -are still in the `main' namespace. - -* Menu: - -* Redefining functions:: Function redefinition is achieved with - redefinition of references on functions. -* Function prototypes:: Conventions used in that manual for function - reference prototypes display. - - -File: texi2html.info, Node: Redefining functions, Next: Function prototypes, Up: Initialization files - -Redefining functions in initialization files -============================================ - - To redefine a function you must replace the corresponding funtion -reference with a reference on your function. Thus you should write -your function, give it a name you are certain it is unique in the -`Texi2HTML::Config' namespace, and override the value of the function -reference with your own function reference. When another function from -the main program (or from another functions of an initialization file) -calls the reference, your function will be used. - - For example the function reference corresponding with the function -called when doing an anchor is called `$anchor'. Thus if you want to -override the corresponding function you could write: - - # override the function reference - $anchor = \&my_own_function; - - # the function reference now refers to - sub my_own_function { - # process arguments and return an html anchor - } - - -File: texi2html.info, Node: Function prototypes, Prev: Redefining functions, Up: Initialization files - -Conventions used for function prototypes -======================================== - - As the functions are defined by a reference name, we will always use -the reference name in function prototypes. For the function arguments -we will use `\@array' for a reference on an array and similarly -`\%hash' for a reference on a hash. - - Thus, the prototype for the function associated with the function -reference `$formatting_function' will be: - - - Function Reference: $text formatting_function $arg1 \@arg2 - `formatting_function' takes as first argument $ARG2, as second - argument a reference on an array \@ARG2 and returns the formatted - text $TEXT. - - To redefined the corresponding function, you should write: - - $formatting_function = \&my_formatting_function - - sub my_formatting_function($ $) - { - my $arg1 = shift; - my $arg2 = shift; - # prepare $formatted_text - ..... - return $formatted_text - } - - -File: texi2html.info, Node: Changing the page layout, Next: Customizing HTML, Prev: Initialization files, Up: Top - -Fine tuning of the page layout -****************************** - - Some features of the page layout might be specified with command line -options, the corresponding variables are described in *Note Page layout -options::. Fine tuning of the page layout may be achieved with -redefinition of other variables and function references in the -initialization files. - -* Menu: - -* The different pages:: The different categories of pages. -* The page layout:: The elements of a page. -* Navigation panel:: How to change the navigation panel. -* Program variables:: The available main program variables and some - usefull functions from the main program. -* Output initialization:: Setting variables before the document - production but after the texinfo parsing. -* Output finalization:: Cleaning after document generation. -* css:: Customizing css lines. -* Customizing header:: -* Customizing section:: -* Customizing footer:: -* Special pages:: Customizing table of contents, top, about page. -* File names:: Customizing the file names. -* External index files:: Putting index entries in external files. - - -File: texi2html.info, Node: The different pages, Next: The page layout, Up: Changing the page layout - -The different categories of pages and sectioning elements -========================================================= - - The following sectioning elements can be associated with pages: - -_Normal elements_ - These are normal sections or nodes. Their association with pages is - determined by the splitting of the document. *Note Splitting - output::. - -_Top element_ - The top element is the higher element in the document structure. - If there is a `@top' section it is the element associated with - that section. Otherwise it is the element associated with the - `@node Top'. If there is no `@node Top' the first element is the - top element. - - The top element is formatted differently than a normal element if - there is a `@top' section or the `@node Top' isn't associated with - a sectioning command. - -_Misc elements_ - These elements are associated with pages if the document is split. - There are four misc elements: - 1. Table of contents - - 2. Short table of contents, also called Overview - - 3. Footnotes page - - 4. About page - - The _About page_ shouldn't be present for documents consisting in - only one sectioning element. The _Footnote page_ should only be - present if the footnotes appear on a separated page (*note Page - layout options::), however a footnote element is present if the - document isn't split. The _Table of contents_ should only be - formatted if `@contents' is present in the document. Similarly - the _Overview_ should only appear if `@shortcontents' or - `@summarycontents' is present. - - -File: texi2html.info, Node: The page layout, Next: Navigation panel, Prev: The different pages, Up: Changing the page layout - -Page layout and navigation panel overview -========================================= - - A page is broken up in three parts. A page header, the sections and -a page footer. A common element in the page layout is a navigation -panel with icons or text linking to other sections or pages. Another -common element is a rule, separating sections or footer. The navigation -panel and the rules may be part of the sections or part of headers or -footers. You may use the variables `$SMALL_RULE', `$DEFAULT_RULE', -`$MIDDLE_RULE' and `$BIG_RULE' for rules of different sizes. The -defaults are - $SMALL_RULE = '<hr size="1">'; - $DEFAULT_RULE = '<hr>'; - $MIDDLE_RULE = '<hr size="2">'; - $BIG_RULE = '<hr size="6">'; - - In the header some important meta data may be defined, like the -title or style information, and textual informations may be present in -comments. All this doesn't appear directly in the displayed HTML, -though. - - The page layout is mainly controlled by functions, the precise -functions called depending on the document splitting. The navigation -panel, however, can be customized with variables. - -Element labels --------------- - - There are 19 items associated with elements. Each of these is -associated with a name and a reference to the element they represent, -when such an element exists. The element is either a global element or -an element relative to the current element. The relative elements are -found with respect with the document structure defined by the section -structuring commands (`@chapter', `@unnumbered'...) or by the nodes (in -that case the node directions are specified on node line or in menu -organization). These items are called "element labels". They may be -associated with a button (*note Button specifications::), and used in -the formatting functions (*note Program variables::). - - Here is the list: - -_` '_ - An empty button - -_Top_ - Top element. The associated name is `$TOP_HEADING' if that - variable is defined. This variable is not set by default. - -_Contents_ - Table of contents - -_About_ - About (help) page - -_Overview_ - Overview, short table of contents - -_First_ - First element in reading order - -_Last_ - Last element in reading order - -_Index_ - The first chapter with `@printindex'. The associated name is - `$INDEX_CHAPTER', if the variable is set. This variable is not set - by default. - -_This_ - The current element - -_Back_ - Preceding element in reading order - -_FastBack_ - Beginning of this chapter or previous chapter if the element is a - chapter - -_Prev_ - Previous section on the same level - -_NodePrev_ - Previous node - -_Forward_ - Next element in reading order - -_FastForward_ - Next chapter - -_Next_ - Next section on the same level - -_NodeNext_ - Next node - -_Following_ - Next node in node reading order - -_Up_ - Up section - -_NodeUp_ - Up node - - -File: texi2html.info, Node: Navigation panel, Next: Program variables, Prev: The page layout, Up: Changing the page layout - -Customization of the navigation panels buttons -============================================== - - A lot of customization of the navigation panel may be achieved -without redefining functions, with variables redefinition. In case it -isn't enough, it is also possible to redefine the function doing the -navigation panel formatting. - -* Menu: - -* General purpose variables:: Variables controlling the navigation panel - at a global level -* Button specifications:: -* Panel formatting function:: - - -File: texi2html.info, Node: General purpose variables, Next: Button specifications, Up: Navigation panel - -Controlling the navigation panel panel at a high level ------------------------------------------------------- - - The global formatting of the navigation panels may be changed with -the following variables: - -`$VERTICAL_HEAD_NAVIGATION' - A vertical navigation panel will be used for the header navigation - panel if this variable is true. - -`$ICONS' - Icons are used instead of textual buttons if this variable is true. - -`$SECTION_NAVIGATION' - If this variable is false there is no section navigation, no - navigation panels for the elements within the pages, only at the - beginning and the end of the page (*note Page layout options::). - - -File: texi2html.info, Node: Button specifications, Next: Panel formatting function, Prev: General purpose variables, Up: Navigation panel - -Specifying the buttons formatting ---------------------------------- - - Several arrays and hashes enable a precise control on the buttons and -their display. The following arrays determine the buttons present in -navigation panels: - -`@SECTION_BUTTONS' - This array is used for the navigation panel buttons present at the - begining of sectioning elements. If split at node or section they - are also used at the page footer, and in the case of section - navigation at the page header. - -`@SECTION_FOOTER_BUTTONS' -`@NODE_FOOTER_BUTTONS' - This array is used for the navigation panel buttons present at the - footer of pages when split at node or at section. - - If `$WORDS_IN_PAGE' is set and the output is split at nodes, these - buttons are only present if there are more than `$WORDS_IN_PAGE' - words in the sectioning element text. This counting is very rough - and include punctuation marks, html elements, numbers. The - default is to include the buttons after 300 words. - -`@CHAPTER_BUTTONS' - This array is used for the buttons appearing at the page footer if - split at chapter, and at the page header if split at chapter and - there is no section navigation. - -`@MISC_BUTTONS' - These buttons appear at the beginning of special and sections and - at the end of these section pages if the output is split. - - The array specify the buttons displayed in navigation panels, and -how the button is displayed. Each element is associated with a button -of the navigation panel from left to right. The signification of the -array element value is the following: - -_reference on a function_ - The function is called with first argument a filehandle reference - on the current file and second argument a boolean true if the - navigation panel should be vertical. - -_reference on a scalar_ - The scalar value is printed. For some possibly usefull scalars, - *Note Elements hashes::. - -_reference on an array_ - In this case the first array element should be a reference on text - and the second element an element label. In that case a link to the - element associated with the element label with the scalar value - text is generated. - - For example if the buttons array element is - [ 'Next', \$Texi2HTML::NODE{Next} ] - - The button will be a link to the next section with text - `$Texi2HTML::NODE{Next}'. - -_element label_ - If icons are not used, the button is a link to the corresponding - element which text is defined by the value associated with the - element label in the `%NAVIGATION_TEXT' hash, surrounded by `[' - and `]'. If the element label is ` ', there is no `[' and `]'. - The element of the `%NAVIGATION_TEXT' hash are defined - dynamically, in the `init_out' function reference (*note Output - initialization::). - - If icons are used, the button is an image with file determined by - the value associated with the element label in the `%ACTIVE_ICONS' - hash if the the link really leads to an element, or in the - `%PASSIVE_ICONS' hash if there is no element to link to. Of course - if there is a link to the element the icon links to that element. - - -File: texi2html.info, Node: Panel formatting function, Prev: Button specifications, Up: Navigation panel - -Changing the navigation panel formatting ----------------------------------------- - - If you are not satisfied with this scheme, it is possible to control -exactly the formatting of navigation panels by redefining a function -reference. The function controlling the display of navigation panel is -associated with the following function reference: - - - Function Reference: print_navigation $filehandle \@buttons $vertical - $FILEHANDLE is the opened filehandle the function should write to. - \@BUTTONS is an array reference which should hold the - specification of the buttons for that navigation panel. $VERTICAL - is true if the navigation panel should be vertical. - - -File: texi2html.info, Node: Program variables, Next: Output initialization, Prev: Navigation panel, Up: Changing the page layout - -Main program variables and usefull functions -============================================ - - In the functions controlling the page layout some global variables -set by the main program are available, with value corresponding with -the current layout element. - -* Menu: - -* Elements hashes:: Accessing information related with the - different elements -* Global informations:: Accessing global informations, like date, - title... -* Global functions:: main program usefull functions - - -File: texi2html.info, Node: Elements hashes, Next: Global informations, Up: Program variables - -Accessing elements informations -------------------------------- - - Four hashes are available, with key the elements labels (as described -in *Note Element labels::) and values: - -`%Texi2HTML::NAME' - The formatted element name - -`%Texi2HTML::HREF' - The element hypertext reference - -`%Texi2HTML::NODE' - The element node name - -`%Texi2HTML::NO_TEXI' - The element name after removal of texi commands - - -File: texi2html.info, Node: Global informations, Next: Global functions, Prev: Elements hashes, Up: Program variables - -Accessing global informations ------------------------------ - - Three kinds of global informations are available, miscalleneous -global strings, flags set by `@set' and special flags and section lines. - -Global strings -.............. - - The `%Texi2HTML::THISDOC' hash holds some global informations: - -`fulltitle' - title set by `@title'. If there is no `@title' other possibilities - are tried (`@settitle', `@shorttitlepage'...). - -`title' - title set by `@settitle', or `fulltitle'. - -`title_no_texi' - title without texi formatting - -`title_texi' - title with texi commands - -`author' - Authors list set by `@author'. - -`authors' - A reference on an array containing each author set by `@author'. - -`copying' - Text appearing in `@copying' with all the texinfo commands removed, - put in comments. - -`program' - The name and version of `texi2html'. - -`program_homepage' - Homepage for `texi2html'. - -`program_authors' - Authors of `texi2html'. - -`file_base_name' - base name of the texinfo manual file. - -`destination_directory' - Destination directory for the resulting files. - -`toc_file' - The file name of the table of contents. - -`today' - The date. - - It also holds the arg of the following commands, associated with the -command name: kbdinputstyle, paragraphindent, setchapternewpage, -headings, footnotestyle, exampleindent, firstparagraphindent, -everyheading, everyfooting, evenheading, evenfooting, oddheading, -oddfooting. - -Flags -..... - - Flags defined by `@set' may be accessed through the `%main::value' -hash. The key is the flag name, the value is the flag value at the end -of the document. - - Special flags are set by the main program. They correspond with a -texinfo command, like `@setfilename', or `@settitle', `@author'... The -corresponding flag is the command name with `_' appended, for example, -`_titlefont' corresponds with `@titlefont'. Like other flags they are -available in `%main::value'. - -Section lines -............. - - The following array references or arrays holds formatted lines: - -`$Texi2HTML::THIS_SECTION' - Lines of the current element. - -`$Texi2HTML::THIS_HEADER' - Lines of the current element appearing before the element label - (anchors). - -`$Texi2HTML::OVERVIEW' - Lines of short table of contents. *Note Special pages::. - -`$Texi2HTML::TOC_LINES' - Lines of table of contents. *Note Special pages::. - - -File: texi2html.info, Node: Global functions, Prev: Global informations, Up: Program variables - -Function usefull in page formatting ------------------------------------ - - The usefull function is a function used to print an array of lines, -which also counts the number of words in the array, if needed. - - - Function: $words_number main::print_lines $filehandle \@lines_array - $FILEHANDLE is the opened filehandle the function should write to. - \@LINES_ARRAY is the array line the function should write to the - file. If this argument is omitted, the function uses - `$Texi2HTML::THIS_SECTION'. $WORDS_NUMBER is the number of words - in the array, only defined if split at nodes and `$WORDS_IN_PAGE' - is defined. - - -File: texi2html.info, Node: Output initialization, Next: Output finalization, Prev: Program variables, Up: Changing the page layout - -Preparing the output -==================== - - After the texinfo file has been parsed, some information is available -which can be used to modify some variables and prepare the outputting. -For example the document language, the document encoding, values set -with `@set' or `@setfilename' and other similar @-commands are not -known before the texinfo parsing. - - The following function reference may be redefined to be called after -texinfo processing and before document generation: - - - Function Reference: $encoding init_out - This function perform the initialization of variables and any other - task before document outputting. It returns the encoding used for - the output files. - - In the default case the `$BODYTEXT' (*note Customizing header::) and -the hashes `%NAVIGATION_TEXT' (*note Button specifications::) and -`%BUTTONS_GOTO' (*note About text::) are initialized. - - To perform the default initializations and also add more code, you -could do as in the following example (save the default function -reference and call it in your own function) : - - my $default_init_out = $init_out; - $init_out = \&makeinfo_like_init_out; - sub makeinfo_like_init_out() - { - my $encoding = &$default_init_out(); - $NAVIGATION_TEXT{'Following'} = ' > '; - return $encoding; - } - - -File: texi2html.info, Node: Output finalization, Next: css, Prev: Output initialization, Up: Changing the page layout - -Finalizing the output -===================== - - If you want to do some cleaning after the document was generated -(close files, write at the end of files and so on), the following -function reference may be redefined: - - - Function Reference: finish_out - This function is called after the document generation. - - The default is to do nothing. - - -File: texi2html.info, Node: css, Next: Customizing header, Prev: Output finalization, Up: Changing the page layout - -Customizing the `texi2html' css lines -===================================== - - It is possible to modify the `texi2html' css lines by modifying the -entries or adding to the `%css_map' hash. Each key is a css selector, -the corresponding value is a style string. - - The whole css text is in the variable `$CSS_LINES'. If this variable -is defined the variable value is used instead of being constructed -using the `%css_map' entries. For example if you don't want any css -entries, set - - $CSS_LINES = ''; - - It is also possible to change completely the way `$CSS_LINES' are -generated by redefining the following function reference: - - - Function Reference: css_lines \@import_lines \@rule_lines - This function should be used to construct the `$CSS_LINES'. - \@IMPORT_LINES are the `@import' lines of the files specified with - `--include-css', and \@RULE_LINES are the css commands lines of - these files. *Note Style options::. - |