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