texi2www.texi

RTEMS (Real-Time Executive for Multiprocessor Systems) is a free open source real-time operating sys

\input texinfo   @c -*-texinfo-*-

@comment %**start of header
@setfilename texi2www
@settitle texi2www user's guide
@setcontentsaftertitlepage
@comment %**end of header

@finalout

@titlepage
@title texi2www
@author Tim Singletary
@end titlepage

@iftex
@everyfooting @| Jan 2 1996
@end iftex

@comment ******************************************************** TOP
@node Top,,,(dir)
@ifhtml
This document describes @var{texi2www}, a utility for converting
texinfo to HTML.

This document provides a pretty good example of @var{texi2www}'s texinfo
to HTML conversion.  @href{Click here,,,texi2wwwdoc.texi.txt} to view
the texinfo source to this document.
@end ifhtml

@menu
* Overview::    What is texi2www? texinfo? HTML? mosaic? WWW?
* Real life::   A real-life example using texi2www
* Invocation::  Command line args, etc.
* Extensions::  @@ commands not in GNU texinfo
* Known Bugs::  Oops!
* Demo::        What various things look like

* texi2dvi::

* Index::
@end menu

@ifhtml
@today{}.
@end ifhtml


@comment **************************************************** CHAPTER
@node Overview
@unnumbered Overview
@cindex What is HTML
@cindex What is texinfo
@cindex What is mosaic
@cindex texi2html
@cindex info2html
@cindex Other texinfo to HTML converters

@var{Texi2www} converts texinfo to HTML:

