   This file documents the texi2html script which converts Texinfo into
HTML.

   Copyright (C) 1999, 2000  Free Software Foundation, Inc.

   This edition is for texi2html version 1.64, 11 July 2000.

   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.

Texi2html
*********

This Manual (Edition 0.11, last updated at 09. July 2000) describes the
`texi2html' Perl script which converters Texinfo (see Texinfo)
into HTML.

   Please send bug reports about this manual to Karl Heinz Marbaise
<khmarbaise@gmx.de>. Please state exact version/edition of the manual
(can be found at start of Texinfo source file; use the entry Id under
Revisions).

   Please note:
     This manual is currently under
     construction and of course incomplete ;-)

1 Overview about `texi2html'
****************************

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 proposed to have a way to produce HTML from Texinfo
sources, like the GNU-Info format. It is much simpler to create one
converter instead of writing all documentation new in HTML, cause there
is so much documentation in Texinfo format all over the world.

   The purpose of `texi2html' is to convert Texinfo documents into HTML.

1.1 Ways to get HTML
====================

You would like to HTML files out of your Texinfo files? You have two
choices. The first one is to use `makeinfo' itself to create HTML files.
The resulted file is only one big file and you don't have much
possibilities to change the layout of some sort of configuration you
like. ...

1.2 Why `texi2html' and not `makeinfo'?
=======================================

In contrast to the HTML produced by `makeinfo --html' (the `makeinfo'
program is part of the Texinfo distribution), the HTML output of
`texi2html' is highly configurable. Among other differences, with
`texi2html' allows you to customize your entire page layout (like
headers, footers, style sheets, etc), split documents at various
levels, and use `latex2html' to convert `@tex' sections.

   `texi2html' should reasonably convert all Texinfo 4.0 constructs. If
not, please send a bug report to <texi2html@mathematik.uni-kl.de>.

2 Installation of `texi2html'
*****************************

description of the installation process.  What do you need?  How?

3 Customizing files
*******************

Result from using `-frames'

     texi2html -V -frames texi2html.texi
   Explanation of the output differences against default, whatever this
is ;-)

4 Customizing what gets expanded
********************************

Test starting.

5 Customizing page layout:
**************************

a) General: Philosopy, and how it works
aa) Navigation panels
b) Top page
c) Section pages
d) Misc pages (ToC, About, etc)

6 Initialization file
*********************

`texi2html.init'

   Initialization options are read first from
`/usr/local/etc/texi2htmlrc' (the exact location being changeable with
the `--sysconfdir=dir' option to the `configure' script), then from
`$HOME/.texi2htmlrc', then any command-line options including
`-init_file' option; with later settings overriding earlier ones.

   The default initialization options are defined in the
`texi2html.init' file contained in the Texi2html distribution (which
gets includes near the biginning 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 inialization file by one of the means described
above.

   For an example on what you can produces with `texi2html' have a look
at the following sites: `http://www.singular.uni-kl.de/Manual/html/'

6.1 Initialization file options
===============================

This section describes in detail all option which can only be used in
initialization file (`texi2html.init'), but not on command line. This
mean the only way to change those options is to change the
initialization file.

6.1.1 Number sections.
----------------------

if set, and $T2H_NUMBER_SECTIONS is set, then use node names in menu
entries, instead of section names

   $T2H_NODE_NAME_IN_MENU = 0;

6.1.2 Avoid menu redundancy
---------------------------

if set and menu entry equals menu descr, then do not print menu descr.
Likewise, if node name equals entry name, do not print entry name.
$T2H_AVOID_MENU_REDUNDANCY = 1;

6.1.3 Center Image
------------------

if set, center @image by default otherwise, do not center by default
$T2H_CENTER_IMAGE = 1;

6.1.4 Example Indent Cell
-------------------------

used as identation for block enclosing command `@example', etc If not
empty, must be enclosed in `<td></td>' $T2H_EXAMPLE_INDENT_CELL =
'<td>&nbsp;</td>';

6.1.5 Small Example Indent
--------------------------

same as above, only for `@small' $T2H_SMALL_EXAMPLE_INDENT_CELL =
"<td>&nbsp;</td>";

6.1.6 Small Font Size
---------------------

# font size for @small $T2H_SMALL_FONT_SIZE = "-1";

6.1.7 Top Heading
-----------------

if non-empty, and no `@..heading' appeared in Top node, then use this
as header for top node/section, otherwise use value of  `@settitle' or
`@shorttitle' (in that order) $T2H_TOP_HEADING = "";

6.1.8 Index Chapter
-------------------

if set, use this chapter for *Index* button, else use first chapter
whose name matches *index* (case insensitive) $T2H_INDEX_CHAPTER = "";

6.1.9 Split Index
-----------------

if set and $T2H_SPLIT is set, then split index pages at the next letter
after they have more than that many entries

   $T2H_SPLIT_INDEX = 100;

6.1.10 HREF Dir Instead File.
-----------------------------

