diff options
Diffstat (limited to 'doc/tools/texi2www/texi2www.texi')
| -rw-r--r-- | doc/tools/texi2www/texi2www.texi | 707 |
1 files changed, 0 insertions, 707 deletions
diff --git a/doc/tools/texi2www/texi2www.texi b/doc/tools/texi2www/texi2www.texi deleted file mode 100644 index c726564c39..0000000000 --- a/doc/tools/texi2www/texi2www.texi +++ /dev/null @@ -1,707 +0,0 @@ -\input ../../texinfo/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><EM></EM> in HTML is like @@var@{@@@@var@} in texinfo. -@@end html -@end example - -@html -produces <EM><EM></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 |