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