if set (e.g., to `index.html') replace *hrefs* to this file  (i.e., to
`index.html') by `./'

   $T2H_HREF_DIR_INSTEAD_FILE = "";

7 Extension file
****************

Here I have to put some explanation about the extension file
`texi2html.ext'.

   I'm not sure which purpose the extension file has.  May be Olaf can
answer this question.

8 Command Line Options
**********************

8.1 Debugging
=============

`-debug'

   debugging: 0 -- no debugging; other values; see beginning of
texi2html

   $DEBUG_TOC   =  1; $DEBUG_INDEX =  2; $DEBUG_BIB   =  4;
$DEBUG_GLOSS =  8; $DEBUG_DEF   = 16; $DEBUG_HTML  = 32; $DEBUG_USER  =
64; $DEBUG_L2H   = 128;

8.2 DocType
===========

`-doctype'

     <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

8.3 Check
=========

`-check' if set, only check files and give the list of all things that
look like untranslated Texinfo commands

8.4 Expand
==========

`-expand' if set to *tex* (or, *info*) expand `@iftex' and `@tex' (or,
`@ifinfo') sections else, neither expand `@iftex', `@tex', nor
`@ifinfo' sections

8.5 Glossary
============

`-glossary' if set, uses section named *Footnotes* for glossary

8.6 Invisible
=============

`-invisible' $T2H_INVISIBLE_MARK is the text used to create invisible
destination anchors for index links (you can for instance use the
`invisible.xbm' file shipped with this program). This is a workaround
for a known bug of many WWW browsers, including Netscape. For me, it
works fine without it -- on the contrary: if there, it inserts space
between headers and start of text (obachman 3/99)

     $T2H_INVISIBLE_MARK = "";
     # $T2H_INVISIBLE_MARK = '&#160;';

8.7 Iso
=======

`-iso'

   if set, ISO8879 characters are used for special symbols (like
Copyright `(C)', etc)

   $T2H_USE_ISO = 0;

8.8 Include Direcotry
=====================

`-I'

   list directories where `@include' files are searched for (besides
the directory of the doc file) additional `-I' args are add to this
list.

   @T2H_INCLUDE_DIRS = (".");

8.9 Top File
============

`-top_file' uses file of this name for top-level file extension is
manipulated appropriately, if necessary.  If empty, `<basename of
document>.html' is used Typically, you would set this to `index.html'.

   $T2H_TOP_FILE = "";

8.10 Table Of content File
==========================

`-toc_file' uses file of this name for table of contents file extension
is manipulated appropriately, if necessary. If empty, `<basename of
document>_toc.html' is used

   $T2H_TOC_FILE = "";

8.11 Frames
===========

`-frames' if set, output two additional files which use HTML 4.0 frames.

   $T2H_FRAMES = 0;

8.12 Menu's
===========

`-menu' or `-nomenu' if set, show the Texinfo menus

   $T2H_SHOW_MENU = 1;

8.13 Number sections
====================

`-number' `-nonumber' if set, number sections and show section names
and numbers in references and menus

8.14 Split
==========

`-split section|chapter|none' if set to *section* (resp. *chapter*)
create one HTML file per (sub)section (resp. chapter) and separate
pages for Top, ToC, Overview, Index, Glossary, About. otherwise, create
monolithic HTML file which contains whole document

   #$T2H_SPLIT = 'section'; $T2H_SPLIT = undef;

8.15 Section navigation
=======================

`-section_navigation'| `-no-section_navigation'

   if set, then navigation panels are printed at the beginning of each
section and, possibly at the end (depending on whether or not there
were more than $T2H_WORDS_IN_PAGE words on page). This is most useful
if you do not want to have section navigation on `-split chapter'

8.16 Subdirectory
=================

`-subdir' if set put result files in this directory if not set result
files are put into current directory

   $T2H_SUBDIR = undef;

8.17 Short extension
====================

`-short_extn' If this is set all HTML file will have extension `.htm'
instead of `.html'. This is helpful when shipping the document to PC
systems.  $T2H_SHORTEXTN = 0;

8.18 Prefix
===========

`-prefix' Set the output file prefix, prepended to all `.html', `.gif'
and `.pl' files.  By default, this is the basename of the document

   $T2H_PREFIX = "";

8.19 Output filename
====================

`-o filename'|`-out_file' If set, generate monolithic document output
HTML into `filename'.

8.20 Short Cross References
===========================

`-short_ref' if set cross-references are given without section numbers

8.21 Index Summary
==================

`-idx_sum' If value is set, then for each `@prinindex $what'
`$docu_name_$what.idx' is created which contains lines of the form
*$key\t$ref* sorted alphabetically (case matters).

8.22 Verbose output
===================

`-verbose' if set, chatter about what we are doing.

8.23 Language Support
=====================

`-lang' For page titles use `$T2H_WORDS->{$T2H_LANG}->{...}' as title.
To add a new languages, supply list of titles (see $T2H_WORDS). and use
ISO 639 language codes (see e.g.  perl module
`Locale-Codes-1.02.tar.gz' for definitions)

   See documentlanguage (Texinfo).

8.24 LaTeX2HTML for `@math' and `@tex'
======================================

`-l2h' if set, uses `latex2html' for generation of math content.

8.24.1 Where to find `latex2html'
---------------------------------

`-l2h_l2h' name/location of `latex2html' progam.

8.24.2 Skip calling LaTeX2HTML
------------------------------

`-l2h_skip' if set, skips actual call to `atex2html' tries to reuse
previously generated content, instead.

8.24.3 Temporary files for LaTeX2HTML
-------------------------------------

`-l2h_tmp' if set, l2h uses this directory for temporarary files. The
path leading to this directory may not contain a dot (i.e., a "."),
otherwise, l2h will fail

Appendix A Indices
******************

A.1 Command Line Option Index
=============================