Subversion Repositories or1k

\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}@}}

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