Doc/perl/python.perl

   1 # python.perl by Fred L. Drake, Jr. <fdrake@acm.org>            -*- perl -*-
   2 #
   3 # Heavily based on Guido van Rossum's myformat.perl (now obsolete).
   4 #
   5 # Extension to LaTeX2HTML for documents using myformat.sty.
   6 # Subroutines of the form do_cmd_<name> here define translations
   7 # for LaTeX commands \<name> defined in the corresponding .sty file.
   8
   9 package main;
  10
  11 use warnings;
  12 use File::Basename;
  13
  14
  15 sub next_argument{
  16     my $param;
  17     $param = missing_braces()
  18       unless ((s/$next_pair_pr_rx/$param=$2;''/eo)
  19               ||(s/$next_pair_rx/$param=$2;''/eo));
  20     return $param;
  21 }
  22
  23 sub next_optional_argument{
  24     my($param, $rx) = ('', "^\\s*(\\[([^]]*)\\])?");
  25     s/$rx/$param=$2;''/eo;
  26     return $param;
  27 }
  28
  29 sub make_icon_filename($){
  30     my($myname, $mydir, $myext) = fileparse($_[0], '\..*');
  31     chop $mydir;
  32     if ($mydir eq '.') {
  33         $mydir = $ICONSERVER;
  34     }
  35     $myext = ".$IMAGE_TYPE"
  36       unless $myext;
  37     return "$mydir$dd$myname$myext";
  38 }
  39
  40 sub get_link_icon($){
  41     my $url = $_[0];
  42     if ($OFF_SITE_LINK_ICON && ($url =~ /^[-a-zA-Z0-9.]+:/)) {
  43         # absolute URL; assume it points off-site
  44         my $icon = make_icon_filename($OFF_SITE_LINK_ICON);
  45         return (" <img src=\"$icon\"\n"
  46                 . '  border="0" class="offsitelink"'
  47                 . ($OFF_SITE_LINK_ICON_HEIGHT
  48                    ? " height=\"$OFF_SITE_LINK_ICON_HEIGHT\""
  49                    : '')
  50                 . ($OFF_SITE_LINK_ICON_WIDTH
  51                    ? " width=\"$OFF_SITE_LINK_ICON_WIDTH\""
  52                    : '')
  53                 . " alt=\"[off-site link]\"\n"
  54                 . "  />");
  55     }
  56     return '';
  57 }
  58
  59 # This is a fairly simple hack; it supports \let when it is used to create
  60 # (or redefine) a macro to exactly be some other macro: \let\newname=\oldname.
  61 # Many possible uses of \let aren't supported or aren't supported correctly.
  62 #
  63 sub do_cmd_let{
  64     local($_) = @_;
  65     my $matched = 0;
  66     s/[\\]([a-zA-Z]+)\s*(=\s*)?[\\]([a-zA-Z]*)/$matched=1; ''/e;
  67     if ($matched) {
  68         my($new, $old) = ($1, $3);
  69         eval "sub do_cmd_$new { do_cmd_$old" . '(@_); }';
  70         print "\ndefining handler for \\$new using \\$old\n";
  71     }
  72     else {
  73         s/[\\]([a-zA-Z]+)\s*(=\s*)?([^\\])/$matched=1; ''/es;
  74         if ($matched) {
  75             my($new, $char) = ($1, $3);
  76             eval "sub do_cmd_$new { \"\\$char\" . \$_[0]; }";
  77             print "\ndefining handler for \\$new to insert '$char'\n";
  78         }
  79         else {
  80             write_warnings("Could not interpret \\let construct...");
  81         }
  82     }
  83     return $_;
  84 }
  85
  86
  87 # the older version of LaTeX2HTML we use doesn't support this, but we use it:
  88
  89 sub do_cmd_textasciitilde{ '&#126;' . $_[0]; }
  90 sub do_cmd_textasciicircum{ '^' . $_[0]; }
  91 sub do_cmd_textbar{ '|' . $_[0]; }
  92 sub do_cmd_texteuro { '&#8364;' . $_[0]; }
  93 sub do_cmd_textgreater{ '&gt;' . $_[0]; }
  94 sub do_cmd_textless{ '&lt;' . $_[0]; }
  95 sub do_cmd_textunderscore{ '_' . $_[0]; }
  96 sub do_cmd_infinity{ '&infin;' . $_[0]; }
  97 sub do_cmd_plusminus{ '&plusmn;' . $_[0]; }
  98 sub do_cmd_guilabel{
  99     return use_wrappers($_[0]. '<span class="guilabel">', '</span>'); }
 100 sub do_cmd_menuselection{
 101     return use_wrappers($_[0], '<span class="guilabel">', '</span>'); }
 102 sub do_cmd_sub{
 103     return '</span> &gt; <span class="guilabel">' . $_[0]; }
 104
 105
 106 # words typeset in a special way (not in HTML though)
 107
 108 sub do_cmd_ABC{ 'ABC' . $_[0]; }
 109 sub do_cmd_UNIX{ '<span class="Unix">Unix</span>' . $_[0]; }
 110 sub do_cmd_LaTeX{ '<span class="LaTeX">LaTeX</span>' . $_[0]; }
 111 sub do_cmd_TeX{ '<span class="TeX">TeX</span>' . $_[0]; }
 112 sub do_cmd_ASCII{ 'ASCII' . $_[0]; }
 113 sub do_cmd_POSIX{ 'POSIX' . $_[0]; }
 114 sub do_cmd_C{ 'C' . $_[0]; }
 115 sub do_cmd_Cpp{ 'C++' . $_[0]; }
 116 sub do_cmd_EOF{ 'EOF' . $_[0]; }
 117 sub do_cmd_NULL{ '<tt class="constant">NULL</tt>' . $_[0]; }
 118
 119 sub do_cmd_e{ '&#92;' . $_[0]; }
 120
 121 $DEVELOPER_ADDRESS = '';
 122 $SHORT_VERSION = '';
 123 $RELEASE_INFO = '';
 124 $PACKAGE_VERSION = '';
 125
 126 sub do_cmd_version{ $PACKAGE_VERSION . $_[0]; }
 127 sub do_cmd_shortversion{ $SHORT_VERSION . $_[0]; }
 128 sub do_cmd_release{
 129     local($_) = @_;
 130     $PACKAGE_VERSION = next_argument();
 131     return $_;
 132 }
 133
 134 sub do_cmd_setreleaseinfo{
 135     local($_) = @_;
 136     $RELEASE_INFO = next_argument();
 137     return $_;
 138 }
 139
 140 sub do_cmd_setshortversion{
 141     local($_) = @_;
 142     $SHORT_VERSION = next_argument();
 143     return $_;
 144 }
 145
 146 sub do_cmd_authoraddress{
 147     local($_) = @_;
 148     $DEVELOPER_ADDRESS = next_argument();
 149     return $_;
 150 }
 151
 152 sub do_cmd_hackscore{
 153     local($_) = @_;
 154     next_argument();
 155     return '_' . $_;
 156 }
 157
 158 # Helper used in many places that arbitrary code-like text appears:
 159
 160 sub codetext($){
 161     my $text = "$_[0]";
 162     # Make sure that "---" is not converted to "--" later when
 163     # LaTeX2HTML tries converting em-dashes based on the conventional
 164     # TeX font ligatures:
 165     $text =~ s/--/-\&#45;/go;
 166     return $text;
 167 }
 168
 169 sub use_wrappers($$$){
 170     local($_,$before,$after) = @_;
 171     my $stuff = next_argument();
 172     return $before . $stuff . $after . $_;
 173 }
 174
 175 sub use_code_wrappers($$$){
 176     local($_,$before,$after) = @_;
 177     my $stuff = codetext(next_argument());
 178     return $before . $stuff . $after . $_;
 179 }
 180
 181 $IN_DESC_HANDLER = 0;
 182 sub do_cmd_optional{
 183     if ($IN_DESC_HANDLER) {
 184         return use_wrappers($_[0], "</var><big>\[</big><var>",
 185                             "</var><big>\]</big><var>");
 186     }
 187     else {
 188         return use_wrappers($_[0], "<big>\[</big>", "<big>\]</big>");
 189     }
 190 }
 191
 192 # Logical formatting (some based on texinfo), needs to be converted to
 193 # minimalist HTML.  The "minimalist" is primarily to reduce the size of
 194 # output files for users that read them over the network rather than
 195 # from local repositories.
 196
 197 sub do_cmd_pytype{ return $_[0]; }
 198 sub do_cmd_makevar{
 199     return use_wrappers($_[0], '<span class="makevar">', '</span>'); }
 200 sub do_cmd_code{
 201     return use_code_wrappers($_[0], '<code>', '</code>'); }
 202 sub do_cmd_module{
 203     return use_wrappers($_[0], '<tt class="module">', '</tt>'); }
 204 sub do_cmd_keyword{
 205     return use_wrappers($_[0], '<tt class="keyword">', '</tt>'); }
 206 sub do_cmd_exception{
 207     return use_wrappers($_[0], '<tt class="exception">', '</tt>'); }
 208 sub do_cmd_class{
 209     return use_wrappers($_[0], '<tt class="class">', '</tt>'); }
 210 sub do_cmd_function{
 211     return use_wrappers($_[0], '<tt class="function">', '</tt>'); }
 212 sub do_cmd_constant{
 213     return use_wrappers($_[0], '<tt class="constant">', '</tt>'); }
 214 sub do_cmd_member{
 215     return use_wrappers($_[0], '<tt class="member">', '</tt>'); }
 216 sub do_cmd_method{
 217     return use_wrappers($_[0], '<tt class="method">', '</tt>'); }
 218 sub do_cmd_cfunction{
 219     return use_wrappers($_[0], '<tt class="cfunction">', '</tt>'); }
 220 sub do_cmd_cdata{
 221     return use_wrappers($_[0], '<tt class="cdata">', '</tt>'); }
 222 sub do_cmd_ctype{
 223     return use_wrappers($_[0], '<tt class="ctype">', '</tt>'); }
 224 sub do_cmd_regexp{
 225     return use_code_wrappers($_[0], '<tt class="regexp">', '</tt>'); }
 226 sub do_cmd_character{
 227     return use_code_wrappers($_[0], '"<tt class="character">', '</tt>"'); }
 228 sub do_cmd_program{
 229     return use_wrappers($_[0], '<b class="program">', '</b>'); }
 230 sub do_cmd_programopt{
 231     return use_wrappers($_[0], '<b class="programopt">', '</b>'); }
 232 sub do_cmd_longprogramopt{
 233     # note that the --- will be later converted to -- by LaTeX2HTML
 234     return use_wrappers($_[0], '<b class="programopt">---', '</b>'); }
 235 sub do_cmd_email{
 236     return use_wrappers($_[0], '<span class="email">', '</span>'); }
 237 sub do_cmd_mailheader{
 238     return use_wrappers($_[0], '<span class="mailheader">', ':</span>'); }
 239 sub do_cmd_mimetype{
 240     return use_wrappers($_[0], '<span class="mimetype">', '</span>'); }
 241 sub do_cmd_var{
 242     return use_wrappers($_[0], "<var>", "</var>"); }
 243 sub do_cmd_dfn{
 244     return use_wrappers($_[0], '<i class="dfn">', '</i>'); }
 245 sub do_cmd_emph{
 246     return use_wrappers($_[0], '<em>', '</em>'); }
 247 sub do_cmd_file{
 248     return use_wrappers($_[0], '<span class="file">', '</span>'); }
 249 sub do_cmd_filenq{
 250     return do_cmd_file($_[0]); }
 251 sub do_cmd_samp{
 252     return use_code_wrappers($_[0], '"<tt class="samp">', '</tt>"'); }
 253 sub do_cmd_kbd{
 254     return use_wrappers($_[0], '<kbd>', '</kbd>'); }
 255 sub do_cmd_strong{
 256     return use_wrappers($_[0], '<strong>', '</strong>'); }
 257 sub do_cmd_textbf{
 258     return use_wrappers($_[0], '<b>', '</b>'); }
 259 sub do_cmd_textit{
 260     return use_wrappers($_[0], '<i>', '</i>'); }
 261 # This can be changed/overridden for translations:
 262 %NoticeNames = ('note' => 'Note:',
 263                 'warning' => 'Warning:',
 264                 );
 265
 266 sub do_cmd_note{
 267     my $label = $NoticeNames{'note'};
 268     return use_wrappers(
 269         $_[0],
 270         "<span class=\"note\"><b class=\"label\">$label</b>\n",
 271         '</span>'); }
 272 sub do_cmd_warning{
 273     my $label = $NoticeNames{'warning'};
 274     return use_wrappers(
 275         $_[0],
 276         "<span class=\"warning\"><b class=\"label\">$label</b>\n",
 277         '</span>'); }
 278
 279 sub do_env_notice{
 280     local($_) = @_;
 281     my $notice = next_optional_argument();
 282     if (!$notice) {
 283         $notice = 'note';
 284     }
 285     my $label = $NoticeNames{$notice};
 286     return ("<div class=\"$notice\"><b class=\"label\">$label</b>\n"
 287             . $_
 288             . '</div>');
 289 }
 290
 291 sub do_cmd_moreargs{
 292     return '...' . $_[0]; }
 293 sub do_cmd_unspecified{
 294     return '...' . $_[0]; }
 295
 296
 297 sub do_cmd_refmodule{
 298     # Insert the right magic to jump to the module definition.
 299     local($_) = @_;
 300     my $key = next_optional_argument();
 301     my $module = next_argument();
 302     $key = $module
 303         unless $key;
 304     return "<tt class=\"module\"><a href=\"module-$key.html\">$module</a></tt>"
 305       . $_;
 306 }
 307
 308 sub do_cmd_newsgroup{
 309     local($_) = @_;
 310     my $newsgroup = next_argument();
 311     my $icon = get_link_icon("news:$newsgroup");
 312     my $stuff = ("<a class=\"newsgroup\" href=\"news:$newsgroup\">"
 313                  . "$newsgroup$icon</a>");
 314     return $stuff . $_;
 315 }
 316
 317 sub do_cmd_envvar{
 318     local($_) = @_;
 319     my $envvar = next_argument();
 320     my($name, $aname, $ahref) = new_link_info();
 321     # The <tt> here is really to keep buildindex.py from making
 322     # the variable name case-insensitive.
 323     add_index_entry("environment variables!$envvar@<tt>$envvar</tt>",
 324                     $ahref);
 325     add_index_entry("$envvar (environment variable)", $ahref);
 326     $aname =~ s/<a/<a class="envvar"/;
 327     return "$aname$envvar</a>" . $_;
 328 }
 329
 330 sub do_cmd_url{
 331     # use the URL as both text and hyperlink
 332     local($_) = @_;
 333     my $url = next_argument();
 334     my $icon = get_link_icon($url);
 335     $url =~ s/~/&#126;/g;
 336     return "<a class=\"url\" href=\"$url\">$url$icon</a>" . $_;
 337 }
 338
 339 sub do_cmd_manpage{
 340     # two parameters:  \manpage{name}{section}
 341     local($_) = @_;
 342     my $page = next_argument();
 343     my $section = next_argument();
 344     return "<span class=\"manpage\"><i>$page</i>($section)</span>" . $_;
 345 }
 346
 347 $PEP_FORMAT = "http://www.python.org/peps/pep-%04d.html";
 348 #$RFC_FORMAT = "http://www.ietf.org/rfc/rfc%04d.txt";
 349 $RFC_FORMAT = "http://www.faqs.org/rfcs/rfc%d.html";
 350
 351 sub get_rfc_url($$){
 352     my($rfcnum, $format) = @_;
 353     return sprintf($format, $rfcnum);
 354 }
 355
 356 sub do_cmd_pep{
 357     local($_) = @_;
 358     my $rfcnumber = next_argument();
 359     my $id = "rfcref-" . ++$global{'max_id'};
 360     my $href = get_rfc_url($rfcnumber, $PEP_FORMAT);
 361     my $icon = get_link_icon($href);
 362     # Save the reference
 363     my $nstr = gen_index_id("Python Enhancement Proposals!PEP $rfcnumber", '');
 364     $index{$nstr} .= make_half_href("$CURRENT_FILE#$id");
 365     return ("<a class=\"rfc\" id='$id' xml:id='$id'\n"
 366             . "href=\"$href\">PEP $rfcnumber$icon</a>" . $_);
 367 }
 368
 369 sub do_cmd_rfc{
 370     local($_) = @_;
 371     my $rfcnumber = next_argument();
 372     my $id = "rfcref-" . ++$global{'max_id'};
 373     my $href = get_rfc_url($rfcnumber, $RFC_FORMAT);
 374     my $icon = get_link_icon($href);
 375     # Save the reference
 376     my $nstr = gen_index_id("RFC!RFC $rfcnumber", '');
 377     $index{$nstr} .= make_half_href("$CURRENT_FILE#$id");
 378     return ("<a class=\"rfc\" id='$id' xml:id='$id'\nhref=\"$href\">"
 379             . "RFC $rfcnumber$icon</a>" . $_);
 380 }
 381
 382 sub do_cmd_ulink{
 383     local($_) = @_;
 384     my $text = next_argument();
 385     my $url = next_argument();
 386     return "<a class=\"ulink\" href=\"$url\"\n  >$text</a>" . $_;
 387 }
 388
 389 sub do_cmd_citetitle{
 390     local($_) = @_;
 391     my $url = next_optional_argument();
 392     my $title = next_argument();
 393     my $icon = get_link_icon($url);
 394     my $repl = '';
 395     if ($url) {
 396         my $titletext = strip_html_markup("$title");
 397         $repl = ("<em class=\"citetitle\"><a\n"
 398                  . " href=\"$url\"\n"
 399                  . " title=\"$titletext\"\n"
 400                  . " >$title$icon</a></em>");
 401     }
 402     else {
 403         $repl = "<em class=\"citetitle\"\n >$title</em>";
 404     }
 405     return $repl . $_;
 406 }
 407
 408 sub do_cmd_deprecated{
 409     # two parameters:  \deprecated{version}{whattodo}
 410     local($_) = @_;
 411     my $release = next_argument();
 412     my $reason = next_argument();
 413     return ('<div class="versionnote">'
 414             . "<b>Deprecated since release $release.</b>"
 415             . "\n$reason</div><p></p>"
 416             . $_);
 417 }
 418
 419 sub versionnote($$){
 420     # one or two parameters:  \versionnote[explanation]{version}
 421     my $type = $_[0];
 422     local $_ = $_[1];
 423     my $explanation = next_optional_argument();
 424     my $release = next_argument();
 425     my $text = "$type in version $release.";
 426     if ($explanation) {
 427         $text = "$type in version $release:\n$explanation.";
 428     }
 429     return "\n<span class=\"versionnote\">$text</span>\n" . $_;
 430 }
 431
 432 sub do_cmd_versionadded{
 433     return versionnote('New', $_[0]);
 434 }
 435
 436 sub do_cmd_versionchanged{
 437     return versionnote('Changed', $_[0]);
 438 }
 439
 440 #
 441 # These function handle platform dependency tracking.
 442 #
 443 sub do_cmd_platform{
 444     local($_) = @_;
 445     my $platform = next_argument();
 446     $ModulePlatforms{"<tt class=\"module\">$THIS_MODULE</tt>"} = $platform;
 447     $platform = "Macintosh"
 448       if $platform eq 'Mac';
 449     return "\n<p class=\"availability\">Availability: <span"
 450       . "\n class=\"platform\">$platform</span>.</p>\n" . $_;
 451 }
 452
 453 $IGNORE_PLATFORM_ANNOTATION = '';
 454 sub do_cmd_ignorePlatformAnnotation{
 455     local($_) = @_;
 456     $IGNORE_PLATFORM_ANNOTATION = next_argument();
 457     return $_;
 458 }
 459
 460
 461 # index commands
 462
 463 $INDEX_SUBITEM = "";
 464
 465 sub get_indexsubitem(){
 466     return $INDEX_SUBITEM ? " $INDEX_SUBITEM" : '';
 467 }
 468
 469 sub do_cmd_setindexsubitem{
 470     local($_) = @_;
 471     $INDEX_SUBITEM = next_argument();
 472     return $_;
 473 }
 474
 475 sub do_cmd_withsubitem{
 476     # We can't really do the right thing, because LaTeX2HTML doesn't
 477     # do things in the right order, but we need to at least strip this stuff
 478     # out, and leave anything that the second argument expanded out to.
 479     #
 480     local($_) = @_;
 481     my $oldsubitem = $INDEX_SUBITEM;
 482     $INDEX_SUBITEM = next_argument();
 483     my $stuff = next_argument();
 484     my $br_id = ++$globals{'max_id'};
 485     my $marker = "$O$br_id$C";
 486     $stuff =~ s/^\s+//;
 487     return
 488       $stuff
 489       . "\\setindexsubitem$marker$oldsubitem$marker"
 490       . $_;
 491 }
 492
 493 # This is the prologue macro which is required to start writing the
 494 # mod\jobname.idx file; we can just ignore it.  (Defining this suppresses
 495 # a warning that \makemodindex is unknown.)
 496 #
 497 sub do_cmd_makemodindex{ return $_[0]; }
 498
 499 # We're in the document subdirectory when this happens!
 500 #
 501 open(IDXFILE, '>index.dat') || die "\n$!\n";
 502 open(INTLABELS, '>intlabels.pl') || die "\n$!\n";
 503 print INTLABELS "%internal_labels = ();\n";
 504 print INTLABELS "1;             # hack in case there are no entries\n\n";
 505
 506 # Using \0 for this is bad because we can't use common tools to work with the
 507 # resulting files.  Things like grep can be useful with this stuff!
 508 #
 509 $IDXFILE_FIELD_SEP = "\1";
 510
 511 sub write_idxfile($$){
 512     my($ahref, $str) = @_;
 513     print IDXFILE $ahref, $IDXFILE_FIELD_SEP, $str, "\n";
 514 }
 515
 516
 517 sub gen_link($$){
 518     my($node, $target) = @_;
 519     print INTLABELS "\$internal_labels{\"$target\"} = \"/$node\";\n";
 520     return "<a href=\"$node#$target\">";
 521 }
 522
 523 sub add_index_entry($$){
 524     # add an entry to the index structures; ignore the return value
 525     my($str, $ahref) = @_;
 526     $str = gen_index_id($str, '');
 527     $index{$str} .= $ahref;
 528     write_idxfile($ahref, $str);
 529 }
 530
 531 sub new_link_name_info(){
 532     my $name = "l2h-" . ++$globals{'max_id'};
 533     my $ahref = gen_link($CURRENT_FILE, $name);
 534     return ($name, $ahref);
 535 }
 536
 537 sub new_link_info(){
 538     my($name, $ahref) = new_link_name_info();
 539     my $aname = "<a id='$name' xml:id='$name'>";
 540     return ($name, $aname, $ahref);
 541 }
 542
 543 $IndexMacroPattern = '';
 544 sub define_indexing_macro(@){
 545     my $count = @_;
 546     my $i = 0;
 547     for (; $i < $count; ++$i) {
 548         my $name = $_[$i];
 549         my $cmd = "idx_cmd_$name";
 550         die "\nNo function $cmd() defined!\n"
 551           if (!defined &$cmd);
 552         eval ("sub do_cmd_$name { return process_index_macros("
 553               . "\$_[0], '$name'); }");
 554         if (length($IndexMacroPattern) == 0) {
 555             $IndexMacroPattern = "$name";
 556         }
 557         else {
 558             $IndexMacroPattern .= "|$name";
 559         }
 560     }
 561 }
 562
 563 $DEBUG_INDEXING = 0;
 564 sub process_index_macros($$){
 565     local($_) = @_;
 566     my $cmdname = $_[1];        # This is what triggered us in the first place;
 567                                 # we know it's real, so just process it.
 568     my($name, $aname, $ahref) = new_link_info();
 569     my $cmd = "idx_cmd_$cmdname";
 570     print "\nIndexing: \\$cmdname"
 571       if $DEBUG_INDEXING;
 572     &$cmd($ahref);              # modifies $_ and adds index entries
 573     while (/^[\s\n]*\\($IndexMacroPattern)</) {
 574         $cmdname = "$1";
 575         print " \\$cmdname"
 576           if $DEBUG_INDEXING;
 577         $cmd = "idx_cmd_$cmdname";
 578         if (!defined &$cmd) {
 579             last;
 580         }
 581         else {
 582             s/^[\s\n]*\\$cmdname//;
 583             &$cmd($ahref);
 584         }
 585     }
 586 # XXX I don't remember why I added this to begin with.
 587 #     if (/^[ \t\r\n]/) {
 588 #         $_ = substr($_, 1);
 589 #     }
 590     return "$aname$anchor_invisible_mark</a>" . $_;
 591 }
 592
 593 define_indexing_macro('index');
 594 sub idx_cmd_index($){
 595     my $str = next_argument();
 596     add_index_entry("$str", $_[0]);
 597 }
 598
 599 define_indexing_macro('kwindex');
 600 sub idx_cmd_kwindex($){
 601     my $str = next_argument();
 602     add_index_entry("<tt>$str</tt>!keyword", $_[0]);
 603     add_index_entry("keyword!<tt>$str</tt>", $_[0]);
 604 }
 605
 606 define_indexing_macro('indexii');
 607 sub idx_cmd_indexii($){
 608     my $str1 = next_argument();
 609     my $str2 = next_argument();
 610     add_index_entry("$str1!$str2", $_[0]);
 611     add_index_entry("$str2!$str1", $_[0]);
 612 }
 613
 614 define_indexing_macro('indexiii');
 615 sub idx_cmd_indexiii($){
 616     my $str1 = next_argument();
 617     my $str2 = next_argument();
 618     my $str3 = next_argument();
 619     add_index_entry("$str1!$str2 $str3", $_[0]);
 620     add_index_entry("$str2!$str3, $str1", $_[0]);
 621     add_index_entry("$str3!$str1 $str2", $_[0]);
 622 }
 623
 624 define_indexing_macro('indexiv');
 625 sub idx_cmd_indexiv($){
 626     my $str1 = next_argument();
 627     my $str2 = next_argument();
 628     my $str3 = next_argument();
 629     my $str4 = next_argument();
 630     add_index_entry("$str1!$str2 $str3 $str4", $_[0]);
 631     add_index_entry("$str2!$str3 $str4, $str1", $_[0]);
 632     add_index_entry("$str3!$str4, $str1 $str2", $_[0]);
 633     add_index_entry("$str4!$str1 $str2 $str3", $_[0]);
 634 }
 635
 636 define_indexing_macro('ttindex');
 637 sub idx_cmd_ttindex($){
 638     my $str = codetext(next_argument());
 639     my $entry = $str . get_indexsubitem();
 640     add_index_entry($entry, $_[0]);
 641 }
 642
 643 sub my_typed_index_helper($$){
 644     my($word, $ahref) = @_;
 645     my $str = next_argument();
 646     add_index_entry("$str $word", $ahref);
 647     add_index_entry("$word!$str", $ahref);
 648 }
 649
 650 define_indexing_macro('stindex', 'opindex', 'exindex', 'obindex');
 651 sub idx_cmd_stindex($){ my_typed_index_helper('statement', $_[0]); }
 652 sub idx_cmd_opindex($){ my_typed_index_helper('operator', $_[0]); }
 653 sub idx_cmd_exindex($){ my_typed_index_helper('exception', $_[0]); }
 654 sub idx_cmd_obindex($){ my_typed_index_helper('object', $_[0]); }
 655
 656 define_indexing_macro('bifuncindex');
 657 sub idx_cmd_bifuncindex($){
 658     my $str = next_argument();
 659     add_index_entry("<tt class=\"function\">$str()</tt> (built-in function)",
 660                     $_[0]);
 661 }
 662
 663
 664 sub make_mod_index_entry($$){
 665     my($str, $define) = @_;
 666     my($name, $aname, $ahref) = new_link_info();
 667     # equivalent of add_index_entry() using $define instead of ''
 668     $ahref =~ s/\#[-_a-zA-Z0-9]*\"/\"/
 669       if ($define eq 'DEF');
 670     $str = gen_index_id($str, $define);
 671     $index{$str} .= $ahref;
 672     write_idxfile($ahref, $str);
 673
 674     if ($define eq 'DEF') {
 675         # add to the module index
 676         $str =~ /(<tt.*<\/tt>)/;
 677         my $nstr = $1;
 678         $Modules{$nstr} .= $ahref;
 679     }
 680     return "$aname$anchor_invisible_mark2</a>";
 681 }
 682
 683
 684 $THIS_MODULE = '';
 685 $THIS_CLASS = '';
 686
 687 sub define_module($$){
 688     my($word, $name) = @_;
 689     my $section_tag = join('', @curr_sec_id);
 690     if ($word ne "built-in" && $word ne "extension"
 691         && $word ne "standard" && $word ne "") {
 692         write_warnings("Bad module type '$word'"
 693                        . " for \\declaremodule (module $name)");
 694         $word = "";
 695     }
 696     $word = "$word " if $word;
 697     $THIS_MODULE = "$name";
 698     $INDEX_SUBITEM = "(in module $name)";
 699     print "[$name]";
 700     return make_mod_index_entry(
 701         "<tt class=\"module\">$name</tt> (${word}module)", 'DEF');
 702 }
 703
 704 sub my_module_index_helper($$){
 705     local($word, $_) = @_;
 706     my $name = next_argument();
 707     return define_module($word, $name) . $_;
 708 }
 709
 710 sub do_cmd_modindex{ return my_module_index_helper('', $_[0]); }
 711 sub do_cmd_bimodindex{ return my_module_index_helper('built-in', $_[0]); }
 712 sub do_cmd_exmodindex{ return my_module_index_helper('extension', $_[0]); }
 713 sub do_cmd_stmodindex{ return my_module_index_helper('standard', $_[0]); }
 714 #     local($_) = @_;
 715 #     my $name = next_argument();
 716 #     return define_module('standard', $name) . $_;
 717 # }
 718
 719 sub ref_module_index_helper($$){
 720     my($word, $ahref) = @_;
 721     my $str = next_argument();
 722     $word = "$word " if $word;
 723     $str = "<tt class=\"module\">$str</tt> (${word}module)";
 724     # can't use add_index_entry() since the 2nd arg to gen_index_id() is used;
 725     # just inline it all here
 726     $str = gen_index_id($str, 'REF');
 727     $index{$str} .= $ahref;
 728     write_idxfile($ahref, $str);
 729 }
 730
 731 # these should be adjusted a bit....
 732 define_indexing_macro('refmodindex', 'refbimodindex',
 733                       'refexmodindex', 'refstmodindex');
 734 sub idx_cmd_refmodindex($){
 735     return ref_module_index_helper('', $_[0]); }
 736 sub idx_cmd_refbimodindex($){
 737     return ref_module_index_helper('built-in', $_[0]); }
 738 sub idx_cmd_refexmodindex($){
 739     return ref_module_index_helper('extension', $_[0]);}
 740 sub idx_cmd_refstmodindex($){
 741     return ref_module_index_helper('standard', $_[0]); }
 742
 743 sub do_cmd_nodename{ return do_cmd_label($_[0]); }
 744
 745 sub init_myformat(){
 746     # This depends on the override of text_cleanup() in l2hinit.perl;
 747     # if that function cleans out empty tags, the first three of these
 748     # variables must be set to comments.
 749     #
 750     # Thanks to Dave Kuhlman for figuring why some named anchors were
 751     # being lost.
 752     $anchor_invisible_mark = '';
 753     $anchor_invisible_mark2 = '';
 754     $anchor_mark = '';
 755     $icons{'anchor_mark'} = '';
 756 }
 757 init_myformat();
 758
 759 # Create an index entry, but include the string in the target anchor
 760 # instead of the dummy filler.
 761 #
 762 sub make_str_index_entry($){
 763     my $str = $_[0];
 764     my($name, $ahref) = new_link_name_info();
 765     add_index_entry($str, $ahref);
 766     if ($str =~ /^<[a-z]+\b/) {
 767         my $s = "$str";
 768         $s =~ s/^<([a-z]+)\b/<$1 id='$name' xml:id='$name'/;
 769         return $s;
 770     }
 771     else {
 772         return "<a id='$name' xml:id='$name'>$str</a>";
 773     }
 774 }
 775
 776
 777 %TokenToTargetMapping = ();     # language:token -> link target
 778 %DefinedGrammars = ();          # language -> full grammar text
 779 %BackpatchGrammarFiles = ();    # file -> 1 (hash of files to fixup)
 780
 781 sub do_cmd_token{
 782     local($_) = @_;
 783     my $token = next_argument();
 784     my $target = $TokenToTargetMapping{"$CURRENT_GRAMMAR:$token"};
 785     if ($token eq $CURRENT_TOKEN || $CURRENT_GRAMMAR eq '*') {
 786         # recursive definition or display-only productionlist
 787         return "$token";
 788     }
 789     if ($target eq '') {
 790         $target = "<pyGrammarToken><$CURRENT_GRAMMAR><$token>";
 791         if (! $BackpatchGrammarFiles{"$CURRENT_FILE"}) {
 792             print "Adding '$CURRENT_FILE' to back-patch list.\n";
 793         }
 794         $BackpatchGrammarFiles{"$CURRENT_FILE"} = 1;
 795     }
 796     return "<a class='grammartoken' href=\"$target\">$token</a>" . $_;
 797 }
 798
 799 sub do_cmd_grammartoken{
 800     return do_cmd_token(@_);
 801 }
 802
 803 sub do_env_productionlist{
 804     local($_) = @_;
 805     my $lang = next_optional_argument();
 806     my $filename = "grammar-$lang.txt";
 807     if ($lang eq '') {
 808         $filename = 'grammar.txt';
 809     }
 810     local($CURRENT_GRAMMAR) = $lang;
 811     $DefinedGrammars{$lang} .= $_;
 812     return ("<dl><dd class=\"grammar\">\n"
 813             . "<div class=\"productions\">\n"
 814             . "<table>\n"
 815             . translate_commands(translate_environments($_))
 816             . "</table>\n"
 817             . "</div>\n"
 818             . (($lang eq '*')
 819                ? ''
 820                : ("<a class=\"grammar-footer\"\n"
 821                   . "  href=\"$filename\" type=\"text/plain\"\n"
 822                   . "  >Download entire grammar as text.</a>\n"))
 823             . "</dd></dl>");
 824 }
 825
 826 sub do_cmd_production{
 827     local($_) = @_;
 828     my $token = next_argument();
 829     my $defn = next_argument();
 830     my $lang = $CURRENT_GRAMMAR;
 831     local($CURRENT_TOKEN) = $token;
 832     if ($lang eq '*') {
 833         return ("<tr>\n"
 834                 . "    <td>$token</td>\n"
 835                 . "    <td>::=</td>\n"
 836                 . "    <td>"
 837                 . translate_commands($defn)
 838                 . "</td></tr>"
 839                 . $_);
 840     }
 841     my $target;
 842     if ($lang eq '') {
 843         $target = "$CURRENT_FILE\#tok-$token";
 844     }
 845     else {
 846         $target = "$CURRENT_FILE\#tok-$lang-$token";
 847     }
 848     $TokenToTargetMapping{"$CURRENT_GRAMMAR:$token"} = $target;
 849     return ("<tr>\n"
 850             . "    <td><a id='tok-$token' xml:id='tok-$token'>"
 851             . "$token</a></td>\n"
 852             . "    <td>::=</td>\n"
 853             . "    <td>"
 854             . translate_commands($defn)
 855             . "</td></tr>"
 856             . $_);
 857 }
 858
 859 sub do_cmd_productioncont{
 860     local($_) = @_;
 861     my $defn = next_argument();
 862     $defn =~ s/^( +)/'&nbsp;' x length $1/e;
 863     return ("<tr>\n"
 864             . "    <td></td>\n"
 865             . "    <td></td>\n"
 866             . "    <td><code>"
 867             . translate_commands($defn)
 868             . "</code></td></tr>"
 869             . $_);
 870 }
 871
 872 sub process_grammar_files(){
 873     my $lang;
 874     my $filename;
 875     local($_);
 876     print "process_grammar_files()\n";
 877     foreach $lang (keys %DefinedGrammars) {
 878         $filename = "grammar-$lang.txt";
 879         if ($lang eq '*') {
 880             next;
 881         }
 882         if ($lang eq '') {
 883             $filename = 'grammar.txt';
 884         }
 885         open(GRAMMAR, ">$filename") || die "\n$!\n";
 886         print GRAMMAR strip_grammar_markup($DefinedGrammars{$lang});
 887         close(GRAMMAR);
 888         print "Wrote grammar file $filename\n";
 889     }
 890     my $PATTERN = '<pyGrammarToken><([^>]*)><([^>]*)>';
 891     foreach $filename (keys %BackpatchGrammarFiles) {
 892         print "\nBack-patching grammar links in $filename\n";
 893         my $buffer;
 894         open(GRAMMAR, "<$filename") || die "\n$!\n";
 895         # read all of the file into the buffer
 896         sysread(GRAMMAR, $buffer, 1024*1024);
 897         close(GRAMMAR);
 898         while ($buffer =~ /$PATTERN/) {
 899             my($lang, $token) = ($1, $2);
 900             my $target = $TokenToTargetMapping{"$lang:$token"};
 901             my $source = "<pyGrammarToken><$lang><$token>";
 902             $buffer =~ s/$source/$target/g;
 903         }
 904         open(GRAMMAR, ">$filename") || die "\n$!\n";
 905         print GRAMMAR $buffer;
 906         close(GRAMMAR);
 907     }
 908 }
 909
 910 sub strip_grammar_markup($){
 911     local($_) = @_;
 912     s/\\productioncont/              /g;
 913     s/\\production(<<\d+>>)(.+)\1/\n$2 ::= /g;
 914     s/\\token(<<\d+>>)(.+)\1/$2/g;
 915     s/\\e([^a-zA-Z])/\\$1/g;
 916     s/<<\d+>>//g;
 917     s/;SPMgt;/>/g;
 918     s/;SPMlt;/</g;
 919     s/;SPMquot;/\"/g;
 920     return $_;
 921 }
 922
 923
 924 $REFCOUNTS_LOADED = 0;
 925
 926 sub load_refcounts(){
 927     $REFCOUNTS_LOADED = 1;
 928
 929     my($myname, $mydir, $myext) = fileparse(__FILE__, '\..*');
 930     chop $mydir;                        # remove trailing '/'
 931     ($myname, $mydir, $myext) = fileparse($mydir, '\..*');
 932     chop $mydir;                        # remove trailing '/'
 933     $mydir = getcwd() . "$dd$mydir"
 934       unless $mydir =~ s|^/|/|;
 935     local $_;
 936     my $filename = "$mydir${dd}api${dd}refcounts.dat";
 937     open(REFCOUNT_FILE, "<$filename") || die "\n$!\n";
 938     print "[loading API refcount data]";
 939     while (<REFCOUNT_FILE>) {
 940         if (/([a-zA-Z0-9_]+):PyObject\*:([a-zA-Z0-9_]*):(0|[-+]1|null):(.*)$/) {
 941             my($func, $param, $count, $comment) = ($1, $2, $3, $4);
 942             #print "\n$func($param) --> $count";
 943             $REFCOUNTS{"$func:$param"} = $count;
 944         }
 945     }
 946 }
 947
 948 sub get_refcount($$){
 949     my($func, $param) = @_;
 950     load_refcounts()
 951         unless $REFCOUNTS_LOADED;
 952     return $REFCOUNTS{"$func:$param"};
 953 }
 954
 955
 956 $TLSTART = '<span class="typelabel">';
 957 $TLEND   = '</span>&nbsp;';
 958
 959 sub cfuncline_helper($$$){
 960     my($type, $name, $args) = @_;
 961     my $idx = make_str_index_entry(
 962         "<tt class=\"cfunction\">$name()</tt>" . get_indexsubitem());
 963     $idx =~ s/ \(.*\)//;
 964     $idx =~ s/\(\)//;           # ???? - why both of these?
 965     $args =~ s/(\s|\*)([a-z_][a-z_0-9]*),/$1<var>$2<\/var>,/g;
 966     $args =~ s/(\s|\*)([a-z_][a-z_0-9]*)$/$1<var>$2<\/var>/s;
 967     return ('<table cellpadding="0" cellspacing="0"><tr valign="baseline">'
 968             . "<td><nobr>$type\&nbsp;<b>$idx</b>(</nobr></td>"
 969             . "<td>$args)</td>"
 970             . '</tr></table>');
 971 }
 972 sub do_cmd_cfuncline{
 973     local($_) = @_;
 974     my $type = next_argument();
 975     my $name = next_argument();
 976     my $args = next_argument();
 977     my $siginfo = cfuncline_helper($type, $name, $args);
 978     return "<dt>$siginfo\n<dd>" . $_;
 979 }
 980 sub do_env_cfuncdesc{
 981     local($_) = @_;
 982     my $type = next_argument();
 983     my $name = next_argument();
 984     my $args = next_argument();
 985     my $siginfo = cfuncline_helper($type, $name, $args);
 986     my $result_rc = get_refcount($name, '');
 987     my $rcinfo = '';
 988     if ($result_rc eq '+1') {
 989         $rcinfo = 'New reference';
 990     }
 991     elsif ($result_rc eq '0') {
 992         $rcinfo = 'Borrowed reference';
 993     }
 994     elsif ($result_rc eq 'null') {
 995         $rcinfo = 'Always <tt class="constant">NULL</tt>';
 996     }
 997     if ($rcinfo ne '') {
 998         $rcinfo = (  "\n<div class=\"refcount-info\">"
 999                    . "\n  <span class=\"label\">Return value:</span>"
1000                    . "\n  <span class=\"value\">$rcinfo.</span>"
1001                    . "\n</div>");
1002     }
1003     return "<dl><dt>$siginfo</dt>\n<dd>"
1004            . $rcinfo
1005            . $_
1006            . '</dd></dl>';
1007 }
1008
1009 sub do_cmd_cmemberline{
1010     local($_) = @_;
1011     my $container = next_argument();
1012     my $type = next_argument();
1013     my $name = next_argument();
1014     my $idx = make_str_index_entry("<tt class=\"cmember\">$name</tt>"
1015                                    . " ($container member)");
1016     $idx =~ s/ \(.*\)//;
1017     return "<dt>$type <b>$idx</b></dt>\n<dd>"
1018            . $_;
1019 }
1020 sub do_env_cmemberdesc{
1021     local($_) = @_;
1022     my $container = next_argument();
1023     my $type = next_argument();
1024     my $name = next_argument();
1025     my $idx = make_str_index_entry("<tt class=\"cmember\">$name</tt>"
1026                                    . " ($container member)");
1027     $idx =~ s/ \(.*\)//;
1028     return "<dl><dt>$type <b>$idx</b></dt>\n<dd>"
1029            . $_
1030            . '</dl>';
1031 }
1032
1033 sub do_env_csimplemacrodesc{
1034     local($_) = @_;
1035     my $name = next_argument();
1036     my $idx = make_str_index_entry("<tt class=\"macro\">$name</tt>");
1037     return "<dl><dt><b>$idx</b></dt>\n<dd>"
1038            . $_
1039            . '</dl>'
1040 }
1041
1042 sub do_env_ctypedesc{
1043     local($_) = @_;
1044     my $index_name = next_optional_argument();
1045     my $type_name = next_argument();
1046     $index_name = $type_name
1047       unless $index_name;
1048     my($name, $aname, $ahref) = new_link_info();
1049     add_index_entry("<tt class=\"ctype\">$index_name</tt> (C type)", $ahref);
1050     return "<dl><dt><b><tt class=\"ctype\">$aname$type_name</a></tt></b></dt>"
1051            . "\n<dd>"
1052            . $_
1053            . '</dl>'
1054 }
1055
1056 sub do_env_cvardesc{
1057     local($_) = @_;
1058     my $var_type = next_argument();
1059     my $var_name = next_argument();
1060     my $idx = make_str_index_entry("<tt class=\"cdata\">$var_name</tt>"
1061                                    . get_indexsubitem());
1062     $idx =~ s/ \(.*\)//;
1063     return "<dl><dt>$var_type <b>$idx</b></dt>\n"
1064            . '<dd>'
1065            . $_
1066            . '</dd></dl>';
1067 }
1068
1069 sub convert_args($){
1070     local($IN_DESC_HANDLER) = 1;
1071     local($_) = @_;
1072     return translate_commands($_);
1073 }
1074
1075 sub funcline_helper($$$){
1076     my($first, $idxitem, $arglist) = @_;
1077     return (($first ? '<dl>' : '')
1078             . '<dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">'
1079             . "\n  <td><nobr><b>$idxitem</b>(</nobr></td>"
1080             . "\n  <td><var>$arglist</var>)</td></tr></table></dt>\n<dd>");
1081 }
1082
1083 sub do_env_funcdesc{
1084     local($_) = @_;
1085     my $function_name = next_argument();
1086     my $arg_list = convert_args(next_argument());
1087     my $idx = make_str_index_entry("<tt class=\"function\">$function_name()"
1088                                    . '</tt>'
1089                                    . get_indexsubitem());
1090     $idx =~ s/ \(.*\)//;
1091     $idx =~ s/\(\)<\/tt>/<\/tt>/;
1092     return funcline_helper(1, $idx, $arg_list) . $_ . '</dl>';
1093 }
1094
1095 sub do_env_funcdescni{
1096     local($_) = @_;
1097     my $function_name = next_argument();
1098     my $arg_list = convert_args(next_argument());
1099     my $prefix = "<tt class=\"function\">$function_name</tt>";
1100     return funcline_helper(1, $prefix, $arg_list) . $_ . '</dl>';
1101 }
1102
1103 sub do_cmd_funcline{
1104     local($_) = @_;
1105     my $function_name = next_argument();
1106     my $arg_list = convert_args(next_argument());
1107     my $prefix = "<tt class=\"function\">$function_name()</tt>";
1108     my $idx = make_str_index_entry($prefix . get_indexsubitem());
1109     $prefix =~ s/\(\)//;
1110
1111     return funcline_helper(0, $prefix, $arg_list) . $_;
1112 }
1113
1114 sub do_cmd_funclineni{
1115     local($_) = @_;
1116     my $function_name = next_argument();
1117     my $arg_list = convert_args(next_argument());
1118     my $prefix = "<tt class=\"function\">$function_name</tt>";
1119
1120     return funcline_helper(0, $prefix, $arg_list) . $_;
1121 }
1122
1123 # Change this flag to index the opcode entries.  I don't think it's very
1124 # useful to index them, since they're only presented to describe the dis
1125 # module.
1126 #
1127 $INDEX_OPCODES = 0;
1128
1129 sub do_env_opcodedesc{
1130     local($_) = @_;
1131     my $opcode_name = next_argument();
1132     my $arg_list = next_argument();
1133     my $idx;
1134     if ($INDEX_OPCODES) {
1135         $idx = make_str_index_entry("<tt class=\"opcode\">$opcode_name</tt>"
1136                                     . ' (byte code instruction)');
1137         $idx =~ s/ \(byte code instruction\)//;
1138     }
1139     else {
1140         $idx = "<tt class=\"opcode\">$opcode_name</tt>";
1141     }
1142     my $stuff = "<dl><dt><b>$idx</b>";
1143     if ($arg_list) {
1144         $stuff .= "&nbsp;&nbsp;&nbsp;&nbsp;<var>$arg_list</var>";
1145     }
1146     return $stuff . "</dt>\n<dd>" . $_ . '</dt></dl>';
1147 }
1148
1149 sub do_env_datadesc{
1150     local($_) = @_;
1151     my $dataname = next_argument();
1152     my $idx = make_str_index_entry("<tt>$dataname</tt>" . get_indexsubitem());
1153     $idx =~ s/ \(.*\)//;
1154     return "<dl><dt><b>$idx</b></dt>\n<dd>"
1155            . $_
1156            . '</dd></dl>';
1157 }
1158
1159 sub do_env_datadescni{
1160     local($_) = @_;
1161     my $idx = next_argument();
1162     if (! $STRING_INDEX_TT) {
1163         $idx = "<tt>$idx</tt>";
1164     }
1165     return "<dl><dt><b>$idx</b></dt>\n<dd>" . $_ . '</dd></dl>';
1166 }
1167
1168 sub do_cmd_dataline{
1169     local($_) = @_;
1170     my $data_name = next_argument();
1171     my $idx = make_str_index_entry("<tt>$data_name</tt>" . get_indexsubitem());
1172     $idx =~ s/ \(.*\)//;
1173     return "<dt><b>$idx</b></dt><dd>" . $_;
1174 }
1175
1176 sub do_cmd_datalineni{
1177     local($_) = @_;
1178     my $data_name = next_argument();
1179     return "<dt><b><tt>$data_name</tt></b></dt><dd>" . $_;
1180 }
1181
1182 sub do_env_excdesc{
1183     local($_) = @_;
1184     my $excname = next_argument();
1185     my $idx = make_str_index_entry("<tt class=\"exception\">$excname</tt>");
1186     return ("<dl><dt><b>${TLSTART}exception$TLEND$idx</b></dt>"
1187             . "\n<dd>"
1188             . $_
1189             . '</dd></dl>');
1190 }
1191
1192 sub do_env_fulllineitems{ return do_env_itemize(@_); }
1193
1194
1195 sub handle_classlike_descriptor($$){
1196     local($_, $what) = @_;
1197     $THIS_CLASS = next_argument();
1198     my $arg_list = convert_args(next_argument());
1199     $idx = make_str_index_entry(
1200         "<tt class=\"$what\">$THIS_CLASS</tt> ($what in $THIS_MODULE)" );
1201     $idx =~ s/ \(.*\)//;
1202     my $prefix = "$TLSTART$what$TLEND$idx";
1203     return funcline_helper(1, $prefix, $arg_list) . $_ . '</dl>';
1204 }
1205
1206 sub do_env_classdesc{
1207     return handle_classlike_descriptor($_[0], "class");
1208 }
1209
1210 sub do_env_classdescstar{
1211     local($_) = @_;
1212     $THIS_CLASS = next_argument();
1213     $idx = make_str_index_entry(
1214         "<tt class=\"class\">$THIS_CLASS</tt> (class in $THIS_MODULE)");
1215     $idx =~ s/ \(.*\)//;
1216     my $prefix = "${TLSTART}class$TLEND$idx";
1217     # Can't use funcline_helper() since there is no args list.
1218     return "<dl><dt><b>$prefix</b>\n<dd>" . $_ . '</dl>';
1219 }
1220
1221 sub do_env_excclassdesc{
1222     return handle_classlike_descriptor($_[0], "exception");
1223 }
1224
1225
1226 sub do_env_methoddesc{
1227     local($_) = @_;
1228     my $class_name = next_optional_argument();
1229     $class_name = $THIS_CLASS
1230         unless $class_name;
1231     my $method = next_argument();
1232     my $arg_list = convert_args(next_argument());
1233     my $extra = '';
1234     if ($class_name) {
1235         $extra = " ($class_name method)";
1236     }
1237     my $idx = make_str_index_entry(
1238         "<tt class=\"method\">$method()</tt>$extra");
1239     $idx =~ s/ \(.*\)//;
1240     $idx =~ s/\(\)//;
1241     return funcline_helper(1, $idx, $arg_list) . $_ . '</dl>';
1242 }
1243
1244
1245 sub do_cmd_methodline{
1246     local($_) = @_;
1247     my $class_name = next_optional_argument();
1248     $class_name = $THIS_CLASS
1249         unless $class_name;
1250     my $method = next_argument();
1251     my $arg_list = convert_args(next_argument());
1252     my $extra = '';
1253     if ($class_name) {
1254         $extra = " ($class_name method)";
1255     }
1256     my $idx = make_str_index_entry(
1257         "<tt class=\"method\">$method()</tt>$extra");
1258     $idx =~ s/ \(.*\)//;
1259     $idx =~ s/\(\)//;
1260     return funcline_helper(0, $idx, $arg_list) . $_;
1261 }
1262
1263
1264 sub do_cmd_methodlineni{
1265     local($_) = @_;
1266     next_optional_argument();
1267     my $method = next_argument();
1268     my $arg_list = convert_args(next_argument());
1269     return funcline_helper(0, $method, $arg_list) . $_;
1270 }
1271
1272 sub do_env_methoddescni{
1273     local($_) = @_;
1274     next_optional_argument();
1275     my $method = next_argument();
1276     my $arg_list = convert_args(next_argument());
1277     return funcline_helper(1, $method, $arg_list) . $_ . '</dl>';
1278 }
1279
1280
1281 sub do_env_memberdesc{
1282     local($_) = @_;
1283     my $class = next_optional_argument();
1284     my $member = next_argument();
1285     $class = $THIS_CLASS
1286         unless $class;
1287     my $extra = '';
1288     $extra = " ($class attribute)"
1289         if ($class ne '');
1290     my $idx = make_str_index_entry("<tt class=\"member\">$member</tt>$extra");
1291     $idx =~ s/ \(.*\)//;
1292     $idx =~ s/\(\)//;
1293     return "<dl><dt><b>$idx</b></dt>\n<dd>" . $_ . '</dl>';
1294 }
1295
1296
1297 sub do_cmd_memberline{
1298     local($_) = @_;
1299     my $class = next_optional_argument();
1300     my $member = next_argument();
1301     $class = $THIS_CLASS
1302         unless $class;
1303     my $extra = '';
1304     $extra = " ($class attribute)"
1305         if ($class ne '');
1306     my $idx = make_str_index_entry("<tt class=\"member\">$member</tt>$extra");
1307     $idx =~ s/ \(.*\)//;
1308     $idx =~ s/\(\)//;
1309     return "<dt><b>$idx</b></dt><dd>" . $_;
1310 }
1311
1312
1313 sub do_env_memberdescni{
1314     local($_) = @_;
1315     next_optional_argument();
1316     my $member = next_argument();
1317     return "<dl><dt><b><tt class=\"member\">$member</tt></b></dt>\n<dd>"
1318            . $_
1319            . '</dd></dl>';
1320 }
1321
1322
1323 sub do_cmd_memberlineni{
1324     local($_) = @_;
1325     next_optional_argument();
1326     my $member = next_argument();
1327     return "<dt><b><tt class=\"member\">$member</tt></b></dt>\n<dd>" . $_;
1328 }
1329
1330
1331 # For tables, we include a class on every cell to allow the CSS to set
1332 # the text-align property; this is because support for styling columns
1333 # via the <col> element appears nearly non-existant on even the latest
1334 # browsers (Mozilla 1.7 is stable at the time of this writing).
1335 # Hopefully this can be improved as browsers evolve.
1336
1337 @col_aligns = ('<td>', '<td>', '<td>', '<td>', '<td>');
1338
1339 %FontConversions = ('cdata' => 'tt class="cdata"',
1340                     'character' => 'tt class="character"',
1341                     'class' => 'tt class="class"',
1342                     'command' => 'code',
1343                     'constant' => 'tt class="constant"',
1344                     'exception' => 'tt class="exception"',
1345                     'file' => 'tt class="file"',
1346                     'filenq' => 'tt class="file"',
1347                     'kbd' => 'kbd',
1348                     'member' => 'tt class="member"',
1349                     'programopt' => 'b',
1350                     'textrm' => '',
1351                     );
1352
1353 sub fix_font($){
1354     # do a little magic on a font name to get the right behavior in the first
1355     # column of the output table
1356     my $font = $_[0];
1357     if (defined $FontConversions{$font}) {
1358         $font = $FontConversions{$font};
1359     }
1360     return $font;
1361 }
1362
1363 sub figure_column_alignment($){
1364     my $a = $_[0];
1365     if (!defined $a) {
1366         return '';
1367     }
1368     my $mark = substr($a, 0, 1);
1369     my $r = '';
1370     if ($mark eq 'c')
1371       { $r = ' class="center"'; }
1372     elsif ($mark eq 'r')
1373       { $r = ' class="right" '; }
1374     elsif ($mark eq 'l')
1375       { $r = ' class="left"  '; }
1376     elsif ($mark eq 'p')
1377       { $r = ' class="left"  '; }
1378     return $r;
1379 }
1380
1381 sub setup_column_alignments($){
1382     local($_) = @_;
1383     my($s1, $s2, $s3, $s4, $s5) = split(/[|]/,$_);
1384     my $a1 = figure_column_alignment($s1);
1385     my $a2 = figure_column_alignment($s2);
1386     my $a3 = figure_column_alignment($s3);
1387     my $a4 = figure_column_alignment($s4);
1388     my $a5 = figure_column_alignment($s5);
1389     $col_aligns[0] = "<td$a1 valign=\"baseline\">";
1390     $col_aligns[1] = "<td$a2>";
1391     $col_aligns[2] = "<td$a3>";
1392     $col_aligns[3] = "<td$a4>";
1393     $col_aligns[4] = "<td$a5>";
1394     # return the aligned header start tags
1395     return ("<th$a1>", "<th$a2>", "<th$a3>", "<th$a4>", "<th$a5>");
1396 }
1397
1398 sub get_table_col1_fonts(){
1399     my $font = $globals{'lineifont'};
1400     my($sfont, $efont) = ('', '');
1401     if ($font) {
1402         $sfont = "<$font>";
1403         $efont = "</$font>";
1404         $efont =~ s/ .*>/>/;
1405     }
1406     return ($sfont, $efont);
1407 }
1408
1409 sub do_env_tableii{
1410     local($_) = @_;
1411     my $arg = next_argument();
1412     my($th1, $th2, $th3, $th4, $th5) = setup_column_alignments($arg);
1413     my $font = fix_font(next_argument());
1414     my $h1 = next_argument();
1415     my $h2 = next_argument();
1416     s/[\s\n]+//;
1417     $globals{'lineifont'} = $font;
1418     my $a1 = $col_aligns[0];
1419     my $a2 = $col_aligns[1];
1420     s/\\lineii</\\lineii[$a1|$a2]</g;
1421     return '<div class="center"><table class="realtable">'
1422            . "\n  <thead>"
1423            . "\n    <tr>"
1424            . "\n      $th1$h1</th>"
1425            . "\n      $th2$h2</th>"
1426            . "\n      </tr>"
1427            . "\n    </thead>"
1428            . "\n  <tbody>"
1429            . $_
1430            . "\n    </tbody>"
1431            . "\n</table></div>";
1432 }
1433
1434 sub do_env_longtableii{
1435     return do_env_tableii(@_);
1436 }
1437
1438 sub do_cmd_lineii{
1439     local($_) = @_;
1440     my $aligns = next_optional_argument();
1441     my $c1 = next_argument();
1442     my $c2 = next_argument();
1443     s/[\s\n]+//;
1444     my($sfont, $efont) = get_table_col1_fonts();
1445     my($c1align, $c2align) = split('\|', $aligns);
1446     return "\n    <tr>$c1align$sfont$c1$efont</td>\n"
1447            . "        $c2align$c2</td></tr>"
1448            . $_;
1449 }
1450
1451 sub do_env_tableiii{
1452     local($_) = @_;
1453     my $arg = next_argument();
1454     my($th1, $th2, $th3, $th4, $th5) = setup_column_alignments($arg);
1455     my $font = fix_font(next_argument());
1456     my $h1 = next_argument();
1457     my $h2 = next_argument();
1458     my $h3 = next_argument();
1459     s/[\s\n]+//;
1460     $globals{'lineifont'} = $font;
1461     my $a1 = $col_aligns[0];
1462     my $a2 = $col_aligns[1];
1463     my $a3 = $col_aligns[2];
1464     s/\\lineiii</\\lineiii[$a1|$a2|$a3]</g;
1465     return '<div class="center"><table class="realtable">'
1466            . "\n  <thead>"
1467            . "\n    <tr>"
1468            . "\n      $th1$h1</th>"
1469            . "\n      $th2$h2</th>"
1470            . "\n      $th3$h3</th>"
1471            . "\n      </tr>"
1472            . "\n    </thead>"
1473            . "\n  <tbody>"
1474            . $_
1475            . "\n    </tbody>"
1476            . "\n</table></div>";
1477 }
1478
1479 sub do_env_longtableiii{
1480     return do_env_tableiii(@_);
1481 }
1482
1483 sub do_cmd_lineiii{
1484     local($_) = @_;
1485     my $aligns = next_optional_argument();
1486     my $c1 = next_argument();
1487     my $c2 = next_argument();
1488     my $c3 = next_argument();
1489     s/[\s\n]+//;
1490     my($sfont, $efont) = get_table_col1_fonts();
1491     my($c1align, $c2align, $c3align) = split('\|', $aligns);
1492     return "\n    <tr>$c1align$sfont$c1$efont</td>\n"
1493            . "        $c2align$c2</td>\n"
1494            . "        $c3align$c3</td></tr>"
1495            . $_;
1496 }
1497
1498 sub do_env_tableiv{
1499     local($_) = @_;
1500     my $arg = next_argument();
1501     my($th1, $th2, $th3, $th4, $th5) = setup_column_alignments($arg);
1502     my $font = fix_font(next_argument());
1503     my $h1 = next_argument();
1504     my $h2 = next_argument();
1505     my $h3 = next_argument();
1506     my $h4 = next_argument();
1507     s/[\s\n]+//;
1508     $globals{'lineifont'} = $font;
1509     my $a1 = $col_aligns[0];
1510     my $a2 = $col_aligns[1];
1511     my $a3 = $col_aligns[2];
1512     my $a4 = $col_aligns[3];
1513     s/\\lineiv</\\lineiv[$a1|$a2|$a3|$a4]</g;
1514     return '<div class="center"><table class="realtable">'
1515            . "\n  <thead>"
1516            . "\n    <tr>"
1517            . "\n      $th1$h1</th>"
1518            . "\n      $th2$h2</th>"
1519            . "\n      $th3$h3</th>"
1520            . "\n      $th4$h4</th>"
1521            . "\n      </tr>"
1522            . "\n    </thead>"
1523            . "\n  <tbody>"
1524            . $_
1525            . "\n    </tbody>"
1526            . "\n</table></div>";
1527 }
1528
1529 sub do_env_longtableiv{
1530     return do_env_tableiv(@_);
1531 }
1532
1533 sub do_cmd_lineiv{
1534     local($_) = @_;
1535     my $aligns = next_optional_argument();
1536     my $c1 = next_argument();
1537     my $c2 = next_argument();
1538     my $c3 = next_argument();
1539     my $c4 = next_argument();
1540     s/[\s\n]+//;
1541     my($sfont, $efont) = get_table_col1_fonts();
1542     my($c1align, $c2align, $c3align, $c4align) = split('\|', $aligns);
1543     return "\n    <tr>$c1align$sfont$c1$efont</td>\n"
1544            . "        $c2align$c2</td>\n"
1545            . "        $c3align$c3</td>\n"
1546            . "        $c4align$c4</td></tr>"
1547            . $_;
1548 }
1549
1550 sub do_env_tablev{
1551     local($_) = @_;
1552     my $arg = next_argument();
1553     my($th1, $th2, $th3, $th4, $th5) = setup_column_alignments($arg);
1554     my $font = fix_font(next_argument());
1555     my $h1 = next_argument();
1556     my $h2 = next_argument();
1557     my $h3 = next_argument();
1558     my $h4 = next_argument();
1559     my $h5 = next_argument();
1560     s/[\s\n]+//;
1561     $globals{'lineifont'} = $font;
1562     my $a1 = $col_aligns[0];
1563     my $a2 = $col_aligns[1];
1564     my $a3 = $col_aligns[2];
1565     my $a4 = $col_aligns[3];
1566     my $a5 = $col_aligns[4];
1567     s/\\linev</\\linev[$a1|$a2|$a3|$a4|$a5]</g;
1568     return '<div class="center"><table class="realtable">'
1569            . "\n  <thead>"
1570            . "\n    <tr>"
1571            . "\n      $th1$h1</th>"
1572            . "\n      $th2$h2</th>"
1573            . "\n      $th3$h3</th>"
1574            . "\n      $th4$h4</th>"
1575            . "\n      $th5$h5</th>"
1576            . "\n      </tr>"
1577            . "\n    </thead>"
1578            . "\n  <tbody>"
1579            . $_
1580            . "\n    </tbody>"
1581            . "\n</table></div>";
1582 }
1583
1584 sub do_env_longtablev{
1585     return do_env_tablev(@_);
1586 }
1587
1588 sub do_cmd_linev{
1589     local($_) = @_;
1590     my $aligns = next_optional_argument();
1591     my $c1 = next_argument();
1592     my $c2 = next_argument();
1593     my $c3 = next_argument();
1594     my $c4 = next_argument();
1595     my $c5 = next_argument();
1596     s/[\s\n]+//;
1597     my($sfont, $efont) = get_table_col1_fonts();
1598     my($c1align, $c2align, $c3align, $c4align, $c5align) = split('\|',$aligns);
1599     return "\n    <tr>$c1align$sfont$c1$efont</td>\n"
1600            . "        $c2align$c2</td>\n"
1601            . "        $c3align$c3</td>\n"
1602            . "        $c4align$c4</td>\n"
1603            . "        $c5align$c5</td></tr>"
1604            . $_;
1605 }
1606
1607
1608 # These can be used to control the title page appearance;
1609 # they need a little bit of documentation.
1610 #
1611 # If $TITLE_PAGE_GRAPHIC is set, it should be the name of a file in the
1612 # $ICONSERVER directory, or include path information (other than "./").  The
1613 # default image type will be assumed if an extension is not provided.
1614 #
1615 # If specified, the "title page" will contain two colums: one containing the
1616 # title/author/etc., and the other containing the graphic.  Use the other
1617 # four variables listed here to control specific details of the layout; all
1618 # are optional.
1619 #
1620 # $TITLE_PAGE_GRAPHIC = "my-company-logo";
1621 # $TITLE_PAGE_GRAPHIC_COLWIDTH = "30%";
1622 # $TITLE_PAGE_GRAPHIC_WIDTH = 150;
1623 # $TITLE_PAGE_GRAPHIC_HEIGHT = 150;
1624 # $TITLE_PAGE_GRAPHIC_ON_RIGHT = 0;
1625
1626 sub make_my_titlepage(){
1627     my $the_title = "";
1628     if ($t_title) {
1629         $the_title .= "\n<h1>$t_title</h1>";
1630     }
1631     else {
1632         write_warnings("\nThis document has no title.");
1633     }
1634     if ($t_author) {
1635         if ($t_authorURL) {
1636             my $href = translate_commands($t_authorURL);
1637             $href = make_named_href('author', $href,
1638                                     "<b><font size=\"+2\">$t_author"
1639                                     . '</font></b>');
1640             $the_title .= "\n<p>$href</p>";
1641         }
1642         else {
1643             $the_title .= ("\n<p><b><font size=\"+2\">$t_author"
1644                            . '</font></b></p>');
1645         }
1646     }
1647     else {
1648         write_warnings("\nThere is no author for this document.");
1649     }
1650     if ($t_institute) {
1651         $the_title .= "\n<p>$t_institute</p>";
1652     }
1653     if ($DEVELOPER_ADDRESS) {
1654         $the_title .= "\n<p>$DEVELOPER_ADDRESS</p>";
1655     }
1656     if ($t_affil) {
1657         $the_title .= "\n<p><i>$t_affil</i></p>";
1658     }
1659     if ($t_date) {
1660         $the_title .= "\n<p>";
1661         if ($PACKAGE_VERSION) {
1662             $the_title .= ('<strong>Release '
1663                            . "$PACKAGE_VERSION$RELEASE_INFO</strong><br />\n");
1664         }
1665         $the_title .= "<strong>$t_date</strong></p>"
1666     }
1667     if ($t_address) {
1668         $the_title .= "\n<p>$t_address</p>";
1669     }
1670     else {
1671         $the_title .= "\n<p></p>";
1672     }
1673     if ($t_email) {
1674         $the_title .= "\n<p>$t_email</p>";
1675     }
1676     return $the_title;
1677 }
1678
1679 sub make_my_titlegraphic(){
1680     my $filename = make_icon_filename($TITLE_PAGE_GRAPHIC);
1681     my $graphic = "<td class=\"titlegraphic\"";
1682     $graphic .= " width=\"$TITLE_PAGE_GRAPHIC_COLWIDTH\""
1683       if ($TITLE_PAGE_GRAPHIC_COLWIDTH);
1684     $graphic .= "><img";
1685     $graphic .= " width=\"$TITLE_PAGE_GRAPHIC_WIDTH\""
1686       if ($TITLE_PAGE_GRAPHIC_WIDTH);
1687     $graphic .= " height=\"$TITLE_PAGE_GRAPHIC_HEIGHT\""
1688       if ($TITLE_PAGE_GRAPHIC_HEIGHT);
1689     $graphic .= "\n  src=\"$filename\" /></td>\n";
1690     return $graphic;
1691 }
1692
1693 sub do_cmd_maketitle{
1694     local($_) = @_;
1695     my $the_title = "\n";
1696     if ($EXTERNAL_UP_LINK) {
1697         # This generates a <link> element in the wrong place (the
1698         # body), but I don't see any other way to get this generated
1699         # at all.  Browsers like Mozilla, that support navigation
1700         # links, can make use of this.
1701         $the_title .= ("<link rel='up' href='$EXTERNAL_UP_LINK'"
1702                        . ($EXTERNAL_UP_TITLE
1703                           ? " title='$EXTERNAL_UP_TITLE'" : '')
1704                        . " />\n");
1705     }
1706     $the_title .= '<div class="titlepage">';
1707     if ($TITLE_PAGE_GRAPHIC) {
1708         if ($TITLE_PAGE_GRAPHIC_ON_RIGHT) {
1709             $the_title .= ("\n<table border=\"0\" width=\"100%\">"
1710                            . "<tr align=\"right\">\n<td>"
1711                            . make_my_titlepage()
1712                            . "</td>\n"
1713                            . make_my_titlegraphic()
1714                            . "</tr>\n</table>");
1715         }
1716         else {
1717             $the_title .= ("\n<table border=\"0\" width=\"100%\"><tr>\n"
1718                            . make_my_titlegraphic()
1719                            . "<td>"
1720                            . make_my_titlepage()
1721                            . "</td></tr>\n</table>");
1722         }
1723     }
1724     else {
1725         $the_title .= ("\n<div class='center'>"
1726                        . make_my_titlepage()
1727                        . "\n</div>");
1728     }
1729     $the_title .= "\n</div>";
1730     return $the_title . $_;
1731 }
1732
1733
1734 #
1735 #  Module synopsis support
1736 #
1737
1738 require SynopsisTable;
1739
1740 sub get_chapter_id(){
1741     my $id = do_cmd_thechapter('');
1742     $id =~ s/<SPAN CLASS="arabic">(\d+)<\/SPAN>/$1/;
1743     $id =~ s/\.//;
1744     return $id;
1745 }
1746
1747 # 'chapter' => 'SynopsisTable instance'
1748 %ModuleSynopses = ();
1749
1750 sub get_synopsis_table($){
1751     my $chap = $_[0];
1752     my $key;
1753     foreach $key (keys %ModuleSynopses) {
1754         if ($key eq $chap) {
1755             return $ModuleSynopses{$chap};
1756         }
1757     }
1758     my $st = SynopsisTable->new();
1759     $ModuleSynopses{$chap} = $st;
1760     return $st;
1761 }
1762
1763 sub do_cmd_moduleauthor{
1764     local($_) = @_;
1765     next_argument();
1766     next_argument();
1767     return $_;
1768 }
1769
1770 sub do_cmd_sectionauthor{
1771     local($_) = @_;
1772     next_argument();
1773     next_argument();
1774     return $_;
1775 }
1776
1777 sub do_cmd_declaremodule{
1778     local($_) = @_;
1779     my $key = next_optional_argument();
1780     my $type = next_argument();
1781     my $name = next_argument();
1782     my $st = get_synopsis_table(get_chapter_id());
1783     #
1784     $key = $name unless $key;
1785     $type = 'built-in' if $type eq 'builtin';
1786     $st->declare($name, $key, $type);
1787     define_module($type, $name);
1788     return anchor_label("module-$key",$CURRENT_FILE,$_)
1789 }
1790
1791 sub do_cmd_modulesynopsis{
1792     local($_) = @_;
1793     my $st = get_synopsis_table(get_chapter_id());
1794     $st->set_synopsis($THIS_MODULE, translate_commands(next_argument()));
1795     return $_;
1796 }
1797
1798 sub do_cmd_localmoduletable{
1799     local($_) = @_;
1800     my $chap = get_chapter_id();
1801     my $st = get_synopsis_table($chap);
1802     $st->set_file("$CURRENT_FILE");
1803     return "<tex2html-localmoduletable><$chap>\\tableofchildlinks[off]" . $_;
1804 }
1805
1806 sub process_all_localmoduletables(){
1807     my $key;
1808     foreach $key (keys %ModuleSynopses) {
1809         my $st = $ModuleSynopses{$key};
1810         my $file = $st->get_file();
1811         if ($file) {
1812             process_localmoduletables_in_file($file);
1813         }
1814         else {
1815             print "\nsynopsis table $key has no file association\n";
1816         }
1817     }
1818 }
1819
1820 sub process_localmoduletables_in_file($){
1821     my $file = $_[0];
1822     open(MYFILE, "<$file");
1823     local($_);
1824     sysread(MYFILE, $_, 1024*1024);
1825     close(MYFILE);
1826     # need to get contents of file in $_
1827     while (/<tex2html-localmoduletable><(\d+)>/) {
1828         my $match = $&;
1829         my $chap = $1;
1830         my $st = get_synopsis_table($chap);
1831         my $data = $st->tohtml();
1832         s/$match/$data/;
1833     }
1834     open(MYFILE,">$file");
1835     print MYFILE $_;
1836     close(MYFILE);
1837 }
1838 sub process_python_state(){
1839     process_all_localmoduletables();
1840     process_grammar_files();
1841 }
1842
1843
1844 #
1845 #  "See also:" -- references placed at the end of a \section
1846 #
1847
1848 sub do_env_seealso{
1849     return ("<div class=\"seealso\">\n  "
1850             . "<p class=\"heading\">See Also:</p>\n"
1851             . $_[0]
1852             . '</div>');
1853 }
1854
1855 sub do_env_seealsostar{
1856     return ("<div class=\"seealso-simple\">\n  "
1857             . $_[0]
1858             . '</div>');
1859 }
1860
1861 sub do_cmd_seemodule{
1862     # Insert the right magic to jump to the module definition.  This should
1863     # work most of the time, at least for repeat builds....
1864     local($_) = @_;
1865     my $key = next_optional_argument();
1866     my $module = next_argument();
1867     my $text = next_argument();
1868     my $period = '.';
1869     $key = $module
1870         unless $key;
1871     if ($text =~ /\.$/) {
1872         $period = '';
1873     }
1874     return ('<dl compact="compact" class="seemodule">'
1875             . "\n    <dt>Module <b><tt class=\"module\">"
1876             . "<a href=\"module-$key.html\">$module</a></tt>:</b>"
1877             . "\n    <dd>$text$period\n  </dl>"
1878             . $_);
1879 }
1880
1881 sub strip_html_markup($){
1882     my $str = $_[0];
1883     my $s = "$str";
1884     $s =~ s/<[a-zA-Z0-9]+(\s+[a-zA-Z0-9]+(\s*=\s*(\'[^\']*\'|\"[^\"]*\"|[a-zA-Z0-9]+))?)*\s*>//g;
1885     $s =~ s/<\/[a-zA-Z0-9]+>//g;
1886     return $s;
1887 }
1888
1889 sub handle_rfclike_reference($$$){
1890     local($_, $what, $format) = @_;
1891     my $rfcnum = next_argument();
1892     my $title = next_argument();
1893     my $text = next_argument();
1894     my $url = get_rfc_url($rfcnum, $format);
1895     my $icon = get_link_icon($url);
1896     my $attrtitle = strip_html_markup($title);
1897     return '<dl compact="compact" class="seerfc">'
1898       . "\n    <dt><a href=\"$url\""
1899       . "\n        title=\"$attrtitle\""
1900       . "\n        >$what $rfcnum, <em>$title</em>$icon</a>"
1901       . "\n    <dd>$text\n  </dl>"
1902       . $_;
1903 }
1904
1905 sub do_cmd_seepep{
1906     return handle_rfclike_reference($_[0], "PEP", $PEP_FORMAT);
1907 }
1908
1909 sub do_cmd_seerfc{
1910     # XXX Would be nice to add links to the text/plain and PDF versions.
1911     return handle_rfclike_reference($_[0], "RFC", $RFC_FORMAT);
1912 }
1913
1914 sub do_cmd_seetitle{
1915     local($_) = @_;
1916     my $url = next_optional_argument();
1917     my $title = next_argument();
1918     my $text = next_argument();
1919     if ($url) {
1920         my $icon = get_link_icon($url);
1921         return '<dl compact="compact" class="seetitle">'
1922           . "\n    <dt><em class=\"citetitle\"><a href=\"$url\""
1923           . "\n        >$title$icon</a></em></dt>"
1924           . "\n    <dd>$text</dd>\n  </dl>"
1925           . $_;
1926     }
1927     return '<dl compact="compact" class="seetitle">'
1928       . "\n    <dt><em class=\"citetitle\""
1929       . "\n        >$title</em></dt>"
1930       . "\n    <dd>$text</dd>\n  </dl>"
1931       . $_;
1932 }
1933
1934 sub do_cmd_seelink{
1935     local($_) = @_;
1936     my $url = next_argument();
1937     my $linktext = next_argument();
1938     my $text = next_argument();
1939     my $icon = get_link_icon($url);
1940     return '<dl compact="compact" class="seeurl">'
1941       . "\n    <dt><a href='$url'"
1942       . "\n        >$linktext$icon</a></dt>"
1943       . "\n    <dd>$text</dd>\n  </dl>"
1944       . $_;
1945 }
1946
1947 sub do_cmd_seeurl{
1948     local($_) = @_;
1949     my $url = next_argument();
1950     my $text = next_argument();
1951     my $icon = get_link_icon($url);
1952     return '<dl compact="compact" class="seeurl">'
1953       . "\n    <dt><a href=\"$url\""
1954       . "\n        class=\"url\">$url$icon</a></dt>"
1955       . "\n    <dd>$text</dd>\n  </dl>"
1956       . $_;
1957 }
1958
1959 sub do_cmd_seetext{
1960     local($_) = @_;
1961     my $content = next_argument();
1962     return '<div class="seetext"><p>' . $content . '</p></div>' . $_;
1963 }
1964
1965
1966 #
1967 #  Definition list support.
1968 #
1969
1970 sub do_env_definitions{
1971     return '<dl class="definitions">' . $_[0] . "</dl>\n";
1972 }
1973
1974 sub do_cmd_term{
1975     local($_) = @_;
1976     my $term = next_argument();
1977     my($name, $aname, $ahref) = new_link_info();
1978     # could easily add an index entry here...
1979     return "<dt><b>$aname" . $term . "</a></b></dt>\n<dd>" . $_;
1980 }
1981
1982
1983 # Commands listed here have process-order dependencies; these often
1984 # are related to indexing operations.
1985 # XXX Not sure why funclineni, methodlineni, and samp are here.
1986 #
1987 process_commands_wrap_deferred(<<_RAW_ARG_DEFERRED_CMDS_);
1988 declaremodule # [] # {} # {}
1989 funcline # {} # {}
1990 funclineni # {} # {}
1991 memberline # [] # {}
1992 methodline # [] # {} # {}
1993 methodlineni # [] # {} # {}
1994 modulesynopsis # {}
1995 bifuncindex # {}
1996 exindex # {}
1997 indexii # {} # {}
1998 indexiii # {} # {} # {}
1999 indexiv # {} # {} # {} # {}
2000 kwindex # {}
2001 obindex # {}
2002 opindex # {}
2003 stindex # {}
2004 platform # {}
2005 samp # {}
2006 setindexsubitem # {}
2007 withsubitem # {} # {}
2008 _RAW_ARG_DEFERRED_CMDS_
2009
2010
2011 $alltt_start = '<div class="verbatim"><pre>';
2012 $alltt_end = '</pre></div>';
2013
2014 sub do_env_alltt{
2015     local ($_) = @_;
2016     local($closures,$reopens,@open_block_tags);
2017
2018     # get the tag-strings for all open tags
2019     local(@keep_open_tags) = @$open_tags_R;
2020     ($closures,$reopens) = &preserve_open_tags() if (@$open_tags_R);
2021
2022     # get the tags for text-level tags only
2023     $open_tags_R = [ @keep_open_tags ];
2024     local($local_closures, $local_reopens);
2025     ($local_closures, $local_reopens,@open_block_tags)
2026       = &preserve_open_block_tags
2027         if (@$open_tags_R);
2028
2029     $open_tags_R = [ @open_block_tags ];
2030
2031     do {
2032         local($open_tags_R) = [ @open_block_tags ];
2033         local(@save_open_tags) = ();
2034
2035         local($cnt) = ++$global{'max_id'};
2036         $_ = join('',"$O$cnt$C\\tt$O", ++$global{'max_id'}, $C
2037                 , $_ , $O, $global{'max_id'}, "$C$O$cnt$C");
2038
2039         $_ = &translate_environments($_);
2040         $_ = &translate_commands($_) if (/\\/);
2041
2042         # remove spurious <BR> someone sticks in; not sure where they
2043         # actually come from
2044         # XXX the replacement space is there to accomodate something
2045         # broken that inserts a space in front of the first line of
2046         # the environment
2047         s/<BR>/ /gi;
2048
2049         $_ = join('', $closures, $alltt_start, $local_reopens
2050                 , $_
2051                 , &balance_tags() #, $local_closures
2052                 , $alltt_end, $reopens);
2053         undef $open_tags_R; undef @save_open_tags;
2054     };
2055     $open_tags_R = [ @keep_open_tags ];
2056     return codetext($_);
2057 }
2058
2059 # List of all filenames produced by do_cmd_verbatiminput()
2060 %VerbatimFiles = ();
2061 @VerbatimOutputs = ();
2062
2063 sub get_verbatim_output_name($){
2064     my $file = $_[0];
2065     #
2066     # Re-write the source filename to always use a .txt extension
2067     # so that Web servers will present it as text/plain.  This is
2068     # needed since there is no other even moderately reliable way
2069     # to get the right Content-Type header on text files for
2070     # servers which we can't configure (like python.org mirrors).
2071     #
2072     if (defined $VerbatimFiles{$file}) {
2073         # We've seen this one before; re-use the same output file.
2074         return $VerbatimFiles{$file};
2075     }
2076     my($srcname, $srcdir, $srcext) = fileparse($file, '\..*');
2077     $filename = "$srcname.txt";
2078     #
2079     # We need to determine if our default filename is already
2080     # being used, and find a new one it it is.  If the name is in
2081     # used, this algorithm will first attempt to include the
2082     # source extension as part of the name, and if that is also in
2083     # use (if the same file is included multiple times, or if
2084     # another source file has that as the base name), a counter is
2085     # used instead.
2086     #
2087     my $found = 1;
2088   FIND:
2089     while ($found) {
2090         foreach $fn (@VerbatimOutputs) {
2091             if ($fn eq $filename) {
2092                 if ($found == 1) {
2093                     $srcext =~ s/^[.]//;  # Remove '.' from extension
2094                     $filename = "$srcname-$srcext.txt";
2095                 }
2096                 else {
2097                     $filename = "$srcname-$found.txt";
2098                 }
2099                 ++$found;
2100                 next FIND;
2101             }
2102         }
2103         $found = 0;
2104     }
2105     push @VerbatimOutputs, $filename;
2106     $VerbatimFiles{$file} = $filename;
2107     return $filename;
2108 }
2109
2110 sub do_cmd_verbatiminput{
2111     local($_) = @_;
2112     my $fname = next_argument();
2113     my $file;
2114     my $found = 0;
2115     my $texpath;
2116     # Search TEXINPUTS for the input file, the way we're supposed to:
2117     foreach $texpath (split /$envkey/, $TEXINPUTS) {
2118         $file = "$texpath$dd$fname";
2119         last if ($found = (-f $file));
2120     }
2121     my $filename = '';
2122     my $text;
2123     if ($found) {
2124         open(MYFILE, "<$file") || die "\n$!\n";
2125         read(MYFILE, $text, 1024*1024);
2126         close(MYFILE);
2127         $filename = get_verbatim_output_name($file);
2128         # Now that we have a filename, write it out.
2129         open(MYFILE, ">$filename");
2130         print MYFILE $text;
2131         close(MYFILE);
2132         #
2133         # These rewrites convert the raw text to something that will
2134         # be properly visible as HTML and also will pass through the
2135         # vagaries of conversion through LaTeX2HTML.  The order in
2136         # which the specific rewrites are performed is significant.
2137         #
2138         $text =~ s/\&/\&amp;/g;
2139         # These need to happen before the normal < and > re-writes,
2140         # since we need to avoid LaTeX2HTML's attempt to perform
2141         # ligature processing without regard to context (since it
2142         # doesn't have font information).
2143         $text =~ s/--/-&\#45;/g;
2144         $text =~ s/<</\&lt;\&\#60;/g;
2145         $text =~ s/>>/\&gt;\&\#62;/g;
2146         # Just normal re-writes...
2147         $text =~ s/</\&lt;/g;
2148         $text =~ s/>/\&gt;/g;
2149         # These last isn't needed for the HTML, but is needed to get
2150         # past LaTeX2HTML processing TeX macros.  We use &#92; instead
2151         # of &sol; since many browsers don't support that.
2152         $text =~ s/\\/\&\#92;/g;
2153     }
2154     else {
2155         return '<b>Could not locate requested file <i>$fname</i>!</b>\n';
2156     }
2157     my $note = 'Download as text.';
2158     if ($file ne $filename) {
2159         $note = ('Download as text (original file name: <span class="file">'
2160                  . $fname
2161                  . '</span>).');
2162     }
2163     return ("<div class=\"verbatim\">\n<pre>"
2164             . $text
2165             . "</pre>\n<div class=\"footer\">\n"
2166             . "<a href=\"$filename\" type=\"text/plain\""
2167             . ">$note</a>"
2168             . "\n</div></div>"
2169             . $_);
2170 }
2171
2172 1;                              # This must be the last line