diff options
-rw-r--r-- | doc/tools/texi2www/archive/texi2www-960103.tgz | bin | 0 -> 131143 bytes | |||
-rw-r--r-- | doc/tools/texi2www/texi2dvi | 213 | ||||
-rwxr-xr-x | doc/tools/texi2www/texi2www | 1202 | ||||
-rw-r--r-- | doc/tools/texi2www/texi2wwwdoc.texi | 707 |
4 files changed, 2122 insertions, 0 deletions
diff --git a/doc/tools/texi2www/archive/texi2www-960103.tgz b/doc/tools/texi2www/archive/texi2www-960103.tgz Binary files differnew file mode 100644 index 0000000000..b0851552c2 --- /dev/null +++ b/doc/tools/texi2www/archive/texi2www-960103.tgz diff --git a/doc/tools/texi2www/texi2dvi b/doc/tools/texi2www/texi2dvi new file mode 100644 index 0000000000..2feff4ba51 --- /dev/null +++ b/doc/tools/texi2www/texi2dvi @@ -0,0 +1,213 @@ +#!/usr/local/bin/perl + +$version = <<END_VERSION; +Jan 2 1996 +END_VERSION + +$copyright = <<END_COPYRIGHT; +texi2dvi - converts texinfo to dvi +Copyright (C) 1996 Tim Singletary + +This program is freely distributable under the terms of the GNU +GENERAL PUBLIC LICENSE. In particular, modified versions of this +program must retain this copyright notice and must remain freely +distributable. +END_COPYRIGHT + +$usage = <<END_USAGE; +Usage: texi2dvi [option ...] texinfo_file ... + -k (-nocleanup) -- don't ``rm -f'' the intermediate files. + -v (-verbose) -- print additional output. + -copyright -- print the copyright and die. + -version -- print the version and die. +Generates a .dvi file from each texinfo (.texi or .texinfo) file. +Understands texi2www extensions (\@gif, etc.). +END_USAGE + +unless ($tex = $ENV{TEX}) {$tex = tex;} +unless ($texindex = $ENV{TEXINDEX}) {$texindex = texindex;} +$texinputs = $ENV{TEXINPUTS}; + +$cleanup = 1; +while ($ARGV[0] =~ /^-/) { + $_ = shift; + if (/-k$/ || /-nocleanup/) {$cleanup = 0; next;} + if (/-v$/ || /-verbose/) {$verbose = 1; next;} + if (/-d$/ || /-vv$/ || /-debug/) {$verbose = 2; next;} + if (/-copyright/) {die $copyright;} + if (/-version/) {die $version;} + die $usage; +} + +$font_prefix = "xx"; +while (&prefix_in_use($font_prefix)) { + ++$font_prefix; + if (length($font_prefix) > 2) { + $font_prefix = "aa"; + } +} + +$unique_base = "_" . $$ . "a-"; +while (&prefix_in_use($unique_base)) {++$unique_base;} + +print "Generated files will begin with \`$unique_base\'\n" if $verbose; + +$arg_index = 'a'; +foreach $raw_texi (@ARGV) { + $base = $unique_base . $arg_index; + ++$arg_index; + + # $tawtexifile is a texinfo file; suffix must be either `.texi' or + # `.texinfo'. If arg is in a different directory, adjust + # TEXINPUTS environment variable to include that (and the current) + # directory. + unless ($raw_texi =~ /(.*).texi(nfo)?$/) { + print "skipping $raw_texi -- has unknown extension!\n"; + next; + } + $raw_texi_base = $1; + if ($raw_texi_base =~ m|^(.*)/([^/]*)$|) { + $raw_texi_base = $2; + $ENV{TEXINPUTS} = ".:$1:$texinputs"; + } else { + $ENV{TEXINPUTS} = ".:$texinputs"; + } + + unless (-r $raw_texi) { + print "skipping $raw_texi -- not readable or doesn't exist!\n"; + next; + } + + # Preprocesses the $rawtexifile (because of @gif{} and other extensions) + $processed_texi = "$base.texi"; + print "Preprocessing $raw_texi into $processed_texi:\n" if $verbose; + &preprocess_texinfo($raw_texi,$processed_texi,$base); + + print "$tex $processed_texi\n" if $verbose; + if (system("$tex $processed_texi") == 0) { + + # @possible_index_file = <$base.??>; only works for the + # first value of $base ... so, + opendir(DIR,".") || die "Couldn't read current directory -- $!\n"; + @possible_index_files = (); + while ($_ = readdir(DIR)) { + push(@possible_index_files,$_) if (/^$base\...$/); + } + closedir(DIR); + + @index_files = (); + foreach $possible_index_file (@possible_index_files) { + print "DEBUG: possible_index_file $possible_index_file\n" + if ($verbose > 1); + next unless (-s $possible_index_file); + push(@index_files,$possible_index_file); + } + + if (@index_files > 0) { + $texindex_cmd = "$texindex " . join(' ',@index_files); + print "$texindex_cmd\n" if $verbose; + if (system($texindex_cmd) == 0) { + print "$tex $processed_texi\n" if $verbose; + system("$tex $processed_texi"); + } + } + } + + # At this point, $base.dvi should exist -- rename it + # to $raw_texi_base.dvi + if (-e "$base.dvi") { + rename("$base.dvi","$raw_texi_base.dvi") + || die "rename $base.dvi $raw_texi_base.dvi -- $!\n"; + } +} +if ($cleanup) {unlink(<$base*>);} + +sub preprocess_texinfo +{ + local ($infile,$outfile,$b) = @_; + + open(IN,"<$infile") || die "Couldn't open $infile -- $!\n"; + open(OUT,">$outfile") || die "Couldn't open $outfile -- $!\n"; + + $gif_index = 'a'; + while (<IN>) { + + # @gif{gif} or @gif{html_gif, tex_gif} + if (/(.*)\@gif\{([^{]*)\}(.*)/) { + $prefix = $1; + $arg = $2; + $suffix = $3; + print OUT "$prefix\n" if $prefix; + + while (1) { + $gif_base = $b . $gif_index; + last unless (-e $gif_base . ".gif"); + ++$gif_index; + } + + $gif_file = ''; + if ($arg =~ /.*,(..*\.gif)/) { + $gif_file = $1; + $font_base = $gif_file; + } else { + $font_base = $arg; + $gif_file = $gif_base . ".gif"; + print "Scaling $arg into $gif_file:\n" if $verbose; + $scale_cmd = "giftopnm $arg | pnmscale 2 | pnmnlfilt 2 1 " + . "| ppmquant 255 | ppmtogif > $gif_file"; + print "$scale_cmd\n" if $verbose; + if (system($scale_cmd) != 0) { + print "$scale_cmd failed\n"; + $gif_file = ''; + } + } + + if ($gif_file =~ /.*\.gif/) { + + + $font_base =~ s|.*/||; + $font_base =~ s|\..*||; + + # $font_base, due to bm2font requirements, can't be more + # than six characters long and must consist entirely of + # lower case letters. + $font_base =~ s/[^a-z]//g; + $font_base = $font_prefix . substr($font_base,0,5); + while (&prefix_in_use($font_base)) {++$font_base;} + + $bm2font_cmd = "bm2font -f$font_base $gif_file"; + print "$bm2font_cmd\n" if $verbose; + if (system($bm2font_cmd) != 0) { + print "$bm2font_cmd failed\n"; + } else { + print OUT "\@tex\n"; + print OUT "\\input $font_base.tex\n"; + print OUT "\\set$font_base\n"; + print OUT "\@end tex\n"; + } + } + + print OUT "$suffix \n" if $suffix; + } else { + print OUT "$_"; + } + } + close OUT; + close IN; +} + +sub prefix_in_use +{ + local ($p) = @_; + + # Returns true or false; returns true if any file in the current + # directory begins with $p. This function is here because + # `<$p*>' only works for the first value of $p! + + opendir(DIR,".") || die "Couldn't read current directory -- $!\n"; + while ($_ = readdir(DIR)) { + last if /^$p/; + } + closedir(DIR); + $rc = /^$p/; +} diff --git a/doc/tools/texi2www/texi2www b/doc/tools/texi2www/texi2www new file mode 100755 index 0000000000..247eccfd68 --- /dev/null +++ b/doc/tools/texi2www/texi2www @@ -0,0 +1,1202 @@ +#!/usr/local/bin/perl +# (Works with both perl 4 and perl 5) +$version = 'Jan 2 1996'; +$copyright = <<EOT; +texi2www - converts texinfo to HTML +Copyright (C) 1994, 1995, 1996 Tim Singletary + +This program is freely distributable under the terms of the GNU +GENERAL PUBLIC LICENSE. In particular, modified versions of this +program must retain this copyright notice and must remain freely +distributable. + +EOT +$usage = <<EOT; +Usage: texi2www [option ...] texinfo_file +where options are: + -dir directory -- Specify output directory. Default is `.'. + -footer path -- Specifies the path to a file containing HTML; + this files gets inserted near the bottom of each + generated HTML file. + -icons path -- Specifies the path, relative to the output directory, + to the arrow files. Default is `..'. + -verbose -- Verbose output. + +The complete user\'s is available at +http://sunland.gsfc.nasa.gov/info/texi2www/Top.html +EOT + +######################################################################## + +$icons = ".."; $dir = "."; +while ($ARGV[0] =~ /^-/) { + $_ = shift; + if (/-dir/) {$_ = shift; s!/$!!; s!$!/!; $dir = $_; next;} + if (/-verbose/) {$verbose = 1; next;} + if (/-footer/) {$footer = shift; next;} + if (/-icons/) {$_ = shift; s!\/$!!; $icons = $_; next;} + die $usage; +} + +&initialize_tables(); + +# +# Read the texinfo input into @texinfo +# +&open_input_file($ARGV[0]); +&read_input(1,'/^\@bye/',"$texinfo_file[0] line 1"); +$texinfo[$ntexinfo] = "\@bye\n"; +$origin[$ntexinfo] = "$texinfo_file[0] line $."; + +# +# Parse @texinfo +# +$texinfo_index = 0; +while ($texinfo_index < @texinfo) { + &get_more_stuff_to_parse(); + if (/^\@bye/) { + &terminate_node(); + print "Normal completion\n"; + exit; + } + &parse(); +} + +print "Huh? didn't parse the \@bye directive!\n"; + +######################################################################## +sub canonical # (node_name) +{ + local ($n) = @_; + + $n =~ s/^\s+//; $n =~ s/\s+$//; # strip whitespace + + return "../dir.html" if ($n =~ /\(dir\)/i); # handle (dir) + + if ($n =~ /^\(([^\)]+)\)(.*)/) { + $p = $1; $p =~ s/^\s+//; $p =~ s/\s+$//; $p .= "/"; + $n = $2; $n =~ s/^\s+//; $n =~ s/\s+$//; + } else { + $p = ""; + } + + + $n =~ s/\$/\$\$/; # `$' -> `$$' + $n =~ s/_/\$_/g; # `_' -> `$_' + $n =~ s/\s+/_/g; # whitespace -> `_' + + # anything else that's funky get + # translated to `$xx' where `xx' + # are hex digits. + while ($n =~ /(.*)([^-a-zA-Z0-9\$_.])(.*)/) { + $n = $1 . sprintf("\$%02x",ord($2)) . $3; + } + + return "$p$n.html" if ($n); + return ""; +} # canonical + +######################################################################## +sub deduce_node_links +# +# On entry, $_ is a node line and $start_index is the index (in @texinfo) +# the node line. +# +# &deduce_node_links() sets $next, $prev, and $up. +{ + local ($level,$i,$node,$j); + + # First, search down from this node to the next sectioning command. + $level = &determine_node_level($start_index+1); + + # Next, look for the `next' node (i.e., the next node at the + # same or a higher level). + undef($next); + for ($i=$start_index+1; $i < $ntexinfo; ++$i) { + $_ = $texinfo[$i]; + next unless /^\@node +([^,]+).*\n/; + $j = &determine_node_level($i+1); + if ($j <= $level) { + if ($j == $level) {$next = $1;} + last; + } + } + + # Look for the `prev' and `up' nodes + undef($prev); + undef($up); + for ($i=$start_index-1; $i > 1; --$i) { + $_ = $texinfo[$i]; + next unless /^\@node\s+([^,]+).*\n/; + $j = &determine_node_level($i+1); + if ($j == $level) { + unless ($prev) {$prev = $1;} + } elsif ($j < $level) { + $up = $1; + last; + } + } + unless (defined($up)) {$up = "(dir)";} + + $xthis = $this; + $xthis =~ s/\n//; + +} # deduce_node_links + +######################################################################## +sub determine_node_level +{ + local ($i) = @_; + local ($level); + + $level = 0; + while ($i < $ntexinfo) { + $_ = $texinfo[$i]; + ++$i; + next if /^\s+$/; + last if (/\@node/); + last unless (/\@(\w+)/); + if ($directive_section{$1}) { + $level = $directive_section{$1}; + last; + } + } + + return $level; +} # determine_node_level + + +######################################################################## +sub expand_xref +{ + local ($cmd,$arg) = @_; + local ($node,$xrefname,$topic,$infofile,$manual,$url,$x); + + if ($cmd eq 'inforef') { + ($node,$xrefname,$infofile) = split(/,/,$arg); + $topic = $manual = ''; + } elsif ($cmd eq 'href') { + ($xrefname,$node,$infofile,$url) = split(/,/,$arg); + } else { + ($node,$xrefname,$topic,$infofile,$manual) = split(/,/,$arg); + } + $xrefname =~ s/^\s+//; $infofile =~ s/^\s+//; + $xrefname =~ s/\s+$//; $infofile =~ s/\s+$//; + $xrefname =~ s/\s+/ /; $infofile =~ s/\s+/ /; + $infofile =~ s/\.texi$//; + $infofile =~ s/\.texinfo$//; + + if ($xrefname =~ /^$/) {$xrefname = $node;} + + $node = &canonical($node); + unless ($url) { + unless ($infofile =~ /^$/) {$url = "../$infofile/";} + $url = $url . $node; + } + $x = "<A HREF=\"$url\">$xrefname</A>"; +} # expand_xref + +######################################################################## +sub get_more_stuff_to_parse +{ + $start_index = $texinfo_index; + + $_ = ''; + do { + if ($texinfo_index >= @texinfo) { + print "Unclosed \@x{y} in chunk beginning at " + . "$origin[$start_index]\n"; + return; + } + s/\n$/ /; + $more = $texinfo[$texinfo_index++]; + $more =~ s/\@\*/<BR>\n/g; + $more =~ s/\@\./\./g; + $more =~ s/\@\://g; + $more =~ s/\@refill//g; + + $_ .= $more; + + # Expand all @a{b} in line + while (/\@(\w+)\{([^{}]*)\}/) { + $atcmd = $1; + $atarg = $2; + + if ($z = $atxy_2_zyz{$atcmd}) { + if ($z =~ /(.+),(.+),(.+)/) { + $left = $1; $z = $2; $right = $3; + } else { + $left = ''; $right = ''; + } + if ($z =~ s/^\^//) {$atarg =~ tr/a-z/A-Z/;} + $x = "$left<$z>$atarg</$z>$right"; + } elsif ($atxy_2_y{$atcmd}) { + $x = $atarg; + } elsif ($z = $atxy_2_z{$atcmd}) { + $x = $z; + } elsif ($z = $atxy_2_ref{$atcmd}) { + $x = $z . &expand_xref($atcmd,$atarg); + $x =~ s/^X//; # works because $z must start with 'X'! + } elsif ($atcmd eq 'value') { + $x = $texinfo_variable{$atarg}; + } elsif ($atcmd eq 'today') { + $x = &today(); + } elsif ($atcmd eq 'footnote') { + $footnote[$nfootnotes++] = $atarg; + $x = "\[$nfootnotes\]"; + } elsif ($atcmd eq 'gif') { + $atarg =~ s/,.*//; + ©_to_destdir($atarg); + $atarg =~ s|.*/||; + $x = "<IMG SRC=\"$atarg\">"; + } else { + print "**WARNING** Don't know how to expand " + . "\@$atcmd\{$atarg\}\n"; + $debug = 1; + $x = "?$atcmd\?$atarg\?"; + } + + print "$origin[$start_index]: \@$atcmd\{$atarg\} => $x\n" + if $debug{expansions}; + + s/\@\w+\{[^{}]*\}/$x/; + } + } while (/\@\w+\{[^}]*$/); + print "$origin[$start_index]: $_" if $debug{chunks}; +} # get_more_stuff_to_parse + +######################################################################## +sub parse +# On entry: +# $_ -- the line(s) to parse. +# $start_index -- where, in $texinfo, $_ begins. +{ + local ($x); + + if (/^\@(\w+)/) { + if ($x=$directive_block{$1}) { # @example, @quotation, etc. + &parse_block($1,$x); + } elsif ($directive_section{$1}) { # @chapter, @subsection, etc. + &process_section(); + } elsif ($1 eq 'bye') { + if ($nfootnotes > 0) { + &printHTML("<P><HR>\n"); + for ($n=0; $n < $nfootnotes; ++$n) { + &printHTML("<P>\[" . ($n+1) . "\] $footnote[$n]</P>\n"); + } + } + &print_footer if $footer; + &printHTML("</BODY></HTML>\n"); + close (HTML); + return; + } elsif ($1 eq 'center') { + /^\@center\s+(.*)/; + &printHTML("$paragraph_end") if $in_paragraph; + &printHTML("<P ALIGN=CENTER>$1</P>\n"); + $in_paragraph = 0; + } elsif ($1 eq 'clear') { + /^\@clear\s+(\S+)/; + undef($texinfo_variable{$1}); + } elsif ($1 =~ /^def(code)?index/) { + /^\@(def|defcode)index\s+(\w+)/; + $index_name{$2} = $2 . "index"; + $index_style{$2} = 'CODE' if ($1 eq "defcode"); + } elsif ($1 =~ /^(def.*)/) { # @defn, @defun, ... @deftp + &parse_def($1); + } elsif ($1 eq 'enumerate') { + &parse_enumerate(); + } elsif ($1 eq 'exdent') { + /^\@exdent\s+(.*)/; + &printHTML("$paragraph_end") if $in_paragraph; + # A bug -- doesn't exdent the line! + &printHTML("<P>$1</P>\n"); + $in_paragraph = 0; + } elsif ($1 eq 'flushleft' || $1 eq 'flushright') { + &parse_flush(); + } elsif ($1 eq 'html') { + while ($texinfo_index < @texinfo) { + &get_more_stuff_to_parse(); + last if (/^\@end\s+html/); + s/\"/\"/g; s/\>/\>/g; s/\</\</g; s/\&/\&/g; + &printHTML("$_"); + } + } elsif ($1 eq 'itemize') { + &parse_itemize(); + } elsif ($1 eq 'menu') { + &parse_menu(); + } elsif ($1 eq 'node') { + &process_node(); + } elsif ($1 eq 'printindex') { + /^\@printindex\s+([a-z]+)/; + &print_index($1); + } elsif ($1 eq 'settitle') { + /^\@settitle\s+(.*)/; + unless ($title) {$title = $1;} + } elsif ($1 eq 'set') { + if (/^\@set\s+(\S+)\s+(.+)$/) { + $texinfo_variable{$1} = $2; + } else { + /^\@set\s+(\S+)/; + $texinfo_variable{$1} = 1; + } + } elsif ($1 eq 'syncodeindex') { + &process_synindex(1); + } elsif ($1 eq 'synindex') { + &process_synindex(0); + } elsif ($1 =~ /^.?table/) { # @table, @vtable, @ftable + unless (/^\@(.?table)\s*\@(\w*)/ + && ($2 eq 'asis' || ($tbltype=$atxy_2_zyz{$2}))) { + print "**WARNING** $origin[$start_index]: assuming " + . "\@table \@asis\n"; + $tbltype = ''; + } + &parse_table($1,$tbltype); + } elsif ($1 =~ /..?index/) { # @cindex, @findex, .. @auindex, etc. + &process_index(); + } else { + print "**WARNING** $origin[$start_index]: ignoring $_"; + } + } else { + if (/^\s*$/) { + if ($in_paragraph) { + &printHTML("$paragraph_end"); + } elsif ($in_preformatted) { + &printHTML("\n"); + } + $in_paragraph = 0; + } else { + unless ($in_preformatted) { + unless ($in_paragraph) { + &printHTML("<P>\n"); + $in_paragraph = 1; + $paragraph_end = "</P>\n"; + } + } + &printHTML("$_"); + } + } +} # parse + +######################################################################## +sub parse_block +# +# Handles @example, @display, etc. +# +# > @example > <PRE> +# > a + b = c ==> > a + b = c +# > @end example > </PRE> +{ + local ($block,$pre) = @_; + local ($started_at); + + $started_at = $start_index; + + &printHTML("$paragraph_end") if $in_paragraph; + $in_paragraph = 0; + + if ($pre eq '>PRE') { + &printHTML("<DL><DT><DD>\n<PRE>\n"); + } else { + &printHTML("<$pre>\n") unless ($pre eq '-'); + } + $in_preformatted = $block; + while ($texinfo_index < @texinfo) { + &get_more_stuff_to_parse(); + if (/^\@end\s+$block/) { + if ($pre eq 'HR') { + &printHTML("</HR>\n"); + } elsif ($pre eq '>PRE') { + &printHTML("</PRE>\n</DL>\n"); + } else { + &printHTML("</$pre>\n") unless ($pre eq '-'); + } + $in_preformatted = 0; + return; + } + &parse(); + } + print "**ERROR** reached EOF while searching for end of the \@$block " + . "block that started on $origin[$started_at]\n"; +} # parse_block + +######################################################################## +sub parse_def +# $_ contains a @def* command +{ + local ($def) = @_; + local ($started_at,$in_dd); + + $started_at = $start_index; + + &printHTML("$paragraph_end") if $in_paragraph; + $in_paragraph = 0; + + &printHTML("<DL>\n"); + + &printdef(); + + while ($texinfo_index < @texinfo) { + &get_more_stuff_to_parse(); + if (/^\@end\s+$def/) { + &printHTML("</DL>\n"); + $in_paragraph = 0; + return; + } + if (s/^(\@def\w+)x\s/$1 /) {&printdef();} + else { + unless ($in_dd) { + &printHTML("<DD>\n"); + ++$in_dd; + $in_paragraph = 1; + $paragraph_end = "\n"; + } + &parse(); + } + } + print "**ERROR** reached EOF while searching for end of the $def " + . "definition that started on $origin[$started_at]\n"; + +} # parse_def +sub printdef +{ + + s/\@defun(x?)\s/\@deffn Function / + || s/\@defmac(x?)\s/\@deffn Macro / + || s/\@defspec(x?)\s/\@deffn \{Special Form\} / + || s/\@defvar(x?)\s/\@defvr Variable / + || s/\@defopt(x?)\s/\@defvr \{User Option\} / + || s/\@deftypefun(x?)\s/\@deftypefn Function / + || s/\@deftypevar(x?)\s/\@deftypefn Variable / + || s/\@defivar(x?)\s/\@defcv \{Instance Variable\} / + || s/\@defmethod(x?)\s/\@defop Method /; + s/(\@\w+)x\s/$1 /; + + @words = split; + + $i = 1; + $category = $words[$i++]; + while ($i < @words && $category =~ /^\{[^}]*$/) { + $category .= ' ' . $words[$i++]; + } + if ($i>=@words) { + print "def error at $origin{$started_at}\n"; + } + $category =~ s/^\{//; + $category =~ s/\}$//; + + &printHTML("<DT>$category: "); + + if ($words[0] eq '@deftypefn' || $words[0] eq '@deftypevr' + || $words[0] eq '@defcv' || $words[0] eq '@defop') { + if ($words[$i] =~ s/^\{//) { + &printHTML("<VAR>"); + until ($words[$i] =~ s/\}$//) {&printHTML("$words[$i++]");} + &printHTML("$words[$i++]</VAR> "); + } else { + &printHTML("<VAR>$words[$i++]</VAR> "); + } + $words[0] =~ /.*([a-z][a-z])/; + $_ = "\@" . $1 . "index " . $words[$i]; + &process_index; + } + &printHTML("<STRONG>$words[$i++]</STRONG>\n<VAR>"); + + while ($i < @words) {&printHTML(" $words[$i++]");} + &printHTML("</VAR>\n"); + +} # printdef + +######################################################################## +sub parse_enumerate +# $_ is `@enumerate'. Note that @enumerate with an arg (`@enumerate 3', +# for example) is kinda funky due to HTML limitations. +{ + local ($count,$started_at); + + $started_at = $start_index; + + &printHTML("$paragraph_end") if $in_paragraph; + $in_paragraph = 0; + + if (/^\@enumerate\s*(\S+)/) {$count = $1;} + + &printHTML("<" . ($count ? "UL" : "OL") . ">\n"); + + while ($texinfo_index < @texinfo) { + &get_more_stuff_to_parse(); + if (/^\@end\s+enumerate/) { + &printHTML("</" . ($count ? "UL" : "OL") . ">\n"); + return; + } + if (/^\@item\s+(.*)/ || /^\@item()$/) { + if ($count) { + &printHTML("<LI>$count: $1\n"); + ++$count; + } else { + &printHTML("<LI>$1\n"); + } + $in_paragraph = 1; + $paragraph_end = "\n"; + } else { + &parse(); + } + } + print "**ERROR** reached EOF while searching for end of the \@enumerate " + . "that started on $origin[$started_at]\n"; +} # parse_enumerate + +######################################################################## +sub parse_flush +{ + local ($started_at,$flush); + + /^\@(\w+)\s/; + $flush = $1; + $started_at = $start_index; + + &printHTML("$paragraph_end") if $in_paragraph; + $in_paragraph = 0; + + while ($texinfo_index < @texinfo) { + &get_more_stuff_to_parse(); + if (/^\@end\s+$flush/) { + return; + } + &parse(); + } + print "**ERROR** reached EOF while searching for end of the $flush " + . "that started on $origin[$started_at]\n"; + + +} # parse_flush + +######################################################################## +sub parse_itemize +# $_ is `@itemize'. Due to HTML limitation, `@itemize @bullet' comes +# out the same as `@itemize @minus'. +{ + local ($started_at); + + $started_at = $start_index; + + &printHTML("$paragraph_end") if $in_paragraph; + $in_paragraph = 0; + + &printHTML("<UL>\n"); + + + while ($texinfo_index < @texinfo) { + &get_more_stuff_to_parse(); + if (/^\@end\s+itemize/) { + &printHTML("</UL>\n"); + return; + } + if (/^\@item\s+(.*)/ || /^\@item()$/) { + &printHTML("<LI>$1\n"); + $in_paragraph = 1; + $paragraph_end = "\n"; + } else { + &parse(); + } + } + print "**ERROR** reached EOF while searching for end of the itemize " + . "that started on $origin[$started_at]\n"; +} # parse_itemize + +######################################################################## +sub parse_menu +{ + local ($started_at); + + $started_at = $start_index; + + &printHTML("$paragraph_end") if $in_paragraph; + $in_paragraph = 0; + + &printHTML("<MENU>\n"); + + while ($texinfo_index < @texinfo) { + &get_more_stuff_to_parse(); + if (/^\@end\s+menu/) { + &printHTML("</MENU>\n"); + return; + } + + # Like ` * menu-item:: description of item' + if (/^\s*\*\s*([^:]*)\s*::\s*(.*)$/) { + &printHTML("$paragraph_end") if $in_paragraph; + $in_paragraph = 0; + $node = &canonical($1); + &printHTML("<LI><A HREF=\"$node\">$1</A>\n"); + &printHTML("$2\n") if $2; + # Like ` * menu-item: cross-reference. description of item' + } elsif (/^\s*\*\s*([^:]*)\s*:([^.]*)\.\s*(.*)$/) { + &printHTML("$paragraph_end") if $in_paragraph; + $in_paragraph = 0; + $node = &canonical($2); + &printHTML("<LI><A HREF=\"$node\">$1</A>\n"); + &printHTML("$3\n"); + } elsif (/^\@/) { + print "**WARNING** Don\'t know how to process \`$_\' inside " + . "a menu!\n"; + } else { + if (/^\s*$/ && !$in_paragraph) { + &printHTML("<P>"); + $in_paragraph = "1"; + $paragraph_end = "</P>\n"; + } + &printHTML("$_"); + } + } + print "**ERROR** reached EOF while searching for end of the menu " + . "that started on $origin[$started_at]\n"; +} # parse_menu + +######################################################################## +sub parse_table +# $_ is `@itemize'. Due to HTML limitation, `@itemize @bullet' comes +# out the same as `@itemize @minus'. +{ + local ($table,$ttype,$after_DT,$started_at,$first_para); + ($table,$ttype) = @_; + + $started_at = $start_index; + + &printHTML("$paragraph_end") if $in_paragraph; + $in_paragraph = 0; + + &printHTML("<DL>\n"); + + while ($texinfo_index < @texinfo) { + &get_more_stuff_to_parse(); + if (/^\@end\s+$table/) { + &printHTML("</DL>\n"); + return; + } + if (/^\@item(x?)\s+(.*)/ || /^\@item(x?)()$/) { + $atarg = $2; + if ($ttype) { + if ($ttype =~ /(.+),(.+),(.+)/) { + $left = $1; $z = $2; $right = $3; + } else { + $left = ''; $z = $ttype; $right = ''; + } + if ($z =~ s/^\^//) {$atarg =~ tr/a-z/A-Z/;} + &printHTML("<DT>$left<$z>$atarg</$z>$right\n"); + } else { + &printHTML("<DT>$2\n"); + } + $item = $2; + if ($item && $table =~ /([fv])table/) { + $_ = "\@" . $1 . "index " . $item; + &process_index; + } + $after_DT = 1; + } else { + if ($after_DT) { + &printHTML("<DD>\n"); + $in_paragraph = 1; + $paragraph_end = "\n"; + $after_DT = 0; + $first_para = 1; + } + unless ($first_para && /^\s*$/) { + $first_para = 0; + &parse(); + } + } + } + print "**ERROR** reached EOF while searching for end of the table " + . "that started on $origin[$started_at]\n"; +} # parse_table + +######################################################################## +sub print_index +{ + local ($index) = @_; + $index = $index_name{$index}; + + eval "\@keys = keys \%$index"; + + &printHTML("<MENU>\n"); + foreach $item (sort texinfo_sort @keys) { + eval "\$val = \$$index\{\$item\}"; + &printHTML("<LI>$val\n"); + } + &printHTML("</MENU>\n"); +} # print_index + +sub texinfo_sort +{ + $x = $a; $x =~ s/<[^>]*>//g; $x =~ tr/A-Z/a-z/; + $y = $b; $y =~ s/<[^>]*>//g; $y =~ tr/A-Z/a-z/; + $x cmp $y; +} # texinfo_sort + +######################################################################## +sub process_index +# +# For example, `@cindex whatever' generates an entry in %cpindex +# +{ + s/\@cindex/\@cpindex/ || s/\@findex/\@fnindex/ + || s/\@vindex/\@vrindex/ || s/\@kindex/\@kyindex/ + || s/\@pindex/\@pgindex/ || s/\@tindex/\@tpindex/; + + /\@(..)index\s+(.*)/; + + if ($x=$index_style{$1}) { + $entry = "<A HREF=\"$cthis\"><$x>$2</$x></A>"; + } else { + $entry = "<A HREF=\"$cthis\">$2</A>"; + } + + print "*** \$$index_name{$1}\{$2\} = $entry\n" if $debug{'index'}; + eval "\$$index_name{$1}\{\$2\} = \$entry"; +} # process_index + +######################################################################## +sub process_node +# On entry, $_ is an @node line. +{ + s/^\@node\s+//; + ($this,$next,$prev,$up) = split(/,/); + + &deduce_node_links() unless ($next || $prev || $up); + + $cthis = &canonical($this); + $cnext = &canonical($next); + $cprev = &canonical($prev); + $cup = &canonical($up); + + &terminate_node(); + + print "... opening $dir$cthis ...\n" if $debug{nodes}; + open(HTML,">$dir/$cthis") || die "Couldn't open $dir$cthis -- $!\n"; + + $nfootnotes = 0; + + &printHTML("<HTML>\n"); + &printHTML("<!-- created $today from " . + $origin[$start_index] . " via texi2www -->\n"); + &printHTML("<HEAD>\n<TITLE>$this</TITLE>\n"); + &printHTML("<LINK REL=\"Precedes\" HREF=\"$cnext\">\n") if $next; + &printHTML("<LINK REV=\"Precedes\" HREF=\"$cprev\">\n") if $prev; + &printHTML("<LINK REV=\"Subdocument\" HREF=\"$cup\">\n") if $up; + &printHTML("</HEAD><BODY><P>\n"); + if ($cprev) { + &printHTML("<A HREF=\"$cprev\"><IMG ALIGN=MIDDLE " + . "SRC=\"$icons/prev-arrow.gif\" ALT=\"PREV\"></A>\n"); + } else { + &printHTML("<A><IMG ALIGN=MIDDLE " + . "SRC=\"$icons/missing-arrow.gif\" ALT=\"prev\"></A>\n"); + } + if ($cup) { + &printHTML("<A HREF=\"$cup\"> <IMG ALIGN=MIDDLE " + . "SRC=\"$icons/up-arrow.gif\" ALT=\"UP\"></A>\n"); + } else { + &printHTML("<A><IMG ALIGN=MIDDLE " + . "SRC=\"$icons/missing-arrow.gif\" ALT=\"up\"></A>\n"); + } + if ($cnext) { + &printHTML("<A HREF=\"$cnext\"><IMG ALIGN=MIDDLE " + . "SRC=\"$icons/next-arrow.gif\" ALT=\"NEXT\"></A>\n"); + } else { + &printHTML("<A><IMG ALIGN=MIDDLE " + . "SRC=\"$icons/missing-arrow.gif\" ALT=\"next\"></A>\n"); + } + &printHTML("<CITE>$title</CITE>") if $title; + &printHTML("</P>\n"); + +} # process_node +sub terminate_node +{ + if ($nfootnotes) { + &printHTML("<P><HR>\n"); + for ($n=0; $n < $nfootnotes; ++$n) { + &printHTML("<P>\[" . ($n+1) . "\] $footnote[$n]</P>\n"); + } + } + &print_footer if $footer; + &printHTML("</BODY></HTML>\n"); + close (HTML); +} + +######################################################################## +sub process_section +# +# On entry: +# $_ is the section command (I.e. `@chapter Overview') +# $i is the index to $_ in @lines +{ + &printHTML("$paragraph_end") if $in_paragraph; + $in_paragraph = 0; + + /^\@(\w+)\s+(.*)/; + + $section_number = ''; + if ($1 eq 'chapter') { + ++$chapter; $section=$subsection=$subsubsection=0; + $section_number = "Chapter $chapter: "; + } elsif ($1 eq 'section') { + ++$section; $subsection=$subsubsection=0; + $section_number = "$chapter.$section: "; + } elsif ($1 eq 'subsection') { + ++$subsection; $subsubsection=0; + $section_number = "$chapter.$section.$subsection: "; + } elsif ($1 eq 'subsubsection') { + ++$subsubsection; + $section_number = "$chapter.$section.$subsection.$subsubsection: "; + } elsif ($1 eq 'appendix') { + ++$appendix; $section=$subsection=$subsubsection=0; + $x = ('A'..'Z')[$appendix-1]; + $section_number = "Appendix $x: "; + } elsif ($1 eq 'appendixsec') { + ++$section; $subsection=$subsubsection=0; + $x = ('A'..'Z')[$appendix-1]; + $section_number = "$x.$section: "; + } elsif ($1 eq 'appendixsubsec') { + ++$subsection; $subsubsection=0; + $x = ('A'..'Z')[$appendix-1]; + $section_number = "$x.$section.$subsection: "; + } elsif ($1 eq 'appendixsubsubsec') { + ++$subsubsection; + $x = ('A'..'Z')[$appendix-1]; + $section_number = "$x.$section.$subsection.$subsubsection: "; + } + + $x = $directive_section{$1}; + &printHTML("<H$x>$section_number$2</H$x>\n"); +} # process_section + +######################################################################## +sub process_synindex +# +# There's perhaps a bug here -- this presumes the @synindex comes before +# any @?index directives; anything already in <from> doesn't get merged +# into <to>! +# +{ + local ($code) = @_; # Either 0 or 1; 1 means @syncodeindex + + /\@syn\w*index\s+(\w+)\s+(\w+)/; + + print "*** synindex $1 $2\n" if $debug{'index'}; + + $index_name{$1} = $2 . "index"; + $index_style{$1} = 'CODE' if $code; +} # process_synindex + +######################################################################## +sub printHTML +{ + local ($line) = @_; + $line =~ s/\$R/\}/g; + $line =~ s/\$L/\{/g; + $line =~ s/\$A/\@/g; + $line =~ s/\$D/\$/g; + if ($debug{printHTML}) { + print $line; + } else { + print HTML $line; + } +} # printHTML + +######################################################################## +sub print_footer +{ + unless (open(FOOTER,$footer)) { + print "WARNING -- couldn't open footer file \"$footer\" -- $!\n"; + $footer = 0; + return; + } + while (<FOOTER>) { + &printHTML($_); + } + close(FOOTER); +} + +######################################################################## +sub read_input +# +# Read the texinfo source into @texinfo. Don't copy comments or the +# `@ifxxx' and `@end ifxxx' surrounding [or the contents of] conditional +# blocks. Read `@include' files. +{ + local ($echo,$terminator_re,$started_at) = @_; + + while (&texinfo_read()) { + + next if (/^\@c$/ || /^\@c\s/ || /^\@comment/); + + if (/^\@ifinfo/) { + &read_input($echo,'/^\@end\s+ifinfo/', + "$texinfo_file[0] line $."); + next; + } + if (/^\@ifhtml/) { + &read_input($echo,'/^\@end\s+ifhtml/', + "$texinfo_file[0] line $."); + next; + } + if (/^\@iftex/) { + &read_input(0,'/^\@end\s+iftex/', + "$texinfo_file[0] line $."); + next; + } + if (/^\@tex/) { + &read_input(0,'/^\@end\s+tex/', + "$texinfo_file[0] line $."); + next; + } + if (/^\@ignore/) { + # @ignore doesn't nest + $ignore_from = "$texinfo_file[0] line $."; + while (&texinfo_read()) { + last if (/^\@end\s+ignore/); + } + unless (/^\@end\s+ignore/) { + print "Unexpected EOF while searching from $ignore_from " + . "for \'\@end ignore\'\n"; + } + next; + } + if (/^\@titlepage/) { + &read_input(0,'/^\@end\s+titlepage/',"$texinfo_file[0] line $."); + next; + } + + if (/^\@ifclear\s+(\S+)/) { + &read_input($echo&&(!defined($set{$1})),'/^\@end\s+ifclear/', + "$texinfo_file[0] line $."); + next; + } + if (/^\@ifset\s+(\S+)/) { + &read_input($echo&&defined($set{$1}),'/^\@end\s+ifset/', + "$texinfo_file[0] line $."); + next; + } + + return if eval "$terminator_re"; + + if (/^\@include\s+(\S+)/) { + &open_input_file($1); + next; + } + + if (/^\@(set|clear)\s+(\S+)/) { + if ($1 eq "set") { + $set{$2} = 1; + } else { + undef($set{$2}); + } + } + + next unless $echo; + + if (/^\@(\w+)/) {next if $ignore_these_directives{$1};} + + # Hide @@, @{, and @} so later on it'll be easier to process + # stuff like `@code{@@TeX@{@}}'. + s/\$/\$D/g; s/\@\@/\$A/g; s/\@{/\$L/g; s/\@}/\$R/g; + + # Convert the HTML special characters + s/\&/\&/g; s/\</\</g; s/\>/\>/g; s/\"/\"/g; + + $texinfo[$ntexinfo] = $_; + $origin[$ntexinfo] = "$texinfo_file[0] line $."; + ++$ntexinfo; + } + + print "Unexpected EOF while searching from $started_at " + . "for $terminator_re\n"; +} # read_input + +######################################################################## +sub initialize_tables +{ + # Lists which `@x{y}' get expanded into `y'. + %atxy_2_y = ( + 'asis', 1, + 'r', 1, + 'w', 1, + ); + + # Describes which `@x{y}' get expanded into `<z>y</z>' and what `z' + # is in those expansions! (If the expansion matches + # ``/(.*),(.*),(.*)/'' then y actually expands to ``$1<$2>y</$2>$3''; + # if z (or $2) begins with ^ then uppercase y before doing the + # expansion). + %atxy_2_zyz= ( + 'b', 'STRONG', + 'cite', 'CITE', + 'code', "CODE", + 'dfn', 'EM', + 'dmn', 'EM', + 'emph', 'EM', + 'file', "`,CODE,'", + 'i', 'EM', + 'kbd', 'KBD', + 'key', '^CODE', + 'math', 'CODE', + 'samp', "`,CODE,'", + 'sc', '^EM', + 'strong', 'STRONG', + 't', 'CODE', + 'titlefont', 'CITE', + 'var', 'VAR', + ); + + # Describes which `@x{y}' can be expanded into `z' and what `z' is in + # those expansions! + %atxy_2_z = ( + 'TeX', '<i>T</i>e<i>X</i>', + 'bullet', '*', + 'copyright', '(C)', + 'dots', '...', + 'equiv', '==', + 'error', 'error-->', + 'expansion', '==>', + 'minus', '-', + 'point', '-!-', + 'print', '-|', + 'result', '=>', + 'today', &today(), + ); + + # Lists the '@x{y}' cross reference commands, and describes how they get + # expanded. Note the 'X' beginning each expansion -- it's there so 'ref' + # doesn't get expanded to ''! + %atxy_2_ref = ( + 'xref', 'XSee ', + 'ref', 'X', + 'pxref', 'Xsee ', + 'href', 'X', + 'inforef', 'XSee ', + ); + + %ignore_these_directives = ( + 'author', 1, + 'break', 1, + 'contents', 1, + 'evenfooting', 1, + 'everyfooting', 1, + 'everyheading', 1, + 'finalout', 1, + 'footnotestyle', 1, + 'headings', 1, + 'need', 1, + 'noindent', 1, + 'oddfooting', 1, + 'page', 1, + 'paragraphindent', 1, + 'setchapternewpage', 1, + 'setfilename', 1, + 'shortcontents', 1, + 'shorttitlepage', 1, + 'smallbook', 1, + 'sp', 1, + 'subtitle', 1, + 'summarycontents', 1, + 'top', 1, + 'vskip', 1, + ); + + # List the section directives and indicate what heading level + # each one gets. + %directive_section = ( + 'chapter', 1, + 'section', 2, + 'subsection', 3, + 'subsubsection',4, + 'appendix', 1, + 'appendixsec', 2, + 'appendixsubsec', 3, + 'appendixsubsubsec', 4, + 'chapheading', 1, + 'majorheading', 1, + 'heading', 2, + 'subheading', 3, + 'subsubheading', 4, + 'unnumbered', 1, + 'unnumberedsec', 2, + 'unnumberedsubsec', 3, + 'unnumberedsubsubsec', 4, + ); + + # These @ directives begin a block of preformatted text + # (">PRE" means indented inside <PRE>...</PRE>) + %directive_block = ( + 'cartouche', 'HR', + 'display', '>PRE', + 'example', '>PRE', + 'format', 'PRE', + 'group', '-', + 'lisp', '>PRE', + 'quotation', 'BLOCKQUOTE', + 'smallexample','>PRE', + ); + + %index_name = ( + 'cp', 'cpindex', + 'fn', 'fnindex', + 'ky', 'kyindex', + 'pg', 'pgindex', + 'tp', 'tpindex', + 'vr', 'vrindex', + ); + %index_style = ( + 'fn', 'CODE', + 'ky', 'CODE', + 'pg', 'CODE', + 'tp', 'CODE', + 'vr', 'CODE', + ); +} # initialize_tables + +######################################################################## +sub open_input_file +{ + unshift(@texinfo_file,$_[0]); + print "opening $_[0] ...\n" if $debug{open_input_file}; + open($texinfo_file[0],$_[0]) || die "Couldn't open $_[0]: $!\n"; +} # open_input_file + +######################################################################## +sub texinfo_read +# Reads the next line of texinfo input into $_. +{ + do { + $fd = $texinfo_file[0]; + $_ = <$fd>; + } while ($_ eq '' && shift @texinfo_file); + return $_; +} # texinfo_read + +######################################################################## +sub today +{ + $today = `date`; + $today =~ s/\w+ (\w+ +[0-9]+) [0-9]+:[0-9]+:[0-9]+ \w+ ([0-9]+)\n/$1 $2/; + $today =~ s/ +/ /g; + return $today; +} # today + +######################################################################## +sub copy_to_destdir +{ + ($copy_from) = @_; + + if ($copy_from =~ m|(.*)/([^/]*)|) { + $copy_from_dir = $1; + $copy_from_file = $2; + } else { + $copy_from_dir = "."; + $copy_from_file = $copy_from; + } + + if ($copy_from_dir ne $dir && !-e "$dir/$copy_from_file") { + system("cp $copy_from $dir") + && die "Couldn\'t \`cp $copy_from $dir\'\n"; + } +} 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 |