Texi2html
*********

This Manual (Edition 0.21, last updated at 14. August 2000) describes the texi2html Perl script which converters Texinfo (http://www.texinfo.org) 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 ;-)

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 all over the world.

A few time ago makeinfo wasn't able to produce HTML output format, but there are needth to have HTML. This was the borning hour for texi2html. The basic purpose of texi2html is to convert Texinfo documents into HTML.

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

You would like to HTML files out of your Texinfo files? There exist two ways which you can go. This first is to use makeinfo itself to produce HTML output. The second is to use texi2html.

Why texi2html and not makeinfo?
===============================

The basic idea of makeinfo's HTML output was to get an readable HTML output. Nothing sophisticated nor good styling just readable.

The current development of texi2html is going into different direction.

The main purpose is to get better styling, better design etc. of the created HTML pages. This way is supported using differnt command line options and of course possible changings of the initialization file to fit your own needs.

The main disadvantage of makeinfo's HTML output is your getting only one big file. This is of course readable but not very usable. The problem of this is, while you like to have splitted chapters or nodes the Texinfo source has to be read at minimum twice times. This makes it impossible to implement this in makeinfo. This would result in complete new implementation of makeinfo's source.

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.

Installation of texi2html
*************************

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

Customizing files
*****************

Result based on using -frames

     texi2html -V -frames texi2html.texi

Explanation of the output differences against default, whatever this is ;-)

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

Test starting.

-expand info -expand tex Take a look at optionexpand.

Customizing page layout
***********************

This chapter is designed to help you to change the complete layout of the HTML output if you like to do so.

a) General: Philosophy, and how it works

aa) Navigation panels

b) Top page

c) Section pages

Tips how to create a new site design
====================================

Here you can find information how you should work to pick up a new design with texi2html.

Page Layout and the philosophy
==============================

Navigation panels
-----------------

Head and foot Navigation panels.

Top Page
========

Section Pages
=============

Misc pages
==========

Here you can find information about the creation of the ToC (Table Of content), About---Page etc. and specialy how to change them to get your own design.

ToC T2H_DEFAULT_print_toc_frame in texi2html.init

Table Of Contents
-----------------

