diff options
Diffstat (limited to 'doc/tools/texi2www/texi2wwwdoc.texi')
| -rw-r--r-- | doc/tools/texi2www/texi2wwwdoc.texi | 707 |
1 files changed, 707 insertions, 0 deletions
diff --git a/doc/tools/texi2www/texi2wwwdoc.texi b/doc/tools/texi2www/texi2wwwdoc.texi new file mode 100644 index 0000000000..030dd41d89 --- /dev/null +++ b/doc/tools/texi2www/texi2wwwdoc.texi @@ -0,0 +1,707 @@ +\input texinfo @c -*-texinfo-*- + +@comment %**start of header +@setfilename texi2wwwdoc.info +@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 |