summaryrefslogtreecommitdiff
path: root/Build/source/utils/texi2html/doc/texi2html.info-1
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/utils/texi2html/doc/texi2html.info-1')
-rw-r--r--Build/source/utils/texi2html/doc/texi2html.info-11299
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'} = ' &gt; ';
- 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::.
-