path: root/doc/tools/texi2www/texi2www.texi

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

@comment %**start of header
@setfilename texi2www
@settitle texi2www user's guide
@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}@}}

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: @gif{prev-arrow.gif},
up: @gif{up-arrow.gif},
and next: @gif{next-arrow.gif}

@subsection @code{@@gif@{@}} and @var{texi2www}

@var{texi2www} copies @var{pict.gif} to the destination directory.

@subsection @code{@@gif@{@}} and @var{texi2dvi}

@href{@var{texi2dvi},texi2dvi} converts @var{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:

@table @asis
@item pbmplus
      A suite of utilities for manipulating images.  @var{texi2dvi} uses
      @var{giftopnm}, @var{pnmscale}, @var{pnmnlfilt}, @var{ppmquant},
      and @var{ppmtogif}.  These utilities can be obtained from
      @href{@code{
         <ftp://ftp.x.org/contrib/utilities/netpbm-1mar1994.tar.gz>},,,
          ftp://ftp.x.org/contrib/utilities/netpbm-1mar1994.tar.gz}.

  
@item bm2font
      @var{bm2font} converts a bitmap images (including ``@code{.gif}''
      images) to a font that can be used in a @TeX{} document.
      @var{bm2font} can be obtained from
      @href{@code{<ftp://ftp.shsu.edu/tex-archive/graphics/bm2font.tar.gz>},,,
                   ftp://ftp.shsu.edu/tex-archive/graphics/bm2font.tar.gz}.
@end table

@comment **************************************************** CHAPTER
@node Known Bugs
@chapter Known Bugs

@enumerate

@item The @href{@code{@@center},titlefont center sp,texinfo} command
      doesn't work since HTML doesn't support centering yet. 

@item The @href{@code{@@noindent},noindent,texinfo} and
      @href{@code{@@exdent},exdent,texinfo} commands don't work since
      HTML doesn't include any facility to control indentation.

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

@item The @href{emacs texinfo files need to be tweaked,
                problems with emacs} to work with @var{texi2www}.

@item One @href{@code{@@gif},gif} command is allowed per line.

@end enumerate

@unnumberedsec Fixed Bugs

@enumerate 

@item Previous versions didn't handle nested tables correctly.  The
      @@item following an inner @@table would be drawn in the wrong
      font.  @var{(tsingle, Jan 2 1996)}
   
@item Previous versions didn't capitalize
      @href{@code{@@sc@{@}},Smallcaps,texinfo} text.  (There's still
      the problem of HTML not supporting true smallcaps, however).
      @var{(tsingle, Sep 6 1995)}

@item Previous versions of @var{texi2www} didn't correctly index
      @href{@code{@@ftable} and @code{@@vtable},ftable vtable,texinfo}
      items; this bug has been fixed! @var{(tsingle, Aug 17 1995)}

@end enumerate

@node problems with emacs
@section emacs.texi @result{} HTML problems

The file @var{man/commands.texi} distributed with GNU Emacs version
version 19.25 contains, near the top of the file:

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

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:

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

@var{killing.texi}, @var{misc.texi}, and @var{trouble.texi} have similar
problems.

@comment **************************************************** CHAPTER
@node Demo
@appendix 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.

@menu
* Fonts::  @@var@{@}, etc.
* Glyphs:: @@result@{@}, etc.
* Blocks:: @@example ... @@end example, etc.
* Tables and Lists:: @@table .. @@end table, etc.
@end menu

@comment **************************************************** SECTION
@node Fonts
@unnumberedsec Text markup

Texi2www supports:

@table @asis

@item @@b@{@var{bold text}@} @result{} @b{bold text}
Here is @b{some text} in the @@b font.

@item @@cite@{@var{reference}@} @result{} @cite{reference}
Indicate the name of a book.
Here is @cite{some text} in the @@cite font.

@item @@code@{@var{sample-code}@} @result{} @code{sample-code}
Indicate text that is a literal example of a piece of a program.
Here is @code{some text} in the @@code font.

@item @@dfn@{@var{term}@} @result{} @dfn{term}
Indicate the introductory or defining use of a term.
Here is @dfn{some text} in the @@dfn font.

@item @@dmn@{@var{text}@} @result{} @dmn{text}
Here is @dmn{some text} in the @@dmn font.

@item @@emph@{@var{text}@} @result{} @emph{text}
Here is @emph{some text} in the @@emph font.

@item @@file@{@var{file-name}@} @result{} @file{file-name}
Indicate the name of a file.
Here is @file{some text} in the @@file font.

@item @@i@{@var{italic text}@} @result{} @i{italic text}
Here is @i{some text} in the @@i font.

@item @@kbd@{@var{keyboard-characters}@} @result{} @kbd{keyboard-characters}
Indicate keyboard input.
Here is @kbd{some text} in the @@kbd font.

@item @@key@{@var{key-name}@} @result{} @key{key-name}
Indicate the conventional name for a key on a keyboard.
Here is @key{some text} in the @@key font.

@item @@math@{@var{ax^2+b}@} @result{} @math{ax^2+b}
Here is @r{some text} in the @@math font.

@item @@r@{@var{roman font text}@} @result{} @r{roman font text}
Here is @r{some text} in the @@r font.

@item @@samp@{@var{text}@} @result{} @samp{text}
Indicate text that is a literal example of a sequence of characters.
Here is @samp{some text} in the @@samp font.

@item @@sc@{@var{text}@} @result{} @sc{text}
Here is @sc{some text} in the @@sc font.

@item @@strong@{@var{text}@} @result{} @strong{text}
Here is @strong{some text} in the @@strong font.

@item @@t@{@var{fixed-width text}@} @result{} @t{fixed-width text}
Here is @t{some text} in the @@t font.

@item @@titlefont@{@var{text}@} @result{} @titlefont{text}
Here is @titlefont{some text} in the @@titlefont font.

@item @@var@{@var{metasyntactic-variable}@} @result{} @var{metasyntactic-variable}
Indicate a metasyntactic variable.
Here is @var{some text} in the @@var font.

@end table


@comment **************************************************** SECTION
@node Glyphs
@unnumberedsec Glyphs

@table @asis

@item @@TeX@{@}       @result{} @TeX{}
@item @@bullet@{@}    @result{} @bullet{}
@item @@copyright@{@} @result{} @copyright{}
@item @@dots@{@}      @result{} @dots{}
@item @@equiv@{@}     @result{} @equiv{}
@item @@error@{@}     @result{} @error{}
@item @@expansion@{@} @result{} @expansion{}
@item @@minus@{@}     @result{} @minus{}
@item @@point@{@}     @result{} @point{}
@item @@print@{@}     @result{} @print{}
@item @@result@{@}    @result{} @result{}
@item @@today@{@}     @result{} @today{}

@end table

@comment **************************************************** SECTION
@node Blocks
@unnumberedsec Blocks

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

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

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

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

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

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

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

@comment **************************************************** SECTION
@node Tables and Lists
@unnumberedsec Tables and Lists

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

@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


@comment **************************************************** CHAPTER
@node texi2dvi
@appendix texi2dvi & texinfo.tex

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

@appendixsec texi2dvi

@appendixsec texinfo.tex

``@code{texinfo.tex}'' is a @TeX{} macro used during the @var{texinfo}
@result{} @var{dvi} conversion.  




@comment **************************************************** CHAPTER
@node Index
@unnumbered Index
@printindex cp

@contents
@bye