Overview
********

TEXI2WWW converts texinfo to HTML:

     texinfo
          A documentation system that uses a single source file to produce both on-line documentation and printed output.  For details see Overview (The Texinfo User's Guide).

     HTML
          HyperText Markup Language,,, http://www.ncsa.uiuc.edu/General/Internet/WWW/HTMLPrimer.html used in World Wide Web documents.  Programs like mosaic understand HTML.

Texinfo's on-line documentation viewers (emacs, info, xinfo, etc.) are quite limited when compared to mosaic.  Mosaic supports multiple fonts, variable width fonts, embedded images, and hypertext links to anywhere (not just to other texinfo documents).  In addition, mosaic keeps a history of nodes visited and can easily go back to previously visited nodes.

TEXINFO converts TEXINFO directly to HTML without going through an intermediate INFO conversion.

Other TEXINFO to HTML converters include:

     HTTP://WWWCN.CERN.CH/DCI/TEXI2HTML/,,, http://wwwcn.cern.ch/dci/texi2html/; and

     HTTP://WWW.ERICSSON.NL/INFO2WWW/INFO2WWW.HTML,,, http://www.ericsson.nl/info2www/info2www.html

Texi2html is very good, but is different from texi2www in several respects, including:

  * Texi2www processes @ifinfo blocks, whereas texi2html processes @iftex blocks.

  * Texi2www always generates menus, whereas menu generation is optional in texi2html.

  * Texi2www generates a seperate document for each node, wherease texi2html can combine several nodes into one document.

  * Texi2www adds @ifhtml blocks,ifhtml blocks, @html blocks,html blocks, and @href{}, href.  Texi2html has @ifhtml blocks, but they work like texi2www's @html blocks.

  * Texi2www uses icons for the prev, up, and next links; texi2html doesn't.

Texi2www is written in perl and may be used and distributed under the terms of the GNU General Public License,Copying,emacs.

Texi2www was written by Tim Singletary,,, http://sunland.gsfc.nasa.gov/personnel/aam/singletary.html (tsingle@sunland.gsfc.nasa.gov) and is available at FTP://SUNLAND.GSFC.NASA.GOV/PUB/TARFILES/TEXI2WWW.TGZ,,, ftp://sunland.gsfc.nasa.gov/pub/tarfiles/texi2www.tgz.

A Real Life Example
*******************

Here's how I used texi2www to set up a directory of texinfo documents,,, http://sunland.gsfc.nasa.gov/info/dir.html. This discussion is the minimum I had to do to set up texinfo,,,http://sunland.gsfc.nasa.gov/info/texinfo/Top.html and texi2www. First, I created the directory ``$HTDOCS/INFO'' ($HTDOCS is the root directory of my web server).

Then, I copied arrow icons ``MISSING-ARROW.GIF'', ``NEXT-ARROW.GIF'', ``PREV-ARROW.GIF'', and ``UP-ARROW.GIF'' into ``$HTDOCS/INFO''. (I obtained my icons from Rutgers University Network Services at http://ns2.rutgers.edu/doc-images/buttons,,, http://ns2.rutgers.edu/doc-images/buttons.)

Next, I created subdirectories ``$HTDOCS/INFO/TEXINFO'' and ``$HTDOCS/INFO/TEXI2WWWDOC''. (I determined the names of these subdirectories by examining the ``@SETFILENAME'' line in the texinfo files. files; TEXI2WWWDOC.TEXI contains the line ``@SETFILENAME TEXI2WWWDOC.INFO'' and TEXINFO.TEXI contains ``@SETFILENAME TEXINFO.INFO''.

Next, I copied the texinfo files into the appropriate directories.  This step isn't strictly required, but I think its a good idea since it makes it simple to keep track of which texinfo files generated which set of html documents.

Then I generated the html documents.  I used the commands:

     > cd $HTDOCS/info/texinfo
     > texi2www texinfo.texi
     Normal completion.
     > cd ../texi2wwwdoc
     > texi2www texi2wwwdoc.texi
     Normal completion.

Examing these directories shows that a bunch of .HTML files got generated, including, in each directory,  ``TOP.HTML''.

Finally, I created a table of contents file ``$HTDOCS/INFO/DIR.HTML''.  The first version of that file looked like:

     <HTML>
     <HEAD><TITLE>info directory table of contents</TITLE></HEAD>
     <BODY>
     <MENU>
     <LI><A HREF="texinfo/Top.html">texinfo</A>
         GNU texinfo version 3.1
     <LI><A HREF="texi2wwwdoc/Top.html">texi2www</A>
         Converts texinfo to html
     </MENU>
     </BODY></HTML>

Invocation
**********

Synopsys
========

texi2www [options] texinfo-file

Options
=======

-dir PATH
     Specifies the path to the directory where the generated files get placed.  If not specified, the current directory is assumed.

-footer FILE
     Specifies a file whose contents get appended at the bottom of each generated HTML file.  Typically looks something like:

          <HR>
          <P>Back to our <A HREF="../../homepage.html">home page</A>.</P>

-icons PATH
     Specifies the path (relative to the directory where the generated files get placed) to the arrow files.  If not specified, .. is assumed.  The names of the arrow files are up_arrow.gif, left_arrow.gif, right_arrow.gif, and missing_arrow.gif

Directory structure
===================

Texi2www will generate a set of HTML files from each texinfo document; each set of HTML files must go in a seperate directory (why? one reason is because each set includes a file named Top.html!).

These directories should be subdirectories of the same base directory. Assume the base directory is $TEXIBASE.  Then HTML files for emacs go in directory $TEXIBASE/emacs, HTML files for texinfo go in $TEXIBASE/texinfo, etc, where the name of the subdirectory is the same as the name of the info file (so cross references between documents will work).

In addition to the subdirectories of HTML files, $TEXIBASE contains a file dir.html and the four arrow gif files up_arrow.gif, left_arrow.gif, right_arrow.gif, and missing_arrow.gif.

$TEXIBASE/dir.html is typically just a menu of links to the subdirectories and can be as simple as

     <HTML><HEAD><TITLE>dir</TITLE></HEAD>
     <BODY>
     <MENU>
     <LI><A HREF="emacs/Top.html">emacs</A>
     <LI><A HREF="texinfo/Top.html">texinfo</A>
     </MENU>
     </BODY></HTML>

($TEXIBASE/dir.html is not generated via texi2www and must be created by hand).

Extensions
**********

@ifhtml and @end ifhtml
=======================

@IFHTML blocks are similar to @IFINFO and @IFTEX blocks.  Lines between @IFHTML and @END IFHTML get processed when generating the hypertext manual but get ignored when generating the printed manual.

TEXINFO.TEX (in /USR/LOCAL/LIB/TEX/MACROS on my machine) needs to be modified in order to use @ifhtml.  I inserted

     \def\ifhtml{\doignore{ifhtml}}

after the \def\ifinfo{\doignore{ifinfo}} line (line 596 ???).

In most cases, it is better to use @IFINFO than @IFHTML.

@html and @end html
===================

@HTML blocks are similar to @TEX blocks; @HTML blocks only get processed when generating HTML and lines within @HTML blocks may contain HTML commands.

TEXINFO.TEX (in /USR/LOCAL/LIB/TEX/MACROS on my machine) needs to be modified in order to use @ifhtml.  I inserted

     \def\html{\doignore{html}}

after the \def\ifinfo{\doignore{ifinfo}} line (line 596 ???).

@href{text,node,file,URL}
=========================

Use @href{text,node,file,URL} when you want a hypertext link in an HTML document and plain text everywhere else.

TEXT is the text you want displayed in the document. NODE,FILE, and URL indicate what TEXT is linked to. NODE and FILE are a normal texinfo style node reference; URL is a HTML URL. One of NODE or URL must be specified (if both are specified, URL is used).

The texinfo source used to create this document,,,texi2wwwdoc.texi.txt contains numerous examples of how @href might be used.

TEXINFO.TEX (in /USR/LOCAL/LIB/TEX/MACROS on my machine) needs to be modified in order to use @href{}.  All I did was insert

     \def\href#1{\hrefX[#1,,,]}
     \def\hrefX[#1,#2,#3,#4]{#1}

before the \def\pxref line (line 3497 ???).

@gif{PICT.GIF}
==============

This extension provides a method for inserting a gif file in both the html and printed document.  For example, here are my arrow icons: prev: prev-arrow.gif, up: up-arrow.gif, and next: next-arrow.gif

@gif{} and TEXI2WWW
-------------------

TEXI2WWW copies PICT.GIF to the destination directory.

@gif{} and TEXI2DVI
-------------------

TEXI2DVI,texi2dvi converts PICT.GIF to a font and uses this font to insert the picture in the document.  This conversion to a font requires that the pbmplus and bm2font utilities be installed on your system:

pbmplus
     A suite of utilities for manipulating images.  TEXI2DVI uses GIFTOPNM, PNMSCALE, PNMNLFILT, PPMQUANT, and PPMTOGIF.  These utilities can be obtained from

     <ftp://ftp.x.org/contrib/utilities/netpbm-1mar1994.tar.gz>,,, ftp://ftp.x.org/contrib/utilities/netpbm-1mar1994.tar.gz.

bm2font
     BM2FONT converts a bitmap images (including ``.gif'' images) to a font that can be used in a TeX document. BM2FONT can be obtained from <ftp://ftp.shsu.edu/tex-archive/graphics/bm2font.tar.gz>,,, ftp://ftp.shsu.edu/tex-archive/graphics/bm2font.tar.gz.

Known Bugs
**********

 1. The @center,titlefont center sp,texinfo command doesn't work since HTML doesn't support centering yet.

 2. The @noindent,noindent,texinfo and @exdent,exdent,texinfo commands don't work since HTML doesn't include any facility to control indentation.

 3. Mark specifications in the @itemize,itemize,texinfo command are ignored since HTML doesn't include any facility to specify the tag in itemized lists.

 4. The emacs texinfo files need to be tweaked, problems with emacs to work with TEXI2WWW.

 5. One @gif,gif command is allowed per line.

Fixed Bugs
==========

 1. Previous versions didn't handle nested tables correctly.  The @item following an inner @table would be drawn in the wrong font.  (TSINGLE, JAN 2 1996)

 2. Previous versions didn't capitalize @sc{},Smallcaps,texinfo text.  (There's still the problem of HTML not supporting true smallcaps, however). (TSINGLE, SEP 6 1995)

 3. Previous versions of TEXI2WWW didn't correctly index @ftable and @vtable,ftable vtable,texinfo items; this bug has been fixed! (TSINGLE, AUG 17 1995)

emacs.texi => HTML problems
===========================

The file MAN/COMMANDS.TEXI distributed with GNU Emacs version version 19.25 contains, near the top of the file:

     @c See file emacs.texi for copying conditions.
     @iftex
     @chapter Characters, Keys and Commands

       This chapter explains the character set used by Emacs for input commands
     and for the contents of files, and also explains the concepts of
     @dfn{keys} and @dfn{commands} which are necessary for understanding how
     your keyboard input is understood by Emacs.
     @end iftex
     @node User Input, Keys, Screen, Top
     @section Keyboard Input

Texi2www doesn't see the @chapter since it's inside an @iftex block; this confuses texi2www's chapter numbering.  My fix was to change this section to:

     @c See file emacs.texi for copying conditions.
     @node User Input, Keys, Screen, Top
     @chapter Characters, Keys and Commands
     @iftex

       This chapter explains the character set used by Emacs for input commands
     and for the contents of files, and also explains the concepts of
     @dfn{keys} and @dfn{commands} which are necessary for understanding how
     your keyboard input is understood by Emacs.
     @end iftex
     @section Keyboard Input

KILLING.TEXI, MISC.TEXI, and TROUBLE.TEXI have similar problems.

Sample output
*************

This document itself is a pretty good example of what texi2www supports and produces.  Following are some examples to really make things clear; to fully appreciate these examples compare the source and printed output to your html viewer.

Text markup
===========

Texi2www supports:

@b{BOLD TEXT} => bold text
     Here is some text in the @b font.

@cite{REFERENCE} => reference
     Indicate the name of a book. Here is some text in the @cite font.

@code{SAMPLE-CODE} => sample-code
     Indicate text that is a literal example of a piece of a program. Here is some text in the @code font.

@dfn{TERM} => term
     Indicate the introductory or defining use of a term. Here is some text in the @dfn font.

@dmn{TEXT} => text
     Here is some text in the @dmn font.

@emph{TEXT} => text
     Here is some text in the @emph font.

@file{FILE-NAME} => file-name
     Indicate the name of a file. Here is some text in the @file font.

@i{ITALIC TEXT} => italic text
     Here is some text in the @i font.

@kbd{KEYBOARD-CHARACTERS} => keyboard-characters
     Indicate keyboard input. Here is some text in the @kbd font.

@key{KEY-NAME} => key-name
     Indicate the conventional name for a key on a keyboard. Here is some text in the @key font.

@math{AX^2+B} => ax^2+b
     Here is some text in the @math font.

@r{ROMAN FONT TEXT} => roman font text
     Here is some text in the @r font.

@samp{TEXT} => text
     Indicate text that is a literal example of a sequence of characters. Here is some text in the @samp font.

@sc{TEXT} => TEXT
     Here is SOME TEXT in the @sc font.

@strong{TEXT} => text
     Here is some text in the @strong font.

@t{FIXED-WIDTH TEXT} => fixed-width text
     Here is some text in the @t font.

@titlefont{TEXT} => text
     Here is some text in the @titlefont font.

@var{METASYNTACTIC-VARIABLE} => METASYNTACTIC-VARIABLE
     Indicate a metasyntactic variable. Here is SOME TEXT in the @var font.

Glyphs
======

@TeX{}       => TeX

@bullet{}    => *

@copyright{} => ©

@dots{}      => ...

@equiv{}     => ==

@error{}     => error-->

@expansion{} => ==>

@minus{}     => -

@point{}     => -!-

@print{}     => -|

@result{}    => =>

@today{}     =>

Blocks
======

     @example
     @cartouche
     Here's two lines
     of text
     @end cartouche
     @end example

     @display
     Here's two lines
     of text
     @end display

     @example
     Here's two lines
     of text
     @end example

     @format
     Here's two lines
     of text
     @end format

     @lisp
     Here's two lines
     of text
     @end lisp

     @quotation Here's two lines of text @end quotation

     @smallexample
     Here's two lines
     of text
     @end smallexample

Tables and Lists
================

     @table @code
     @item code-one
     @table @var
     @item var-one
     @table @samp
     @item samp-one
     Hmmm.
     @item samp-two
     Mmmmh.
     @end table
     @item var-two
     Huh?
     @end table
     @item code-two
     Duh?
     @end table

code-one

     var-one

          samp-one
               Hmmm.

          samp-two
               Mmmmh.

     var-two
          Huh?

code-two
     Duh?

texi2dvi & texinfo.tex
**********************

Versions of ``texi2dvi'' and ``texinfo.tex'' are included with this package.  These are compatible with the texi2www extensions,Extensions.

texi2dvi
========

texinfo.tex
===========

``texinfo.tex'' is a TeX macro used during the TEXINFO => DVI conversion.