cpython/Doc/perl/l2hinit.perl
Fred Drake f730fc3e4e Be a little more careful to avoid including style information in the
generated markup.

Don't be careless with the navigation icons!  We should use the blank
icon where there is not anyplace to go for a particular position in the
navigation bar.
2000-08-31 07:19:07 +00:00

530 lines
17 KiB
Perl

# LaTeX2HTML support base for use with Python documentation.
package main;
use L2hos;
$HTML_VERSION = 4.0;
$MAX_LINK_DEPTH = 2;
$ADDRESS = '';
$NO_FOOTNODE = 1;
$NUMBERED_FOOTNOTES = 1;
# Python documentation uses section numbers to support references to match
# in the printed and online versions.
#
$SHOW_SECTION_NUMBERS = 1;
$ICONSERVER = '../icons';
$IMAGE_TYPE = 'gif';
# Control where the navigation bars should show up:
$TOP_NAVIGATION = 1;
$BOTTOM_NAVIGATION = 1;
$AUTO_NAVIGATION = 0;
# these exactly match the python.org colors
$BODYTEXT = ('bgcolor="#ffffff" text="#000000"'
. ' link="#0000bb" vlink="#551a8b" alink="#ff0000"');
$CHILDLINE = "\n<p><hr>\n";
$VERBOSITY = 0;
# default # of columns for the indexes
$INDEX_COLUMNS = 2;
$MODULE_INDEX_COLUMNS = 4;
# A little painful, but lets us clean up the top level directory a little,
# and not be tied to the current directory (as far as I can tell). Testing
# an existing definition of $mydir is needed since it cannot be computed when
# run under mkhowto with recent versions of LaTeX2HTML, since this file is
# not read directly by LaTeX2HTML any more. mkhowto is required to prepend
# the required definition at the top of the actual input file.
#
if (!defined $mydir) {
use Cwd;
use File::Basename;
($myname, $mydir, $myext) = fileparse(__FILE__, '\..*');
chop $mydir; # remove trailing '/'
$mydir = getcwd() . "$dd$mydir"
unless $mydir =~ s|^/|/|;
}
$LATEX2HTMLSTYLES = "$mydir$envkey$LATEX2HTMLSTYLES";
push (@INC, $mydir);
($myrootname, $myrootdir, $myext) = fileparse($mydir, '\..*');
chop $myrootdir;
# Hackish way to get the appropriate paper-*/ directory into $TEXINPUTS;
# pass in the paper size (a4 or letter) as the environment variable PAPER
# to add the right directory. If not given, the current directory is
# added instead for use with HOWTO processing.
#
if (defined $ENV{'PAPER'}) {
$mytexinputs = "$myrootdir${dd}paper-$ENV{'PAPER'}$envkey";
}
else {
$mytexinputs = getcwd() . $envkey;
}
$mytexinputs .= "$myrootdir${dd}texinputs";
# Change this variable to change the text added in "About this document...";
# this should be an absolute pathname to get it right.
#
$ABOUT_FILE = "$myrootdir${dd}html${dd}stdabout.dat";
sub custom_driver_hook {
#
# This adds the directory of the main input file to $TEXINPUTS; it
# seems to be sufficiently general that it should be fine for HOWTO
# processing.
#
my $file = @_[0];
my($jobname, $dir, $ext) = fileparse($file, '\..*');
$dir = L2hos->Make_directory_absolute($dir);
$dir =~ s/$dd$//;
$TEXINPUTS = "$dir$envkey$mytexinputs";
print "\nAdding $dir to \$TEXINPUTS\n";
}
$CUSTOM_BUTTONS = '';
sub make_nav_sectref {
my($label,$title) = @_;
if ($title) {
return ("<b class='navlabel'>$label:</b> "
. "<span class='sectref'>$title</span>\n");
}
return '';
}
sub make_my_icon {
my($name, $text) = @_;
my $iconserver = ($ICONSERVER eq '.') ? '' : "$ICONSERVER/";
return "<img src=\"$iconserver$name.$IMAGE_TYPE\" border=\"0\""
. " height=\"32\"\n alt=\"$text\" width=\"32\">";
}
$BLANK_ICON = make_my_icon('blank', '');
@my_icons = ();
$my_icons{'next_page_inactive'} = $BLANK_ICON;
$my_icons{'previous_page_inactive'} = $BLANK_ICON;
$my_icons{'up_page_inactive'} = $BLANK_ICON;
$x = make_my_icon('next', 'Next Page');
$my_icons{'next_page'} = $x;
$my_icons{'next'} = $x;
$x = make_my_icon('previous', 'Previous Page');
$my_icons{'previous_page'} = $x;
$my_icons{'previous'} = $x;
$my_icons{'up'} = make_my_icon('up', 'Up One Level');
$my_icons{'contents'} = make_my_icon('contents', 'Contents');
$my_icons{'index'} = make_my_icon('index', 'Index');
$my_icons{'modules'} = make_my_icon('modules', 'Module Index');
sub use_my_icon {
my $s = @_[0];
$s =~ s/\<tex2html_([a-z_]+)_visible_mark\>/$my_icons{$1}/;
return $s;
}
sub make_nav_panel {
my $s;
$NEXT = $NEXT_TITLE ? use_my_icon("$NEXT") : $BLANK_ICON;
$UP = $UP_TITLE ? use_my_icon("$UP") : $BLANK_ICON;
$PREVIOUS = $PREVIOUS_TITLE ? use_my_icon("$PREVIOUS") : $BLANK_ICON;
$CONTENTS = use_my_icon("$CONTENTS");
$INDEX = $INDEX ? use_my_icon("$INDEX") : $BLANK_ICON;
if (!$CUSTOM_BUTTONS) {
$CUSTOM_BUTTONS = $BLANK_ICON;
}
$s = ('<table align="center" width="100%" cellpadding="0" cellspacing="2">'
. "\n<tr>"
# left-hand side
. "\n<td>$PREVIOUS</td>"
. "\n<td>$UP</td>"
. "\n<td>$NEXT</td>"
# title box
. "\n<td align=\"center\" width=\"100%\">$t_title</td>"
# right-hand side
. "\n<td>$CONTENTS</td>"
. "\n<td>$CUSTOM_BUTTONS</td>" # module index
. "\n<td>$INDEX</td>"
. "\n</tr></table>\n"
# textual navigation
. make_nav_sectref("Previous", $PREVIOUS_TITLE)
. make_nav_sectref("Up", $UP_TITLE)
. make_nav_sectref("Next", $NEXT_TITLE)
);
# remove these; they are unnecessary and cause errors from validation
$s =~ s/ NAME="tex2html\d+"\n */ /g;
return $s;
}
sub top_navigation_panel {
return make_nav_panel()
. '<br><hr>';
}
sub bot_navigation_panel {
return "<p><hr>"
. make_nav_panel();
}
sub add_link {
# Returns a pair (iconic link, textual link)
my($icon, $current_file, @link) = @_;
my($dummy, $file, $title) = split($delim,
$section_info{join(' ',@link)});
$icon =~ s/\<tex2html_([_a-z]+)_visible_mark\>/$my_icons{$1}/;
if ($title && ($file ne $current_file)) {
$title = purify($title);
$title = get_first_words($title, $WORDS_IN_NAVIGATION_PANEL_TITLES);
return (make_href($file, $icon), make_href($file, "$title"))
}
elsif ($icon eq $my_icons{"up"} && $EXTERNAL_UP_LINK) {
return (make_href($EXTERNAL_UP_LINK, $icon),
make_href($EXTERNAL_UP_LINK, "$EXTERNAL_UP_TITLE"))
}
elsif ($icon eq $my_icons{"previous"}
&& $EXTERNAL_PREV_LINK && $EXTERNAL_PREV_TITLE) {
return (make_href($EXTERNAL_PREV_LINK, $icon),
make_href($EXTERNAL_PREV_LINK, "$EXTERNAL_PREV_TITLE"))
}
elsif ($icon eq $my_icons{"next"}
&& $EXTERNAL_DOWN_LINK && $EXTERNAL_DOWN_TITLE) {
return (make_href($EXTERNAL_DOWN_LINK, $icon),
make_href($EXTERNAL_DOWN_LINK, "$EXTERNAL_DOWN_TITLE"))
}
return (&inactive_img($icon), "");
}
sub add_special_link {
my($icon, $file, $current_file) = @_;
$icon =~ s/\<tex2html_([_a-z]+)_visible_mark\>/$my_icons{$1}/;
return (($file && ($file ne $current_file))
? make_href($file, $icon)
: undef)
}
# The img_tag() function seems only to be called with the parameter
# 'anchor_invisible_mark', which we want to turn into ''. Since
# replace_icon_marks() is the only interesting caller, and all it really
# does is call img_tag(), we can just define the hook alternative to be
# a no-op instead.
#
sub replace_icons_hook {}
sub do_cmd_arabic {
# get rid of that nasty <SPAN CLASS="arabic">...</SPAN>
my($ctr, $val, $id, $text) = &read_counter_value(@_[0]);
return ($val ? farabic($val) : "0") . $text;
}
sub gen_index_id {
# this is used to ensure common index key generation and a stable sort
my($str,$extra) = @_;
sprintf('%s###%s%010d', $str, $extra, ++$global{'max_id'});
}
sub insert_index {
my($mark,$datafile,$columns,$letters,$prefix) = @_;
my $prog = "$myrootdir/tools/buildindex.py";
my $index;
if ($letters) {
$index = `$prog --columns $columns --letters $datafile`;
}
else {
$index = `$prog --columns $columns $datafile`;
}
s/$mark/$prefix$index/;
}
sub add_idx {
print "\nBuilding HTML for the index ...";
close(IDXFILE);
insert_index($idx_mark, 'index.dat', $INDEX_COLUMNS, 1, '');
}
$idx_module_mark = '<tex2html_idx_module_mark>';
$idx_module_title = 'Module Index';
sub add_module_idx {
print "\nBuilding HTML for the module index ...";
my $key;
my $first = 1;
my $prevplat = '';
my $allthesame = 1;
my $prefix = '';
foreach $key (keys %Modules) {
$key =~ s/<tt>([a-zA-Z0-9._]*)<\/tt>/\1/;
my $plat = "$ModulePlatforms{$key}";
$plat = ''
if ($plat eq $IGNORE_PLATFORM_ANNOTATION);
if (!$first) {
$allthesame = 0
if ($prevplat ne $plat);
}
else { $first = 0; }
$prevplat = $plat;
}
open(MODIDXFILE, '>modindex.dat') || die "\n$!\n";
foreach $key (keys %Modules) {
# dump the line in the data file; just use a dummy seqno field
my $nkey = $1;
my $moditem = "$Modules{$key}";
my $plat = '';
$key =~ s/<tt>([a-zA-Z0-9._]*)<\/tt>/\1/;
if ($ModulePlatforms{$key} && !$allthesame) {
$plat = (" <em>(<span class='platform'>$ModulePlatforms{$key}"
. '</span>)</em>');
}
print MODIDXFILE $moditem . $IDXFILE_FIELD_SEP
. "<tt class='module'>$key</tt>$plat###\n";
}
close(MODIDXFILE);
if (!$allthesame) {
$prefix = <<PLAT_DISCUSS;
<p> Some module names are followed by an annotation indicating what
platform they are available on.</p>
PLAT_DISCUSS
}
insert_index($idx_module_mark, 'modindex.dat', $MODULE_INDEX_COLUMNS, 0,
$prefix);
}
# replace both indexes as needed:
sub add_idx_hook {
add_idx() if (/$idx_mark/);
add_module_idx() if (/$idx_module_mark/);
process_python_state();
}
# In addition to the standard stuff, add label to allow named node files and
# support suppression of the page complete (for HTML Help use).
sub do_cmd_tableofcontents {
local($_) = @_;
$TITLE = $toc_title;
$tocfile = $CURRENT_FILE;
my($closures,$reopens) = preserve_open_tags();
anchor_label('contents', $CURRENT_FILE, $_); # this is added
join('', "<BR>\n\\tableofchildlinks[off]", $closures
, make_section_heading($toc_title, 'H2'), $toc_mark
, $reopens, $_);
}
# In addition to the standard stuff, add label to allow named node files.
sub do_cmd_listoffigures {
local($_) = @_;
$TITLE = $lof_title;
$loffile = $CURRENT_FILE;
my($closures,$reopens) = preserve_open_tags();
anchor_label('lof', $CURRENT_FILE, $_); # this is added
join('', "<BR>\n", $closures
, make_section_heading($lof_title, 'H2'), $lof_mark
, $reopens, $_);
}
# In addition to the standard stuff, add label to allow named node files.
sub do_cmd_listoftables {
local($_) = @_;
$TITLE = $lot_title;
$lotfile = $CURRENT_FILE;
my($closures,$reopens) = preserve_open_tags();
anchor_label('lot', $CURRENT_FILE, $_); # this is added
join('', "<BR>\n", $closures
, make_section_heading($lot_title, 'H2'), $lot_mark
, $reopens, $_);
}
# In addition to the standard stuff, add label to allow named node files.
sub do_cmd_textohtmlinfopage {
local($_) = @_;
if ($INFO) { #
anchor_label("about",$CURRENT_FILE,$_); # this is added
} #
my $the_version = ''; # and the rest is
if ($t_date) { # mostly ours
$the_version = ",\n$t_date";
if ($PYTHON_VERSION) {
$the_version .= ", Release $PYTHON_VERSION";
}
}
$_ = (($INFO == 1)
? join('',
$close_all,
"<strong>$t_title</strong>$the_version\n",
`cat $ABOUT_FILE`,
$open_all, $_)
: join('', $close_all, $INFO,"\n", $open_all, $_));
$_;
}
# $idx_mark will be replaced with the real index at the end
sub do_cmd_textohtmlindex {
local($_) = @_;
$TITLE = $idx_title;
$idxfile = $CURRENT_FILE;
if (%index_labels) { make_index_labels(); }
if (($SHORT_INDEX) && (%index_segment)) { make_preindex(); }
else { $preindex = ''; }
my $heading = make_section_heading($idx_title, 'h2') . $idx_mark;
my($pre,$post) = minimize_open_tags($heading);
anchor_label('genindex',$CURRENT_FILE,$_); # this is added
'<br>\n' . $pre . $_;
}
# $idx_module_mark will be replaced with the real index at the end
sub do_cmd_textohtmlmoduleindex {
local($_) = @_;
$TITLE = $idx_module_title;
anchor_label("modindex",$CURRENT_FILE,$_);
'<p>' . make_section_heading($idx_module_title, "h2")
. $idx_module_mark . $_;
}
# The bibliography and the index should be treated as separate sections
# in their own HTML files. The \bibliography{} command acts as a sectioning command
# that has the desired effect. But when the bibliography is constructed
# manually using the thebibliography environment, or when using the
# theindex environment it is not possible to use the normal sectioning
# mechanism. This subroutine inserts a \bibliography{} or a dummy
# \textohtmlindex command just before the appropriate environments
# to force sectioning.
# XXX This *assumes* that if there are two {theindex} environments, the
# first is the module index and the second is the standard index. This
# is sufficient for the current Python documentation, but that's about
# it.
sub add_bbl_and_idx_dummy_commands {
my $id = $global{'max_id'};
s/([\\]begin\s*$O\d+$C\s*thebibliography)/$bbl_cnt++; $1/eg;
s/([\\]begin\s*$O\d+$C\s*thebibliography)/$id++; "\\bibliography$O$id$C$O$id$C $1"/geo;
my(@parts) = split(/\\begin\s*$O\d+$C\s*theindex/);
if (scalar(@parts) == 3) {
# Be careful to re-write the string in place, since $_ is *not*
# returned explicity; *** nasty side-effect dependency! ***
print "\nadd_bbl_and_idx_dummy_commands ==> adding module index";
my $rx = "([\\\\]begin\\s*$O\\d+$C\\s*theindex[\\s\\S]*)"
. "([\\\\]begin\\s*$O\\d+$C\\s*theindex)";
s/$rx/\\textohtmlmoduleindex \1 \\textohtmlindex \2/o;
# Add a button to the navigation areas:
$CUSTOM_BUTTONS .= $my_icons{'modules'};
}
else {
$CUSTOM_BUTTONS .= $BLANK_ICON;
$global{'max_id'} = $id; # not sure why....
s/([\\]begin\s*$O\d+$C\s*theindex)/\\textohtmlindex $1/o;
s/[\\]printindex/\\textohtmlindex /o;
}
#----------------------------------------------------------------------
lib_add_bbl_and_idx_dummy_commands()
if defined(&lib_add_bbl_and_idx_dummy_commands);
}
# The bibliographic references, the appendices, the lists of figures and tables
# etc. must appear in the contents table at the same level as the outermost
# sectioning command. This subroutine finds what is the outermost level and
# sets the above to the same level;
sub set_depth_levels {
# Sets $outermost_level
my $level;
#RRM: do not alter user-set value for $MAX_SPLIT_DEPTH
foreach $level ("part", "chapter", "section", "subsection",
"subsubsection", "paragraph") {
last if (($outermost_level) = /\\($level)$delimiter_rx/);
}
$level = ($outermost_level ? $section_commands{$outermost_level} :
do {$outermost_level = 'section'; 3;});
#RRM: but calculate value for $MAX_SPLIT_DEPTH when a $REL_DEPTH was given
if ($REL_DEPTH && $MAX_SPLIT_DEPTH) {
$MAX_SPLIT_DEPTH = $level + $MAX_SPLIT_DEPTH;
} elsif (!($MAX_SPLIT_DEPTH)) { $MAX_SPLIT_DEPTH = 1 };
%unnumbered_section_commands = ('tableofcontents' => $level,
'listoffigures' => $level,
'listoftables' => $level,
'bibliography' => $level,
'textohtmlindex' => $level,
'textohtmlmoduleindex' => $level);
$section_headings{'textohtmlmoduleindex'} = 'h1';
%section_commands = (%unnumbered_section_commands,
%section_commands);
make_sections_rx();
}
# This changes the markup used for {verbatim} environments, and is the
# best way I've found that ensures the <dl> goes on the outside of the
# <pre>...</pre>.
#
# Note that this *must* be done in the init file, not the python.perl
# style support file. The %declarations must be set before initialize()
# is called in the main LaTeX2HTML script (which happens before style files
# are loaded).
#
%declarations = ('preform' => '<dl><dd><pre class="verbatim"></pre></dl>',
%declarations);
# This is added to get rid of the long comment that follows the doctype
# declaration; MSIE5 on NT4 SP4 barfs on it and drops the content of the
# page.
sub make_head_and_body {
my($title, $body) = @_;
my $DTDcomment = '';
my($version, $isolanguage) = ($HTML_VERSION, 'EN');
my %isolanguages = ( 'english', 'EN' , 'USenglish', 'EN.US'
, 'original', 'EN' , 'german' , 'DE'
, 'austrian', 'DE.AT', 'french' , 'FR'
, 'spanish', 'ES');
$isolanguage = $isolanguages{$default_language};
$isolanguage = 'EN' unless $isolanguage;
$title = &purify($title,1);
eval("\$title = ". $default_title ) unless ($title);
# allow user-modification of the <TITLE> tag; thanks Dan Young
if (defined &custom_TITLE_hook) {
$title = &custom_TITLE_hook($title, $toc_sec_title);
}
if ($DOCTYPE =~ /\/\/[\w\.]+\s*$/) { # language spec included
$DTDcomment = "<!DOCTYPE html PUBLIC \"$DOCTYPE\">\n";
} else {
$DTDcomment = "<!DOCTYPE html PUBLIC \"$DOCTYPE//"
. ($ISO_LANGUAGE ? $ISO_LANGUAGE : $isolanguage) . "\">\n";
}
$STYLESHEET = $FILE.".css" unless $STYLESHEET;
if (!$charset && $CHARSET) { $charset = $CHARSET; $charset =~ s/_/\-/go; }
join('', ($DOCTYPE ? $DTDcomment : '' )
,"<html>\n<head>\n<title>", $title, "</title>\n"
, &meta_information($title)
, ($CHARSET && $HTML_VERSION ge "2.1" ?
"<meta http-equiv=\"Content-Type\" content=\"text/html; charset=$charset\">\n"
: "" )
, ($BASE ? "<base href=\"$BASE\">\n" : "" )
, "<link rel=\"STYLESHEET\" href=\"$STYLESHEET\">"
, $more_links_mark
, "\n</head>\n<body $body>\n");
}
1; # This must be the last line