@table @asis
@item
@table @asis
@item texinfo
A documentation system that uses a single source file to produce both
on-line documentation and printed output.  For details see
@ref{Top,the Texinfo User's Guide,Overview,texinfo,The Texinfo User's Guide}.
@item HTML
@href{HyperText Markup Language,,,
http://www.ncsa.uiuc.edu/General/Internet/WWW/HTMLPrimer.html}
used in World Wide Web documents.  Programs like mosaic
understand HTML.
@end table
@end table

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.

@var{Texinfo} converts @var{texinfo} directly to @var{HTML} without
going through an intermediate @var{info} conversion.

Other @var{texinfo} to @var{HTML} converters include:

@table @asis
@item 
@href{@var{http://wwwcn.cern.ch/dci/texi2html/},,,
      http://wwwcn.cern.ch/dci/texi2html/}; and
@item 
@href{@var{http://www.ericsson.nl/info2www/info2www.html},,,
      http://www.ericsson.nl/info2www/info2www.html}
@end table

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

@itemize
@item Texi2www processes @@ifinfo blocks, whereas texi2html processes
      @@iftex blocks.
@item Texi2www always generates menus, whereas menu generation is
      optional in texi2html.
@item Texi2www generates a seperate document for each node, wherease
      texi2html can combine several nodes into one document.
@item Texi2www adds @href{@code{@@ifhtml} blocks,ifhtml blocks}, 
      @href{@code{@@html} blocks,html blocks}, and @href{@code{@@href@{@}},
      href}.  Texi2html has @code{@@ifhtml} blocks, but they work like
      texi2www's @code{@@html} blocks.
@item Texi2www uses icons for the prev, up, and next links; texi2html
      doesn't.
@end itemize

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

Texi2www was written by
@href{Tim Singletary,,,
http://sunland.gsfc.nasa.gov/personnel/aam/singletary.html}
(@cite{tsingle@@sunland.gsfc.nasa.gov}) and is available at
@href{@var{ftp://sunland.gsfc.nasa.gov/pub/tarfiles/texi2www.tgz},,,
ftp://sunland.gsfc.nasa.gov/pub/tarfiles/texi2www.tgz}.

@comment **************************************************** CHAPTER
@node Real life
@chapter A Real Life Example

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

Then, I copied arrow icons ``@var{missing-arrow.gif}'',
``@var{next-arrow.gif}'', ``@var{prev-arrow.gif}'', and
``@var{up-arrow.gif}'' into ``@var{$HTDOCS/info}''.
(I obtained my icons from 
@cite{Rutgers University Network Services} at
@href{http://ns2.rutgers.edu/doc-images/buttons,,,
      http://ns2.rutgers.edu/doc-images/buttons}.)

Next, I created subdirectories ``@var{$HTDOCS/info/texinfo}'' and
``@var{$HTDOCS/info/texi2wwwdoc}''.
(I determined the names of these subdirectories by examining the
``@var{@@setfilename}'' line in the texinfo files.
files; @var{texi2wwwdoc.texi} contains the line
``@var{@@setfilename texi2wwwdoc.info}'' and @var{texinfo.texi} contains
``@var{@@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:
@example
> cd $HTDOCS/info/texinfo
> texi2www texinfo.texi
Normal completion.
> cd ../texi2wwwdoc
> texi2www texi2wwwdoc.texi
Normal completion.
@end example
Examing these directories shows that a bunch of @var{.html} files got
generated, including, in each directory,  ``@var{Top.html}''.

Finally, I created a table of contents file
``@var{$HTDOCS/info/dir.html}''.  The first version of that file looked
like:

@example
<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>
@end example

@comment **************************************************** CHAPTER
@node Invocation
@chapter Invocation
@cindex Command line options
@cindex Obtaining gif files

@unnumberedsec Synopsys

@code{texi2www [options] texinfo-file}

@unnumberedsec Options
@table @asis

@item @code{-dir} @var{path} 
      Specifies the path to the directory where the
      generated files get placed.  If not specified, the current
      directory is assumed.

@item @code{-footer} @var{file} 
      Specifies a file whose contents get
      appended at the bottom of each generated HTML file.  Typically
      looks something like:

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

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

@end table

@unnumberedsec 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 @code{Top.html}!).

These directories should be subdirectories of the same base directory.
Assume the base directory is @code{$TEXIBASE}.  Then HTML files for
emacs go in directory @code{$TEXIBASE/emacs}, HTML files for texinfo go
in @code{$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, @code{$TEXIBASE}
contains a file @code{dir.html} and the four arrow gif files
@code{up_arrow.gif}, @code{left_arrow.gif}, @code{right_arrow.gif}, and
@code{missing_arrow.gif}.

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

@example
<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>
@end example

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



@comment **************************************************** CHAPTER
@node Extensions
@chapter Extensions
@ifhtml
Texi2www understands the following extensions to pure texinfo:
@end ifhtml
@menu
* ifhtml blocks:: @code{@@ifhtml} and @code{@@end ifhtml}
* html blocks:: @code{@@html} and @code{@@end html}
* href:: @code{@@href@{text,node,file,URL@}}
* gif:: @code{@@gif@{gif-file@}}
@end menu

@comment ******************************************************* NODE
@comment Top -> Extensions ->
@node ifhtml blocks
@section @code{@@ifhtml} and @code{@@end ifhtml}
@cindex Conditional HTML blocks

@var{@@ifhtml} blocks are similar to @var{@@ifinfo} and @var{@@iftex}
blocks.  Lines between @var{@@ifhtml} and @var{@@end ifhtml} get
processed when generating the hypertext manual but get ignored when
generating the printed manual.

@var{texinfo.tex} (in @var{/usr/local/lib/tex/macros} on my machine)
needs to be modified in order to use @@ifhtml.  I inserted
@example
\def\ifhtml@{\doignore@{ifhtml@}@}
@end example
after the @code{\def\ifinfo@{\doignore@{ifinfo@}@}} line (line
596 ???).

In most cases, it is better to use @var{@@ifinfo} than @var{@@ifhtml}.

@comment ******************************************************* NODE
@node html blocks
@section @code{@@html} and @code{@@end html}
@cindex Pure HTML blocks

@var{@@html} blocks are similar to @var{@@tex} blocks; @var{@@html}
blocks only get processed when generating HTML and lines within
@var{@@html} blocks may contain HTML commands.

@ifhtml
For example,

@example
@@html
produces <EM>&lt;EM&gt;</EM> in HTML is like @@var@{@@@@var@} in texinfo.
@@end html
@end example

@html
produces <EM>&lt;EM&gt;</EM> in HTML is like @var{@@var} in texinfo.
@end html
@end ifhtml

@var{texinfo.tex} (in @var{/usr/local/lib/tex/macros} on my machine)
needs to be modified in order to use @@ifhtml.  I inserted
@example
\def\html@{\doignore@{html@}@}
@end example
after the @code{\def\ifinfo@{\doignore@{ifinfo@}@}} line (line
596 ???). 

@comment ******************************************************* NODE
@node href
@section @code{@@href@{text,node,file,URL@}}

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

@var{Text} is the text you want displayed in the document.  
@var{Node},@var{file}, and @var{URL} indicate what @var{text} is linked to.
@var{Node} and @var{file} are a normal texinfo style node reference;
@var{URL} is a HTML URL.  
One of @var{node} or @var{URL} must be specified (if both are specified,
@var{URL} is used).

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

@var{texinfo.tex} (in @var{/usr/local/lib/tex/macros} on my machine)
needs to be modified in order to use @@href@{@}.  All I did was insert
@example
\def\href#1{\hrefX[#1,,,]}
\def\hrefX[#1,#2,#3,#4]{#1}
@end example
before the @code{\def\pxref} line (line 3497 ???).

@comment ******************************************************* NODE
@node gif
@section @code{@@gif@{@var{pict.gif}@}}