From 4fdcf08051a59eb8f00faa35d735e3fe2524a975 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Fri, 3 Apr 1998 16:29:29 +0000 Subject: Renamed. --- doc/tools/texi2www/texi2www.texi | 707 ++++++++++++++++++++++++++++++++++++ doc/tools/texi2www/texi2wwwdoc.texi | 707 ------------------------------------ 2 files changed, 707 insertions(+), 707 deletions(-) create mode 100644 doc/tools/texi2www/texi2www.texi delete mode 100644 doc/tools/texi2www/texi2wwwdoc.texi diff --git a/doc/tools/texi2www/texi2www.texi b/doc/tools/texi2www/texi2www.texi new file mode 100644 index 0000000000..c726564c39 --- /dev/null +++ b/doc/tools/texi2www/texi2www.texi @@ -0,0 +1,707 @@ +\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 + +info directory table of contents + + +
  • texinfo + GNU texinfo version 3.1 +
  • texi2www + Converts texinfo to 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 +
    +

    Back to our home page.

    +@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 +dir + + +
  • emacs +
  • texinfo +
    •  + +@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> in HTML is like @@var@{@@@@var@} in texinfo. +@@end html +@end example + +@html +produces <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}. + + +@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}. +@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 diff --git a/doc/tools/texi2www/texi2wwwdoc.texi b/doc/tools/texi2www/texi2wwwdoc.texi deleted file mode 100644 index 2791b0451c..0000000000 --- a/doc/tools/texi2www/texi2wwwdoc.texi +++ /dev/null @@ -1,707 +0,0 @@ -\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 - -info directory table of contents - - -
  • texinfo - GNU texinfo version 3.1 -
  • texi2www - Converts texinfo to 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 -
    -

    Back to our home page.

    -@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 -dir - - -
  • emacs -
  • texinfo -
    •  - -@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> in HTML is like @@var@{@@@@var@} in texinfo. -@@end html -@end example - -@html -produces <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}. - - -@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}. -@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 -- cgit v1.2.3