The following code is the original code out of the initialization file (see Initialization file).

     sub T2H_DEFAULT_print_toc_frame
     {
       my $fh = shift;
       &$T2H_print_page_head($fh);
       print $fh <<EOT;
     <H2>Content</H2>
     EOT
       print $fh map {s/HREF=/target=\"main\" HREF=/; $_;} @stoc_lines;
       print $fh "</BODY></HTML>\n";
     }

As you can see it is very simple Perl Code, which can be changed more or less simple to fit you requirements (see T2H_DEFAULT_print_page_head).

Page header
-----------

Page Head T2H_DEFAULT_print_page_head

     sub T2H_DEFAULT_print_page_head
     {
       my $fh = shift;
       my $longtitle = "$T2H_THISDOC{title}: $T2H_NAME{This}";
       print $fh <<EOT;
     <HTML>
     $T2H_DOCTYPE
     <!-- Created on $T2H_TODAY by $THISPROG -->
     <!--
     $T2H_AUTHORS
     -->
     <HEAD>
     <TITLE>$longtitle</TITLE>

     <META NAME="description" CONTENT="$longtitle">
     <META NAME="keywords" CONTENT="$longtitle">
     <META NAME="resource-type" CONTENT="document">
     <META NAME="distribution" CONTENT="global">
     <META NAME="Generator" CONTENT="$THISPROG">
     $T2H_EXTRA_HEAD
     </HEAD>

     <BODY $T2H_BODYTEXT>
     $T2H_AFTER_BODY_OPEN
     EOT
     }

Page footer
-----------

Page Foot T2H_DEFAULT_print_page_foot

Customizing HTML
****************

If you like to read the following section, it is assumed you are famillar with HTML. If not, you shouldn't read this, cause you don't know what we are talking about.

Here you can find information how to change the HTML parts of a document. These are the header, body etc.

These are the defaults which are part of the distribution as texi2html.init.

How to do changes of the customization... needed steps.

Body
====

Body Text
---------

     $T2H_BODYTEXT =
         . 'LANG="' . $T2H_LANG . '" BGCOLOR="#FFFFFF" '
         . 'TEXT="#000000" LINK="#0000FF" '
         . 'VLINK="#800080" ALINK="#FF0000"';

If you like to change the basic color combination, you can change the entry T2H_BODYTEXT.

Body Text
---------

After Body Text
---------------

     # text inserted after <BODY ...>
     $T2H_AFTER_BODY_OPEN = '';

     #text inserted before </BODY>
     $T2H_PRE_BODY_CLOSE = '';

     # this is used in footer
     $T2H_ADDRESS = "by <I>$T2H_USER</I> " if $T2H_USER;
     $T2H_ADDRESS .= "on <I>$T2H_TODAY</I>";

     # this is added inside <HEAD></HEAD> after <TITLE> and some META NAME stuff
     # can be used for <style> <script>, <meta> tags
     $T2H_EXTRA_HEAD = '';

The default output into the HTML file. See OptionDocType.

The following code is produced by T2H_DEFAULT_print_page_head.

Detailed information can be found at CustPagePageHead.

     <HTML>
     $T2H_DOCTYPE
     <!-- Created on $T2H_TODAY by $THISPROG -->
     <!--
     $T2H_AUTHORS
     -->
     <HEAD>
     <TITLE>$longtitle</TITLE>

     <META NAME="description" CONTENT="$longtitle">
     <META NAME="keywords" CONTENT="$longtitle">
     <META NAME="resource-type" CONTENT="document">
     <META NAME="distribution" CONTENT="global">
     <META NAME="Generator" CONTENT="$THISPROG">
     $T2H_EXTRA_HEAD
     </HEAD>

     <BODY $T2H_BODYTEXT>
     $T2H_AFTER_BODY_OPEN

Head
====

Initialization file
*******************

texi2html.init

The basics about init files
===========================

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 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.

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/

Global initialization file
==========================

User initialization file
========================

Loadable initialization file
============================

-init_file

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

This section describes in detail all options that can be used only in the initialization file (texi2html.init), and cannot be specified on the command line. This means the only way to change those options is first to copy the original texi2html.init to e.g. texi2html.init.myown and make changes to fit your needs.

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;

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

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

Center Image
------------

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

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

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

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

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

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

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

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 = "";

Index Chapter
-------------

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

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;

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

if set (e.g., to index.html) replace HREF's to this file  (i.e., to index.html) by ./

$T2H_HREF_DIR_INSTEAD_FILE = "";

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

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;

DocType
=======

-doctype

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

Check
=====

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

Expand
======

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

Glossary
========

-glossary if set, uses section named Footnotes for glossary

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;';

Iso
===

-iso

if set, ISO8859 characters are used for special symbols (like Copyright ©, etc)

$T2H_USE_ISO = 0;

Include Directory
=================

-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 = (".");

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 = "";

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 = "";

Frames
======

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

$T2H_FRAMES = 0;

Menus
=====

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

$T2H_SHOW_MENU = 1;

Number sections
===============

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

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 a monolithic HTML file that contains the whole document.

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

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

Subdirectory
============

-subdir If set, then put result files in the specified directory. If not set, then result files are put into the current directory.

$T2H_SUBDIR = undef;

Short extension
===============

-short_extn If this is set, then all HTML files will have extension .htm instead of .html. This is helpful when shipping the document to DOS-based systems. $T2H_SHORTEXTN = 0;

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 = "";

Output filename
===============

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

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

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

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).

Verbose output
==============

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

Language Support
================

-lang For page titles, use $T2H_WORDS->{$T2H_LANG}->{...} as title. To add a new language, 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).

If you don't give a -lang then we got it from the Texinfo source file (@documentlanguage see documentlanguage (Texinfo)). If there is no @documentlanguage we use the default en for the language.

LaTeX2HTML for @math and @tex
=============================

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

Where to find latex2html
------------------------

-l2h_l2h name/location of latex2html program.

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

-l2h_skip If set, skips actual call to latex2html: tries to reuse previously generated content, instead.

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

-l2h_tmp If set, l2h uses this directory for temporary files.  The path leading to this directory may not contain a dot (i.e., a .); otherwise, l2h will fail.

Function Reference
******************

Print ToC Frame
===============

 -- Function: T2H_DEFAULT_print_toc_frame (FileName)

     Description of the subroutine. What does it do? Which parameters it needs etc.

Print Page Head
===============

 -- Function: T2H_DEFAULT_print_page_head (FileName)

     Description of the subroutine. What does it do? Which parameters it needs etc.

Indices
*******