Doc/perl/l2hinit.perl

   1 #LaTeX2HTML Version 96.1 : dot.latex2html-init          -*- perl -*-
   2 #
   3 #  Significantly revised by Fred L. Drake, Jr. <fdrake@acm.org> for use
   4 #  with the Python documentation.
   5 #
   6 #  New name to avoid distributing "dot" files with the Python documentation.
   7 #
   8
   9 package Override;
  10
  11 use Cwd qw(getcwd);
  12
  13
  14 package main;
  15
  16 $HTML_VERSION = 4.0;
  17
  18 $MAX_LINK_DEPTH = 2;
  19 $ADDRESS = '';
  20
  21 $NO_FOOTNODE = 1;
  22 $NUMBERED_FOOTNOTES = 1;
  23
  24 # Python documentation uses section numbers to support references to match
  25 # in the printed and online versions.
  26 #
  27 $SHOW_SECTION_NUMBERS = 1;
  28
  29 $ICONSERVER = '../icons';
  30
  31 # Control where the navigation bars should show up:
  32 $TOP_NAVIGATION = 1;
  33 $BOTTOM_NAVIGATION = 1;
  34 $AUTO_NAVIGATION = 0;
  35
  36 $BODYTEXT = 'bgcolor="#ffffff"';
  37 $CHILDLINE = "\n<p><hr>\n";
  38 $VERBOSITY = 0;
  39
  40 # default # of columns for the indexes
  41 $INDEX_COLUMNS = 2;
  42 $MODULE_INDEX_COLUMNS = 4;
  43
  44
  45 # A little painful, but lets us clean up the top level directory a little,
  46 # and not be tied to the current directory (as far as I can tell).
  47 #
  48 use Cwd;
  49 use File::Basename;
  50 ($myname, $mydir, $myext) = fileparse(__FILE__, '\..*');
  51 chop $mydir;                    # remove trailing '/'
  52 $mydir = getcwd() . "$dd$mydir"
  53   unless $mydir =~ s|^/|/|;
  54 $LATEX2HTMLSTYLES = "$mydir$envkey$LATEX2HTMLSTYLES";
  55 push (@INC, $mydir);
  56
  57 ($myrootname, $myrootdir, $myext) = fileparse($mydir, '\..*');
  58 chop $myrootdir;
  59
  60
  61 # Hackish way to get the appropriate paper-*/ directory into $TEXINPUTS;
  62 # pass in the paper size (a4 or letter) as the environment variable PAPER
  63 # to add the right directory.  If not given, the current directory is
  64 # added instead for use with HOWTO processing.
  65 #
  66 if (defined $ENV{'PAPER'}) {
  67     $mytexinputs = "$myrootdir${dd}paper-$ENV{'PAPER'}$envkey";
  68 }
  69 else {
  70     $mytexinputs = getcwd() . $envkey;
  71 }
  72 $mytexinputs .= "$myrootdir${dd}texinputs";
  73
  74
  75 sub custom_driver_hook{
  76     #
  77     # This adds the directory of the main input file to $TEXINPUTS; it
  78     # seems to be sufficiently general that it should be fine for HOWTO
  79     # processing.
  80     #
  81     my $file = @_[0];
  82     my($jobname,$dir,$ext) = fileparse($file, '\..*');
  83     $dir = make_directory_absolute($dir);
  84     $dir =~ s/$dd$//;
  85     $TEXINPUTS = "$dir$envkey$mytexinputs";
  86     print "\nadding $dir to \$TEXINPUTS\n";
  87 }
  88
  89
  90 sub set_icon_size{
  91     my($name, $w, $h) = @_;
  92     $iconsizes{$name} = "width=$w height=$h";
  93 }
  94
  95 foreach $name (split(/ /, 'up next previous contents index modules blank')) {
  96     set_icon_size($name, 32, 32);
  97 }
  98 # The '_motif' is really annoying, and makes the HTML larger with no value
  99 # added, so strip it off:
 100 foreach $name (keys %icons) {
 101     my $icon = $icons{$name};
 102     # Strip off the wasteful '_motif':
 103     $icon =~ s/_motif//;
 104     # Change the greyed-out icons to be blank:
 105     $icon =~ s/[a-z]*_gr/blank/;
 106     $icons{$name} = $icon;
 107 }
 108 $icons{'blank'} = 'blank.' . $IMAGE_TYPE;
 109
 110 $CUSTOM_BUTTONS = '';
 111 $BLANK_ICON = "\n<td>" . img_tag('blank.' . $IMAGE_TYPE) . "</td>";
 112 $BLANK_ICON =~ s/alt="blank"/alt=""/;
 113 $NAV_BGCOLOR = " bgcolor=\"#99CCFF\"";
 114
 115 sub make_nav_sectref{
 116     my($label,$title) = @_;
 117     if ($title) {
 118         return ("<b class=navlabel>$label:</b> "
 119                 . "<span class=sectref>$title</span>\n");
 120     }
 121     return '';
 122 }
 123
 124 sub make_nav_panel{
 125     return ("<table align=center width=\"100%\" cellpadding=0 cellspacing=2>"
 126             . "\n<tr>"
 127             . "\n<td>$NEXT</td>"
 128             . "\n<td>$UP</td>"
 129             . "\n<td>$PREVIOUS</td>"
 130             . "\n<td align=center$NAV_BGCOLOR width=\"100%\">"
 131             . "\n <b class=title>$t_title</b></td>"
 132             . ($CONTENTS ? "\n<td>$CONTENTS</td>" : $BLANK_ICON)
 133             . "\n<td>$CUSTOM_BUTTONS</td>" # module index
 134             . ($INDEX ? "\n<td>$INDEX</td>" : $BLANK_ICON)
 135             . "\n</tr></table>"
 136             #. "<hr>"
 137             . make_nav_sectref("Next", $NEXT_TITLE)
 138             . make_nav_sectref("Up", $UP_TITLE)
 139             . make_nav_sectref("Previous", $PREVIOUS_TITLE)
 140            );
 141 }
 142
 143 sub top_navigation_panel {
 144     "<div class=navigation>\n"
 145       . make_nav_panel()
 146       . '<br><hr></div>';
 147 }
 148
 149 sub bot_navigation_panel {
 150     "<p>\n<div class=navigation><hr>"
 151       . make_nav_panel()
 152       . '</div>';
 153 }
 154
 155 sub add_link {
 156     # Returns a pair (iconic link, textual link)
 157     my($icon, $current_file, @link) = @_;
 158     my($dummy, $file, $title) = split($delim,
 159                                       $section_info{join(' ',@link)});
 160     if ($title && ($file ne $current_file)) {
 161         $title = purify($title);
 162         $title = get_first_words($title, $WORDS_IN_NAVIGATION_PANEL_TITLES);
 163         return (make_href($file, $icon), make_href($file, "$title"))
 164         }
 165     elsif ($icon eq $up_visible_mark && $EXTERNAL_UP_LINK) {
 166         return (make_href($EXTERNAL_UP_LINK, $icon),
 167                 make_href($EXTERNAL_UP_LINK, "$EXTERNAL_UP_TITLE"))
 168         }
 169     elsif (($icon eq $previous_visible_mark
 170             || $icon eq $previous_page_visible_mark)
 171            && $EXTERNAL_PREV_LINK && $EXTERNAL_PREV_TITLE) {
 172         return (make_href($EXTERNAL_PREV_LINK, $icon),
 173                 make_href($EXTERNAL_PREV_LINK, "$EXTERNAL_PREV_TITLE"))
 174         }
 175     elsif (($icon eq $next_visible_mark
 176             ||  $icon eq $next_page_visible_mark)
 177            && $EXTERNAL_DOWN_LINK && $EXTERNAL_DOWN_TITLE) {
 178         return (make_href($EXTERNAL_DOWN_LINK, $icon),
 179                 make_href($EXTERNAL_DOWN_LINK, "$EXTERNAL_DOWN_TITLE"))
 180         }
 181     (&inactive_img($icon), "");
 182 }
 183
 184 sub add_special_link {
 185     my($icon, $file, $current_file) = @_;
 186     (($file && ($file ne $current_file)) ? make_href($file, $icon) : undef)
 187 }
 188
 189 sub img_tag {
 190     local($icon) = @_;
 191     my $alt;
 192     my $align = " align=bottom ";
 193
 194     # having this list hardcoded here is really bogus....
 195     $alt = join('|', 'up', 'next_group', 'previous_group'
 196                 , 'next', 'previous', 'change_begin_right', 'change_begin'
 197                 , 'change_end_right', 'change_end', 'change_delete_right'
 198                 , 'change_delete', 'contents', 'index', 'modules', 'blank');
 199
 200     if ($icon =~ /(gif|png)$/) {
 201         $used_icons{$icon} = 1;
 202         if ($icon =~ /change_(begin|end|delete)_right/) { $align = ' ' };
 203         my $nav_border = "$NAV_BORDER";
 204         if ($icon =~ /($alt)/) {
 205             $alt = $1;
 206             $alt = ""
 207               if ($alt eq "blank");
 208         }
 209         else {
 210             $nav_border = '1';
 211             $alt = '[*]';
 212         };
 213         if ($LOCAL_ICONS) {
 214             return join('', '<img ', $iconsizes{$1}, $align
 215                         ,'border=', $nav_border, ' alt="', $alt
 216                         ,'" src="', $icon, '">' );
 217         }
 218         return join('', '<img ', $iconsizes{$1}, $align
 219                     ,'border=', $nav_border, ' alt="', $alt, "\"\n"
 220                     ,' src="', $ICONSERVER, "/$icon", '">' );
 221     }
 222     else {
 223         return $icon;
 224     }
 225 }
 226
 227
 228 sub do_cmd_arabic {
 229     # get rid of that nasty <SPAN CLASS="arabic">...</SPAN>
 230     local($ctr, $val, $id, $_) = &read_counter_value(@_[0]);
 231     return ($val ? &farabic($val) : "0") . $_;
 232 }
 233
 234
 235 sub gen_index_id {
 236     # this is used to ensure common index key generation and a stable sort
 237     my($str,$extra) = @_;
 238     sprintf('%s###%s%010d', $str, $extra, ++$global{'max_id'});
 239 }
 240
 241 sub make_index_entry {
 242     my($br_id,$str) = @_;
 243     # If TITLE is not yet available (i.e the \index command is in the title of the
 244     # current section), use $ref_before.
 245     $TITLE = $ref_before unless $TITLE;
 246     # Save the reference
 247     $str = gen_index_id($str, '');
 248     $index{$str} .= make_half_href("$CURRENT_FILE#$br_id");
 249     "<a name=\"$br_id\">$anchor_invisible_mark<\/a>";
 250 }
 251
 252
 253 sub insert_index{
 254     my($mark,$datafile,$columns,$letters,$prefix) = @_;
 255     my $prog = "$myrootdir/tools/buildindex.py";
 256     my $index;
 257     if ($letters) {
 258         $index = `$prog --columns $columns --letters $datafile`;
 259     }
 260     else {
 261         $index = `$prog --columns $columns $datafile`;
 262     }
 263     s/$mark/$prefix$index/;
 264 }
 265
 266 sub add_idx{
 267     print "\nBuilding HTML for the index ...";
 268     close(IDXFILE);
 269     insert_index($idx_mark, 'index.dat', $INDEX_COLUMNS, 1, '');
 270 }
 271
 272
 273 $idx_module_mark = '<tex2html_idx_module_mark>';
 274 $idx_module_title = 'Module Index';
 275
 276 sub add_module_idx{
 277     print "\nBuilding HTML for the module index ...";
 278     my $key;
 279     my $first = 1;
 280     my $prevplat = '';
 281     my $allthesame = 1;
 282     my $prefix = '';
 283     foreach $key (keys %Modules) {
 284         $key =~ s/<tt>([a-zA-Z0-9._]*)<\/tt>/\1/;
 285         my $plat = "$ModulePlatforms{$key}";
 286         $plat = ''
 287           if ($plat eq $IGNORE_PLATFORM_ANNOTATION);
 288         if (!$first) {
 289             $allthesame = 0
 290               if ($prevplat ne $plat);
 291         }
 292         else { $first = 0; }
 293         $prevplat = $plat;
 294     }
 295     open(MODIDXFILE, '>modindex.dat') || die "\n$!\n";
 296     foreach $key (keys %Modules) {
 297         # dump the line in the data file; just use a dummy seqno field
 298         my $nkey = $1;
 299         my $moditem = "$Modules{$key}";
 300         my $plat = '';
 301         $key =~ s/<tt>([a-zA-Z0-9._]*)<\/tt>/\1/;
 302         if ($ModulePlatforms{$key} && !$allthesame) {
 303             $plat = (" <em>(<span class=platform>$ModulePlatforms{$key}"
 304                      . '</span>)</em>');
 305         }
 306         print MODIDXFILE
 307           $moditem
 308             . $IDXFILE_FIELD_SEP
 309             . "<tt class=module>$key</tt>$plat###\n";
 310     }
 311     close(MODIDXFILE);
 312     if (!$allthesame) {
 313         $prefix = <<PLAT_DISCUSS;
 314
 315
 316 <p> Some module names are followed by an annotation indicating what
 317 platform they are available on.</p>
 318
 319 PLAT_DISCUSS
 320     }
 321     insert_index($idx_module_mark, 'modindex.dat', $MODULE_INDEX_COLUMNS, 0,
 322                  $prefix);
 323 }
 324
 325 # replace both indexes as needed:
 326 sub add_idx_hook{
 327     add_idx() if (/$idx_mark/);
 328     add_module_idx() if (/$idx_module_mark/);
 329     process_python_state();
 330 }
 331
 332
 333 # In addition to the standard stuff, add label to allow named node files.
 334 sub do_cmd_tableofcontents {
 335     local($_) = @_;
 336     $TITLE = $toc_title;
 337     $tocfile = $CURRENT_FILE;
 338     my($closures,$reopens) = preserve_open_tags();
 339     anchor_label('contents', $CURRENT_FILE, $_);        # this is added
 340     join('', "<BR>\n\\tableofchildlinks[off]", $closures
 341          , make_section_heading($toc_title, 'H2'), $toc_mark
 342          , $reopens, $_);
 343 }
 344 # In addition to the standard stuff, add label to allow named node files.
 345 sub do_cmd_listoffigures {
 346     local($_) = @_;
 347     $TITLE = $lof_title;
 348     $loffile = $CURRENT_FILE;
 349     my($closures,$reopens) = preserve_open_tags();
 350     anchor_label('lof', $CURRENT_FILE, $_);             # this is added
 351     join('', "<BR>\n", $closures
 352          , make_section_heading($lof_title, 'H2'), $lof_mark
 353          , $reopens, $_);
 354 }
 355 # In addition to the standard stuff, add label to allow named node files.
 356 sub do_cmd_listoftables {
 357     local($_) = @_;
 358     $TITLE = $lot_title;
 359     $lotfile = $CURRENT_FILE;
 360     my($closures,$reopens) = preserve_open_tags();
 361     anchor_label('lot', $CURRENT_FILE, $_);             # this is added
 362     join('', "<BR>\n", $closures
 363          , make_section_heading($lot_title, 'H2'), $lot_mark
 364          , $reopens, $_);
 365 }
 366 # In addition to the standard stuff, add label to allow named node files.
 367 sub do_cmd_textohtmlinfopage {
 368     local($_) = @_;
 369     if ($INFO) {                                        #
 370         anchor_label("about",$CURRENT_FILE,$_);         # this is added
 371     }                                                   #
 372     my $the_version = '';                               # and the rest is
 373     if ($t_date) {                                      # mostly ours
 374         $the_version = ",\n$t_date";
 375         if ($PYTHON_VERSION) {
 376             $the_version .= ", Release $PYTHON_VERSION";
 377         }
 378     }
 379     $_ = (($INFO == 1)
 380       ? join('', $close_all
 381         , "<strong>$t_title</strong>$the_version\n"
 382         , `cat $myrootdir${dd}html${dd}about.dat`
 383         , $open_all, $_)
 384       : join('', $close_all, $INFO,"\n", $open_all, $_));
 385     $_;
 386 }
 387
 388 # $idx_mark will be replaced with the real index at the end
 389 sub do_cmd_textohtmlindex {
 390     local($_) = @_;
 391     $TITLE = $idx_title;
 392     $idxfile = $CURRENT_FILE;
 393     if (%index_labels) { make_index_labels(); }
 394     if (($SHORT_INDEX) && (%index_segment)) { make_preindex(); }
 395     else { $preindex = ''; }
 396     my $heading = make_section_heading($idx_title, 'h2') . $idx_mark;
 397     my($pre,$post) = minimize_open_tags($heading);
 398     anchor_label('genindex',$CURRENT_FILE,$_);          # this is added
 399     '<br>\n' . $pre . $_;
 400 }
 401
 402 # $idx_module_mark will be replaced with the real index at the end
 403 sub do_cmd_textohtmlmoduleindex {
 404     local($_) = @_;
 405     $TITLE = $idx_module_title;
 406     anchor_label("modindex",$CURRENT_FILE,$_);
 407     '<p>' . make_section_heading($idx_module_title, "h2")
 408       . $idx_module_mark . $_;
 409 }
 410
 411 # The bibliography and the index should be treated as separate sections
 412 # in their own HTML files. The \bibliography{} command acts as a sectioning command
 413 # that has the desired effect. But when the bibliography is constructed
 414 # manually using the thebibliography environment, or when using the
 415 # theindex environment it is not possible to use the normal sectioning
 416 # mechanism. This subroutine inserts a \bibliography{} or a dummy
 417 # \textohtmlindex command just before the appropriate environments
 418 # to force sectioning.
 419
 420 # XXX   This *assumes* that if there are two {theindex} environments, the
 421 #       first is the module index and the second is the standard index.  This
 422 #       is sufficient for the current Python documentation, but that's about
 423 #       it.
 424
 425 sub add_bbl_and_idx_dummy_commands {
 426     my $id = $global{'max_id'};
 427
 428     s/([\\]begin\s*$O\d+$C\s*thebibliography)/$bbl_cnt++; $1/eg;
 429     s/([\\]begin\s*$O\d+$C\s*thebibliography)/$id++; "\\bibliography$O$id$C$O$id$C $1"/geo
 430       #if ($bbl_cnt == 1)
 431     ;
 432     #}
 433     #----------------------------------------------------------------------
 434     # (FLD) This was added
 435     my(@parts) = split(/\\begin\s*$O\d+$C\s*theindex/);
 436     if (scalar(@parts) == 3) {
 437         # Be careful to re-write the string in place, since $_ is *not*
 438         # returned explicity;  *** nasty side-effect dependency! ***
 439         print "\nadd_bbl_and_idx_dummy_commands ==> adding module index";
 440         my $rx = "([\\\\]begin\\s*$O\\d+$C\\s*theindex[\\s\\S]*)"
 441                  . "([\\\\]begin\\s*$O\\d+$C\\s*theindex)";
 442         s/$rx/\\textohtmlmoduleindex \1 \\textohtmlindex \2/o;
 443         # Add a button to the navigation areas:
 444         $CUSTOM_BUTTONS .= ("<a\n href=\"modindex.html\">"
 445                             . img_tag('modules.'.$IMAGE_TYPE) . "</a>");
 446     }
 447     else {
 448         $CUSTOM_BUTTONS .= img_tag('blank.' . $IMAGE_TYPE);
 449         $global{'max_id'} = $id; # not sure why....
 450         s/([\\]begin\s*$O\d+$C\s*theindex)/\\textohtmlindex $1/o;
 451         s/[\\]printindex/\\textohtmlindex /o;
 452     }
 453     #----------------------------------------------------------------------
 454     lib_add_bbl_and_idx_dummy_commands()
 455         if defined(&lib_add_bbl_and_idx_dummy_commands);
 456 }
 457
 458 # The bibliographic references, the appendices, the lists of figures and tables
 459 # etc. must appear in the contents table at the same level as the outermost
 460 # sectioning command. This subroutine finds what is the outermost level and
 461 # sets the above to the same level;
 462
 463 sub set_depth_levels {
 464     # Sets $outermost_level
 465     my $level;
 466     #RRM:  do not alter user-set value for  $MAX_SPLIT_DEPTH
 467     foreach $level ("part", "chapter", "section", "subsection",
 468                     "subsubsection", "paragraph") {
 469         last if (($outermost_level) = /\\($level)$delimiter_rx/);
 470     }
 471     $level = ($outermost_level ? $section_commands{$outermost_level} :
 472               do {$outermost_level = 'section'; 3;});
 473
 474     #RRM:  but calculate value for $MAX_SPLIT_DEPTH when a $REL_DEPTH was given
 475     if ($REL_DEPTH && $MAX_SPLIT_DEPTH) {
 476         $MAX_SPLIT_DEPTH = $level + $MAX_SPLIT_DEPTH;
 477     } elsif (!($MAX_SPLIT_DEPTH)) { $MAX_SPLIT_DEPTH = 1 };
 478
 479     %unnumbered_section_commands = ('tableofcontents' => $level,
 480                                     'listoffigures' => $level,
 481                                     'listoftables' => $level,
 482                                     'bibliography' => $level,
 483                                     'textohtmlindex' => $level,
 484                                     'textohtmlmoduleindex' => $level);
 485     $section_headings{'textohtmlmoduleindex'} = 'h1';
 486
 487     %section_commands = (%unnumbered_section_commands,
 488                          %section_commands);
 489
 490     make_sections_rx();
 491 }
 492
 493
 494 # Fix from Ross Moore for ']' in \item[...]; this can be removed once the next
 495 # patch to LaTeX2HTML is released and tested ... if the patch gets included.
 496 # Be very careful to keep this around, just in case things break again!
 497 #
 498 sub protect_useritems {
 499     local(*_) = @_;
 500     local($preitems,$thisitem);
 501     while (/\\item\s*\[/) {
 502         $preitems .= $`;
 503         $_ = $';
 504         $thisitem = $&.'<<'.++$global{'max_id'}.'>>';
 505         s/^(((($O|$OP)\d+($C|$CP)).*\3|<[^<>]*>|[^\]<]+)*)\]/$thisitem.=$1;''/e;
 506         $preitems .= $thisitem . '<<' . $global{'max_id'} . '>>]';
 507         s/^]//;
 508     }
 509     $_ = $preitems . $_;
 510 }
 511
 512 # This changes the markup used for {verbatim} environments, and is the
 513 # best way I've found that ensures the <dl> goes on the outside of the
 514 # <pre>...</pre>.
 515 #
 516 # Note that this *must* be done in the init file, not the python.perl
 517 # style support file.  The %declarations must be set before initialize()
 518 # is called in the main script.
 519 #
 520 %declarations = ('preform' => '<dl><dd><pre class=verbatim></pre></dl>',
 521                  %declarations);
 522
 523 1;      # This must be the last line