source: rtems/doc/tools/texi2www/texi2wwwdoc.texi @ cfdba52

4.104.114.84.95
Last change on this file since cfdba52 was cfdba52, checked in by Joel Sherrill <joel.sherrill@…>, on 04/03/98 at 15:35:08

Base files from texi2www-960103

  • Property mode set to 100644
File size: 20.3 KB
Line 
1\input texinfo @c -*-texinfo-*-
2
3@comment %**start of header
4@setfilename texi2wwwdoc.info
5@settitle texi2www user's guide
6@comment %**end of header
7
8@finalout
9
10@titlepage
11@title texi2www
12@author Tim Singletary
13@end titlepage
14
15@iftex
16@everyfooting @| Jan 2 1996
17@end iftex
18
19@comment ******************************************************** TOP
20@node Top,,,(dir)
21@ifhtml
22This document describes @var{texi2www}, a utility for converting
23texinfo to HTML.
24
25This document provides a pretty good example of @var{texi2www}'s texinfo
26to HTML conversion.  @href{Click here,,,texi2wwwdoc.texi.txt} to view
27the texinfo source to this document.
28@end ifhtml
29
30@menu
31* Overview::    What is texi2www? texinfo? HTML? mosaic? WWW?
32* Real life::   A real-life example using texi2www
33* Invocation::  Command line args, etc.
34* Extensions::  @@ commands not in GNU texinfo
35* Known Bugs::  Oops!
36* Demo::        What various things look like
37
38* texi2dvi::
39
40* Index::
41@end menu
42
43@ifhtml
44@today{}.
45@end ifhtml
46
47
48@comment **************************************************** CHAPTER
49@node Overview
50@unnumbered Overview
51@cindex What is HTML
52@cindex What is texinfo
53@cindex What is mosaic
54@cindex texi2html
55@cindex info2html
56@cindex Other texinfo to HTML converters
57
58@var{Texi2www} converts texinfo to HTML:
59
60@table @asis
61@item
62@table @asis
63@item texinfo
64A documentation system that uses a single source file to produce both
65on-line documentation and printed output.  For details see
66@ref{Top,the Texinfo User's Guide,Overview,texinfo,The Texinfo User's Guide}.
67@item HTML
68@href{HyperText Markup Language,,,
69http://www.ncsa.uiuc.edu/General/Internet/WWW/HTMLPrimer.html}
70used in World Wide Web documents.  Programs like mosaic
71understand HTML.
72@end table
73@end table
74
75Texinfo's on-line documentation viewers (emacs, info, xinfo, etc.) are
76quite limited when compared to mosaic.  Mosaic supports multiple fonts,
77variable width fonts, embedded images, and hypertext links to anywhere
78(not just to other texinfo documents).  In addition, mosaic keeps a
79history of nodes visited and can easily go back to previously visited
80nodes.
81
82@var{Texinfo} converts @var{texinfo} directly to @var{HTML} without
83going through an intermediate @var{info} conversion.
84
85Other @var{texinfo} to @var{HTML} converters include:
86
87@table @asis
88@item
89@href{@var{http://wwwcn.cern.ch/dci/texi2html/},,,
90      http://wwwcn.cern.ch/dci/texi2html/}; and
91@item
92@href{@var{http://www.ericsson.nl/info2www/info2www.html},,,
93      http://www.ericsson.nl/info2www/info2www.html}
94@end table
95
96Texi2html is very good, but is different from texi2www in several respects,
97including:
98
99@itemize
100@item Texi2www processes @@ifinfo blocks, whereas texi2html processes
101      @@iftex blocks.
102@item Texi2www always generates menus, whereas menu generation is
103      optional in texi2html.
104@item Texi2www generates a seperate document for each node, wherease
105      texi2html can combine several nodes into one document.
106@item Texi2www adds @href{@code{@@ifhtml} blocks,ifhtml blocks},
107      @href{@code{@@html} blocks,html blocks}, and @href{@code{@@href@{@}},
108      href}.  Texi2html has @code{@@ifhtml} blocks, but they work like
109      texi2www's @code{@@html} blocks.
110@item Texi2www uses icons for the prev, up, and next links; texi2html
111      doesn't.
112@end itemize
113
114Texi2www is written in perl and may be used and distributed under the
115terms of the @href{GNU General Public License,Copying,emacs}.
116
117Texi2www was written by
118@href{Tim Singletary,,,
119http://sunland.gsfc.nasa.gov/personnel/aam/singletary.html}
120(@cite{tsingle@@sunland.gsfc.nasa.gov}) and is available at
121@href{@var{ftp://sunland.gsfc.nasa.gov/pub/tarfiles/texi2www.tgz},,,
122ftp://sunland.gsfc.nasa.gov/pub/tarfiles/texi2www.tgz}.
123
124@comment **************************************************** CHAPTER
125@node Real life
126@chapter A Real Life Example
127
128Here's how I used texi2www to set up a
129@href{directory of texinfo documents,,,
130                            http://sunland.gsfc.nasa.gov/info/dir.html}.
131This discussion is the minimum I had to do to set up
132@href{texinfo,,,http://sunland.gsfc.nasa.gov/info/texinfo/Top.html} and
133texi2www.
134First, I created the directory ``@var{$HTDOCS/info}'' (@var{$HTDOCS} is
135the root directory of my web server).
136
137Then, I copied arrow icons ``@var{missing-arrow.gif}'',
138``@var{next-arrow.gif}'', ``@var{prev-arrow.gif}'', and
139``@var{up-arrow.gif}'' into ``@var{$HTDOCS/info}''.
140(I obtained my icons from
141@cite{Rutgers University Network Services} at
142@href{http://ns2.rutgers.edu/doc-images/buttons,,,
143      http://ns2.rutgers.edu/doc-images/buttons}.)
144
145Next, I created subdirectories ``@var{$HTDOCS/info/texinfo}'' and
146``@var{$HTDOCS/info/texi2wwwdoc}''.
147(I determined the names of these subdirectories by examining the
148``@var{@@setfilename}'' line in the texinfo files.
149files; @var{texi2wwwdoc.texi} contains the line
150``@var{@@setfilename texi2wwwdoc.info}'' and @var{texinfo.texi} contains
151``@var{@@setfilename texinfo.info}''.
152
153Next, I copied the texinfo files into the appropriate directories.  This
154step isn't strictly required, but I think its a good idea since it makes
155it simple to keep track of which texinfo files generated which set of
156html documents.
157
158Then I generated the html documents.  I used the commands:
159@example
160> cd $HTDOCS/info/texinfo
161> texi2www texinfo.texi
162Normal completion.
163> cd ../texi2wwwdoc
164> texi2www texi2wwwdoc.texi
165Normal completion.
166@end example
167Examing these directories shows that a bunch of @var{.html} files got
168generated, including, in each directory,  ``@var{Top.html}''.
169
170Finally, I created a table of contents file
171``@var{$HTDOCS/info/dir.html}''.  The first version of that file looked
172like:
173
174@example
175<HTML>
176<HEAD><TITLE>info directory table of contents</TITLE></HEAD>
177<BODY>
178<MENU>
179<LI><A HREF="texinfo/Top.html">texinfo</A>
180    GNU texinfo version 3.1
181<LI><A HREF="texi2wwwdoc/Top.html">texi2www</A>
182    Converts texinfo to html
183</MENU>
184</BODY></HTML>
185@end example
186
187@comment **************************************************** CHAPTER
188@node Invocation
189@chapter Invocation
190@cindex Command line options
191@cindex Obtaining gif files
192
193@unnumberedsec Synopsys
194
195@code{texi2www [options] texinfo-file}
196
197@unnumberedsec Options
198@table @asis
199
200@item @code{-dir} @var{path}
201      Specifies the path to the directory where the
202      generated files get placed.  If not specified, the current
203      directory is assumed.
204
205@item @code{-footer} @var{file}
206      Specifies a file whose contents get
207      appended at the bottom of each generated HTML file.  Typically
208      looks something like:
209
210@example
211<HR>
212<P>Back to our <A HREF="../../homepage.html">home page</A>.</P>
213@end example
214
215@item @code{-icons} @var{path}
216      Specifies the path (relative to the directory where the generated
217      files get placed) to the arrow files.  If not specified, @file{..}
218      is assumed.  The names of the arrow
219      files are @file{up_arrow.gif}, @file{left_arrow.gif},
220      @file{right_arrow.gif}, and @file{missing_arrow.gif}
221
222@end table
223
224@unnumberedsec Directory structure
225
226Texi2www will generate a set of HTML files from each texinfo document;
227each set of HTML files must go in a seperate directory (why? one reason
228is because each set includes a file named @code{Top.html}!).
229
230These directories should be subdirectories of the same base directory.
231Assume the base directory is @code{$TEXIBASE}.  Then HTML files for
232emacs go in directory @code{$TEXIBASE/emacs}, HTML files for texinfo go
233in @code{$TEXIBASE/texinfo}, etc, where the name of the subdirectory is
234the same as the name of the info file (so cross references between
235documents will work).
236
237In addition to the subdirectories of HTML files, @code{$TEXIBASE}
238contains a file @code{dir.html} and the four arrow gif files
239@code{up_arrow.gif}, @code{left_arrow.gif}, @code{right_arrow.gif}, and
240@code{missing_arrow.gif}.
241
242@code{$TEXIBASE/dir.html} is typically just a menu of links to the
243subdirectories and can be as simple as
244
245@example
246<HTML><HEAD><TITLE>dir</TITLE></HEAD>
247<BODY>
248<MENU>
249<LI><A HREF="emacs/Top.html">emacs</A>
250<LI><A HREF="texinfo/Top.html">texinfo</A>
251</MENU>
252</BODY></HTML>
253@end example
254
255(@code{$TEXIBASE/dir.html} is not generated via texi2www and must be
256created by hand).
257
258
259
260@comment **************************************************** CHAPTER
261@node Extensions
262@chapter Extensions
263@ifhtml
264Texi2www understands the following extensions to pure texinfo:
265@end ifhtml
266@menu
267* ifhtml blocks:: @code{@@ifhtml} and @code{@@end ifhtml}
268* html blocks:: @code{@@html} and @code{@@end html}
269* href:: @code{@@href@{text,node,file,URL@}}
270* gif:: @code{@@gif@{gif-file@}}
271@end menu
272
273@comment ******************************************************* NODE
274@comment Top -> Extensions ->
275@node ifhtml blocks
276@section @code{@@ifhtml} and @code{@@end ifhtml}
277@cindex Conditional HTML blocks
278
279@var{@@ifhtml} blocks are similar to @var{@@ifinfo} and @var{@@iftex}
280blocks.  Lines between @var{@@ifhtml} and @var{@@end ifhtml} get
281processed when generating the hypertext manual but get ignored when
282generating the printed manual.
283
284@var{texinfo.tex} (in @var{/usr/local/lib/tex/macros} on my machine)
285needs to be modified in order to use @@ifhtml.  I inserted
286@example
287\def\ifhtml@{\doignore@{ifhtml@}@}
288@end example
289after the @code{\def\ifinfo@{\doignore@{ifinfo@}@}} line (line
290596 ???).
291
292In most cases, it is better to use @var{@@ifinfo} than @var{@@ifhtml}.
293
294@comment ******************************************************* NODE
295@node html blocks
296@section @code{@@html} and @code{@@end html}
297@cindex Pure HTML blocks
298
299@var{@@html} blocks are similar to @var{@@tex} blocks; @var{@@html}
300blocks only get processed when generating HTML and lines within
301@var{@@html} blocks may contain HTML commands.
302
303@ifhtml
304For example,
305
306@example
307@@html
308produces <EM>&lt;EM&gt;</EM> in HTML is like @@var@{@@@@var@} in texinfo.
309@@end html
310@end example
311
312@html
313produces <EM>&lt;EM&gt;</EM> in HTML is like @var{@@var} in texinfo.
314@end html
315@end ifhtml
316
317@var{texinfo.tex} (in @var{/usr/local/lib/tex/macros} on my machine)
318needs to be modified in order to use @@ifhtml.  I inserted
319@example
320\def\html@{\doignore@{html@}@}
321@end example
322after the @code{\def\ifinfo@{\doignore@{ifinfo@}@}} line (line
323596 ???).
324
325@comment ******************************************************* NODE
326@node href
327@section @code{@@href@{text,node,file,URL@}}
328
329Use @code{@@href@{text,node,file,URL@}} when you want a hypertext link in an
330HTML document and plain text everywhere else.
331
332@var{Text} is the text you want displayed in the document. 
333@var{Node},@var{file}, and @var{URL} indicate what @var{text} is linked to.
334@var{Node} and @var{file} are a normal texinfo style node reference;
335@var{URL} is a HTML URL. 
336One of @var{node} or @var{URL} must be specified (if both are specified,
337@var{URL} is used).
338
339The @href{texinfo source used to create this
340document,,,texi2wwwdoc.texi.txt} contains numerous examples of how
341@@href might be used.
342
343@var{texinfo.tex} (in @var{/usr/local/lib/tex/macros} on my machine)
344needs to be modified in order to use @@href@{@}.  All I did was insert
345@example
346\def\href#1{\hrefX[#1,,,]}
347\def\hrefX[#1,#2,#3,#4]{#1}
348@end example
349before the @code{\def\pxref} line (line 3497 ???).
350
351@comment ******************************************************* NODE
352@node gif
353@section @code{@@gif@{@var{pict.gif}@}}
354
355This extension provides a method for inserting a gif file in both the
356html and printed document.  For example, here are my arrow icons:
357@*
358prev: @gif{prev-arrow.gif},
359up: @gif{up-arrow.gif},
360and next: @gif{next-arrow.gif}
361
362@subsection @code{@@gif@{@}} and @var{texi2www}
363
364@var{texi2www} copies @var{pict.gif} to the destination directory.
365
366@subsection @code{@@gif@{@}} and @var{texi2dvi}
367
368@href{@var{texi2dvi},texi2dvi} converts @var{pict.gif} to a font and
369uses this font to insert the picture in the document.  This conversion
370to a font requires that the pbmplus and bm2font utilities be installed on
371your system:
372
373@table @asis
374@item pbmplus
375      A suite of utilities for manipulating images.  @var{texi2dvi} uses
376      @var{giftopnm}, @var{pnmscale}, @var{pnmnlfilt}, @var{ppmquant},
377      and @var{ppmtogif}.  These utilities can be obtained from
378      @href{@code{
379         <ftp://ftp.x.org/contrib/utilities/netpbm-1mar1994.tar.gz>},,,
380          ftp://ftp.x.org/contrib/utilities/netpbm-1mar1994.tar.gz}.
381
382 
383@item bm2font
384      @var{bm2font} converts a bitmap images (including ``@code{.gif}''
385      images) to a font that can be used in a @TeX{} document.
386      @var{bm2font} can be obtained from
387      @href{@code{<ftp://ftp.shsu.edu/tex-archive/graphics/bm2font.tar.gz>},,,
388                   ftp://ftp.shsu.edu/tex-archive/graphics/bm2font.tar.gz}.
389@end table
390
391@comment **************************************************** CHAPTER
392@node Known Bugs
393@chapter Known Bugs
394
395@enumerate
396
397@item The @href{@code{@@center},titlefont center sp,texinfo} command
398      doesn't work since HTML doesn't support centering yet.
399
400@item The @href{@code{@@noindent},noindent,texinfo} and
401      @href{@code{@@exdent},exdent,texinfo} commands don't work since
402      HTML doesn't include any facility to control indentation.
403
404@item Mark specifications in the @href{@code{@@itemize},itemize,texinfo}
405      command are ignored since HTML doesn't include any facility to
406      specify the tag in itemized lists.
407
408@item The @href{emacs texinfo files need to be tweaked,
409                problems with emacs} to work with @var{texi2www}.
410
411@item One @href{@code{@@gif},gif} command is allowed per line.
412
413@end enumerate
414
415@unnumberedsec Fixed Bugs
416
417@enumerate
418
419@item Previous versions didn't handle nested tables correctly.  The
420      @@item following an inner @@table would be drawn in the wrong
421      font.  @var{(tsingle, Jan 2 1996)}
422   
423@item Previous versions didn't capitalize
424      @href{@code{@@sc@{@}},Smallcaps,texinfo} text.  (There's still
425      the problem of HTML not supporting true smallcaps, however).
426      @var{(tsingle, Sep 6 1995)}
427
428@item Previous versions of @var{texi2www} didn't correctly index
429      @href{@code{@@ftable} and @code{@@vtable},ftable vtable,texinfo}
430      items; this bug has been fixed! @var{(tsingle, Aug 17 1995)}
431
432@end enumerate
433
434@node problems with emacs
435@section emacs.texi @result{} HTML problems
436
437The file @var{man/commands.texi} distributed with GNU Emacs version
438version 19.25 contains, near the top of the file:
439
440@example
441@@c See file emacs.texi for copying conditions.
442@@iftex
443@@chapter Characters, Keys and Commands
444
445  This chapter explains the character set used by Emacs for input commands
446and for the contents of files, and also explains the concepts of
447@@dfn@{keys@} and @@dfn@{commands@} which are necessary for understanding how
448your keyboard input is understood by Emacs.
449@@end iftex
450@@node User Input, Keys, Screen, Top
451@@section Keyboard Input
452@end example
453
454Texi2www doesn't see the @@chapter since it's inside an @@iftex block;
455this confuses texi2www's chapter numbering.  My fix was to change this
456section to:
457
458@example
459@@c See file emacs.texi for copying conditions.
460@@node User Input, Keys, Screen, Top
461@@chapter Characters, Keys and Commands
462@@iftex
463
464  This chapter explains the character set used by Emacs for input commands
465and for the contents of files, and also explains the concepts of
466@@dfn@{keys@} and @@dfn@{commands@} which are necessary for understanding how
467your keyboard input is understood by Emacs.
468@@end iftex
469@@section Keyboard Input
470@end example
471
472@var{killing.texi}, @var{misc.texi}, and @var{trouble.texi} have similar
473problems.
474
475@comment **************************************************** CHAPTER
476@node Demo
477@appendix Sample output
478
479This document itself is a pretty good example of what texi2www supports
480and produces.  Following are some examples to really make things clear;
481to fully appreciate these examples compare the source and printed output
482to your html viewer.
483
484@menu
485* Fonts::  @@var@{@}, etc.
486* Glyphs:: @@result@{@}, etc.
487* Blocks:: @@example ... @@end example, etc.
488* Tables and Lists:: @@table .. @@end table, etc.
489@end menu
490
491@comment **************************************************** SECTION
492@node Fonts
493@unnumberedsec Text markup
494
495Texi2www supports:
496
497@table @asis
498
499@item @@b@{@var{bold text}@} @result{} @b{bold text}
500Here is @b{some text} in the @@b font.
501
502@item @@cite@{@var{reference}@} @result{} @cite{reference}
503Indicate the name of a book.
504Here is @cite{some text} in the @@cite font.
505
506@item @@code@{@var{sample-code}@} @result{} @code{sample-code}
507Indicate text that is a literal example of a piece of a program.
508Here is @code{some text} in the @@code font.
509
510@item @@dfn@{@var{term}@} @result{} @dfn{term}
511Indicate the introductory or defining use of a term.
512Here is @dfn{some text} in the @@dfn font.
513
514@item @@dmn@{@var{text}@} @result{} @dmn{text}
515Here is @dmn{some text} in the @@dmn font.
516
517@item @@emph@{@var{text}@} @result{} @emph{text}
518Here is @emph{some text} in the @@emph font.
519
520@item @@file@{@var{file-name}@} @result{} @file{file-name}
521Indicate the name of a file.
522Here is @file{some text} in the @@file font.
523
524@item @@i@{@var{italic text}@} @result{} @i{italic text}
525Here is @i{some text} in the @@i font.
526
527@item @@kbd@{@var{keyboard-characters}@} @result{} @kbd{keyboard-characters}
528Indicate keyboard input.
529Here is @kbd{some text} in the @@kbd font.
530
531@item @@key@{@var{key-name}@} @result{} @key{key-name}
532Indicate the conventional name for a key on a keyboard.
533Here is @key{some text} in the @@key font.
534
535@item @@math@{@var{ax^2+b}@} @result{} @math{ax^2+b}
536Here is @r{some text} in the @@math font.
537
538@item @@r@{@var{roman font text}@} @result{} @r{roman font text}
539Here is @r{some text} in the @@r font.
540
541@item @@samp@{@var{text}@} @result{} @samp{text}
542Indicate text that is a literal example of a sequence of characters.
543Here is @samp{some text} in the @@samp font.
544
545@item @@sc@{@var{text}@} @result{} @sc{text}
546Here is @sc{some text} in the @@sc font.
547
548@item @@strong@{@var{text}@} @result{} @strong{text}
549Here is @strong{some text} in the @@strong font.
550
551@item @@t@{@var{fixed-width text}@} @result{} @t{fixed-width text}
552Here is @t{some text} in the @@t font.
553
554@item @@titlefont@{@var{text}@} @result{} @titlefont{text}
555Here is @titlefont{some text} in the @@titlefont font.
556
557@item @@var@{@var{metasyntactic-variable}@} @result{} @var{metasyntactic-variable}
558Indicate a metasyntactic variable.
559Here is @var{some text} in the @@var font.
560
561@end table
562
563
564@comment **************************************************** SECTION
565@node Glyphs
566@unnumberedsec Glyphs
567
568@table @asis
569
570@item @@TeX@{@}       @result{} @TeX{}
571@item @@bullet@{@}    @result{} @bullet{}
572@item @@copyright@{@} @result{} @copyright{}
573@item @@dots@{@}      @result{} @dots{}
574@item @@equiv@{@}     @result{} @equiv{}
575@item @@error@{@}     @result{} @error{}
576@item @@expansion@{@} @result{} @expansion{}
577@item @@minus@{@}     @result{} @minus{}
578@item @@point@{@}     @result{} @point{}
579@item @@print@{@}     @result{} @print{}
580@item @@result@{@}    @result{} @result{}
581@item @@today@{@}     @result{} @today{}
582
583@end table
584
585@comment **************************************************** SECTION
586@node Blocks
587@unnumberedsec Blocks
588
589@example
590@cartouche
591@@example
592@@cartouche
593Here's two lines
594of text
595@@end cartouche
596@@end example
597@end cartouche
598@end example
599
600@display
601@@display
602Here's two lines
603of text
604@@end display
605@end display
606
607@example
608@@example
609Here's two lines
610of text
611@@end example
612@end example
613
614@format
615@@format
616Here's two lines
617of text
618@@end format
619@end format
620
621@lisp
622@@lisp
623Here's two lines
624of text
625@@end lisp
626@end lisp
627
628@quotation
629@@quotation
630Here's two lines
631of text
632@@end quotation
633@end quotation
634
635@smallexample
636@@smallexample
637Here's two lines
638of text
639@@end smallexample
640@end smallexample
641
642@comment **************************************************** SECTION
643@node Tables and Lists
644@unnumberedsec Tables and Lists
645
646@example
647@@table @@code
648@@item code-one
649@@table @@var
650@@item var-one
651@@table @@samp
652@@item samp-one
653Hmmm.
654@@item samp-two
655Mmmmh.
656@@end table
657@@item var-two
658Huh?
659@@end table
660@@item code-two
661Duh?
662@@end table
663@end example
664
665@table @code
666@item code-one
667@table @var
668@item var-one
669@table @samp
670@item samp-one
671Hmmm.
672@item samp-two
673Mmmmh.
674@end table
675@item var-two
676Huh?
677@end table
678@item code-two
679Duh?
680@end table
681
682
683@comment **************************************************** CHAPTER
684@node texi2dvi
685@appendix texi2dvi & texinfo.tex
686
687Versions of ``@code{texi2dvi}'' and ``@code{texinfo.tex}'' are included
688with this package.  These are compatible with the
689@href{texi2www extensions,Extensions}.
690
691@appendixsec texi2dvi
692
693@appendixsec texinfo.tex
694
695``@code{texinfo.tex}'' is a @TeX{} macro used during the @var{texinfo}
696@result{} @var{dvi} conversion. 
697
698
699
700
701@comment **************************************************** CHAPTER
702@node Index
703@unnumbered Index
704@printindex cp
705
706@contents
707@bye
Note: See TracBrowser for help on using the repository browser.