initial source import
diff --git a/doc/tools/anno-api.py b/doc/tools/anno-api.py
new file mode 100755
index 0000000..0d355d2
--- /dev/null
+++ b/doc/tools/anno-api.py
@@ -0,0 +1,71 @@
+#! /usr/bin/env python
+"""Add reference count annotations to the Python/C API Reference."""
+__version__ = '$Revision: 1.1.1.1 $'
+
+import getopt
+import os
+import sys
+
+import refcounts
+
+
+PREFIX_1 = r"\begin{cfuncdesc}{PyObject*}{"
+PREFIX_2 = r"\begin{cfuncdesc}{PyVarObject*}{"
+
+
+def main():
+ rcfile = os.path.join(os.path.dirname(refcounts.__file__), os.pardir,
+ "api", "refcounts.dat")
+ outfile = "-"
+ opts, args = getopt.getopt(sys.argv[1:], "o:r:", ["output=", "refcounts="])
+ for opt, arg in opts:
+ if opt in ("-o", "--output"):
+ outfile = arg
+ elif opt in ("-r", "--refcounts"):
+ rcfile = arg
+ rcdict = refcounts.load(rcfile)
+ if outfile == "-":
+ output = sys.stdout
+ else:
+ output = open(outfile, "w")
+ if not args:
+ args = ["-"]
+ for infile in args:
+ if infile == "-":
+ input = sys.stdin
+ else:
+ input = open(infile)
+ while 1:
+ line = input.readline()
+ if not line:
+ break
+ prefix = None
+ if line.startswith(PREFIX_1):
+ prefix = PREFIX_1
+ elif line.startswith(PREFIX_2):
+ prefix = PREFIX_2
+ if prefix:
+ s = line[len(prefix):].split('}', 1)[0]
+ try:
+ info = rcdict[s]
+ except KeyError:
+ sys.stderr.write("No refcount data for %s\n" % s)
+ else:
+ if info.result_type in ("PyObject*", "PyVarObject*"):
+ if info.result_refs is None:
+ rc = "Always \NULL{}"
+ else:
+ rc = info.result_refs and "New" or "Borrowed"
+ rc = rc + " reference"
+ line = (r"\begin{cfuncdesc}[%s]{%s}{"
+ % (rc, info.result_type)) \
+ + line[len(prefix):]
+ output.write(line)
+ if infile != "-":
+ input.close()
+ if outfile != "-":
+ output.close()
+
+
+if __name__ == "__main__":
+ main()
diff --git a/doc/tools/buildindex.py b/doc/tools/buildindex.py
new file mode 100755
index 0000000..5a41c0e
--- /dev/null
+++ b/doc/tools/buildindex.py
@@ -0,0 +1,353 @@
+#! /usr/bin/env python
+
+__version__ = '$Revision: 1.1.1.1 $'
+
+import os
+import re
+import string
+import sys
+
+
+class Node:
+ __rmjunk = re.compile("<#\d+#>")
+
+ continuation = 0
+
+ def __init__(self, link, str, seqno):
+ self.links = [link]
+ self.seqno = seqno
+ # remove <#\d+#> left in by moving the data out of LaTeX2HTML
+ str = self.__rmjunk.sub('', str)
+ # build up the text
+ self.text = split_entry_text(str)
+ self.key = split_entry_key(str)
+
+ def __cmp__(self, other):
+ """Comparison operator includes sequence number, for use with
+ list.sort()."""
+ return self.cmp_entry(other) or cmp(self.seqno, other.seqno)
+
+ def cmp_entry(self, other):
+ """Comparison 'operator' that ignores sequence number."""
+ c = 0
+ for i in range(min(len(self.key), len(other.key))):
+ c = (cmp_part(self.key[i], other.key[i])
+ or cmp_part(self.text[i], other.text[i]))
+ if c:
+ break
+ return c or cmp(self.key, other.key) or cmp(self.text, other.text)
+
+ def __repr__(self):
+ return "<Node for %s (%s)>" % (string.join(self.text, '!'), self.seqno)
+
+ def __str__(self):
+ return string.join(self.key, '!')
+
+ def dump(self):
+ return "%s\1%s###%s\n" \
+ % (string.join(self.links, "\1"),
+ string.join(self.text, '!'),
+ self.seqno)
+
+
+def cmp_part(s1, s2):
+ result = cmp(s1, s2)
+ if result == 0:
+ return 0
+ l1 = string.lower(s1)
+ l2 = string.lower(s2)
+ minlen = min(len(s1), len(s2))
+ if len(s1) < len(s2) and l1 == l2[:len(s1)]:
+ result = -1
+ elif len(s2) < len(s1) and l2 == l1[:len(s2)]:
+ result = 1
+ else:
+ result = cmp(l1, l2) or cmp(s1, s2)
+ return result
+
+
+def split_entry(str, which):
+ stuff = []
+ parts = string.split(str, '!')
+ parts = map(string.split, parts, ['@'] * len(parts))
+ for entry in parts:
+ if len(entry) != 1:
+ key = entry[which]
+ else:
+ key = entry[0]
+ stuff.append(key)
+ return stuff
+
+
+_rmtt = re.compile(r"""(.*)<tt(?: class=['"][a-z0-9]+["'])?>(.*)</tt>(.*)$""",
+ re.IGNORECASE)
+_rmparens = re.compile(r"\(\)")
+
+def split_entry_key(str):
+ parts = split_entry(str, 1)
+ for i in range(len(parts)):
+ m = _rmtt.match(parts[i])
+ if m:
+ parts[i] = string.join(m.group(1, 2, 3), '')
+ else:
+ parts[i] = string.lower(parts[i])
+ # remove '()' from the key:
+ parts[i] = _rmparens.sub('', parts[i])
+ return map(trim_ignored_letters, parts)
+
+
+def split_entry_text(str):
+ if '<' in str:
+ m = _rmtt.match(str)
+ if m:
+ str = string.join(m.group(1, 2, 3), '')
+ return split_entry(str, 1)
+
+
+def load(fp):
+ nodes = []
+ rx = re.compile("(.*)\1(.*)###(.*)$")
+ while 1:
+ line = fp.readline()
+ if not line:
+ break
+ m = rx.match(line)
+ if m:
+ link, str, seqno = m.group(1, 2, 3)
+ nodes.append(Node(link, str, seqno))
+ return nodes
+
+
+def trim_ignored_letters(s):
+ # ignore $ to keep environment variables with the
+ # leading letter from the name
+ s = string.lower(s)
+ if s[0] == "$":
+ return s[1:]
+ else:
+ return s
+
+def get_first_letter(s):
+ return string.lower(trim_ignored_letters(s)[0])
+
+
+def split_letters(nodes):
+ letter_groups = []
+ if nodes:
+ group = []
+ append = group.append
+ letter = get_first_letter(nodes[0].text[0])
+ letter_groups.append((letter, group))
+ for node in nodes:
+ nletter = get_first_letter(node.text[0])
+ if letter != nletter:
+ letter = nletter
+ group = []
+ letter_groups.append((letter, group))
+ append = group.append
+ append(node)
+ return letter_groups
+
+
+# need a function to separate the nodes into columns...
+def split_columns(nodes, columns=1):
+ if columns <= 1:
+ return [nodes]
+ # This is a rough height; we may have to increase to avoid breaks before
+ # a subitem.
+ colheight = len(nodes) / columns
+ numlong = len(nodes) % columns
+ if numlong:
+ colheight = colheight + 1
+ else:
+ numlong = columns
+ cols = []
+ for i in range(numlong):
+ start = i * colheight
+ end = start + colheight
+ cols.append(nodes[start:end])
+ del nodes[:end]
+ colheight = colheight - 1
+ try:
+ numshort = len(nodes) / colheight
+ except ZeroDivisionError:
+ cols = cols + (columns - len(cols)) * [[]]
+ else:
+ for i in range(numshort):
+ start = i * colheight
+ end = start + colheight
+ cols.append(nodes[start:end])
+ #
+ # If items continue across columns, make sure they are marked
+ # as continuations so the user knows to look at the previous column.
+ #
+ for i in range(len(cols) - 1):
+ try:
+ prev = cols[i][-1]
+ next = cols[i + 1][0]
+ except IndexError:
+ return cols
+ else:
+ n = min(len(prev.key), len(next.key))
+ for j in range(n):
+ if prev.key[j] != next.key[j]:
+ break
+ next.continuation = j + 1
+ return cols
+
+
+DL_LEVEL_INDENT = " "
+
+def format_column(nodes):
+ strings = ["<dl compact>"]
+ append = strings.append
+ level = 0
+ previous = []
+ for node in nodes:
+ current = node.text
+ count = 0
+ for i in range(min(len(current), len(previous))):
+ if previous[i] != current[i]:
+ break
+ count = i + 1
+ if count > level:
+ append("<dl compact>" * (count - level) + "\n")
+ level = count
+ elif level > count:
+ append("\n")
+ append(level * DL_LEVEL_INDENT)
+ append("</dl>" * (level - count))
+ level = count
+ # else: level == count
+ for i in range(count, len(current) - 1):
+ term = node.text[i]
+ level = level + 1
+ if node.continuation > i:
+ extra = " (continued)"
+ else:
+ extra = ""
+ append("\n<dt>%s%s\n<dd>\n%s<dl compact>"
+ % (term, extra, level * DL_LEVEL_INDENT))
+ append("\n%s<dt>%s%s</a>"
+ % (level * DL_LEVEL_INDENT, node.links[0], node.text[-1]))
+ for link in node.links[1:]:
+ append(",\n%s %s[Link]</a>" % (level * DL_LEVEL_INDENT, link))
+ previous = current
+ append("\n")
+ append("</dl>" * (level + 1))
+ return string.join(strings, '')
+
+
+def format_nodes(nodes, columns=1):
+ strings = []
+ append = strings.append
+ if columns > 1:
+ colnos = range(columns)
+ colheight = len(nodes) / columns
+ if len(nodes) % columns:
+ colheight = colheight + 1
+ colwidth = 100 / columns
+ append('<table width="100%"><tr valign="top">')
+ for col in split_columns(nodes, columns):
+ append('<td width="%d%%">\n' % colwidth)
+ append(format_column(col))
+ append("\n</td>")
+ append("\n</tr></table>")
+ else:
+ append(format_column(nodes))
+ append("\n<p>\n")
+ return string.join(strings, '')
+
+
+def format_letter(letter):
+ if letter == '.':
+ lettername = ". (dot)"
+ elif letter == '_':
+ lettername = "_ (underscore)"
+ else:
+ lettername = string.upper(letter)
+ return "\n<hr>\n<h2><a name=\"letter-%s\">%s</a></h2>\n\n" \
+ % (letter, lettername)
+
+
+def format_html_letters(nodes, columns=1):
+ letter_groups = split_letters(nodes)
+ items = []
+ for letter, nodes in letter_groups:
+ s = "<b><a href=\"#letter-%s\">%s</a></b>" % (letter, letter)
+ items.append(s)
+ s = ["<hr><center>\n%s</center>\n" % string.join(items, " |\n")]
+ for letter, nodes in letter_groups:
+ s.append(format_letter(letter))
+ s.append(format_nodes(nodes, columns))
+ return string.join(s, '')
+
+def format_html(nodes, columns):
+ return format_nodes(nodes, columns)
+
+
+def collapse(nodes):
+ """Collapse sequences of nodes with matching keys into a single node.
+ Destructive."""
+ if len(nodes) < 2:
+ return
+ prev = nodes[0]
+ i = 1
+ while i < len(nodes):
+ node = nodes[i]
+ if not node.cmp_entry(prev):
+ prev.links.append(node.links[0])
+ del nodes[i]
+ else:
+ i = i + 1
+ prev = node
+
+
+def dump(nodes, fp):
+ for node in nodes:
+ fp.write(node.dump())
+
+
+def process_nodes(nodes, columns, letters):
+ nodes.sort()
+ collapse(nodes)
+ if letters:
+ return format_html_letters(nodes, columns)
+ else:
+ return format_html(nodes, columns)
+
+
+def main():
+ import getopt
+ ifn = "-"
+ ofn = "-"
+ columns = 1
+ letters = 0
+ opts, args = getopt.getopt(sys.argv[1:], "c:lo:",
+ ["columns=", "letters", "output="])
+ for opt, val in opts:
+ if opt in ("-o", "--output"):
+ ofn = val
+ elif opt in ("-c", "--columns"):
+ columns = string.atoi(val)
+ elif opt in ("-l", "--letters"):
+ letters = 1
+ if not args:
+ args = [ifn]
+ nodes = []
+ for fn in args:
+ nodes = nodes + load(open(fn))
+ num_nodes = len(nodes)
+ html = process_nodes(nodes, columns, letters)
+ program = os.path.basename(sys.argv[0])
+ if ofn == "-":
+ sys.stdout.write(html)
+ sys.stderr.write("\n%s: %d index nodes" % (program, num_nodes))
+ else:
+ open(ofn, "w").write(html)
+ print
+ print "%s: %d index nodes" % (program, num_nodes)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/doc/tools/checkargs.pm b/doc/tools/checkargs.pm
new file mode 100644
index 0000000..de52f69
--- /dev/null
+++ b/doc/tools/checkargs.pm
@@ -0,0 +1,112 @@
+#!/uns/bin/perl
+
+package checkargs;
+require 5.004; # uses "for my $var"
+require Exporter;
+@ISA = qw(Exporter);
+@EXPORT = qw(check_args check_args_range check_args_at_least);
+use strict;
+use Carp;
+
+=head1 NAME
+
+checkargs -- Provide rudimentary argument checking for perl5 functions
+
+=head1 SYNOPSIS
+
+ check_args(cArgsExpected, @_)
+ check_args_range(cArgsMin, cArgsMax, @_)
+ check_args_at_least(cArgsMin, @_)
+where "@_" should be supplied literally.
+
+=head1 DESCRIPTION
+
+As the first line of user-written subroutine foo, do one of the following:
+
+ my ($arg1, $arg2) = check_args(2, @_);
+ my ($arg1, @rest) = check_args_range(1, 4, @_);
+ my ($arg1, @rest) = check_args_at_least(1, @_);
+ my @args = check_args_at_least(0, @_);
+
+These functions may also be called for side effect (put a call to one
+of the functions near the beginning of the subroutine), but using the
+argument checkers to set the argument list is the recommended usage.
+
+The number of arguments and their definedness are checked; if the wrong
+number are received, the program exits with an error message.
+
+=head1 AUTHOR
+
+Michael D. Ernst <F<mernst@cs.washington.edu>>
+
+=cut
+
+## Need to check that use of caller(1) really gives desired results.
+## Need to give input chunk information.
+## Is this obviated by Perl 5.003's declarations? Not entirely, I think.
+
+sub check_args ( $@ )
+{
+ my ($num_formals, @args) = @_;
+ my ($pack, $file_arg, $line_arg, $subname, $hasargs, $wantarr) = caller(1);
+ if (@_ < 1) { croak "check_args needs at least 7 args, got ", scalar(@_), ": @_\n "; }
+ if ((!wantarray) && ($num_formals != 0))
+ { croak "check_args called in scalar context"; }
+ # Can't use croak below here: it would only go out to caller, not its caller
+ my $num_actuals = @args;
+ if ($num_actuals != $num_formals)
+ { die "$file_arg:$line_arg: function $subname expected $num_formals argument",
+ (($num_formals == 1) ? "" : "s"),
+ ", got $num_actuals",
+ (($num_actuals == 0) ? "" : ": @args"),
+ "\n"; }
+ for my $index (0..$#args)
+ { if (!defined($args[$index]))
+ { die "$file_arg:$line_arg: function $subname undefined argument ", $index+1, ": @args[0..$index-1]\n"; } }
+ return @args;
+}
+
+sub check_args_range ( $$@ )
+{
+ my ($min_formals, $max_formals, @args) = @_;
+ my ($pack, $file_arg, $line_arg, $subname, $hasargs, $wantarr) = caller(1);
+ if (@_ < 2) { croak "check_args_range needs at least 8 args, got ", scalar(@_), ": @_"; }
+ if ((!wantarray) && ($max_formals != 0) && ($min_formals !=0) )
+ { croak "check_args_range called in scalar context"; }
+ # Can't use croak below here: it would only go out to caller, not its caller
+ my $num_actuals = @args;
+ if (($num_actuals < $min_formals) || ($num_actuals > $max_formals))
+ { die "$file_arg:$line_arg: function $subname expected $min_formals-$max_formals arguments, got $num_actuals",
+ ($num_actuals == 0) ? "" : ": @args", "\n"; }
+ for my $index (0..$#args)
+ { if (!defined($args[$index]))
+ { die "$file_arg:$line_arg: function $subname undefined argument ", $index+1, ": @args[0..$index-1]\n"; } }
+ return @args;
+}
+
+sub check_args_at_least ( $@ )
+{
+ my ($min_formals, @args) = @_;
+ my ($pack, $file_arg, $line_arg, $subname, $hasargs, $wantarr) = caller(1);
+ # Don't do this, because we want every sub to start with a call to check_args*
+ # if ($min_formals == 0)
+ # { die "Isn't it pointless to check for at least zero args to $subname?\n"; }
+ if (scalar(@_) < 1)
+ { croak "check_args_at_least needs at least 1 arg, got ", scalar(@_), ": @_"; }
+ if ((!wantarray) && ($min_formals != 0))
+ { croak "check_args_at_least called in scalar context"; }
+ # Can't use croak below here: it would only go out to caller, not its caller
+ my $num_actuals = @args;
+ if ($num_actuals < $min_formals)
+ { die "$file_arg:$line_arg: function $subname expected at least $min_formals argument",
+ ($min_formals == 1) ? "" : "s",
+ ", got $num_actuals",
+ ($num_actuals == 0) ? "" : ": @args", "\n"; }
+ for my $index (0..$#args)
+ { if (!defined($args[$index]))
+ { warn "$file_arg:$line_arg: function $subname undefined argument ", $index+1, ": @args[0..$index-1]\n"; last; } }
+ return @args;
+}
+
+1; # successful import
+__END__
diff --git a/doc/tools/cklatex b/doc/tools/cklatex
new file mode 100755
index 0000000..396e914
--- /dev/null
+++ b/doc/tools/cklatex
@@ -0,0 +1,26 @@
+#! /bin/sh
+# -*- ksh -*-
+
+# This script *helps* locate lines of normal content that end in '}';
+# this is useful since LaTeX2HTML (at least the old version that we
+# use) breaks on many lines that end that way.
+#
+# Usage: cklatex files... | less
+#
+# *Read* the output looking for suspicious lines!
+
+grep -n "[^ ]}\$" $@ | \
+ grep -v '\\begin{' | \
+ grep -v '\\end{' | \
+ grep -v '\\input{' | \
+ grep -v '\\documentclass{' | \
+ grep -v '\\title{' | \
+ grep -v '\\chapter{' | \
+ grep -v '\\chapter\*{' | \
+ grep -v '\\section{' | \
+ grep -v '\\subsection{' | \
+ grep -v '\\subsubsection{' | \
+ grep -v '\\sectionauthor{' | \
+ grep -v '\\moduleauthor{'
+
+exit $?
diff --git a/doc/tools/custlib.py b/doc/tools/custlib.py
new file mode 100644
index 0000000..9958451
--- /dev/null
+++ b/doc/tools/custlib.py
@@ -0,0 +1,73 @@
+# Generate custlib.tex, which is a site-specific library document.
+
+# Phase I: list all the things that can be imported
+
+import glob, os, sys, string
+modules={}
+
+for modname in sys.builtin_module_names:
+ modules[modname]=modname
+
+for dir in sys.path:
+ # Look for *.py files
+ filelist=glob.glob(os.path.join(dir, '*.py'))
+ for file in filelist:
+ path, file = os.path.split(file)
+ base, ext=os.path.splitext(file)
+ modules[string.lower(base)]=base
+
+ # Look for shared library files
+ filelist=(glob.glob(os.path.join(dir, '*.so')) +
+ glob.glob(os.path.join(dir, '*.sl')) +
+ glob.glob(os.path.join(dir, '*.o')) )
+ for file in filelist:
+ path, file = os.path.split(file)
+ base, ext=os.path.splitext(file)
+ if base[-6:]=='module': base=base[:-6]
+ modules[string.lower(base)]=base
+
+# Minor oddity: the types module is documented in libtypes2.tex
+if modules.has_key('types'):
+ del modules['types'] ; modules['types2']=None
+
+# Phase II: find all documentation files (lib*.tex)
+# and eliminate modules that don't have one.
+
+docs={}
+filelist=glob.glob('lib*.tex')
+for file in filelist:
+ modname=file[3:-4]
+ docs[modname]=modname
+
+mlist=modules.keys()
+mlist=filter(lambda x, docs=docs: docs.has_key(x), mlist)
+mlist.sort()
+mlist=map(lambda x, docs=docs: docs[x], mlist)
+
+modules=mlist
+
+# Phase III: write custlib.tex
+
+# Write the boilerplate
+# XXX should be fancied up.
+print """\documentstyle[twoside,11pt,myformat]{report}
+\\title{Python Library Reference}
+\\input{boilerplate}
+\\makeindex % tell \\index to actually write the .idx file
+\\begin{document}
+\\pagenumbering{roman}
+\\maketitle
+\\input{copyright}
+\\begin{abstract}
+\\noindent This is a customized version of the Python Library Reference.
+\\end{abstract}
+\\pagebreak
+{\\parskip = 0mm \\tableofcontents}
+\\pagebreak\\pagenumbering{arabic}"""
+
+for modname in mlist:
+ print "\\input{lib%s}" % (modname,)
+
+# Write the end
+print """\\input{custlib.ind} % Index
+\\end{document}"""
diff --git a/doc/tools/cvsinfo.py b/doc/tools/cvsinfo.py
new file mode 100644
index 0000000..58a32c2
--- /dev/null
+++ b/doc/tools/cvsinfo.py
@@ -0,0 +1,81 @@
+"""Utility class and function to get information about the CVS repository
+based on checked-out files.
+"""
+
+import os
+
+
+def get_repository_list(paths):
+ d = {}
+ for name in paths:
+ if os.path.isfile(name):
+ dir = os.path.dirname(name)
+ else:
+ dir = name
+ rootfile = os.path.join(name, "CVS", "Root")
+ root = open(rootfile).readline().strip()
+ if not d.has_key(root):
+ d[root] = RepositoryInfo(dir), [name]
+ else:
+ d[root][1].append(name)
+ return d.values()
+
+
+class RepositoryInfo:
+ """Record holding information about the repository we want to talk to."""
+ cvsroot_path = None
+ branch = None
+
+ # type is '', ':ext', or ':pserver:'
+ type = ""
+
+ def __init__(self, dir=None):
+ if dir is None:
+ dir = os.getcwd()
+ dir = os.path.join(dir, "CVS")
+ root = open(os.path.join(dir, "Root")).readline().strip()
+ if root.startswith(":pserver:"):
+ self.type = ":pserver:"
+ root = root[len(":pserver:"):]
+ elif ":" in root:
+ if root.startswith(":ext:"):
+ root = root[len(":ext:"):]
+ self.type = ":ext:"
+ self.repository = root
+ if ":" in root:
+ host, path = root.split(":", 1)
+ self.cvsroot_path = path
+ else:
+ self.cvsroot_path = root
+ fn = os.path.join(dir, "Tag")
+ if os.path.isfile(fn):
+ self.branch = open(fn).readline().strip()[1:]
+
+ def get_cvsroot(self):
+ return self.type + self.repository
+
+ _repository_dir_cache = {}
+
+ def get_repository_file(self, path):
+ filename = os.path.abspath(path)
+ if os.path.isdir(path):
+ dir = path
+ join = 0
+ else:
+ dir = os.path.dirname(path)
+ join = 1
+ try:
+ repodir = self._repository_dir_cache[dir]
+ except KeyError:
+ repofn = os.path.join(dir, "CVS", "Repository")
+ repodir = open(repofn).readline().strip()
+ repodir = os.path.join(self.cvsroot_path, repodir)
+ self._repository_dir_cache[dir] = repodir
+ if join:
+ fn = os.path.join(repodir, os.path.basename(path))
+ else:
+ fn = repodir
+ return fn[len(self.cvsroot_path)+1:]
+
+ def __repr__(self):
+ return "<RepositoryInfo for %s>" % `self.get_cvsroot()`
diff --git a/doc/tools/findacks b/doc/tools/findacks
new file mode 100755
index 0000000..c13b00f
--- /dev/null
+++ b/doc/tools/findacks
@@ -0,0 +1,161 @@
+#!/usr/bin/env python
+"""Script to locate email addresses in the CVS logs."""
+__version__ = '$Revision: 1.1.1.1 $'
+
+import os
+import re
+import sys
+import UserDict
+
+import cvsinfo
+
+
+class Acknowledgements(UserDict.UserDict):
+ def add(self, email, name, path):
+ d = self.data
+ d.setdefault(email, {})[path] = name
+
+
+def open_cvs_log(info, paths=None):
+ cvsroot = info.get_cvsroot()
+ cmd = "cvs -q -d%s log " % cvsroot
+ if paths:
+ cmd += " ".join(paths)
+ return os.popen(cmd, "r")
+
+
+email_rx = re.compile("<([a-z][-a-z0-9._]*@[-a-z0-9.]+)>", re.IGNORECASE)
+
+def find_acks(f, acks):
+ prev = ''
+ filename = None
+ MAGIC_WORDS = ('van', 'von')
+ while 1:
+ line = f.readline()
+ if not line:
+ break
+ if line.startswith("Working file: "):
+ filename = line.split(None, 2)[2].strip()
+ prev = line
+ continue
+ m = email_rx.search(line)
+ if m:
+ words = prev.split() + line[:m.start()].split()
+ L = []
+ while words \
+ and (words[-1][0].isupper() or words[-1] in MAGIC_WORDS):
+ L.insert(0, words.pop())
+ name = " ".join(L)
+ email = m.group(1).lower()
+ acks.add(email, name, filename)
+ prev = line
+
+
+def load_cvs_log_acks(acks, args):
+ repolist = cvsinfo.get_repository_list(args or [""])
+ for info, paths in repolist:
+ print >>sys.stderr, "Repository:", info.get_cvsroot()
+ f = open_cvs_log(info, paths)
+ find_acks(f, acks)
+ f.close()
+
+
+def load_tex_source_acks(acks, args):
+ for path in args:
+ path = path or os.curdir
+ if os.path.isfile(path):
+ read_acks_from_tex_file(acks, path)
+ else:
+ read_acks_from_tex_dir(acks, path)
+
+
+def read_acks_from_tex_file(acks, path):
+ f = open(path)
+ while 1:
+ line = f.readline()
+ if not line:
+ break
+ if line.startswith(r"\sectionauthor{"):
+ line = line[len(r"\sectionauthor"):]
+ name, line = extract_tex_group(line)
+ email, line = extract_tex_group(line)
+ acks.add(email, name, path)
+
+
+def read_acks_from_tex_dir(acks, path):
+ stack = [path]
+ while stack:
+ p = stack.pop()
+ for n in os.listdir(p):
+ n = os.path.join(p, n)
+ if os.path.isdir(n):
+ stack.insert(0, n)
+ elif os.path.normpath(n).endswith(".tex"):
+ read_acks_from_tex_file(acks, n)
+
+
+def extract_tex_group(s):
+ c = 0
+ for i in range(len(s)):
+ if s[i] == '{':
+ c += 1
+ elif s[i] == '}':
+ c -= 1
+ if c == 0:
+ return s[1:i], s[i+1:]
+
+
+def print_acks(acks):
+ first = 1
+ for email, D in acks.items():
+ if first:
+ first = 0
+ else:
+ print
+ L = D.items()
+ L.sort()
+ prefname = L[0][1]
+ for file, name in L[1:]:
+ if name != prefname:
+ prefname = ""
+ break
+ if prefname:
+ print prefname, "<%s>:" % email
+ else:
+ print email + ":"
+ for file, name in L:
+ if name == prefname:
+ print " " + file
+ else:
+ print " %s (as %s)" % (file, name)
+
+
+def print_ack_names(acks):
+ names = []
+ for email, D in acks.items():
+ L = D.items()
+ L.sort()
+ prefname = L[0][1]
+ for file, name in L[1:]:
+ prefname = prefname or name
+ names.append(prefname or email)
+ def f(s1, s2):
+ s1 = s1.lower()
+ s2 = s2.lower()
+ return cmp((s1.split()[-1], s1),
+ (s2.split()[-1], s2))
+ names.sort(f)
+ for name in names:
+ print name
+
+
+def main():
+ args = sys.argv[1:]
+ acks = Acknowledgements()
+ load_cvs_log_acks(acks, args)
+ load_tex_source_acks(acks, args)
+ print_ack_names(acks)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/doc/tools/findmodrefs b/doc/tools/findmodrefs
new file mode 100755
index 0000000..8c5f93f
--- /dev/null
+++ b/doc/tools/findmodrefs
@@ -0,0 +1,63 @@
+#! /usr/bin/env python
+# -*- Python -*-
+
+import fileinput
+import getopt
+import glob
+import os
+import re
+import sys
+
+
+declare_rx = re.compile(
+ r"\\declaremodule(?:\[[a-zA-Z0-9]*\]*)?{[a-zA-Z_0-9]+}{([a-zA-Z_0-9]+)}")
+
+module_rx = re.compile(r"\\module{([a-zA-Z_0-9]+)}")
+
+def main():
+ try:
+ just_list = 0
+ print_lineno = 0
+ opts, args = getopt.getopt(sys.argv[1:], "ln", ["list", "number"])
+ for opt, arg in opts:
+ if opt in ("-l", "--list"):
+ just_list = 1
+ elif opt in ("-n", "--number"):
+ print_lineno = 1
+ files = args
+ if not files:
+ files = glob.glob("*.tex")
+ files.sort()
+ modulename = None
+ for line in fileinput.input(files):
+ if line[:9] == r"\section{":
+ modulename = None
+ continue
+ if line[:16] == r"\modulesynopsys{":
+ continue
+ m = declare_rx.match(line)
+ if m:
+ modulename = m.group(1)
+ continue
+ if not modulename:
+ continue
+ m = module_rx.search(line)
+ if m:
+ name = m.group(1)
+ if name != modulename:
+ filename = fileinput.filename()
+ if just_list:
+ print filename
+ fileinput.nextfile()
+ modulename = None
+ elif print_lineno:
+ print "%s(%d):%s" \
+ % (filename, fileinput.filelineno(), line[:-1])
+ else:
+ print "%s:%s" % (filename, line[:-1])
+ except KeyboardInterrupt:
+ sys.exit(1)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/doc/tools/fix_hack b/doc/tools/fix_hack
new file mode 100755
index 0000000..8dad111
--- /dev/null
+++ b/doc/tools/fix_hack
@@ -0,0 +1,2 @@
+#!/bin/sh
+sed -e 's/{\\ptt[ ]*\\char[ ]*'"'"'137}/_/g' <"$1" > "@$1" && mv "@$1" $1
diff --git a/doc/tools/fix_libaux.sed b/doc/tools/fix_libaux.sed
new file mode 100755
index 0000000..fb33cc5
--- /dev/null
+++ b/doc/tools/fix_libaux.sed
@@ -0,0 +1,3 @@
+#! /bin/sed -f
+s/{\\tt \\hackscore {}\\hackscore {}/\\sectcode{__/
+s/\\hackscore {}\\hackscore {}/__/
diff --git a/doc/tools/fixinfo.el b/doc/tools/fixinfo.el
new file mode 100644
index 0000000..267a7e3
--- /dev/null
+++ b/doc/tools/fixinfo.el
@@ -0,0 +1,15 @@
+(defun fix-python-texinfo ()
+ (goto-char (point-min))
+ (replace-regexp "\\(@setfilename \\)\\([-a-z]*\\)$"
+ "\\1python-\\2.info")
+ (replace-string "@node Front Matter\n@chapter Abstract\n"
+ "@node Abstract\n@section Abstract\n")
+ (mark-whole-buffer)
+ (texinfo-master-menu 'update-all-nodes)
+ (save-buffer)
+ ) ;; fix-python-texinfo
+
+;; now really do it:
+(find-file (car command-line-args-left))
+(fix-python-texinfo)
+(kill-emacs)
diff --git a/doc/tools/getpagecounts b/doc/tools/getpagecounts
new file mode 100755
index 0000000..179ced1
--- /dev/null
+++ b/doc/tools/getpagecounts
@@ -0,0 +1,88 @@
+#! /usr/bin/env python
+# -*- Python -*-
+
+"""Generate a page count report of the PostScript version of the manuals."""
+
+__version__ = '$Revision: 1.1.1.1 $'
+
+
+class PageCounter:
+ def __init__(self):
+ self.doclist = []
+ self.total = 0
+ self.title_width = 0
+
+ def add_document(self, prefix, title):
+ count = count_pages(prefix + ".ps")
+ self.doclist.append((title, prefix, count))
+ self.title_width = max(self.title_width, len(title))
+ self.total = self.total + count
+
+ def dump(self):
+ fmt = "%%-%ds (%%s.ps, %%d pages)" % self.title_width
+ for item in self.doclist:
+ print fmt % item
+ print
+ print " Total page count: %d" % self.total
+
+ def run(self):
+ for prefix, title in [
+ ("api", "Python/C API"),
+ ("ext", "Extending and Embedding the Python Interpreter"),
+ ("lib", "Python Library Reference"),
+ ("mac", "Macintosh Module Reference"),
+ ("ref", "Python Reference Manual"),
+ ("tut", "Python Tutorial"),
+ ("doc", "Documenting Python"),
+ ("inst", "Installing Python Modules"),
+ ("dist", "Distributing Python Modules"),
+ ]:
+ self.add_document(prefix, title)
+ print self.PREFIX
+ self.dump()
+ print self.SUFFIX
+
+ PREFIX = """\
+This is the PostScript version of the standard Python documentation.
+If you plan to print this, be aware that some of the documents are
+long. It is formatted for printing on two-sided paper; if you do plan
+to print this, *please* print two-sided if you have a printer capable
+of it! To locate published copies of the larger manuals, or other
+Python reference material, consult the PSA Online Bookstore at:
+
+ http://www.python.org/psa/bookstore/
+
+The following manuals are included:
+"""
+ SUFFIX = """\
+
+
+If you have any questions, comments, or suggestions regarding these
+documents, please send them via email to python-docs@python.org.
+
+If you would like to support the development and maintenance of
+documentation for Python, please consider joining the Python Software
+Activity (PSA; see http://www.python.org/psa/), or urging your
+organization to join the PSA or the Python Consortium (see
+http://www.python.org/consortium/).
+"""
+
+def count_pages(filename):
+ fp = open(filename)
+ count = 0
+ while 1:
+ lines = fp.readlines(1024*40)
+ if not lines:
+ break
+ for line in lines:
+ if line[:7] == "%%Page:":
+ count = count + 1
+ fp.close()
+ return count
+
+
+def main():
+ PageCounter().run()
+
+if __name__ == "__main__":
+ main()
diff --git a/doc/tools/html/about.dat b/doc/tools/html/about.dat
new file mode 100644
index 0000000..e6f8b55
--- /dev/null
+++ b/doc/tools/html/about.dat
@@ -0,0 +1,24 @@
+<p> This document was generated using the <a
+ href="http://saftsack.fs.uni-bayreuth.de/;SPMtilde;latex2ht/">
+ <strong>LaTeX</strong>2<tt>HTML</tt></a> translator.
+</p>
+
+<p> <a
+ href="http://saftsack.fs.uni-bayreuth.de/;SPMtilde;latex2ht/">
+ <strong>LaTeX</strong>2<tt>HTML</tt></a> is Copyright ©
+ 1993, 1994, 1995, 1996, 1997, <a
+ href="http://cbl.leeds.ac.uk/nikos/personal.html">Nikos
+ Drakos</a>, Computer Based Learning Unit, University of
+ Leeds, and Copyright © 1997, 1998, <a
+ href="http://www.maths.mq.edu.au/;SPMtilde;ross/">Ross
+ Moore</a>, Mathematics Department, Macquarie University,
+ Sydney.
+</p>
+
+<p> The application of <a
+ href="http://saftsack.fs.uni-bayreuth.de/;SPMtilde;latex2ht/">
+ <strong>LaTeX</strong>2<tt>HTML</tt></a> to the Python
+ documentation has been heavily tailored by Fred L. Drake,
+ Jr. Original navigation icons were contributed by Christopher
+ Petrilli.
+</p>
diff --git a/doc/tools/html/about.html b/doc/tools/html/about.html
new file mode 100644
index 0000000..3203faf
--- /dev/null
+++ b/doc/tools/html/about.html
@@ -0,0 +1,74 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+ <head>
+ <title>About the Python Documentation</title>
+ <meta name="description"
+ content="Overview information about the Python documentation">
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+ <link rel="STYLESHEET" href="lib/lib.css">
+ </head>
+ <body>
+ <div class="navigation">
+ <table width="100%" cellpadding="0" cellspacing="2">
+ <tr>
+ <td><img width="32" height="32" align="bottom" border="0" alt=""
+ src="icons/blank.gif"></td>
+ <td><a href="./"
+ title="Python Documentation Index"><img width="32" height="32"
+ align="bottom" border="0" alt="up"
+ src="icons/up.gif"></a></td>
+ <td><img width="32" height="32" align="bottom" border="0" alt=""
+ src="icons/blank.gif"></td>
+ <td align="center" width="100%">About the Python Documentation</td>
+ <td><img width="32" height="32" align="bottom" border="0" alt=""
+ src="icons/blank.gif"></td>
+ <td><img width="32" height="32" align="bottom" border="0" alt=""
+ src="icons/blank.gif"></td>
+ <td><img width="32" height="32" align="bottom" border="0" alt=""
+ src="icons/blank.gif"></td>
+ </tr>
+ </table>
+ <b class="navlabel">Up:</b>
+ <span class="sectref">
+ <a href="./" title="Python Documentation Index">
+ Python Documentation Index</A></span>
+ <br>
+ </div>
+ <hr>
+
+ <h2>About the Python Documentation</h2>
+
+ <p>The Python documentation was originally written by Guido van
+ Rossum, but has increasingly become a community effort over the
+ past several years. This growing collection of documents is
+ available in several formats, including typeset versions in PDF
+ and PostScript for printing, from the <a
+ href="http://www.python.org/">Python Web site</a>.
+
+ <p>A <a href="acks.html">list of contributors</a> is available.
+
+ <h2>Comments and Questions</h2>
+
+ <p> General comments and questions regarding this document should
+ be sent by email to <a href="mailto:python-docs@python.org"
+ >python-docs@python.org</a>. If you find specific errors in
+ this document, please report the bug at the <a
+ href="http://sourceforge.net/bugs/?group_id=5470">Python Bug
+ Tracker</a> at <a href="http://sourceforge.net/">SourceForge</a>.
+ </p>
+
+ <p> Questions regarding how to use the information in this
+ document should be sent to the Python news group, <a
+ href="news:comp.lang.python">comp.lang.python</a>, or the <a
+ href="http://www.python.org/mailman/listinfo/python-list"
+ >Python mailing list</a> (which is gated to the newsgroup and
+ carries the same content).
+ </p>
+
+ <p> For any of these channels, please be sure not to send HTML email.
+ Thanks.
+ </p>
+
+ <hr>
+ </body>
+</html>
diff --git a/doc/tools/html/icons/blank.gif b/doc/tools/html/icons/blank.gif
new file mode 100644
index 0000000..2e31f4e
--- /dev/null
+++ b/doc/tools/html/icons/blank.gif
Binary files differ
diff --git a/doc/tools/html/icons/blank.png b/doc/tools/html/icons/blank.png
new file mode 100644
index 0000000..2af5639
--- /dev/null
+++ b/doc/tools/html/icons/blank.png
Binary files differ
diff --git a/doc/tools/html/icons/contents.gif b/doc/tools/html/icons/contents.gif
new file mode 100644
index 0000000..6d299c4
--- /dev/null
+++ b/doc/tools/html/icons/contents.gif
Binary files differ
diff --git a/doc/tools/html/icons/contents.png b/doc/tools/html/icons/contents.png
new file mode 100644
index 0000000..3429be0
--- /dev/null
+++ b/doc/tools/html/icons/contents.png
Binary files differ
diff --git a/doc/tools/html/icons/index.gif b/doc/tools/html/icons/index.gif
new file mode 100644
index 0000000..32eecfb
--- /dev/null
+++ b/doc/tools/html/icons/index.gif
Binary files differ
diff --git a/doc/tools/html/icons/index.png b/doc/tools/html/icons/index.png
new file mode 100644
index 0000000..cd918af
--- /dev/null
+++ b/doc/tools/html/icons/index.png
Binary files differ
diff --git a/doc/tools/html/icons/modules.gif b/doc/tools/html/icons/modules.gif
new file mode 100644
index 0000000..f5860b6
--- /dev/null
+++ b/doc/tools/html/icons/modules.gif
Binary files differ
diff --git a/doc/tools/html/icons/modules.png b/doc/tools/html/icons/modules.png
new file mode 100644
index 0000000..8fa8b75
--- /dev/null
+++ b/doc/tools/html/icons/modules.png
Binary files differ
diff --git a/doc/tools/html/icons/next.gif b/doc/tools/html/icons/next.gif
new file mode 100644
index 0000000..5dcaff8
--- /dev/null
+++ b/doc/tools/html/icons/next.gif
Binary files differ
diff --git a/doc/tools/html/icons/next.png b/doc/tools/html/icons/next.png
new file mode 100644
index 0000000..cfe5e51
--- /dev/null
+++ b/doc/tools/html/icons/next.png
Binary files differ
diff --git a/doc/tools/html/icons/previous.gif b/doc/tools/html/icons/previous.gif
new file mode 100644
index 0000000..de1da16
--- /dev/null
+++ b/doc/tools/html/icons/previous.gif
Binary files differ
diff --git a/doc/tools/html/icons/previous.png b/doc/tools/html/icons/previous.png
new file mode 100644
index 0000000..497def4
--- /dev/null
+++ b/doc/tools/html/icons/previous.png
Binary files differ
diff --git a/doc/tools/html/icons/up.gif b/doc/tools/html/icons/up.gif
new file mode 100644
index 0000000..a9d3e13
--- /dev/null
+++ b/doc/tools/html/icons/up.gif
Binary files differ
diff --git a/doc/tools/html/icons/up.png b/doc/tools/html/icons/up.png
new file mode 100644
index 0000000..a90e028
--- /dev/null
+++ b/doc/tools/html/icons/up.png
Binary files differ
diff --git a/doc/tools/html/index.html.in b/doc/tools/html/index.html.in
new file mode 100644
index 0000000..86b28cc
--- /dev/null
+++ b/doc/tools/html/index.html.in
@@ -0,0 +1,117 @@
+<html>
+ <head>
+ <title>Python @RELEASE@ Documentation - @DATE@</title>
+ <link rel="STYLESHEET" href="lib/lib.css" type="text/css">
+ <meta name="description"
+ content="Top-level index to the standard documentation for
+ Python @RELEASE@.">
+ <style type="text/css">
+ a.title { font-weight: bold; font-size: 110%; }
+ ul { margin-left: 1em; padding: 0pt; border: 0pt; }
+ </style>
+ </head>
+ <body>
+ <div class="navigation">
+ <table align="center" width="100%" cellpadding="0" cellspacing="2">
+ <tr>
+ <td><img width="32" height="32" align="bottom" border="0" alt=""
+ src="icons/blank.gif"></td>
+ <td><img width="32" height="32" align="bottom" border="0" alt=""
+ src="icons/blank.gif"></td>
+ <td><img width="32" height="32" align="bottom" border="0" alt=""
+ src="icons/blank.gif"></td>
+ <td align="center" width="100%">
+ <b class="title">Python Documentation</b></td>
+ <td><img width="32" height="32" align="bottom" border="0" alt=""
+ src="icons/blank.gif"></td>
+ <td><a href="modindex.html"><img width="32" height="32"
+ align="bottom" border="0" alt="Module Index"
+ src="icons/modules.gif"></a></td>
+ <td><img width="32" height="32" align="bottom" border="0" alt=""
+ src="icons/blank.gif"></A></td>
+ </tr>
+ </table>
+ <hr>
+ </div>
+ <div align="center" class="titlepage">
+ <h1>Python Documentation</h1>
+
+ <p>
+ <strong>Release @RELEASE@</strong>
+ <br>
+ <strong>@DATE@</strong>
+ </p>
+ </div>
+
+ <table align="center">
+ <tbody>
+ <tr><td>
+ <ul>
+ <li> <a href="tut/tut.html" class="title">Tutorial</a>
+ <br>(start here)
+
+ <li> <a href="modindex.html" class="title">Global Module Index</a>
+ <br>(for quick access to all documentation)
+
+ <li> <a href="lib/lib.html" class="title">Library Reference</a>
+ <br>(keep this under your pillow)
+
+ <li> <a href="mac/mac.html" class="title">Macintosh Module
+ Reference</a>
+ <br>(this too, if you use a Macintosh)
+
+ <li> <a href="inst/inst.html" class="title">Installing
+ Python Modules</a>
+ <br>(for administrators)
+ </ul>
+ </td>
+ <td>
+ <ul>
+ <li> <a href="ref/ref.html" class="title">Language Reference</a>
+ <br>(for language lawyers)
+
+ <li> <a href="ext/ext.html" class="title">Extending and
+ Embedding</a>
+ <br>(tutorial for C/C++ programmers)
+
+ <li> <a href="api/api.html" class="title">Python/C API</a>
+ <br>(reference for C/C++ programmers)
+
+ <li> <a href="doc/doc.html" class="title">Documenting Python</a>
+ <br>(information for documentation authors)
+
+ <li> <a href="dist/dist.html" class="title">Distributing
+ Python Modules</a>
+ <br>(for developers and packagers)
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td>
+
+ <ul>
+ <li> <a href="http://www.python.org/doc/" class="title"
+ >Documentation Central</a>
+ <br>(for everyone)
+ </ul>
+ </td>
+ <td>
+
+ <ul>
+ <li> <a href="http://www.python.org/doc/howto/" class="title"
+ >Python How-To Guides</a>
+ <br>(special topics)
+ </ul>
+ </td>
+ </tr>
+ </tbody>
+ </table>
+ <p>
+
+ <address>
+ <hr>
+ See <i><a href="about.html">About the Python Documentation</a></i>
+ for information on suggesting changes.
+ </address>
+ </body>
+</html>
diff --git a/doc/tools/html/stdabout.dat b/doc/tools/html/stdabout.dat
new file mode 100644
index 0000000..a9b2718
--- /dev/null
+++ b/doc/tools/html/stdabout.dat
@@ -0,0 +1,48 @@
+<p> This document was generated using the <a
+ href="http://saftsack.fs.uni-bayreuth.de/;SPMtilde;latex2ht/">
+ <strong>LaTeX</strong>2<tt>HTML</tt></a> translator.
+</p>
+
+<p> <a
+ href="http://saftsack.fs.uni-bayreuth.de/;SPMtilde;latex2ht/">
+ <strong>LaTeX</strong>2<tt>HTML</tt></a> is Copyright ©
+ 1993, 1994, 1995, 1996, 1997, <a
+ href="http://cbl.leeds.ac.uk/nikos/personal.html">Nikos
+ Drakos</a>, Computer Based Learning Unit, University of
+ Leeds, and Copyright © 1997, 1998, <a
+ href="http://www.maths.mq.edu.au/;SPMtilde;ross/">Ross
+ Moore</a>, Mathematics Department, Macquarie University,
+ Sydney.
+</p>
+
+<p> The application of <a
+ href="http://saftsack.fs.uni-bayreuth.de/;SPMtilde;latex2ht/">
+ <strong>LaTeX</strong>2<tt>HTML</tt></a> to the Python
+ documentation has been heavily tailored by Fred L. Drake,
+ Jr. Original navigation icons were contributed by Christopher
+ Petrilli.
+</p>
+
+<hr>
+
+<h2>Comments and Questions</h2>
+
+<p> General comments and questions regarding this document should
+ be sent by email to <a href="mailto:python-docs@python.org"
+ >python-docs@python.org</a>. If you find specific errors in
+ this document, please report the bug at the <a
+ href="http://sourceforge.net/bugs/?group_id=5470">Python Bug
+ Tracker</a> at <a href="http://sourceforge.net/">SourceForge</a>.
+</p>
+
+<p> Questions regarding how to use the information in this
+ document should be sent to the Python news group, <a
+ href="news:comp.lang.python">comp.lang.python</a>, or the <a
+ href="http://www.python.org/mailman/listinfo/python-list"
+ >Python mailing list</a> (which is gated to the newsgroup and
+ carries the same content).
+</p>
+
+<p> For any of these channels, please be sure not to send HTML email.
+ Thanks.
+</p>
diff --git a/doc/tools/html/style.css b/doc/tools/html/style.css
new file mode 100644
index 0000000..767cf74
--- /dev/null
+++ b/doc/tools/html/style.css
@@ -0,0 +1,88 @@
+/*
+ * The first part of this is the standard CSS generated by LaTeX2HTML,
+ * with the "empty" declarations removed.
+ */
+
+/* Century Schoolbook font is very similar to Computer Modern Math: cmmi */
+.math { font-family: "Century Schoolbook", serif; }
+.math i { font-family: "Century Schoolbook", serif;
+ font-weight: bold }
+.boldmath { font-family: "Century Schoolbook", serif;
+ font-weight: bold }
+
+/* Implement both fixed-size and relative sizes: */
+small.xtiny { font-size : xx-small }
+small.tiny { font-size : x-small }
+small.scriptsize { font-size : smaller }
+small.footnotesize { font-size : small }
+big.xlarge { font-size : large }
+big.xxlarge { font-size : x-large }
+big.huge { font-size : larger }
+big.xhuge { font-size : xx-large }
+
+/*
+ * Document-specific styles come next;
+ * these are added for the Python documentation.
+ *
+ * Note that the size specifications for the H* elements are because
+ * Netscape on Solaris otherwise doesn't get it right; they all end up
+ * the normal text size.
+ */
+
+body { color: #000000;
+ background-color: #ffffff; }
+
+a:active { color: #ff0000; }
+a:visited { color: #551a8b; }
+a:link { color: #0000bb; }
+
+h1, h2, h3, h4, h5, h6 { font-family: avantgarde, sans-serif;
+ font-weight: bold }
+h1 { font-size: 180% }
+h2 { font-size: 150% }
+h3, h4 { font-size: 120% }
+code, tt { font-family: monospace }
+var { font-family: times, serif;
+ font-style: italic;
+ font-weight: normal }
+
+.navigation td { background-color: #99ccff;
+ font-weight: bold;
+ font-family: avantgarde, sans-serif;
+ font-size: 110% }
+
+.release-info { font-style: italic; }
+
+.titlegraphic { vertical-align: top; }
+
+.verbatim { color: #00008b }
+
+.email { font-family: avantgarde, sans-serif }
+.mimetype { font-family: avantgarde, sans-serif }
+.newsgroup { font-family: avantgarde, sans-serif }
+.url { font-family: avantgarde, sans-serif }
+.file { font-family: avantgarde, sans-serif }
+
+.tableheader { background-color: #99ccff;
+ font-family: avantgarde, sans-serif; }
+
+.refcount-info { font-style: italic }
+.refcount-info .value { font-weight: bold;
+ color: #006600 }
+
+/*
+ * Some decoration for the "See also:" blocks, in part inspired by some of
+ * the styling on Lars Marius Garshol's XSA pages.
+ * (The blue in the navigation bars is #99CCFF.)
+ */
+.seealso { background-color: #fffaf0;
+ border: thin solid black;
+ padding: 4pt }
+
+.seealso .heading { font-size: 110% }
+
+/*
+ * Class 'availability' is used for module availability statements at
+ * the top of modules.
+ */
+.availability .platform { font-weight: bold }
diff --git a/doc/tools/html2texi.pl b/doc/tools/html2texi.pl
new file mode 100755
index 0000000..be050b1
--- /dev/null
+++ b/doc/tools/html2texi.pl
@@ -0,0 +1,1750 @@
+#! /usr/bin/env perl
+# html2texi.pl -- Convert HTML documentation to Texinfo format
+# Michael Ernst <mernst@cs.washington.edu>
+# Time-stamp: <1999-01-12 21:34:27 mernst>
+
+# This program converts HTML documentation trees into Texinfo format.
+# Given the name of a main (or contents) HTML file, it processes that file,
+# and other files (transitively) referenced by it, into a Texinfo file
+# (whose name is chosen from the file or directory name of the argument).
+# For instance:
+# html2texi.pl api/index.html
+# produces file "api.texi".
+
+# Texinfo format can be easily converted to Info format (for browsing in
+# Emacs or the standalone Info browser), to a printed manual, or to HTML.
+# Thus, html2texi.pl permits conversion of HTML files to Info format, and
+# secondarily enables producing printed versions of Web page hierarchies.
+
+# Unlike HTML, Info format is searchable. Since Info is integrated into
+# Emacs, one can read documentation without starting a separate Web
+# browser. Additionally, Info browsers (including Emacs) contain
+# convenient features missing from Web browsers, such as easy index lookup
+# and mouse-free browsing.
+
+# Limitations:
+# html2texi.pl is currently tuned to latex2html output (and it corrects
+# several latex2html bugs), but should be extensible to arbitrary HTML
+# documents. It will be most useful for HTML with a hierarchical structure
+# and an index, and it recognizes those features as created by latex2html
+# (and possibly by some other tools). The HTML tree to be traversed must
+# be on local disk, rather than being accessed via HTTP.
+# This script requires the use of "checkargs.pm". To eliminate that
+# dependence, replace calls to check_args* by @_ (which is always the last
+# argument to those functions).
+# Also see the "to do" section, below.
+# Comments, suggestions, bug fixes, and enhancements are welcome.
+
+# Troubleshooting:
+# Malformed HTML can cause this program to abort, so
+# you should check your HTML files to make sure they are legal.
+
+
+###
+### Typical usage for the Python documentation:
+###
+
+# (Actually, most of this is in a Makefile instead.)
+# The resulting Info format Python documentation is currently available at
+# ftp://ftp.cs.washington.edu/homes/mernst/python-info.tar.gz
+
+# Fix up HTML problems, eg <DT><DL COMPACT><DD> should be <DT><DL COMPACT><DD>.
+
+# html2texi.pl /homes/fish/mernst/tmp/python-doc/html/api/index.html
+# html2texi.pl /homes/fish/mernst/tmp/python-doc/html/ext/index.html
+# html2texi.pl /homes/fish/mernst/tmp/python-doc/html/lib/index.html
+# html2texi.pl /homes/fish/mernst/tmp/python-doc/html/mac/index.html
+# html2texi.pl /homes/fish/mernst/tmp/python-doc/html/ref/index.html
+# html2texi.pl /homes/fish/mernst/tmp/python-doc/html/tut/index.html
+
+# Edit the generated .texi files:
+# * change @setfilename to prefix "python-"
+# * fix up any sectioning, such as for Abstract
+# * make Texinfo menus
+# * perhaps remove the @detailmenu ... @end detailmenu
+# In Emacs, to do all this:
+# (progn (goto-char (point-min)) (replace-regexp "\\(@setfilename \\)\\([-a-z]*\\)$" "\\1python-\\2.info") (replace-string "@node Front Matter\n@chapter Abstract\n" "@node Abstract\n@section Abstract\n") (progn (mark-whole-buffer) (texinfo-master-menu 'update-all-nodes)) (save-buffer))
+
+# makeinfo api.texi
+# makeinfo ext.texi
+# makeinfo lib.texi
+# makeinfo mac.texi
+# makeinfo ref.texi
+# makeinfo tut.texi
+
+
+###
+### Structure of the code
+###
+
+# To be written...
+
+
+###
+### Design decisions
+###
+
+# Source and destination languages
+# --------------------------------
+#
+# The goal is Info files; I create Texinfo, so I don't have to worry about
+# the finer details of Info file creation. (I'm not even sure of its exact
+# format.)
+#
+# Why not start from LaTeX rather than HTML?
+# I could hack latex2html itself to produce Texinfo instead, or fix up
+# partparse.py (which already translates LaTeX to Teinfo).
+# Pros:
+# * has high-level information such as index entries, original formatting
+# Cons:
+# * those programs are complicated to read and understand
+# * those programs try to handle arbitrary LaTeX input, track catcodes,
+# and more: I don't want to go to that effort. HTML isn't as powerful
+# as LaTeX, so there are fewer subtleties.
+# * the result wouldn't work for arbitrary HTML documents; it would be
+# nice to eventually extend this program to HTML produced from Docbook,
+# Frame, and more.
+
+# Parsing
+# -------
+#
+# I don't want to view the text as a linear stream; I'd rather parse the
+# whole thing and then do pattern matching over the parsed representation (to
+# find idioms such as indices, lists of child nodes, etc.).
+# * Perl provides HTML::TreeBuilder, which does just what I want.
+# * libwww-perl: http://www.linpro.no/lwp/
+# * TreeBuilder: HTML-Tree-0.51.tar.gz
+# * Python Parsers, Formatters, and Writers don't really provide the right
+# interface (and the version in Grail doesn't correspond to another
+# distributed version, so I'm confused about which to be using). I could
+# write something in Python that creates a parse tree, but why bother?
+
+# Other implementation language issues:
+# * Python lacks variable declarations, reasonable scoping, and static
+# checking tools. I've written some of the latter for myself that make
+# my Perl programming a lot safer than my Python programming will be until
+# I have a similar suite for that language.
+
+
+###########################################################################
+### To do
+###
+
+# Section names:
+# Fix the problem with multiple sections in a single file (eg, Abstract in
+# Front Matter section).
+# Deal with cross-references, as in /homes/fish/mernst/tmp/python-doc/html/ref/types.html:310
+# Index:
+# Perhaps double-check that every tag mentioned in the index is found
+# in the text.
+# Python: email to python-docs@python.org, to get their feedback.
+# Compare to existing lib/ Info manual
+# Write the hooks into info-look; replace pyliblookup1-1.tar.gz.
+# Postpass to remove extra quotation marks around typography already in
+# a different font (to avoid double delimiters as in "`code'"); or
+# perhaps consider using only font-based markup so that we don't get
+# the extra *bold* and `code' markup in Info.
+
+## Perhaps don't rely on automatic means for adding up, next, prev; I have
+## all that info available to me already, so it's not so much trouble to
+## add it. (Right?) But it is *so* easy to use Emacs instead...
+
+
+###########################################################################
+### Strictures
+###
+
+# man HTML::TreeBuilder
+# man HTML::Parser
+# man HTML::Element
+
+# require HTML::ParserWComment;
+require HTML::Parser;
+require HTML::TreeBuilder;
+require HTML::Element;
+
+use File::Basename;
+
+use strict;
+# use Carp;
+
+use checkargs;
+
+
+###########################################################################
+### Variables
+###
+
+my @section_stack = (); # elements are chapter/section/subsec nodetitles (I think)
+my $current_ref_tdf; # for the file currently being processed;
+ # used in error messages
+my $html_directory;
+my %footnotes;
+
+# First element should not be used.
+my @sectionmarker = ("manual", "chapter", "section", "subsection", "subsubsection");
+
+my %inline_markup = ("b" => "strong",
+ "code" => "code",
+ "i" => "emph",
+ "kbd" => "kbd",
+ "samp" => "samp",
+ "strong" => "strong",
+ "tt" => "code",
+ "var" => "var");
+
+my @deferred_index_entries = ();
+
+my @index_titles = (); # list of (filename, type) lists
+my %index_info = ("Index" => ["\@blindex", "bl"],
+ "Concept Index" => ["\@cindex", "cp"],
+ "Module Index" => ["\@mdindex", "md"]);
+
+
+###########################################################################
+### Main/contents page
+###
+
+# Process first-level page on its own, or just a contents page? Well, I do
+# want the title, author, etc., and the front matter... For now, just add
+# that by hand at the end.
+
+
+# data structure possibilities:
+# * tree-like (need some kind of stack when processing (or parent pointers))
+# * list of name and depth; remember old and new depths.
+
+# Each element is a reference to a list of (nodetitle, depth, filename).
+my @contents_list = ();
+
+# The problem with doing fixups on the fly is that some sections may have
+# already been processed (and no longer available) by the time we notice
+# others with the same name. It's probably better to fully construct the
+# contents list (reading in all files of interest) upfront; that will also
+# let me do a better job with cross-references, because again, all files
+# will already be read in.
+my %contents_hash = ();
+my %contents_fixups = ();
+
+my @current_contents_list = ();
+
+# Merge @current_contents_list into @contents_list,
+# and set @current_contents_list to be empty.
+sub merge_contents_lists ( )
+{ check_args(0, @_);
+
+ # Three possibilities:
+ # * @contents_list is empty: replace it by @current_contents_list.
+ # * prefixes of the two lists are identical: do nothing
+ # * @current_contents_list is all at lower level than $contents_list[0];
+ # prefix @contents_list by @current_contents_list
+
+ if (scalar(@current_contents_list) == 0)
+ { die "empty current_contents_list"; }
+
+ # if (scalar(@contents_list) == 0)
+ # { @contents_list = @current_contents_list;
+ # @current_contents_list = ();
+ # return; }
+
+ # if (($ {$contents_list[0]}[1]) < ($ {$current_contents_list[0]}[1]))
+ # { unshift @contents_list, @current_contents_list;
+ # @current_contents_list = ();
+ # return; }
+
+ for (my $i=0; $i<scalar(@current_contents_list); $i++)
+ { my $ref_c_tdf = $current_contents_list[$i];
+ if ($i >= scalar(@contents_list))
+ { push @contents_list, $ref_c_tdf;
+ my $title = $ {$ref_c_tdf}[0];
+ if (defined $contents_hash{$title})
+ { $contents_fixups{$title} = 1; }
+ else
+ { $contents_hash{$title} = 1; }
+ next; }
+ my $ref_tdf = $contents_list[$i];
+ my ($title, $depth, $file) = @{$ref_tdf};
+ my ($c_title, $c_depth, $c_file) = @{$ref_c_tdf};
+
+ if (($title ne $c_title)
+ && ($depth < $c_depth)
+ && ($file ne $c_file))
+ { splice @contents_list, $i, 0, $ref_c_tdf;
+ if (defined $contents_hash{$c_title})
+ { $contents_fixups{$c_title} = 1; }
+ else
+ { $contents_hash{$c_title} = 1; }
+ next; }
+
+ if (($title ne $c_title)
+ || ($depth != $c_depth)
+ || ($file ne $c_file))
+ { die ("while processing $ {$current_ref_tdf}[2] at depth $ {$current_ref_tdf}[1], mismatch at index $i:",
+ "\n main: <<<$title>>> $depth $file",
+ "\n curr: <<<$c_title>>> $c_depth $c_file"); }
+ }
+ @current_contents_list = ();
+}
+
+
+
+# Set @current_contents_list to a list of (title, href, sectionlevel);
+# then merge that list into @contents_list.
+# Maybe this function should also produce a map
+# from title (or href) to sectionlevel (eg "chapter"?).
+sub process_child_links ( $ )
+{ my ($he) = check_args(1, @_);
+
+ # $he->dump();
+ if (scalar(@current_contents_list) != 0)
+ { die "current_contents_list nonempty: @current_contents_list"; }
+ $he->traverse(\&increment_current_contents_list, 'ignore text');
+
+ # Normalize the depths; for instance, convert 1,3,5 into 0,1,2.
+ my %depths = ();
+ for my $ref_tdf (@current_contents_list)
+ { $depths{$ {$ref_tdf}[1]} = 1; }
+ my @sorted_depths = sort keys %depths;
+ my $current_depth = scalar(@section_stack)-1;
+ my $current_depth_2 = $ {$current_ref_tdf}[1];
+ if ($current_depth != $current_depth_2)
+ { die "mismatch in current depths: $current_depth $current_depth_2; ", join(", ", @section_stack); }
+ for (my $i=0; $i<scalar(@sorted_depths); $i++)
+ { $depths{$sorted_depths[$i]} = $i + $current_depth+1; }
+ for my $ref_tdf (@current_contents_list)
+ { $ {$ref_tdf}[1] = $depths{$ {$ref_tdf}[1]}; }
+
+ # Eliminate uninteresting sections. Hard-coded hack for now.
+ if ($ {$current_contents_list[-1]}[0] eq "About this document ...")
+ { pop @current_contents_list; }
+ if ((scalar(@current_contents_list) > 1)
+ && ($ {$current_contents_list[1]}[0] eq "Contents"))
+ { my $ref_first_tdf = shift @current_contents_list;
+ $current_contents_list[0] = $ref_first_tdf; }
+
+ for (my $i=0; $i<scalar(@current_contents_list); $i++)
+ { my $ref_tdf = $current_contents_list[$i];
+ my $title = $ {$ref_tdf}[0];
+ if (exists $index_info{$title})
+ { my $index_file = $ {$ref_tdf}[2];
+ my ($indexing_command, $suffix) = @{$index_info{$title}};
+ process_index_file($index_file, $indexing_command);
+ print TEXI "\n\@defindex $suffix\n";
+ push @index_titles, $title;
+ splice @current_contents_list, $i, 1;
+ $i--; }
+ elsif ($title =~ /\bIndex$/)
+ { print STDERR "Warning: \"$title\" might be an index; if so, edit \%index_info.\n"; } }
+
+ merge_contents_lists();
+
+ # print_contents_list();
+ # print_index_info();
+}
+
+
+sub increment_current_contents_list ( $$$ )
+{ my ($he, $startflag, $depth) = check_args(3, @_);
+ if (!$startflag)
+ { return; }
+
+ if ($he->tag eq "li")
+ { my @li_content = @{$he->content};
+ if ($li_content[0]->tag ne "a")
+ { die "first element of <LI> should be <A>"; }
+ my ($name, $href, @content) = anchor_info($li_content[0]);
+ # unused $name
+ my $title = join("", collect_texts($li_content[0]));
+ $title = texi_remove_punctuation($title);
+ # The problem with these is that they are formatted differently in
+ # @menu and @node!
+ $title =~ s/``/\"/g;
+ $title =~ s/''/\"/g;
+ $title =~ s/ -- / /g;
+ push @current_contents_list, [ $title, $depth, $href ]; }
+ return 1;
+}
+
+# Simple version for section titles
+sub html_to_texi ( $ )
+{ my ($he) = check_args(1, @_);
+ if (!ref $he)
+ { return $he; }
+
+ my $tag = $he->tag;
+ if (exists $inline_markup{$tag})
+ { my $result = "\@$inline_markup{$tag}\{";
+ for my $elt (@{$he->content})
+ { $result .= html_to_texi($elt); }
+ $result .= "\}";
+ return $result; }
+ else
+ { $he->dump();
+ die "html_to_texi confused by <$tag>"; }
+}
+
+
+
+sub print_contents_list ()
+{ check_args(0, @_);
+ print STDERR "Contents list:\n";
+ for my $ref_tdf (@contents_list)
+ { my ($title, $depth, $file) = @{$ref_tdf};
+ print STDERR "$title $depth $file\n"; }
+}
+
+
+
+###########################################################################
+### Index
+###
+
+my $l2h_broken_link_name = "l2h-";
+
+
+# map from file to (map from anchor name to (list of index texts))
+# (The list is needed when a single LaTeX command like \envvar
+# expands to multiple \index commands.)
+my %file_index_entries = ();
+my %this_index_entries; # map from anchor name to (list of index texts)
+
+my %file_index_entries_broken = (); # map from file to (list of index texts)
+my @this_index_entries_broken;
+
+my $index_prefix = "";
+my @index_prefixes = ();
+
+my $this_indexing_command;
+
+sub print_index_info ()
+{ check_args(0, @_);
+ my ($key, $val);
+ for my $file (sort keys %file_index_entries)
+ { my %index_entries = %{$file_index_entries{$file}};
+ print STDERR "file: $file\n";
+ for my $aname (sort keys %index_entries)
+ { my @entries = @{$index_entries{$aname}};
+ if (scalar(@entries) == 1)
+ { print STDERR " $aname : $entries[0]\n"; }
+ else
+ { print STDERR " $aname : ", join("\n " . (" " x length($aname)), @entries), "\n"; } } }
+ for my $file (sort keys %file_index_entries_broken)
+ { my @entries = @{$file_index_entries_broken{$file}};
+ print STDERR "file: $file\n";
+ for my $entry (@entries)
+ { print STDERR " $entry\n"; }
+ }
+}
+
+
+sub process_index_file ( $$ )
+{ my ($file, $indexing_command) = check_args(2, @_);
+ # print "process_index_file $file $indexing_command\n";
+
+ my $he = file_to_tree($html_directory . $file);
+ # $he->dump();
+
+ $this_indexing_command = $indexing_command;
+ $he->traverse(\&process_if_index_dl_compact, 'ignore text');
+ undef $this_indexing_command;
+ # print "process_index_file done\n";
+}
+
+
+sub process_if_index_dl_compact ( $$$ )
+{ my ($he, $startflag) = (check_args(3, @_))[0,1]; # ignore depth argument
+ if (!$startflag)
+ { return; }
+
+ if (($he->tag() eq "dl") && (defined $he->attr('compact')))
+ { process_index_dl_compact($he);
+ return 0; }
+ else
+ { return 1; }
+}
+
+
+# The elements of a <DL COMPACT> list from a LaTeX2HTML index:
+# * a single space: text to be ignored
+# * <DT> elements with an optional <DD> element following each one
+# Two types of <DT> elements:
+# * Followed by a <DD> element: the <DT> contains a single
+# string, and the <DD> contains a whitespace string to be ignored, a
+# <DL COMPACT> to be recursively processed (with the <DT> string as a
+# prefix), and a whitespace string to be ignored.
+# * Not followed by a <DD> element: contains a list of anchors
+# and texts (ignore the texts, which are only whitespace and commas).
+# Optionally contains a <DL COMPACT> to be recursively processed (with
+# the <DT> string as a prefix)
+sub process_index_dl_compact ( $ )
+{ my ($h) = check_args(1, @_);
+ my @content = @{$h->content()};
+ for (my $i = 0; $i < scalar(@content); $i++)
+ { my $this_he = $content[$i];
+ if ($this_he->tag ne "dt")
+ { $this_he->dump();
+ die "Expected <DT> tag: " . $this_he->tag; }
+ if (($i < scalar(@content) - 1) && ($content[$i+1]->tag eq "dd"))
+ { process_index_dt_and_dd($this_he, $content[$i+1]);
+ $i++; }
+ else
+ { process_index_lone_dt($this_he); } } }
+
+
+
+# Argument is a <DT> element. If it contains more than one anchor, then
+# the texts of all subsequent ones are "[Link]". Example:
+# <DT>
+# <A HREF="embedding.html#l2h-201">
+# "$PATH"
+# ", "
+# <A HREF="embedding.html#l2h-205">
+# "[Link]"
+# Optionally contains a <DL COMPACT> as well. Example:
+# <DT>
+# <A HREF="types.html#l2h-616">
+# "attribute"
+# <DL COMPACT>
+# <DT>
+# <A HREF="assignment.html#l2h-3074">
+# "assignment"
+# ", "
+# <A HREF="assignment.html#l2h-3099">
+# "[Link]"
+# <DT>
+# <A HREF="types.html#l2h-">
+# "assignment, class"
+
+sub process_index_lone_dt ( $ )
+{ my ($dt) = check_args(1, @_);
+ my @dtcontent = @{$dt->content()};
+ my $acontent;
+ my $acontent_suffix;
+ for my $a (@dtcontent)
+ { if ($a eq ", ")
+ { next; }
+ if (!ref $a)
+ { $dt->dump;
+ die "Unexpected <DT> string element: $a"; }
+
+ if ($a->tag eq "dl")
+ { push @index_prefixes, $index_prefix;
+ if (!defined $acontent_suffix)
+ { die "acontent_suffix not yet defined"; }
+ $index_prefix .= $acontent_suffix . ", ";
+ process_index_dl_compact($a);
+ $index_prefix = pop(@index_prefixes);
+ return; }
+
+ if ($a->tag ne "a")
+ { $dt->dump;
+ $a->dump;
+ die "Expected anchor in lone <DT>"; }
+
+ my ($aname, $ahref, @acontent) = anchor_info($a);
+ # unused $aname
+ if (scalar(@acontent) != 1)
+ { die "Expected just one content of <A> in <DT>: @acontent"; }
+ if (ref $acontent[0])
+ { $acontent[0]->dump;
+ die "Expected string content of <A> in <DT>: $acontent[0]"; }
+ if (!defined($acontent))
+ { $acontent = $index_prefix . $acontent[0];
+ $acontent_suffix = $acontent[0]; }
+ elsif (($acontent[0] ne "[Link]") && ($acontent ne ($index_prefix . $acontent[0])))
+ { die "Differing content: <<<$acontent>>>, <<<$acontent[0]>>>"; }
+
+ if (!defined $ahref)
+ { $dt->dump;
+ die "no HREF in nachor in <DT>"; }
+ my ($ahref_file, $ahref_name) = split(/\#/, $ahref);
+ if (!defined $ahref_name)
+ { # Reference to entire file
+ $ahref_name = ""; }
+
+ if ($ahref_name eq $l2h_broken_link_name)
+ { if (!exists $file_index_entries_broken{$ahref_file})
+ { $file_index_entries_broken{$ahref_file} = []; }
+ push @{$file_index_entries_broken{$ahref_file}}, "$this_indexing_command $acontent";
+ next; }
+
+ if (!exists $file_index_entries{$ahref_file})
+ { $file_index_entries{$ahref_file} = {}; }
+ # Don't do this! It appears to make a copy, which is not desired.
+ # my %index_entries = %{$file_index_entries{$ahref_file}};
+ if (!exists $ {$file_index_entries{$ahref_file}}{$ahref_name})
+ { $ {$file_index_entries{$ahref_file}}{$ahref_name} = []; }
+ # { my $oldcontent = $ {$file_index_entries{$ahref_file}}{$ahref_name};
+ # if ($acontent eq $oldcontent)
+ # { die "Multiple identical index entries?"; }
+ # die "Trying to add $acontent, but already have index entry pointing at $ahref_file\#$ahref_name: ${$file_index_entries{$ahref_file}}{$ahref_name}"; }
+
+ push @{$ {$file_index_entries{$ahref_file}}{$ahref_name}}, "$this_indexing_command $acontent";
+ # print STDERR "keys: ", keys %{$file_index_entries{$ahref_file}}, "\n";
+ }
+}
+
+sub process_index_dt_and_dd ( $$ )
+{ my ($dt, $dd) = check_args(2, @_);
+ my $dtcontent;
+ { my @dtcontent = @{$dt->content()};
+ if ((scalar(@dtcontent) != 1) || (ref $dtcontent[0]))
+ { $dd->dump;
+ $dt->dump;
+ die "Expected single string (actual size = " . scalar(@dtcontent) . ") in content of <DT>: @dtcontent"; }
+ $dtcontent = $dtcontent[0];
+ $dtcontent =~ s/ +$//; }
+ my $ddcontent;
+ { my @ddcontent = @{$dd->content()};
+ if (scalar(@ddcontent) != 1)
+ { die "Expected single <DD> content, got ", scalar(@ddcontent), " elements:\n", join("\n", @ddcontent), "\n "; }
+ $ddcontent = $ddcontent[0]; }
+ if ($ddcontent->tag ne "dl")
+ { die "Expected <DL> as content of <DD>, but saw: $ddcontent"; }
+
+ push @index_prefixes, $index_prefix;
+ $index_prefix .= $dtcontent . ", ";
+ process_index_dl_compact($ddcontent);
+ $index_prefix = pop(@index_prefixes);
+}
+
+
+###########################################################################
+### Ordinary sections
+###
+
+sub process_section_file ( $$$ )
+{ my ($file, $depth, $nodetitle) = check_args(3, @_);
+ my $he = file_to_tree(($file =~ /^\//) ? $file : $html_directory . $file);
+
+ # print STDERR "process_section_file: $file $depth $nodetitle\n";
+
+ # Equivalently:
+ # while ($depth >= scalar(@section_stack)) { pop(@section_stack); }
+ @section_stack = @section_stack[0..$depth-1];
+
+ # Not a great nodename fixup scheme; need a more global view
+ if ((defined $contents_fixups{$nodetitle})
+ && (scalar(@section_stack) > 0))
+ { my $up_title = $section_stack[$#section_stack];
+ # hack for Python Standard Library
+ $up_title =~ s/^(Built-in|Standard) Module //g;
+ my ($up_first_word) = split(/ /, $up_title);
+ $nodetitle = "$up_first_word $nodetitle";
+ }
+
+ push @section_stack, $nodetitle;
+ # print STDERR "new section_stack: ", join(", ", @section_stack), "\n";
+
+ $he->traverse(\&process_if_child_links, 'ignore text');
+ %footnotes = ();
+ # $he->dump;
+ $he->traverse(\&process_if_footnotes, 'ignore text');
+
+ # $he->dump;
+
+ if (exists $file_index_entries{$file})
+ { %this_index_entries = %{$file_index_entries{$file}};
+ # print STDERR "this_index_entries:\n ", join("\n ", keys %this_index_entries), "\n";
+ }
+ else
+ { # print STDERR "Warning: no index entries for file $file\n";
+ %this_index_entries = (); }
+
+ if (exists $file_index_entries_broken{$file})
+ { @this_index_entries_broken = @{$file_index_entries_broken{$file}}; }
+ else
+ { # print STDERR "Warning: no index entries for file $file\n";
+ @this_index_entries_broken = (); }
+
+
+ if ($he->tag() ne "html")
+ { die "Expected <HTML> at top level"; }
+ my @content = @{$he->content()};
+ if ((!ref $content[0]) or ($content[0]->tag ne "head"))
+ { $he->dump;
+ die "<HEAD> not first element of <HTML>"; }
+ if ((!ref $content[1]) or ($content[1]->tag ne "body"))
+ { $he->dump;
+ die "<BODY> not second element of <HTML>"; }
+
+ $content[1]->traverse(\&output_body);
+}
+
+# stack of things we're inside that are preventing indexing from occurring now.
+# These are "h1", "h2", "h3", "h4", "h5", "h6", "dt" (and possibly others?)
+my @index_deferrers = ();
+
+sub push_or_pop_index_deferrers ( $$ )
+{ my ($tag, $startflag) = check_args(2, @_);
+ if ($startflag)
+ { push @index_deferrers, $tag; }
+ else
+ { my $old_deferrer = pop @index_deferrers;
+ if ($tag ne $old_deferrer)
+ { die "Expected $tag at top of index_deferrers but saw $old_deferrer; remainder = ", join(" ", @index_deferrers); }
+ do_deferred_index_entries(); }
+}
+
+
+sub label_add_index_entries ( $;$ )
+{ my ($label, $he) = check_args_range(1, 2, @_);
+ # print ((exists $this_index_entries{$label}) ? "*" : " "), " label_add_index_entries $label\n";
+ # $he is the anchor element
+ if (exists $this_index_entries{$label})
+ { push @deferred_index_entries, @{$this_index_entries{$label}};
+ return; }
+
+ if ($label eq $l2h_broken_link_name)
+ { # Try to find some text to use in guessing which links should point here
+ # I should probably only look at the previous element, or if that is
+ # all punctuation, the one before it; collecting all the previous texts
+ # is a bit of overkill.
+ my @anchor_texts = collect_texts($he);
+ my @previous_texts = collect_texts($he->parent, $he);
+ # 4 elements is arbitrary; ought to filter out punctuation and small words
+ # first, then perhaps keep fewer. Perhaps also filter out formatting so
+ # that we can see a larger chunk of text? (Probably not.)
+ # Also perhaps should do further chunking into words, in case the
+ # index term isn't a chunk of its own (eg, was in <tt>...</tt>.
+ my @candidate_texts = (@anchor_texts, (reverse(@previous_texts))[0..min(3,$#previous_texts)]);
+
+ my $guessed = 0;
+ for my $text (@candidate_texts)
+ { # my $orig_text = $text;
+ if ($text =~ /^[\"\`\'().?! ]*$/)
+ { next; }
+ if (length($text) <= 2)
+ { next; }
+ # hack for Python manual; maybe defer until failure first time around?
+ $text =~ s/^sys\.//g;
+ for my $iterm (@this_index_entries_broken)
+ { # I could test for zero: LaTeX2HTML's failures in the Python
+ # documentation are only for items of the form "... (built-in...)"
+ if (index($iterm, $text) != -1)
+ { push @deferred_index_entries, $iterm;
+ # print STDERR "Guessing index term `$iterm' for text `$orig_text'\n";
+ $guessed = 1;
+ } } }
+ if (!$guessed)
+ { # print STDERR "No guess in `", join("'; `", @this_index_entries_broken), "' for texts:\n `", join("'\n `", @candidate_texts), "'\n";
+ }
+ }
+}
+
+
+# Need to add calls to this at various places.
+# Perhaps add HTML::Element argument and do the check for appropriateness
+# here (ie, no action if inside <H1>, etc.).
+sub do_deferred_index_entries ()
+{ check_args(0, @_);
+ if ((scalar(@deferred_index_entries) > 0)
+ && (scalar(@index_deferrers) == 0))
+ { print TEXI "\n", join("\n", @deferred_index_entries), "\n";
+ @deferred_index_entries = (); }
+}
+
+my $table_columns; # undefined if not in a table
+my $table_first_column; # boolean
+
+sub output_body ( $$$ )
+{ my ($he, $startflag) = (check_args(3, @_))[0,1]; # ignore depth argument
+
+ if (!ref $he)
+ { my $space_index = index($he, " ");
+ if ($space_index != -1)
+ { # Why does
+ # print TEXI texi_quote(substr($he, 0, $space_index+1));
+ # give: Can't locate object method "TEXI" via package "texi_quote"
+ # (Because the definition texi_quote hasn't been seen yet.)
+ print TEXI &texi_quote(substr($he, 0, $space_index+1));
+ do_deferred_index_entries();
+ print TEXI &texi_quote(substr($he, $space_index+1)); }
+ else
+ { print TEXI &texi_quote($he); }
+ return; }
+
+ my $tag = $he->tag();
+
+ # Ordinary text markup first
+ if (exists $inline_markup{$tag})
+ { if ($startflag)
+ { print TEXI "\@$inline_markup{$tag}\{"; }
+ else
+ { print TEXI "\}"; } }
+ elsif ($tag eq "a")
+ { my ($name, $href, @content) = anchor_info($he);
+ if (!$href)
+ { # This anchor is only here for indexing/cross referencing purposes.
+ if ($startflag)
+ { label_add_index_entries($name, $he); }
+ }
+ elsif ($href =~ "^(ftp|http|news):")
+ { if ($startflag)
+ { # Should avoid second argument if it's identical to the URL.
+ print TEXI "\@uref\{$href, "; }
+ else
+ { print TEXI "\}"; }
+ }
+ elsif ($href =~ /^\#(foot[0-9]+)$/)
+ { # Footnote
+ if ($startflag)
+ { # Could double-check name and content, but I'm not
+ # currently storing that information.
+ print TEXI "\@footnote\{";
+ $footnotes{$1}->traverse(\&output_body);
+ print TEXI "\}";
+ return 0; } }
+ else
+ { if ($startflag)
+ { # cross-references are not active Info links, but no text is lost
+ print STDERR "Can't deal with internal HREF anchors yet:\n";
+ $he->dump; }
+ }
+ }
+ elsif ($tag eq "br")
+ { print TEXI "\@\n"; }
+ elsif ($tag eq "body")
+ { }
+ elsif ($tag eq "center")
+ { if (has_single_content_string($he)
+ && ($ {$he->content}[0] =~ /^ *$/))
+ { return 0; }
+ if ($startflag)
+ { print TEXI "\n\@center\n"; }
+ else
+ { print TEXI "\n\@end center\n"; }
+ }
+ elsif ($tag eq "div")
+ { my $align = $he->attr('align');
+ if (defined($align) && ($align eq "center"))
+ { if (has_single_content_string($he)
+ && ($ {$he->content}[0] =~ /^ *$/))
+ { return 0; }
+ if ($startflag)
+ { print TEXI "\n\@center\n"; }
+ else
+ { print TEXI "\n\@end center\n"; } }
+ }
+ elsif ($tag eq "dl")
+ { # Recognize "<dl><dd><pre> ... </pre></dl>" paradigm for "@example"
+ if (has_single_content_with_tag($he, "dd"))
+ { my $he_dd = $ {$he->content}[0];
+ if (has_single_content_with_tag($he_dd, "pre"))
+ { my $he_pre = $ {$he_dd->content}[0];
+ print_pre($he_pre);
+ return 0; } }
+ if ($startflag)
+ { # Could examine the elements, to be cleverer about formatting.
+ # (Also to use ftable, vtable...)
+ print TEXI "\n\@table \@asis\n"; }
+ else
+ { print TEXI "\n\@end table\n"; }
+ }
+ elsif ($tag eq "dt")
+ { push_or_pop_index_deferrers($tag, $startflag);
+ if ($startflag)
+ { print TEXI "\n\@item "; }
+ else
+ { } }
+ elsif ($tag eq "dd")
+ { if ($startflag)
+ { print TEXI "\n"; }
+ else
+ { }
+ if (scalar(@index_deferrers) != 0)
+ { $he->dump;
+ die "Unexpected <$tag> while inside: (" . join(" ", @index_deferrers) . "); bad HTML?"; }
+ do_deferred_index_entries();
+ }
+ elsif ($tag =~ /^(font|big|small)$/)
+ { # Do nothing for now.
+ }
+ elsif ($tag =~ /^h[1-6]$/)
+ { # We don't need this because we never recursively enter the heading content.
+ # push_or_pop_index_deferrers($tag, $startflag);
+ my $secname = "";
+ my @seclabels = ();
+ for my $elt (@{$he->content})
+ { if (!ref $elt)
+ { $secname .= $elt; }
+ elsif ($elt->tag eq "br")
+ { }
+ elsif ($elt->tag eq "a")
+ { my ($name, $href, @acontent) = anchor_info($elt);
+ if ($href)
+ { $he->dump;
+ $elt->dump;
+ die "Nonsimple anchor in <$tag>"; }
+ if (!defined $name)
+ { die "No NAME for anchor in $tag"; }
+ push @seclabels, $name;
+ for my $subelt (@acontent)
+ { $secname .= html_to_texi($subelt); } }
+ else
+ { $secname .= html_to_texi($elt); } }
+ if ($secname eq "")
+ { die "No section name in <$tag>"; }
+ if (scalar(@section_stack) == 1)
+ { if ($section_stack[-1] ne "Top")
+ { die "Not top? $section_stack[-1]"; }
+ print TEXI "\@settitle $secname\n";
+ print TEXI "\@c %**end of header\n";
+ print TEXI "\n";
+ print TEXI "\@node Top\n";
+ print TEXI "\n"; }
+ else
+ { print TEXI "\n\@node $section_stack[-1]\n";
+ print TEXI "\@$sectionmarker[scalar(@section_stack)-1] ", texi_remove_punctuation($secname), "\n"; }
+ for my $seclabel (@seclabels)
+ { label_add_index_entries($seclabel); }
+ # This should only happen once per file.
+ label_add_index_entries("");
+ if (scalar(@index_deferrers) != 0)
+ { $he->dump;
+ die "Unexpected <$tag> while inside: (" . join(" ", @index_deferrers) . "); bad HTML?"; }
+ do_deferred_index_entries();
+ return 0;
+ }
+ elsif ($tag eq "hr")
+ { }
+ elsif ($tag eq "ignore")
+ { # Hack for ignored elements
+ return 0;
+ }
+ elsif ($tag eq "li")
+ { if ($startflag)
+ { print TEXI "\n\n\@item\n";
+ do_deferred_index_entries(); } }
+ elsif ($tag eq "ol")
+ { if ($startflag)
+ { print TEXI "\n\@enumerate \@bullet\n"; }
+ else
+ { print TEXI "\n\@end enumerate\n"; } }
+ elsif ($tag eq "p")
+ { if ($startflag)
+ { print TEXI "\n\n"; }
+ if (scalar(@index_deferrers) != 0)
+ { $he->dump;
+ die "Unexpected <$tag> while inside: (" . join(" ", @index_deferrers) . "); bad HTML?"; }
+ do_deferred_index_entries(); }
+ elsif ($tag eq "pre")
+ { print_pre($he);
+ return 0; }
+ elsif ($tag eq "table")
+ { # Could also indicate common formatting for first column, or
+ # determine relative widths for columns (or determine a prototype row)
+ if ($startflag)
+ { if (defined $table_columns)
+ { $he->dump;
+ die "Can't deal with table nested inside $table_columns-column table"; }
+ $table_columns = table_columns($he);
+ if ($table_columns < 2)
+ { $he->dump;
+ die "Column with $table_columns columns?"; }
+ elsif ($table_columns == 2)
+ { print TEXI "\n\@table \@asis\n"; }
+ else
+ { print TEXI "\n\@multitable \@columnfractions";
+ for (my $i=0; $i<$table_columns; $i++)
+ { print TEXI " ", 1.0/$table_columns; }
+ print TEXI "\n"; } }
+ else
+ { if ($table_columns == 2)
+ { print TEXI "\n\@end table\n"; }
+ else
+ { print TEXI "\n\@end multitable\n"; }
+ undef $table_columns; } }
+ elsif (($tag eq "td") || ($tag eq "th"))
+ { if ($startflag)
+ { if ($table_first_column)
+ { print TEXI "\n\@item ";
+ $table_first_column = 0; }
+ elsif ($table_columns > 2)
+ { print TEXI "\n\@tab "; } }
+ else
+ { print TEXI "\n"; } }
+ elsif ($tag eq "tr")
+ { if ($startflag)
+ { $table_first_column = 1; } }
+ elsif ($tag eq "ul")
+ { if ($startflag)
+ { print TEXI "\n\@itemize \@bullet\n"; }
+ else
+ { print TEXI "\n\@end itemize\n"; } }
+ else
+ { # I used to have a newline before "output_body" here.
+ print STDERR "output_body: ignoring <$tag> tag\n";
+ $he->dump;
+ return 0; }
+
+ return 1;
+}
+
+sub print_pre ( $ )
+{ my ($he_pre) = check_args(1, @_);
+ if (!has_single_content_string($he_pre))
+ { die "Multiple or non-string content for <PRE>: ", @{$he_pre->content}; }
+ my $pre_content = $ {$he_pre->content}[0];
+ print TEXI "\n\@example";
+ print TEXI &texi_quote($pre_content);
+ print TEXI "\@end example\n";
+}
+
+sub table_columns ( $ )
+{ my ($table) = check_args(1, @_);
+ my $result = 0;
+ for my $row (@{$table->content})
+ { if ($row->tag ne "tr")
+ { $table->dump;
+ $row->dump;
+ die "Expected <TR> as table row."; }
+ $result = max($result, scalar(@{$row->content})); }
+ return $result;
+}
+
+
+###########################################################################
+### Utilities
+###
+
+sub min ( $$ )
+{ my ($x, $y) = check_args(2, @_);
+ return ($x < $y) ? $x : $y;
+}
+
+sub max ( $$ )
+{ my ($x, $y) = check_args(2, @_);
+ return ($x > $y) ? $x : $y;
+}
+
+sub file_to_tree ( $ )
+{ my ($file) = check_args(1, @_);
+
+ my $tree = new HTML::TreeBuilder;
+ $tree->ignore_unknown(1);
+ # $tree->warn(1);
+ $tree->parse_file($file);
+ cleanup_parse_tree($tree);
+ return $tree
+}
+
+
+sub has_single_content ( $ )
+{ my ($he) = check_args(1, @_);
+ if (!ref $he)
+ { # return 0;
+ die "Non-reference argument: $he"; }
+ my $ref_content = $he->content;
+ if (!defined $ref_content)
+ { return 0; }
+ my @content = @{$ref_content};
+ if (scalar(@content) != 1)
+ { return 0; }
+ return 1;
+}
+
+
+# Return true if the content of the element contains only one element itself,
+# and that inner element has the specified tag.
+sub has_single_content_with_tag ( $$ )
+{ my ($he, $tag) = check_args(2, @_);
+ if (!has_single_content($he))
+ { return 0; }
+ my $content = $ {$he->content}[0];
+ if (!ref $content)
+ { return 0; }
+ my $content_tag = $content->tag;
+ if (!defined $content_tag)
+ { return 0; }
+ return $content_tag eq $tag;
+}
+
+sub has_single_content_string ( $ )
+{ my ($he) = check_args(1, @_);
+ if (!has_single_content($he))
+ { return 0; }
+ my $content = $ {$he->content}[0];
+ if (ref $content)
+ { return 0; }
+ return 1;
+}
+
+
+# Return name, href, content. First two may be undefined; third is an array.
+# I don't see how to determine if there are more attributes.
+sub anchor_info ( $ )
+{ my ($he) = check_args(1, @_);
+ if ($he->tag ne "a")
+ { $he->dump;
+ die "passed non-anchor to anchor_info"; }
+ my $name = $he->attr('name');
+ my $href = $he->attr('href');
+ my @content = ();
+ { my $ref_content = $he->content;
+ if (defined $ref_content)
+ { @content = @{$ref_content}; } }
+ return ($name, $href, @content);
+}
+
+
+sub texi_quote ( $ )
+{ my ($text) = check_args(1, @_);
+ $text =~ s/([\@\{\}])/\@$1/g;
+ $text =~ s/ -- / --- /g;
+ return $text;
+}
+
+# Eliminate bad punctuation (that confuses Makeinfo or Info) for section titles.
+sub texi_remove_punctuation ( $ )
+{ my ($text) = check_args(1, @_);
+
+ $text =~ s/^ +//g;
+ $text =~ s/[ :]+$//g;
+ $text =~ s/^[1-9][0-9.]* +//g;
+ $text =~ s/,//g;
+ # Both embedded colons and " -- " confuse makeinfo. (Perhaps " -- "
+ # gets converted into " - ", just as "---" would be converted into " -- ",
+ # so the names end up differing.)
+ # $text =~ s/:/ -- /g;
+ $text =~ s/://g;
+ return $text;
+}
+
+
+## Do not use this inside `traverse': it throws off the traversal. Use
+## html_replace_by_ignore or html_replace_by_meta instead.
+# Returns 1 if success, 0 if failure.
+sub html_remove ( $;$ )
+{ my ($he, $parent) = check_args_range(1, 2, @_);
+ if (!defined $parent)
+ { $parent = $he->parent; }
+ my $ref_pcontent = $parent->content;
+ my @pcontent = @{$ref_pcontent};
+ for (my $i=0; $i<scalar(@pcontent); $i++)
+ { if ($pcontent[$i] eq $he)
+ { splice @{$ref_pcontent}, $i, 1;
+ $he->parent(undef);
+ return 1; } }
+ die "Didn't find $he in $parent";
+}
+
+
+sub html_replace ( $$;$ )
+{ my ($orig, $new, $parent) = check_args_range(2, 3, @_);
+ if (!defined $parent)
+ { $parent = $orig->parent; }
+ my $ref_pcontent = $parent->content;
+ my @pcontent = @{$ref_pcontent};
+ for (my $i=0; $i<scalar(@pcontent); $i++)
+ { if ($pcontent[$i] eq $orig)
+ { $ {$ref_pcontent}[$i] = $new;
+ $new->parent($parent);
+ $orig->parent(undef);
+ return 1; } }
+ die "Didn't find $orig in $parent";
+}
+
+sub html_replace_by_meta ( $;$ )
+{ my ($orig, $parent) = check_args_range(1, 2, @_);
+ my $meta = new HTML::Element "meta";
+ if (!defined $parent)
+ { $parent = $orig->parent; }
+ return html_replace($orig, $meta, $parent);
+}
+
+sub html_replace_by_ignore ( $;$ )
+{ my ($orig, $parent) = check_args_range(1, 2, @_);
+ my $ignore = new HTML::Element "ignore";
+ if (!defined $parent)
+ { $parent = $orig->parent; }
+ return html_replace($orig, $ignore, $parent);
+}
+
+
+
+###
+### Collect text elements
+###
+
+my @collected_texts;
+my $collect_texts_stoppoint;
+my $done_collecting;
+
+sub collect_texts ( $;$ )
+{ my ($root, $stop) = check_args_range(1, 2, @_);
+ # print STDERR "collect_texts: $root $stop\n";
+ $collect_texts_stoppoint = $stop;
+ $done_collecting = 0;
+ @collected_texts = ();
+ $root->traverse(\&collect_if_text); # process texts
+ # print STDERR "collect_texts => ", join(";;;", @collected_texts), "\n";
+ return @collected_texts;
+}
+
+sub collect_if_text ( $$$ )
+{ my $he = (check_args(3, @_))[0]; # ignore depth and startflag arguments
+ if ($done_collecting)
+ { return 0; }
+ if (!defined $he)
+ { return 0; }
+ if (!ref $he)
+ { push @collected_texts, $he;
+ return 0; }
+ if ((defined $collect_texts_stoppoint) && ($he eq $collect_texts_stoppoint))
+ { $done_collecting = 1;
+ return 0; }
+ return 1;
+}
+
+
+###########################################################################
+### Clean up parse tree
+###
+
+sub cleanup_parse_tree ( $ )
+{ my ($he) = check_args(1, @_);
+ $he->traverse(\&delete_if_navigation, 'ignore text');
+ $he->traverse(\&delete_extra_spaces, 'ignore text');
+ $he->traverse(\&merge_dl, 'ignore text');
+ $he->traverse(\&reorder_dt_and_dl, 'ignore text');
+ return $he;
+}
+
+
+## Simpler version that deletes contents but not the element itself.
+# sub delete_if_navigation ( $$$ )
+# { my $he = (check_args(3, @_))[0]; # ignore startflag and depth
+# if (($he->tag() eq "div") && ($he->attr('class') eq 'navigation'))
+# { $he->delete();
+# return 0; }
+# else
+# { return 1; }
+# }
+
+sub delete_if_navigation ( $$$ )
+{ my ($he, $startflag) = (check_args(3, @_))[0,1]; # ignore depth argument
+ if (!$startflag)
+ { return; }
+
+ if (($he->tag() eq "div") && (defined $he->attr('class')) && ($he->attr('class') eq 'navigation'))
+ { my $ref_pcontent = $he->parent()->content();
+ # Don't try to modify @pcontent, which appears to be a COPY.
+ # my @pcontent = @{$ref_pcontent};
+ for (my $i = 0; $i<scalar(@{$ref_pcontent}); $i++)
+ { if (${$ref_pcontent}[$i] eq $he)
+ { splice(@{$ref_pcontent}, $i, 1);
+ last; } }
+ $he->delete();
+ return 0; }
+ else
+ { return 1; }
+}
+
+sub delete_extra_spaces ( $$$ )
+{ my ($he, $startflag) = (check_args(3, @_))[0,1]; # ignore depth argument
+ if (!$startflag)
+ { return; }
+
+ my $tag = $he->tag;
+ if ($tag =~ /^(head|html|table|tr|ul)$/)
+ { delete_child_spaces($he); }
+ delete_trailing_spaces($he);
+ return 1;
+}
+
+
+sub delete_child_spaces ( $ )
+{ my ($he) = check_args(1, @_);
+ my $ref_content = $he->content();
+ for (my $i = 0; $i<scalar(@{$ref_content}); $i++)
+ { if ($ {$ref_content}[$i] =~ /^ *$/)
+ { splice(@{$ref_content}, $i, 1);
+ $i--; } }
+}
+
+sub delete_trailing_spaces ( $ )
+{ my ($he) = check_args(1, @_);
+ my $ref_content = $he->content();
+ if (! defined $ref_content)
+ { return; }
+ # Could also check for previous element = /^h[1-6]$/.
+ for (my $i = 0; $i<scalar(@{$ref_content})-1; $i++)
+ { if ($ {$ref_content}[$i] =~ /^ *$/)
+ { my $next_elt = $ {$ref_content}[$i+1];
+ if ((ref $next_elt) && ($next_elt->tag =~ /^(br|dd|dl|dt|hr|p|ul)$/))
+ { splice(@{$ref_content}, $i, 1);
+ $i--; } } }
+ if ($he->tag =~ /^(dd|dt|^h[1-6]|li|p)$/)
+ { my $last_elt = $ {$ref_content}[$#{$ref_content}];
+ if ((defined $last_elt) && ($last_elt =~ /^ *$/))
+ { pop @{$ref_content}; } }
+}
+
+
+# LaTeX2HTML sometimes creates
+# <DT>text
+# <DL COMPACT><DD>text
+# which should actually be:
+# <DL COMPACT>
+# <DT>text
+# <DD>text
+# Since a <DL> gets added, this ends up looking like
+# <P>
+# <DL>
+# <DT>
+# text1...
+# <DL COMPACT>
+# <DD>
+# text2...
+# dt_or_dd1...
+# dt_or_dd2...
+# which should become
+# <P>
+# <DL COMPACT>
+# <DT>
+# text1...
+# <DD>
+# text2...
+# dt_or_dd1...
+# dt_or_dd2...
+
+sub reorder_dt_and_dl ( $$$ )
+{ my ($he, $startflag) = (check_args(3, @_))[0,1]; # ignore depth argument
+ if (!$startflag)
+ { return; }
+
+ if ($he->tag() eq "p")
+ { my $ref_pcontent = $he->content();
+ if (defined $ref_pcontent)
+ { my @pcontent = @{$ref_pcontent};
+ # print "reorder_dt_and_dl found a <p>\n"; $he->dump();
+ if ((scalar(@pcontent) >= 1)
+ && (ref $pcontent[0]) && ($pcontent[0]->tag() eq "dl")
+ && $pcontent[0]->implicit())
+ { my $ref_dlcontent = $pcontent[0]->content();
+ # print "reorder_dt_and_dl found a <p> and implicit <dl>\n";
+ if (defined $ref_dlcontent)
+ { my @dlcontent = @{$ref_dlcontent};
+ if ((scalar(@dlcontent) >= 1)
+ && (ref $dlcontent[0]) && ($dlcontent[0]->tag() eq "dt"))
+ { my $ref_dtcontent = $dlcontent[0]->content();
+ # print "reorder_dt_and_dl found a <p>, implicit <dl>, and <dt>\n";
+ if (defined $ref_dtcontent)
+ { my @dtcontent = @{$ref_dtcontent};
+ if ((scalar(@dtcontent) > 0)
+ && (ref $dtcontent[$#dtcontent])
+ && ($dtcontent[$#dtcontent]->tag() eq "dl"))
+ { my $ref_dl2content = $dtcontent[$#dtcontent]->content();
+ # print "reorder_dt_and_dl found a <p>, implicit <dl>, <dt>, and <dl>\n";
+ if (defined $ref_dl2content)
+ { my @dl2content = @{$ref_dl2content};
+ if ((scalar(@dl2content) > 0)
+ && (ref ($dl2content[0]))
+ && ($dl2content[0]->tag() eq "dd"))
+ {
+ # print "reorder_dt_and_dl found a <p>, implicit <dl>, <dt>, <dl>, and <dd>\n";
+ # print STDERR "CHANGING\n"; $he->dump();
+ html_replace_by_ignore($dtcontent[$#dtcontent]);
+ splice(@{$ref_dlcontent}, 1, 0, @dl2content);
+ # print STDERR "CHANGED TO:\n"; $he->dump();
+ return 0; # don't traverse children
+ } } } } } } } } }
+ return 1;
+}
+
+
+# If we find a paragraph that looks like
+# <P>
+# <HR>
+# <UL>
+# then accumulate its links into a contents_list and delete the paragraph.
+sub process_if_child_links ( $$$ )
+{ my ($he, $startflag) = (check_args(3, @_))[0,1]; # ignore depth argument
+ if (!$startflag)
+ { return; }
+
+ if ($he->tag() eq "p")
+ { my $ref_content = $he->content();
+ if (defined $ref_content)
+ { my @content = @{$ref_content};
+ if ((scalar(@content) == 2)
+ && (ref $content[0]) && $content[0]->tag() eq "hr"
+ && (ref $content[1]) && $content[1]->tag() eq "ul")
+ { process_child_links($he);
+ $he->delete();
+ return 0; } } }
+ return 1;
+}
+
+
+# If we find
+# <H4>
+# "Footnotes"
+# <DL>
+# <DT>
+# <A NAME="foot560">
+# "...borrow"
+# <A HREF="refcountsInPython.html#tex2html2" NAME="foot560">
+# "1.2"
+# <DD>
+# "The metaphor of ``borrowing'' a reference is not completely correct: the owner still has a copy of the reference. "
+# ...
+# then record the footnote information and delete the section and list.
+
+my $process_if_footnotes_expect_dl_next = 0;
+
+sub process_if_footnotes ( $$$ )
+{ my ($he, $startflag) = (check_args(3, @_))[0,1]; # ignore depth argument
+ if (!$startflag)
+ { return; }
+
+ if (($he->tag() eq "h4")
+ && has_single_content_string($he)
+ && ($ {$he->content}[0] eq "Footnotes"))
+ { html_replace_by_ignore($he);
+ $process_if_footnotes_expect_dl_next = 1;
+ return 0; }
+
+ if ($process_if_footnotes_expect_dl_next && ($he->tag() eq "dl"))
+ { my $ref_content = $he->content();
+ if (defined $ref_content)
+ { $process_if_footnotes_expect_dl_next = 0;
+ my @content = @{$ref_content};
+ for (my $i=0; $i<$#content; $i+=2)
+ { my $he_dt = $content[$i];
+ my $he_dd = $content[$i+1];
+ if (($he_dt->tag ne "dt") || ($he_dd->tag ne "dd"))
+ { $he->dump;
+ die "expected <DT> and <DD> at positions $i and ", $i+1; }
+ my @dt_content = @{$he_dt->content()};
+ if ((scalar(@dt_content) != 2)
+ || ($dt_content[0]->tag ne "a")
+ || ($dt_content[1]->tag ne "a"))
+ { $he_dt->dump;
+ die "Expected 2 anchors as content of <DT>"; }
+ my ($dt1_name, $dt1_href, $dt1_content) = anchor_info($dt_content[0]);
+ my ($dt2_name, $dt2_href, $dt2_content) = anchor_info($dt_content[0]);
+ # unused: $dt1_href, $dt1_content, $dt2_href, $dt2_content
+ if ($dt1_name ne $dt2_name)
+ { $he_dt->dump;
+ die "Expected identical names for anchors"; }
+ html_replace_by_ignore($he_dd);
+ $he_dd->tag("div"); # has no effect
+ $footnotes{$dt1_name} = $he_dd; }
+ html_replace_by_ignore($he);
+ return 0; } }
+
+ if ($process_if_footnotes_expect_dl_next)
+ { $he->dump;
+ die "Expected <DL> for footnotes next"; }
+
+ return 1;
+}
+
+
+
+## Merge two adjacent paragraphs containing <DL> items, such as:
+# <P>
+# <DL>
+# <DT>
+# ...
+# <DD>
+# ...
+# <P>
+# <DL>
+# <DT>
+# ...
+# <DD>
+# ...
+
+sub merge_dl ( $$$ )
+{ my ($he, $startflag) = (check_args(3, @_))[0,1]; # ignore depth argument
+ if (!$startflag)
+ { return; }
+
+ my $ref_content = $he->content;
+ if (!defined $ref_content)
+ { return; }
+ my $i = 0;
+ while ($i < scalar(@{$ref_content})-1)
+ { my $p1 = $ {$ref_content}[$i];
+ if ((ref $p1) && ($p1->tag eq "p")
+ && has_single_content_with_tag($p1, "dl"))
+ { my $dl1 = $ {$p1->content}[0];
+ # In this loop, rhs, not lhs, of < comparison changes,
+ # because we are removing elements from the content of $he.
+ while ($i < scalar(@{$ref_content})-1)
+ { my $p2 = $ {$ref_content}[$i+1];
+ if (!((ref $p2) && ($p2->tag eq "p")
+ && has_single_content_with_tag($p2, "dl")))
+ { last; }
+ # Merge these two elements.
+ splice(@{$ref_content}, $i+1, 1); # remove $p2
+ my $dl2 = $ {$p2->content}[0];
+ $dl1->push_content(@{$dl2->content}); # put $dl2's content in $dl1
+ }
+ # extra increment because next element isn't a candidate for $p1
+ $i++; }
+ $i++; }
+ return 1;
+}
+
+
+
+###########################################################################
+### Testing
+###
+
+sub test ( $$ )
+{ my ($action, $file) = check_args(2, @_);
+
+ # General testing
+ if (($action eq "view") || ($action eq ""))
+ { # # $file = "/homes/gws/mernst/www/links.html";
+ # # $file = "/homes/gws/mernst/www/index.html";
+ # # $file = "/homes/fish/mernst/java/gud/doc/manual.html";
+ # # $file = "/projects/cecil/cecil/doc/manuals/stdlib-man/stdlib/stdlib.html";
+ # # $file = "/homes/fish/mernst/tmp/python-doc/html/index.html";
+ # $file = "/homes/fish/mernst/tmp/python-doc/html/api/complexObjects.html";
+ my $tree = file_to_tree($file);
+
+ ## Testing
+ # print STDERR $tree->as_HTML;
+ $tree->dump();
+
+ # print STDERR $tree->tag(), "\n";
+ # print STDERR @{$tree->content()}, "\n";
+ #
+ # for (@{ $tree->extract_links(qw(a img)) }) {
+ # my ($link, $linkelem) = @$_;
+ # print STDERR "$link ", $linkelem->as_HTML;
+ # }
+ #
+ # print STDERR @{$tree->extract_links()}, "\n";
+
+ # my @top_level_elts = @{$tree->content()};
+
+ # if scalar(@{$tree->content()})
+ return;
+ }
+
+ elsif ($action eq "raw")
+ { my $tree = new HTML::TreeBuilder;
+ $tree->ignore_unknown(1);
+ # $tree->warn(1);
+ $tree->parse_file($file);
+
+ $tree->dump();
+
+ # cleanup_parse_tree($tree);
+ # $tree->dump();
+ return;
+ }
+
+ # Test dealing with a section.
+ elsif ($action eq "section")
+ { # my $file;
+ # $file = "/homes/fish/mernst/tmp/python-doc/html/api/intro.html";
+ # $file = "/homes/fish/mernst/tmp/python-doc/html/api/includes.html";
+ # $file = "/homes/fish/mernst/tmp/python-doc/html/api/complexObjects.html";
+ process_section_file($file, 0, "Title");
+ }
+
+ # Test dealing with many sections
+ elsif (0)
+ { my @files = ("/homes/fish/mernst/tmp/python-doc/html/api/about.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/abstract.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/api.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/cObjects.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/complexObjects.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/concrete.html",
+ # "/homes/fish/mernst/tmp/python-doc/html/api/contents.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/countingRefs.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/debugging.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/dictObjects.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/embedding.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/exceptionHandling.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/exceptions.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/fileObjects.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/floatObjects.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/front.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/fundamental.html",
+ # "/homes/fish/mernst/tmp/python-doc/html/api/genindex.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/importing.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/includes.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/index.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/initialization.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/intObjects.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/intro.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/listObjects.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/longObjects.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/mapObjects.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/mapping.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/newTypes.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/node24.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/noneObject.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/number.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/numericObjects.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/object.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/objects.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/os.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/otherObjects.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/processControl.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/refcountDetails.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/refcounts.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/sequence.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/sequenceObjects.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/standardExceptions.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/stringObjects.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/threads.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/tupleObjects.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/typeObjects.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/types.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/utilities.html",
+ "/homes/fish/mernst/tmp/python-doc/html/api/veryhigh.html");
+ for my $file (@files)
+ { print STDERR "\n", "=" x 75, "\n", "$file:\n";
+ process_section_file($file, 0, "Title");
+ }
+ }
+
+ # Test dealing with index.
+ elsif ($action eq "index")
+ { # my $file;
+ # $file = "/homes/fish/mernst/tmp/python-doc/html/api/genindex.html";
+
+ process_index_file($file, "\@cindex");
+ print_index_info();
+ }
+
+ else
+ { die "Unrecognized action `$action'"; }
+}
+
+
+###########################################################################
+### Main loop
+###
+
+sub process_contents_file ( $ )
+{ my ($file) = check_args(1, @_);
+
+ # could also use File::Basename
+ my $info_file = $file;
+ $info_file =~ s/(\/?index)?\.html$//;
+ if ($info_file eq "")
+ { chomp($info_file = `pwd`); }
+ $info_file =~ s/^.*\///; # not the most efficient way to remove dirs
+
+ $html_directory = $file;
+ $html_directory =~ s/(\/|^)[^\/]+$/$1/;
+
+ my $texi_file = "$info_file.texi";
+ open(TEXI, ">$texi_file");
+
+ print TEXI "\\input texinfo \@c -*-texinfo-*-\n";
+ print TEXI "\@c %**start of header\n";
+ print TEXI "\@setfilename $info_file\n";
+
+ # 2. Summary Description and Copyright
+ # The "Summary Description and Copyright" segment describes the
+ # document and contains the copyright notice and copying permissions
+ # for the Info file. The segment must be enclosed between `@ifinfo'
+ # and `@end ifinfo' commands so that the formatters place it only in
+ # the Info file.
+ #
+ # The summary description and copyright segment does not appear in the
+ # printed document.
+ #
+ # @ifinfo
+ # This is a short example of a complete Texinfo file.
+ #
+ # Copyright @copyright{} 1990 Free Software Foundation, Inc.
+ # @end ifinfo
+
+
+ # 3. Title and Copyright
+ # The "Title and Copyright" segment contains the title and copyright
+ # pages and copying permissions for the printed manual. The segment
+ # must be enclosed between `@titlepage' and `@end titlepage'
+ # commands. The title and copyright page appear only in the printed
+ # manual.
+ #
+ # The titlepage segment does not appear in the Info file.
+ #
+ # @titlepage
+ # @sp 10
+ # @comment The title is printed in a large font.
+ # @center @titlefont{Sample Title}
+ #
+ # @c The following two commands start the copyright page.
+ # @page
+ # @vskip 0pt plus 1filll
+ # Copyright @copyright{} 1990 Free Software Foundation, Inc.
+ # @end titlepage
+
+
+ # 4. `Top' Node and Master Menu
+ # The "Master Menu" contains a complete menu of all the nodes in the
+ # whole Info file. It appears only in the Info file, in the `Top'
+ # node.
+ #
+ # The `Top' node contains the master menu for the Info file. Since a
+ # printed manual uses a table of contents rather than a menu, the master
+ # menu appears only in the Info file.
+ #
+ # @node Top, First Chapter, , (dir)
+ # @comment node-name, next, previous, up
+ #
+ # @menu
+ # * First Chapter:: The first chapter is the
+ # only chapter in this sample.
+ # * Concept Index:: This index has two entries.
+ # @end menu
+
+
+
+ $current_ref_tdf = [ "Top", 0, $ARGV[0] ];
+ process_section_file($file, 0, "Top");
+ while (scalar(@contents_list))
+ { $current_ref_tdf = shift @contents_list;
+ process_section_file($ {$current_ref_tdf}[2], $ {$current_ref_tdf}[1], $ {$current_ref_tdf}[0]);
+ }
+
+ print TEXI "\n";
+ for my $indextitle (@index_titles)
+ { print TEXI "\@node $indextitle\n";
+ print TEXI "\@unnumbered $indextitle\n";
+ print TEXI "\@printindex $ {$index_info{$indextitle}}[1]\n";
+ print TEXI "\n"; }
+
+ print TEXI "\@contents\n";
+ print TEXI "\@bye\n";
+ close(TEXI);
+}
+
+# This needs to be last so global variable initializations are reached.
+
+if (scalar(@ARGV) == 0)
+{ die "No arguments supplied to html2texi.pl"; }
+
+if ($ARGV[0] eq "-test")
+{ my @test_args = @ARGV[1..$#ARGV];
+ if (scalar(@test_args) == 0)
+ { test("", "index.html"); }
+ elsif (scalar(@test_args) == 1)
+ { test("", $test_args[0]); }
+ elsif (scalar(@test_args) == 2)
+ { test($test_args[0], $test_args[1]); }
+ else
+ { die "Too many test arguments passed to html2texi: ", join(" ", @ARGV); }
+ exit();
+}
+
+if (scalar(@ARGV) != 1)
+{ die "Pass one argument, the main/contents page"; }
+
+process_contents_file($ARGV[0]);
+
+# end of html2texi.pl
diff --git a/doc/tools/indfix.py b/doc/tools/indfix.py
new file mode 100755
index 0000000..38f95bc
--- /dev/null
+++ b/doc/tools/indfix.py
@@ -0,0 +1,101 @@
+#! /usr/bin/env python
+
+"""Combine similar index entries into an entry and subentries.
+
+For example:
+
+ \item {foobar} (in module flotz), 23
+ \item {foobar} (in module whackit), 4323
+
+becomes
+
+ \item {foobar}
+ \subitem in module flotz, 23
+ \subitem in module whackit, 4323
+
+Note that an item which matches the format of a collapsable item but which
+isn't part of a group of similar items is not modified.
+"""
+__version__ = '$Revision: 1.1.1.1 $'
+
+import re
+import string
+import StringIO
+import sys
+
+
+def cmp_entries(e1, e2, lower=string.lower):
+ return cmp(lower(e1[1]), lower(e2[1])) or cmp(e1, e2)
+
+
+def dump_entries(write, entries):
+ if len(entries) == 1:
+ write(" \\item %s (%s)%s\n" % entries[0])
+ return
+ write(" \item %s\n" % entries[0][0])
+ # now sort these in a case insensitive manner:
+ if len(entries) > 0:
+ entries.sort(cmp_entries)
+ for xxx, subitem, pages in entries:
+ write(" \subitem %s%s\n" % (subitem, pages))
+
+
+breakable_re = re.compile(
+ r" \\item (.*) [(](.*)[)]((?:(?:, \d+)|(?:, \\[a-z]*\{\d+\}))+)")
+
+
+def process(ifn, ofn=None):
+ if ifn == "-":
+ ifp = sys.stdin
+ else:
+ ifp = open(ifn)
+ if ofn is None:
+ ofn = ifn
+ ofp = StringIO.StringIO()
+ entries = []
+ match = breakable_re.match
+ write = ofp.write
+ while 1:
+ line = ifp.readline()
+ if not line:
+ break
+ m = match(line)
+ if m:
+ entry = m.group(1, 2, 3)
+ if entries and entries[-1][0] != entry[0]:
+ dump_entries(write, entries)
+ entries = []
+ entries.append(entry)
+ elif entries:
+ dump_entries(write, entries)
+ entries = []
+ write(line)
+ else:
+ write(line)
+ del write
+ del match
+ ifp.close()
+ data = ofp.getvalue()
+ ofp.close()
+ if ofn == "-":
+ ofp = sys.stdout
+ else:
+ ofp = open(ofn, "w")
+ ofp.write(data)
+ ofp.close()
+
+
+def main():
+ import getopt
+ outfile = None
+ opts, args = getopt.getopt(sys.argv[1:], "o:")
+ for opt, val in opts:
+ if opt in ("-o", "--output"):
+ outfile = val
+ filename = args[0]
+ outfile = outfile or filename
+ process(filename, outfile)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/doc/tools/info/Makefile b/doc/tools/info/Makefile
new file mode 100644
index 0000000..24d6057
--- /dev/null
+++ b/doc/tools/info/Makefile
@@ -0,0 +1,73 @@
+# Generate the Python "info" documentation.
+
+TOPDIR=..
+TOOLSDIR=$(TOPDIR)/tools
+HTMLDIR=$(TOPDIR)/html
+
+MKINFO=$(TOOLSDIR)/mkinfo
+SCRIPTS=$(TOOLSDIR)/html2texi.pl $(TOOLSDIR)/checkargs.pm $(TOOLSDIR)/mkinfo \
+ $(TOOLSDIR)/fixinfo.el
+
+all: python-api.info python-ext.info python-lib.info \
+ python-ref.info python-tut.info \
+ python-dist.info python-inst.info
+
+
+python-api.info: $(HTMLDIR)/api/api.html $(SCRIPTS)
+ $(MKINFO) $<
+
+python-ext.info: $(HTMLDIR)/ext/ext.html $(SCRIPTS)
+ $(MKINFO) $<
+
+python-lib.info: $(HTMLDIR)/lib/lib.html $(SCRIPTS)
+ $(MKINFO) $<
+
+# Not built by default; the conversion doesn't really handle it well.
+python-mac.info: $(HTMLDIR)/mac/mac.html $(SCRIPTS)
+ $(MKINFO) $<
+
+python-ref.info: $(HTMLDIR)/ref/ref.html $(SCRIPTS)
+ $(MKINFO) $<
+
+python-tut.info: $(HTMLDIR)/tut/tut.html $(SCRIPTS)
+ $(MKINFO) $<
+
+python-dist.info: $(HTMLDIR)/dist/dist.html $(SCRIPTS)
+ $(MKINFO) $<
+
+python-inst.info: $(HTMLDIR)/inst/inst.html $(SCRIPTS)
+ $(MKINFO) $<
+
+clean:
+ rm -f *.texi~ *.texi
+
+clobber: clean
+ rm -f *.texi python-*.info python-*.info-[0-9]*
+
+
+# This makes sure we can build info files from a "clean" tree,
+# in case we haven't already built the HTML:
+
+$(HTMLDIR)/api/api.html:
+ (cd $(HTMLDIR); $(MAKE) api)
+
+$(HTMLDIR)/ext/ext.html:
+ (cd $(HTMLDIR); $(MAKE) ext)
+
+$(HTMLDIR)/lib/lib.html:
+ (cd $(HTMLDIR); $(MAKE) lib)
+
+$(HTMLDIR)/mac/mac.html:
+ (cd $(HTMLDIR); $(MAKE) mac)
+
+$(HTMLDIR)/ref/ref.html:
+ (cd $(HTMLDIR); $(MAKE) ref)
+
+$(HTMLDIR)/tut/tut.html:
+ (cd $(HTMLDIR); $(MAKE) tut)
+
+$(HTMLDIR)/dist/dist.html:
+ (cd $(HTMLDIR); $(MAKE) dist)
+
+$(HTMLDIR)/inst/inst.html:
+ (cd $(HTMLDIR); $(MAKE) inst)
diff --git a/doc/tools/info/README b/doc/tools/info/README
new file mode 100644
index 0000000..8e49a99
--- /dev/null
+++ b/doc/tools/info/README
@@ -0,0 +1,21 @@
+This archive contains the standard Python documentation in GNU info
+format. Five manuals are included:
+
+ python-ref.info* Python Reference Manual
+ python-mac.info* Python Macintosh Modules
+ python-lib.info* Python Library Reference
+ python-ext.info* Extending and Embedding the Python Interpreter
+ python-api.info* Python/C API Reference
+ python-tut.info* Python Tutorial
+
+The file python.dir is a fragment of a "dir" file that can be used to
+incorporate these documents into an existing GNU info installation:
+insert the contents of this file into the "dir" or "localdir" file at
+an appropriate point and copy the python-*.info* files to the same
+directory.
+
+Thanks go to Milan Zamazal <pdm@freesoft.cz> for providing this
+conversion to the info format.
+
+Questions and comments on these documents should be directed to
+python-docs@python.org.
diff --git a/doc/tools/info/python.dir b/doc/tools/info/python.dir
new file mode 100644
index 0000000..60e3e3a
--- /dev/null
+++ b/doc/tools/info/python.dir
@@ -0,0 +1,9 @@
+
+Python Standard Documentation
+
+* Python Library: (python-lib). Python Library Reference
+* Python Mac Modules: (python-mac). Python Macintosh Modules
+* Python Reference: (python-ref). Python Reference Manual
+* Python API: (python-api). Python/C API Reference Manual
+* Python Extending: (python-ext). Extending & Embedding Python
+* Python Tutorial: (python-tut). Python Tutorial
diff --git a/doc/tools/keywords.py b/doc/tools/keywords.py
new file mode 100644
index 0000000..6da352a
--- /dev/null
+++ b/doc/tools/keywords.py
@@ -0,0 +1,20 @@
+#! /usr/bin/env python
+
+# This Python program sorts and reformats the table of keywords in ref2.tex
+
+import string
+l = []
+try:
+ while 1:
+ l = l + string.split(raw_input())
+except EOFError:
+ pass
+l.sort()
+for x in l[:]:
+ while l.count(x) > 1: l.remove(x)
+ncols = 5
+nrows = (len(l)+ncols-1)/ncols
+for i in range(nrows):
+ for j in range(i, len(l), nrows):
+ print string.ljust(l[j], 10),
+ print
diff --git a/doc/tools/listmodules b/doc/tools/listmodules
new file mode 100755
index 0000000..7ac90a8
--- /dev/null
+++ b/doc/tools/listmodules
@@ -0,0 +1,183 @@
+#! /usr/bin/env python
+# -*- Python -*-
+#
+# This script can be used to identify undocumented modules in the Python
+# standard library. Use it like this:
+#
+# .../Doc/tools/listmodules --ignore-from .../Doc/paper-<paper>/modlib.idx
+
+"""%(program)s - list modules in the Python standard library
+
+-a, --annotate Annotate the module names with the subdirectory they
+ live in
+-c, --categorize Group the modules by subdirectory
+-i <file>,
+
+--ignore-from <file> Ignore the modules listed in <file>. <file> may
+ contain a list of module names or a module index file
+ as produced when formatting the Python documentation
+ (.idx or .html flavor).
+
+If neither -a nor -c are given, the modules are listed in alphabetical
+order.
+
+Note that -a and -c are mutually exclusive.
+
+Limitation: Modules loadable as shared objects may not be listed,
+though this script attempts to locate such modules.
+
+"""
+
+__version__ = '$Revision: 1.1.1.1 $'
+
+import getopt
+import glob
+import os
+import re
+import string
+import sys
+
+
+REMOVE_DIRS = ["dos-8x3", "encodings", "distutils",
+ "lib-old", "lib-stdwin", "test"]
+
+
+def main():
+ args = sys.argv[1:]
+ annotate = 0
+ builtin = 0
+ categorize = 0
+ ignore_dict = {}
+ ignore = ignore_dict.has_key
+ try:
+ opts, args = getopt.getopt(
+ args, "abchi:",
+ ["annotate", "built-in", "categorize", "help", "ignore-from="])
+ except getopt.error, msg:
+ sys.stdout = sys.stderr
+ print msg
+ print
+ usage()
+ sys.exit(2)
+ for opt, arg in opts:
+ if opt in ("-a", "--annotate"):
+ annotate = 1
+ elif opt in ("-b", "--built-in"):
+ builtin = 1
+ elif opt in ("-c", "--categorize"):
+ categorize = 1
+ elif opt in ("-h", "--help"):
+ usage()
+ sys.exit()
+ elif opt in ("-i", "--ignore-from"):
+ data = open(arg).read()
+ if data[:1] == "\\":
+ ignore_from_idx(data, ignore_dict)
+ else:
+ ignore_from_modulelist(data, ignore_dict)
+ if args or (annotate and categorize):
+ usage()
+ sys.exit(2)
+ #
+ # Populate the database:
+ #
+ srcdir = os.path.normpath(os.path.join(
+ os.path.dirname(sys.argv[0]), os.pardir, os.pardir))
+ os.chdir(srcdir)
+ modules_by_name = {}
+ modules_by_dir = {}
+ if builtin:
+ l = []
+ modules_by_dir["<builtin>"] = l
+ for name in sys.builtin_module_names:
+ if not ignore(name):
+ modules_by_name[name] = "<built-in>"
+ l.append(name)
+ rx = re.compile("Lib/plat-[a-zA-Z0-9]*/")
+ fp = os.popen("find Lib -name \*.py -print", "r")
+ while 1:
+ line = fp.readline()
+ if not line:
+ break
+ m = rx.match(line)
+ if m:
+ line = "Lib/plat-*/" + line[m.end():]
+ line = line[4:-4] # strip off 'Lib/' and '.py\n'
+ dir, name = os.path.split(line)
+ dir = dir or "<standard>"
+ if ignore(name):
+ continue
+ if dir not in REMOVE_DIRS:
+ modules_by_name[name] = dir
+ l = modules_by_dir.get(dir, [])
+ modules_by_dir[dir] = l
+ if name not in l:
+ l.append(name)
+ # load up extension modules:
+ pwd = os.getcwd()
+ try:
+ os.chdir("Modules")
+ dir = "<extension>"
+ for line in glob.glob("*module.c"):
+ name = line[:-8]
+ if ignore(name) or modules_by_name.has_key(name) or name == "xx":
+ continue
+ modules_by_name[name] = dir
+ l = modules_by_dir.get(dir, [])
+ modules_by_dir[dir] = l
+ if name not in l:
+ l.append(name)
+ finally:
+ os.chdir(pwd)
+ #
+ # Dump the results:
+ #
+ if annotate:
+ modules = modules_by_name.items()
+ modules.sort()
+ width = max(map(len, modules_by_name.keys()))
+ format = "%%-%ds %%s" % width
+ for name, dir in modules:
+ if dir and dir[0] != "<":
+ print format % (name, dir)
+ else:
+ print name
+ elif categorize:
+ modules = modules_by_dir.items()
+ modules.sort()
+ width = max(map(len, modules_by_dir.keys()))
+ format = "%%-%ds %%s" % width
+ for dir, names in modules:
+ names.sort()
+ print format % (dir, names[0])
+ for name in names[1:]:
+ print format % ('', name)
+ print
+ else:
+ modules = modules_by_name.keys()
+ modules.sort()
+ print string.join(modules, "\n")
+
+
+def ignore_from_modulelist(data, ignore_dict):
+ for name in string.split(data):
+ ignore_dict[name] = name
+
+def ignore_from_idx(data, ignore_dict):
+ data = string.replace(data, r"\hackscore {}", "_")
+ rx = re.compile(r"\\indexentry\s*{([^@]*)@")
+ for line in string.split(data, "\n"):
+ m = rx.match(line)
+ if m:
+ name = m.group(1)
+ ignore_dict[name] = name
+
+
+def usage():
+ vars = {}
+ vars["program"] = os.path.basename(sys.argv[0])
+ print __doc__ % vars
+
+
+if __name__ == "__main__":
+ main()
diff --git a/doc/tools/mkackshtml b/doc/tools/mkackshtml
new file mode 100755
index 0000000..917b303
--- /dev/null
+++ b/doc/tools/mkackshtml
@@ -0,0 +1,65 @@
+#! /usr/bin/env python
+# -*- Python -*-
+
+import string
+import support
+import sys
+
+
+def collect(fp):
+ names = []
+ while 1:
+ line = fp.readline()
+ if not line:
+ break
+ line = string.strip(line)
+ if line:
+ names.append(line)
+ else:
+ names = []
+ return names
+
+
+def main():
+ options = support.Options()
+ options.columns = 4
+ options.variables["title"] = "Acknowledgements"
+ options.parse(sys.argv[1:])
+ names = collect(sys.stdin)
+ percol = (len(names) + options.columns - 1) / options.columns
+ colnums = []
+ for i in range(options.columns):
+ colnums.append(percol*i)
+ fp = options.get_output_file()
+ fp.write(string.rstrip(options.get_header()) + "\n")
+ fp.write(THANKS + "\n")
+ fp.write('<table width="100%" align="center">\n')
+ for i in range(percol):
+ fp.write(" <tr>\n")
+ for j in colnums:
+ try:
+ fp.write(" <td>%s</td>\n" % names[i + j])
+ except IndexError:
+ pass
+ fp.write(" </tr>\n")
+ fp.write("</table>\n")
+ fp.write(string.rstrip(options.get_footer()) + "\n")
+ fp.close()
+
+THANKS = '''\
+
+<p>These people have contributed in some way to the Python
+documentation. This list is probably not complete -- if you feel that
+you or anyone else should be on this list, please let us know (send
+email to <a
+href="mailto:python-docs@python.org">python-docs@python.org</a>), and
+we will be glad to correct the problem.</p>
+
+<p>It is only with the input and contributions of the Python community
+that Python has such wonderful documentation -- <b>Thank You!</b></p>
+
+'''
+
+
+if __name__ == "__main__":
+ main()
diff --git a/doc/tools/mkhowto b/doc/tools/mkhowto
new file mode 100755
index 0000000..feeb093
--- /dev/null
+++ b/doc/tools/mkhowto
@@ -0,0 +1,597 @@
+#! /usr/bin/env python
+# -*- Python -*-
+"""usage: %(program)s [options...] file ...
+
+Options specifying formats to build:
+ --html HyperText Markup Language (default)
+ --pdf Portable Document Format
+ --ps PostScript
+ --dvi 'DeVice Indepentent' format from TeX
+ --text ASCII text (requires lynx)
+
+ More than one output format may be specified, or --all.
+
+HTML options:
+ --address, -a Specify an address for page footers.
+ --link Specify the number of levels to include on each page.
+ --split, -s Specify a section level for page splitting, default: %(max_split_depth)s.
+ --iconserver, -i Specify location of icons (default: ../).
+ --image-type Specify the image type to use in HTML output;
+ values: gif (default), png.
+ --numeric Don't rename the HTML files; just keep node#.html for
+ the filenames.
+ --style Specify the CSS file to use for the output (filename,
+ not a URL).
+ --up-link URL to a parent document.
+ --up-title Title of a parent document.
+
+Other options:
+ --a4 Format for A4 paper.
+ --letter Format for US letter paper (the default).
+ --help, -H Show this text.
+ --logging, -l Log stdout and stderr to a file (*.how).
+ --debugging, -D Echo commands as they are executed.
+ --keep, -k Keep temporary files around.
+ --quiet, -q Do not print command output to stdout.
+ (stderr is also lost, sorry; see *.how for errors)
+"""
+
+import getopt
+import glob
+import os
+import re
+import shutil
+import string
+import sys
+import tempfile
+
+
+MYDIR = os.path.abspath(sys.path[0])
+
+ISTFILE = os.path.join(MYDIR, "texinputs", "python.ist")
+NODE2LABEL_SCRIPT = os.path.join(MYDIR, "node2label.pl")
+L2H_INIT_FILE = os.path.join(MYDIR, "perl", "l2hinit.perl")
+
+BIBTEX_BINARY = "bibtex"
+DVIPS_BINARY = "dvips"
+LATEX_BINARY = "latex"
+LATEX2HTML_BINARY = "latex2html"
+LYNX_BINARY = "lynx"
+MAKEINDEX_BINARY = "makeindex"
+PDFLATEX_BINARY = "pdflatex"
+PERL_BINARY = "perl"
+PYTHON_BINARY = "python"
+
+
+def usage(options):
+ print __doc__ % options
+
+def error(options, message, err=2):
+ sys.stdout = sys.stderr
+ print message
+ print
+ usage(options)
+ sys.exit(2)
+
+
+class Options:
+ program = os.path.basename(sys.argv[0])
+ #
+ address = ''
+ builddir = None
+ debugging = 0
+ discard_temps = 1
+ have_temps = 0
+ icon_server = None
+ image_type = "gif"
+ logging = 0
+ max_link_depth = 3
+ max_split_depth = 6
+ paper = "letter"
+ quiet = 0
+ runs = 0
+ numeric = 0
+ global_module_index = None
+ style_file = os.path.join(MYDIR, "html", "style.css")
+ about_file = os.path.join(MYDIR, "html", "about.dat")
+ up_link = None
+ up_title = None
+ #
+ DEFAULT_FORMATS = ("html",)
+ ALL_FORMATS = ("dvi", "html", "pdf", "ps", "text")
+
+ def __init__(self):
+ self.formats = []
+ self.l2h_init_files = []
+
+ def __getitem__(self, key):
+ # This is used when formatting the usage message.
+ try:
+ return getattr(self, key)
+ except AttributeError:
+ raise KeyError, key
+
+ def parse(self, args):
+ opts, args = getopt.getopt(args, "Hi:a:s:lDkqr:",
+ ["all", "postscript", "help", "iconserver=",
+ "address=", "a4", "letter", "l2h-init=",
+ "link=", "split=", "logging", "debugging",
+ "keep", "quiet", "runs=", "image-type=",
+ "about=", "numeric", "style=", "paper=",
+ "up-link=", "up-title=", "dir=",
+ "global-module-index="]
+ + list(self.ALL_FORMATS))
+ for opt, arg in opts:
+ if opt == "--all":
+ self.formats = list(self.ALL_FORMATS)
+ elif opt in ("-H", "--help"):
+ usage(self)
+ sys.exit()
+ elif opt == "--iconserver":
+ self.icon_server = arg
+ elif opt in ("-a", "--address"):
+ self.address = arg
+ elif opt == "--a4":
+ self.paper = "a4"
+ elif opt == "--letter":
+ self.paper = "letter"
+ elif opt == "--link":
+ self.max_link_depth = int(arg)
+ elif opt in ("-s", "--split"):
+ self.max_split_depth = int(arg)
+ elif opt in ("-l", "--logging"):
+ self.logging = self.logging + 1
+ elif opt in ("-D", "--debugging"):
+ self.debugging = self.debugging + 1
+ elif opt in ("-k", "--keep"):
+ self.discard_temps = 0
+ elif opt in ("-q", "--quiet"):
+ self.quiet = 1
+ elif opt in ("-r", "--runs"):
+ self.runs = int(arg)
+ elif opt == "--image-type":
+ self.image_type = arg
+ elif opt == "--about":
+ # always make this absolute:
+ self.about_file = os.path.normpath(
+ os.path.abspath(arg))
+ elif opt == "--numeric":
+ self.numeric = 1
+ elif opt == "--style":
+ self.style_file = os.path.abspath(arg)
+ elif opt == "--l2h-init":
+ self.l2h_init_files.append(os.path.abspath(arg))
+ elif opt == "--up-link":
+ self.up_link = arg
+ elif opt == "--up-title":
+ self.up_title = arg
+ elif opt == "--global-module-index":
+ self.global_module_index = arg
+ elif opt == "--dir":
+ self.builddir = arg
+ elif opt == "--paper":
+ self.paper = arg
+ #
+ # Format specifiers:
+ #
+ elif opt[2:] in self.ALL_FORMATS:
+ self.add_format(opt[2:])
+ elif opt == "--postscript":
+ # synonym for --ps
+ self.add_format("ps")
+ self.initialize()
+ #
+ # return the args to allow the caller access:
+ #
+ return args
+
+ def add_format(self, format):
+ """Add a format to the formats list if not present."""
+ if not format in self.formats:
+ self.formats.append(format)
+
+ def initialize(self):
+ """Complete initialization. This is needed if parse() isn't used."""
+ # add the default format if no formats were specified:
+ if not self.formats:
+ self.formats = self.DEFAULT_FORMATS
+ # determine the base set of texinputs directories:
+ texinputs = string.split(os.environ.get("TEXINPUTS", ""), os.pathsep)
+ if not texinputs:
+ texinputs = ['']
+ self.base_texinputs = [
+ os.path.join(MYDIR, "paper-" + self.paper),
+ os.path.join(MYDIR, "texinputs"),
+ ] + texinputs
+
+
+class Job:
+ latex_runs = 0
+
+ def __init__(self, options, path):
+ self.options = options
+ self.doctype = get_doctype(path)
+ self.filedir, self.doc = split_pathname(path)
+ self.log_filename = self.doc + ".how"
+ if os.path.exists(self.log_filename):
+ os.unlink(self.log_filename)
+ if os.path.exists(self.doc + ".l2h"):
+ self.l2h_aux_init_file = tempfile.mktemp()
+ else:
+ self.l2h_aux_init_file = self.doc + ".l2h"
+ self.write_l2h_aux_init_file()
+
+ def build(self):
+ self.setup_texinputs()
+ formats = self.options.formats
+ if "dvi" in formats or "ps" in formats:
+ self.build_dvi()
+ if "pdf" in formats:
+ self.build_pdf()
+ if "ps" in formats:
+ self.build_ps()
+ if "html" in formats:
+ self.require_temps()
+ self.build_html(self.options.builddir or self.doc)
+ if self.options.icon_server == ".":
+ pattern = os.path.join(MYDIR, "html", "icons",
+ "*." + self.options.image_type)
+ imgs = glob.glob(pattern)
+ if not imgs:
+ self.warning(
+ "Could not locate support images of type %s."
+ % `self.options.image_type`)
+ for fn in imgs:
+ new_fn = os.path.join(self.doc, os.path.basename(fn))
+ shutil.copyfile(fn, new_fn)
+ if "text" in formats:
+ self.require_temps()
+ tempdir = self.doc
+ need_html = "html" not in formats
+ if self.options.max_split_depth != 1:
+ fp = open(self.l2h_aux_init_file, "a")
+ fp.write("# re-hack this file for --text:\n")
+ l2hoption(fp, "MAX_SPLIT_DEPTH", "1")
+ fp.write("1;\n")
+ fp.close()
+ tempdir = self.doc + "-temp-html"
+ need_html = 1
+ if need_html:
+ self.build_html(tempdir, max_split_depth=1)
+ self.build_text(tempdir)
+ if self.options.discard_temps:
+ self.cleanup()
+
+ def setup_texinputs(self):
+ texinputs = [self.filedir] + list(self.options.base_texinputs)
+ os.environ["TEXINPUTS"] = string.join(['.']+texinputs, os.pathsep)
+ self.message("TEXINPUTS=" + os.environ["TEXINPUTS"])
+
+ def build_aux(self, binary=None):
+ if binary is None:
+ binary = LATEX_BINARY
+ new_index( "%s.ind" % self.doc, "genindex")
+ new_index("mod%s.ind" % self.doc, "modindex")
+ self.run("%s %s" % (binary, self.doc))
+ self.use_bibtex = check_for_bibtex(self.doc + ".aux")
+ self.latex_runs = 1
+
+ def build_dvi(self):
+ self.use_latex(LATEX_BINARY)
+
+ def build_pdf(self):
+ self.use_latex(PDFLATEX_BINARY)
+
+ def use_latex(self, binary):
+ self.require_temps(binary=binary)
+ if self.latex_runs < 2:
+ if os.path.isfile("mod%s.idx" % self.doc):
+ self.run("%s mod%s.idx" % (MAKEINDEX_BINARY, self.doc))
+ use_indfix = 0
+ if os.path.isfile(self.doc + ".idx"):
+ use_indfix = 1
+ # call to Doc/tools/fix_hack omitted; doesn't appear necessary
+ self.run("%s %s.idx" % (MAKEINDEX_BINARY, self.doc))
+ import indfix
+ indfix.process(self.doc + ".ind")
+ if self.use_bibtex:
+ self.run("%s %s" % (BIBTEX_BINARY, self.doc))
+ self.process_synopsis_files()
+ #
+ # let the doctype-specific handler do some intermediate work:
+ #
+ self.run("%s %s" % (binary, self.doc))
+ self.latex_runs = self.latex_runs + 1
+ if os.path.isfile("mod%s.idx" % self.doc):
+ self.run("%s -s %s mod%s.idx"
+ % (MAKEINDEX_BINARY, ISTFILE, self.doc))
+ if use_indfix:
+ self.run("%s -s %s %s.idx"
+ % (MAKEINDEX_BINARY, ISTFILE, self.doc))
+ indfix.process(self.doc + ".ind")
+ self.process_synopsis_files()
+ #
+ # and now finish it off:
+ #
+ if os.path.isfile(self.doc + ".toc") and binary == PDFLATEX_BINARY:
+ import toc2bkm
+ if self.doctype == "manual":
+ bigpart = "chapter"
+ else:
+ bigpart = "section"
+ toc2bkm.process(self.doc + ".toc", self.doc + ".bkm", bigpart)
+ if self.use_bibtex:
+ self.run("%s %s" % (BIBTEX_BINARY, self.doc))
+ self.run("%s %s" % (binary, self.doc))
+ self.latex_runs = self.latex_runs + 1
+
+ def process_synopsis_files(self):
+ synopsis_files = glob.glob(self.doc + "*.syn")
+ for path in synopsis_files:
+ uniqify_module_table(path)
+
+ def build_ps(self):
+ self.run("%s -N0 -o %s.ps %s" % (DVIPS_BINARY, self.doc, self.doc))
+
+ def build_html(self, builddir=None, max_split_depth=None):
+ if builddir is None:
+ builddir = self.doc
+ if max_split_depth is None:
+ max_split_depth = self.options.max_split_depth
+ texfile = None
+ for p in string.split(os.environ["TEXINPUTS"], os.pathsep):
+ fn = os.path.join(p, self.doc + ".tex")
+ if os.path.isfile(fn):
+ texfile = fn
+ break
+ if not texfile:
+ self.warning("Could not locate %s.tex; aborting." % self.doc)
+ sys.exit(1)
+ # remove leading ./ (or equiv.); might avoid problems w/ dvips
+ if texfile[:2] == os.curdir + os.sep:
+ texfile = texfile[2:]
+ # build the command line and run LaTeX2HTML:
+ if not os.path.isdir(builddir):
+ os.mkdir(builddir)
+ else:
+ for fname in glob.glob(os.path.join(builddir, "*.html")):
+ os.unlink(fname)
+ args = [LATEX2HTML_BINARY,
+ "-init_file", self.l2h_aux_init_file,
+ "-dir", builddir,
+ texfile
+ ]
+ self.run(string.join(args)) # XXX need quoting!
+ # ... postprocess
+ shutil.copyfile(self.options.style_file,
+ os.path.join(builddir, self.doc + ".css"))
+ shutil.copyfile(os.path.join(builddir, self.doc + ".html"),
+ os.path.join(builddir, "index.html"))
+ if max_split_depth != 1:
+ if self.options.numeric:
+ label_file = os.path.join(builddir, "labels.pl")
+ fp = open(label_file)
+ about_node = None
+ target = " = q/about/;\n"
+ x = len(target)
+ while 1:
+ line = fp.readline()
+ if not line:
+ break
+ if line[-x:] == target:
+ line = fp.readline()
+ m = re.search(r"\|(node\d+\.[a-z]+)\|", line)
+ about_node = m.group(1)
+ shutil.copyfile(os.path.join(builddir, about_node),
+ os.path.join(builddir, "about.html"))
+ break
+ else:
+ pwd = os.getcwd()
+ try:
+ os.chdir(builddir)
+ self.run("%s %s *.html" % (PERL_BINARY, NODE2LABEL_SCRIPT))
+ finally:
+ os.chdir(pwd)
+
+ def build_text(self, tempdir=None):
+ if tempdir is None:
+ tempdir = self.doc
+ indexfile = os.path.join(tempdir, "index.html")
+ self.run("%s -nolist -dump %s >%s.txt"
+ % (LYNX_BINARY, indexfile, self.doc))
+
+ def require_temps(self, binary=None):
+ if not self.latex_runs:
+ self.build_aux(binary=binary)
+
+ def write_l2h_aux_init_file(self):
+ options = self.options
+ fp = open(self.l2h_aux_init_file, "w")
+ d = string_to_perl(os.path.dirname(L2H_INIT_FILE))
+ fp.write("package main;\n"
+ "push (@INC, '%s');\n"
+ "$mydir = '%s';\n"
+ % (d, d))
+ fp.write(open(L2H_INIT_FILE).read())
+ for filename in options.l2h_init_files:
+ fp.write("\n# initialization code incorporated from:\n# ")
+ fp.write(filename)
+ fp.write("\n")
+ fp.write(open(filename).read())
+ fp.write("\n"
+ "# auxillary init file for latex2html\n"
+ "# generated by mkhowto\n"
+ "$NO_AUTO_LINK = 1;\n"
+ )
+ l2hoption(fp, "ABOUT_FILE", options.about_file)
+ l2hoption(fp, "ICONSERVER", options.icon_server)
+ l2hoption(fp, "IMAGE_TYPE", options.image_type)
+ l2hoption(fp, "ADDRESS", options.address)
+ l2hoption(fp, "MAX_LINK_DEPTH", options.max_link_depth)
+ l2hoption(fp, "MAX_SPLIT_DEPTH", options.max_split_depth)
+ l2hoption(fp, "EXTERNAL_UP_LINK", options.up_link)
+ l2hoption(fp, "EXTERNAL_UP_TITLE", options.up_title)
+ l2hoption(fp, "GLOBAL_MODULE_INDEX", options.global_module_index)
+ fp.write("1;\n")
+ fp.close()
+
+ def cleanup(self):
+ self.__have_temps = 0
+ for pattern in ("%s.aux", "%s.log", "%s.out", "%s.toc", "%s.bkm",
+ "%s.idx", "%s.ilg", "%s.ind", "%s.pla",
+ "%s.bbl", "%s.blg",
+ "mod%s.idx", "mod%s.ind", "mod%s.ilg",
+ ):
+ safe_unlink(pattern % self.doc)
+ map(safe_unlink, glob.glob(self.doc + "*.syn"))
+ for spec in ("IMG*", "*.pl", "WARNINGS", "index.dat", "modindex.dat"):
+ pattern = os.path.join(self.doc, spec)
+ map(safe_unlink, glob.glob(pattern))
+ if "dvi" not in self.options.formats:
+ safe_unlink(self.doc + ".dvi")
+ if os.path.isdir(self.doc + "-temp-html"):
+ shutil.rmtree(self.doc + "-temp-html", ignore_errors=1)
+ if not self.options.logging:
+ os.unlink(self.log_filename)
+ if not self.options.debugging:
+ os.unlink(self.l2h_aux_init_file)
+
+ def run(self, command):
+ self.message(command)
+ rc = os.system("(%s) </dev/null >>%s 2>&1"
+ % (command, self.log_filename))
+ if rc:
+ self.warning(
+ "Session transcript and error messages are in %s."
+ % self.log_filename)
+ sys.stderr.write("The relevant lines from the transcript are:\n")
+ sys.stderr.write("-" * 72 + "\n")
+ sys.stderr.writelines(get_run_transcript(self.log_filename))
+ sys.exit(rc)
+
+ def message(self, msg):
+ msg = "+++ " + msg
+ if not self.options.quiet:
+ print msg
+ self.log(msg + "\n")
+
+ def warning(self, msg):
+ msg = "*** %s\n" % msg
+ sys.stderr.write(msg)
+ self.log(msg)
+
+ def log(self, msg):
+ fp = open(self.log_filename, "a")
+ fp.write(msg)
+ fp.close()
+
+
+def get_run_transcript(filename):
+ """Return lines from the transcript file for the most recent run() call."""
+ fp = open(filename)
+ lines = fp.readlines()
+ fp.close()
+ lines.reverse()
+ L = []
+ for line in lines:
+ L.append(line)
+ if line[:4] == "+++ ":
+ break
+ L.reverse()
+ return L
+
+
+def safe_unlink(path):
+ """Unlink a file without raising an error if it doesn't exist."""
+ try:
+ os.unlink(path)
+ except os.error:
+ pass
+
+
+def split_pathname(path):
+ path = os.path.normpath(os.path.join(os.getcwd(), path))
+ dirname, basename = os.path.split(path)
+ if basename[-4:] == ".tex":
+ basename = basename[:-4]
+ return dirname, basename
+
+
+_doctype_rx = re.compile(r"\\documentclass(?:\[[^]]*\])?{([a-zA-Z]*)}")
+def get_doctype(path):
+ fp = open(path)
+ doctype = None
+ while 1:
+ line = fp.readline()
+ if not line:
+ break
+ m = _doctype_rx.match(line)
+ if m:
+ doctype = m.group(1)
+ break
+ fp.close()
+ return doctype
+
+
+def main():
+ options = Options()
+ try:
+ args = options.parse(sys.argv[1:])
+ except getopt.error, msg:
+ error(options, msg)
+ if not args:
+ # attempt to locate single .tex file in current directory:
+ args = glob.glob("*.tex")
+ if not args:
+ error(options, "No file to process.")
+ if len(args) > 1:
+ error(options, "Could not deduce which files should be processed.")
+ #
+ # parameters are processed, let's go!
+ #
+ for path in args:
+ Job(options, path).build()
+
+
+def l2hoption(fp, option, value):
+ if value:
+ fp.write('$%s = "%s";\n' % (option, string_to_perl(str(value))))
+
+
+_to_perl = {}
+for c in map(chr, range(1, 256)):
+ _to_perl[c] = c
+_to_perl["@"] = "\\@"
+_to_perl["$"] = "\\$"
+_to_perl['"'] = '\\"'
+
+def string_to_perl(s):
+ return string.join(map(_to_perl.get, s), '')
+
+
+def check_for_bibtex(filename):
+ fp = open(filename)
+ pos = string.find(fp.read(), r"\bibdata{")
+ fp.close()
+ return pos >= 0
+
+def uniqify_module_table(filename):
+ lines = open(filename).readlines()
+ if len(lines) > 1:
+ if lines[-1] == lines[-2]:
+ del lines[-1]
+ open(filename, "w").writelines(lines)
+
+
+def new_index(filename, label="genindex"):
+ fp = open(filename, "w")
+ fp.write(r"""\
+\begin{theindex}
+\label{%s}
+\end{theindex}
+""" % label)
+ fp.close()
+
+
+if __name__ == "__main__":
+ main()
diff --git a/doc/tools/mkinfo b/doc/tools/mkinfo
new file mode 100755
index 0000000..edba1db
--- /dev/null
+++ b/doc/tools/mkinfo
@@ -0,0 +1,48 @@
+#! /bin/sh
+# -*- Ksh -*-
+
+# Script to drive the HTML-info conversion process.
+# Pass in a single parameter: the name of the top-level HTML file
+# generated by LaTeX2HTML.
+#
+# Written by Fred L. Drake, Jr. <fdrake@acm.org>
+
+PERL=${PERL:-perl}
+EMACS=${EMACS:-emacs}
+MAKEINFO=${MAKEINFO:-makeinfo}
+
+
+# Normalize file name since something called by html2texi.pl seems to
+# screw up with relative path names.
+FILENAME="$1"
+DOCDIR=`dirname "$FILENAME"`
+DOCFILE=`basename "$FILENAME"`
+DOCNAME=`basename "$FILENAME" .html`
+
+# Now build the real directory names, and locate our support stuff:
+WORKDIR=`pwd`
+cd `dirname $0`
+TOOLSDIR=`pwd`
+cd $DOCDIR
+DOCDIR=`pwd`
+cd $WORKDIR
+
+
+run() {
+ # show what we're doing, like make does:
+ echo "$*"
+ $* || exit $?
+}
+
+
+# generate the Texinfo file:
+
+run $PERL -I$TOOLSDIR $TOOLSDIR/html2texi.pl $DOCDIR/$DOCFILE
+run $EMACS -batch -l $TOOLSDIR/fixinfo.el $DOCNAME.texi
+rm -f $DOCNAME.texi~
+
+
+# generate the .info files:
+
+run $MAKEINFO --footnote-style end --fill-column 72 \
+ --paragraph-indent 0 $DOCNAME.texi
diff --git a/doc/tools/mkmodindex b/doc/tools/mkmodindex
new file mode 100755
index 0000000..5f2da0e
--- /dev/null
+++ b/doc/tools/mkmodindex
@@ -0,0 +1,136 @@
+#! /usr/bin/env python
+# -*- Python -*-
+
+"""usage: %(program)s [options] file...
+
+Supported options:
+
+ --address addr
+ -a addr Set the address text to include at the end of the generated
+ HTML; this should be used for contact information.
+ --columns cols
+ -c cols Set the number of columns each index section should be
+ displayed in. The default is 1.
+ --help
+ -h Display this help message.
+ --letters
+ -l Split the output into sections by letter.
+ --output file
+ -o file Write output to 'file' instead of standard out.
+ --iconserver is Use 'is' as the directory containing icons for the
+ navigation bar. The default is 'icons'.
+ --title str Set the page title to 'str'. The default is 'Global
+ Module Index'.
+ --uplink url Set the upward link URL. The default is './'.
+ --uptitle str Set the upward link title. The default is 'Python
+ Documentation Index'.
+"""
+import buildindex
+import os
+import re
+import string
+import support
+import sys
+
+
+class IndexOptions(support.Options):
+ def __init__(self):
+ support.Options.__init__(self)
+ self.add_args("l", ["letters"])
+ self.letters = 0
+
+ def handle_option(self, opt, val):
+ if opt in ("-l", "--letters"):
+ self.letters = 1
+
+ def usage(self):
+ program = os.path.basename(sys.argv[0])
+ print __doc__ % {"program": program}
+
+
+class Node(buildindex.Node):
+ annotation = ""
+
+ def __init__(self, link, str, seqno):
+ parts = string.split(str, None, 1)
+ if parts[0][-5:] == "</tt>":
+ self.modname = parts[0][:-5]
+ else:
+ self.modname = parts[0]
+ if len(parts) == 2:
+ self.annotation = parts[1]
+ buildindex.Node.__init__(self, link, self.modname, seqno)
+
+ def __str__(self):
+ return '<tt class="module">%s</tt> %s' \
+ % (self.modname, self.annotation)
+
+_rx = re.compile(
+ "<dt><a href='(module-.*\.html)#l2h-\d+'><tt class='module'>"
+ "([a-zA-Z_][a-zA-Z0-9_.]*</tt>(\s*<em>"
+ "\(<span class='platform'>.*</span>\)</em>)?)</a>")
+
+def main():
+ options = IndexOptions()
+ options.variables["title"] = "Global Module Index"
+ options.parse(sys.argv[1:])
+ args = options.args
+ if not args:
+ args = ["-"]
+ #
+ # Collect the input data:
+ #
+ nodes = []
+ seqno = 0
+ has_plat_flag = 0
+ for ifn in args:
+ if ifn == "-":
+ ifp = sys.stdin
+ dirname = ''
+ else:
+ ifp = open(ifn)
+ dirname = os.path.dirname(ifn)
+ while 1:
+ line = ifp.readline()
+ if not line:
+ break
+ m = _rx.match(line)
+ if m:
+ # This line specifies a module!
+ basename, modname = m.group(1, 2)
+ has_plat_flag = has_plat_flag or m.group(3)
+ linkfile = os.path.join(dirname, basename)
+ nodes.append(Node('<a href="%s">' % linkfile, modname, seqno))
+ seqno = seqno + 1
+ ifp.close()
+ #
+ # Generate all output:
+ #
+ num_nodes = len(nodes)
+ # Here's the HTML generation:
+ parts = [options.get_header(),
+ buildindex.process_nodes(nodes, options.columns, options.letters),
+ options.get_footer(),
+ ]
+ if has_plat_flag:
+ parts.insert(1, PLAT_DISCUSS)
+ html = string.join(parts, '')
+ program = os.path.basename(sys.argv[0])
+ fp = options.get_output_file()
+ fp.write(string.rstrip(html) + "\n")
+ if options.outputfile == "-":
+ sys.stderr.write("%s: %d index nodes\n" % (program, num_nodes))
+ else:
+ print
+ print "%s: %d index nodes" % (program, num_nodes)
+
+
+PLAT_DISCUSS = """
+<p> Some module names are followed by an annotation indicating what
+platform they are available on.</p>
+
+"""
+
+
+if __name__ == "__main__":
+ main()
diff --git a/doc/tools/mksourcepkg b/doc/tools/mksourcepkg
new file mode 100755
index 0000000..c3ea863
--- /dev/null
+++ b/doc/tools/mksourcepkg
@@ -0,0 +1,163 @@
+#! /usr/bin/env python
+# -*- Python -*-
+
+"""%(program)s - script to create the latex source distribution
+
+usage:
+ %(program)s [-t|--tools] release [tag]
+
+with -t|--tools: doesn't include the documents, only the framework
+
+without [tag]: generate from the current version that's checked in
+ (*NOT* what's in the current directory!)
+
+with [tag]: generate from the named tag
+"""
+#* should be modified to get the Python version number automatically
+# from the Makefile or someplace.
+
+import getopt
+import glob
+import os
+import re
+import shutil
+import sys
+import tempfile
+
+import cvsinfo
+
+
+quiet = 0
+rx = re.compile(r":ext:(?:[a-zA-Z0-9]+)@cvs\.([a-zA-Z0-9]+).sourceforge.net:"
+ r"/cvsroot/\1")
+
+
+def main():
+ global quiet
+ try:
+ opts, args = getopt.getopt(sys.argv[1:], "abgtzq",
+ ["all", "bzip2", "gzip", "tools", "zip",
+ "quiet"])
+ except getopt.error, e:
+ usage(warning=str(e))
+ sys.exit(2)
+ if len(args) not in (1, 2):
+ usage(warning="wrong number of parameters")
+ sys.exit(2)
+ tools = 0
+ formats = {}
+ for opt, arg in opts:
+ if opt in ("-t", "--tools"):
+ tools = 1
+ elif opt in ("-q", "--quiet"):
+ quiet = quiet + 1
+ elif opt in ("-b", "--bzip2"):
+ formats["bzip2"] = 1
+ elif opt in ("-g", "--gzip"):
+ formats["gzip"] = 1
+ elif opt in ("-z", "--zip"):
+ formats["zip"] = 1
+ elif opt in ("-a", "--all"):
+ formats["bzip2"] = 1
+ formats["gzip"] = 1
+ formats["zip"] = 1
+ if formats:
+ # make order human-predictable
+ formats = formats.keys()
+ formats.sort()
+ else:
+ formats = ["gzip"]
+ release = args[0]
+ cvstag = None
+ if len(args) > 1:
+ cvstag = args[1]
+ tempdir = tempfile.mktemp()
+ os.mkdir(tempdir)
+ pkgdir = os.path.join(tempdir, "Python-" + release)
+ os.mkdir(pkgdir)
+ pwd = os.getcwd()
+ mydir = os.path.abspath(os.path.dirname(sys.argv[0]))
+ info = cvsinfo.RepositoryInfo(mydir)
+ cvsroot = info.get_cvsroot()
+ m = rx.match(cvsroot)
+ if m:
+ # If this is an authenticated SourceForge repository, convert to
+ # anonymous usage for the export/checkout, since that avoids the
+ # SSH overhead.
+ group = m.group(1)
+ cvsroot = ":pserver:anonymous@cvs.%s.sourceforge.net:/cvsroot/%s" \
+ % (group, group)
+ # For some reason, SourceForge/CVS doesn't seem to care that we
+ # might not have done a "cvs login" to the anonymous server.
+ # That avoids a lot of painful gunk here.
+ os.chdir(pkgdir)
+ if not quiet:
+ print "--- current directory is:", pkgdir
+ if cvstag:
+ run("cvs -d%s export -r %s -d Doc python/dist/src/Doc"
+ % (cvsroot, cvstag))
+ else:
+ run("cvs -Q -d%s checkout -d Doc python/dist/src/Doc" % cvsroot)
+ # remove CVS directories
+ for p in ('*/CVS', '*/*/CVS', '*/*/*/CVS'):
+ map(shutil.rmtree, glob.glob(p))
+ for f in ('.cvsignore', '*/.cvsignore'):
+ map(os.unlink, glob.glob(f))
+ LICENSE = os.path.normpath(
+ os.path.join(mydir, os.pardir, os.pardir, "LICENSE"))
+ shutil.copyfile(LICENSE, "Doc/LICENSE")
+ if tools:
+ archive = "doctools-" + release
+ # we don't want the actual documents in this case:
+ for d in ("api", "dist", "doc", "ext", "inst",
+ "lib", "mac", "ref", "tut"):
+ shutil.rmtree(os.path.join(os.path.join(pkgdir, "Doc"), d))
+ else:
+ archive = "latex-" + release
+
+ # XXX should also remove the .cvsignore files at this point
+
+ os.chdir(tempdir)
+ archive = os.path.join(pwd, archive)
+ for format in formats:
+ if format == "bzip2":
+ run("tar cf - Python-%s | bzip2 -9 >%s.tar.bz2"
+ % (release, archive))
+ elif format == "gzip":
+ run("tar cf - Python-%s | gzip -9 >%s.tgz"
+ % (release, archive))
+ elif format == "zip":
+ if os.path.exists(archive + ".zip"):
+ os.unlink(archive + ".zip")
+ run("zip -q -r9 %s.zip Python-%s"
+ % (archive, release))
+
+ # clean up the work area:
+ os.chdir(pwd)
+ shutil.rmtree(tempdir)
+
+
+def run(cmd):
+ if quiet < 2:
+ print "+++", cmd
+ if quiet:
+ cmd = "%s >/dev/null" % cmd
+ rc = os.system(cmd)
+ if rc:
+ sys.exit(rc)
+
+
+def usage(warning=None):
+ stdout = sys.stdout
+ sys.stdout = sys.stderr
+ program = os.path.basename(sys.argv[0])
+ try:
+ if warning:
+ print "%s: %s\n" % (program, warning)
+ print __doc__ % {"program": program}
+ finally:
+ sys.stdout = stdout
+
+
+if __name__ == "__main__":
+ main()
diff --git a/doc/tools/node2label.pl b/doc/tools/node2label.pl
new file mode 100755
index 0000000..f3e6bd8
--- /dev/null
+++ b/doc/tools/node2label.pl
@@ -0,0 +1,55 @@
+#! /usr/bin/env perl
+
+use English;
+$INPLACE_EDIT = '';
+
+# read the labels, then reverse the mappings
+require "labels.pl";
+
+%nodes = ();
+my $key;
+# sort so that we get a consistent assignment for nodes with multiple labels
+foreach $label (sort keys %external_labels) {
+ $key = $external_labels{$label};
+ $key =~ s|^/||;
+ $nodes{$key} = $label;
+}
+
+# This adds the "internal" labels added for indexing. These labels will not
+# be used for file names.
+require "internals.pl";
+foreach $label (keys %internal_labels) {
+ $key = $internal_labels{$label};
+ $key =~ s|^/||;
+ if (defined($nodes{$key})) {
+ $nodes{$label} = $nodes{$key};
+ }
+}
+
+# collect labels that have been used
+%newnames = ();
+
+while (<>) {
+ # don't want to do one s/// per line per node
+ # so look for lines with hrefs, then do s/// on nodes present
+ if (/(HREF|href)=[\"\']([^\#\"\']*)html[\#\"\']/) {
+ @parts = split(/(HREF|href)\=[\"\']/);
+ shift @parts;
+ for $node (@parts) {
+ $node =~ s/[\#\"\'].*$//g;
+ chop($node);
+ if (defined($nodes{$node})) {
+ $label = $nodes{$node};
+ if (s/(HREF|href)=([\"\'])$node([\#\"\'])/href=$2$label.html$3/g) {
+ s/(HREF|href)=([\"\'])$label.html/href=$2$label.html/g;
+ $newnames{$node} = "$label.html";
+ }
+ }
+ }
+ }
+ print;
+}
+
+foreach $oldname (keys %newnames) {
+ rename($oldname, $newnames{$oldname});
+}
diff --git a/doc/tools/paper-a4/pypaper.sty b/doc/tools/paper-a4/pypaper.sty
new file mode 100644
index 0000000..10b22f8
--- /dev/null
+++ b/doc/tools/paper-a4/pypaper.sty
@@ -0,0 +1,5 @@
+%
+% Change this to say a4paper instead of letterpaper if you want A4.
+%
+\newcommand{\py@paper}{a4paper}
+\newcommand{\py@ptsize}{10pt}
diff --git a/doc/tools/perl/SynopsisTable.pm b/doc/tools/perl/SynopsisTable.pm
new file mode 100644
index 0000000..6a03dd2
--- /dev/null
+++ b/doc/tools/perl/SynopsisTable.pm
@@ -0,0 +1,89 @@
+package SynopsisTable;
+
+sub new{
+ return bless {names=>'', info=>{}, file=>''};
+}
+
+sub declare{
+ my($self,$name,$key,$type) = @_;
+ if ($self->{names}) {
+ $self->{names} .= ",$name";
+ }
+ else {
+ $self->{names} .= "$name";
+ }
+ $self->{info}{$name} = "$key,$type,";
+}
+
+# The 'file' attribute is used to store the filename of the node in which
+# the table will be presented; this assumes that each table will be presented
+# only once, which works for the current use of this object.
+
+sub set_file{
+ my($self, $filename) = @_;
+ $self->{file} = "$filename";
+}
+
+sub get_file{
+ my $self = shift;
+ return $self->{file};
+}
+
+sub set_synopsis{
+ my($self,$name,$synopsis) = @_;
+ my($key,$type,$unused) = split ',', $self->{info}{$name}, 3;
+ $self->{info}{$name} = "$key,$type,$synopsis";
+}
+
+sub get{
+ my($self,$name) = @_;
+ return split /,/, $self->{info}{$name}, 3;
+}
+
+sub show{
+ my $self = shift;
+ my $name;
+ print "names: ", $self->{names}, "\n\n";
+ foreach $name (split /,/, $self->{names}) {
+ my($key,$type,$synopsis) = $self->get($name);
+ print "$name($key) is $type: $synopsis\n";
+ }
+}
+
+sub tohtml{
+ my $self = shift;
+ my $data = "<table class='synopsistable'>\n";
+ my $name;
+ foreach $name (split /,/, $self->{names}) {
+ my($key,$type,$synopsis) = $self->get($name);
+ my $link = "<a href='module-$key.html'>";
+ $data .= (' <tr>'
+ . "<td><b><tt class='module'>$link$name</a></tt></b></td>\n"
+ . " <td class='synopsis'>$synopsis</td></tr>\n");
+ }
+ $data .= "</table>\n";
+ $data;
+}
+
+
+package testSynopsisTable;
+
+sub test{
+ # this little test is mostly to debug the stuff above, since this is
+ # my first Perl "object".
+ my $st = SynopsisTable->new();
+ $st->declare("sample", "sample", "standard");
+ $st->set_synopsis("sample", "This is a little synopsis....");
+ $st->declare("copy_reg", "copyreg", "standard");
+ $st->set_synopsis("copy_reg", "pickle support stuff");
+ $st->show();
+
+ print "\n\n";
+
+ my $st2 = SynopsisTable->new();
+ $st2->declare("st2module", "st2module", "built-in");
+ $st2->set_synopsis("st2module", "silly little synopsis");
+ $st2->show();
+}
+
+1; # This must be the last line -- Perl is bogus!
diff --git a/doc/tools/perl/distutils.perl b/doc/tools/perl/distutils.perl
new file mode 100644
index 0000000..ab524bb
--- /dev/null
+++ b/doc/tools/perl/distutils.perl
@@ -0,0 +1,21 @@
+# LaTeX2HTML support for distutils.sty.
+
+package main;
+
+sub do_cmd_command {
+ return use_wrappers(@_[0], '<code>', '</code>');
+}
+
+sub do_cmd_option {
+ return use_wrappers(@_[0], '<font face="sans-serif">', '</font>');
+}
+
+sub do_cmd_filevar {
+ return use_wrappers(@_[0], '<font face="sans-serif"></i>', '</i></font>');
+}
+
+sub do_cmd_XXX {
+ return use_wrappers(@_[0], '<b>** ', ' **</b>');
+}
+
+1;
diff --git a/doc/tools/perl/howto.perl b/doc/tools/perl/howto.perl
new file mode 100644
index 0000000..76791eb
--- /dev/null
+++ b/doc/tools/perl/howto.perl
@@ -0,0 +1,12 @@
+# -*- perl -*-
+#
+# This implements the Python howto class. All it really needs to do it
+# load the "python" style.
+
+package main;
+
+do_require_package("article");
+do_require_package("alltt");
+do_require_package("python");
+
+1; # sheesh....
diff --git a/doc/tools/perl/l2hinit.perl b/doc/tools/perl/l2hinit.perl
new file mode 100644
index 0000000..d3720d9
--- /dev/null
+++ b/doc/tools/perl/l2hinit.perl
@@ -0,0 +1,594 @@
+# LaTeX2HTML support base for use with Python documentation.
+
+package main;
+
+use L2hos;
+
+$HTML_VERSION = 4.0;
+
+$MAX_LINK_DEPTH = 2;
+$ADDRESS = '';
+
+$NO_FOOTNODE = 1;
+$NUMBERED_FOOTNOTES = 1;
+
+# Python documentation uses section numbers to support references to match
+# in the printed and online versions.
+#
+$SHOW_SECTION_NUMBERS = 1;
+
+$ICONSERVER = '../icons';
+$IMAGE_TYPE = 'gif';
+
+# Control where the navigation bars should show up:
+$TOP_NAVIGATION = 1;
+$BOTTOM_NAVIGATION = 1;
+$AUTO_NAVIGATION = 0;
+
+$BODYTEXT = '';
+$CHILDLINE = "\n<p><hr>\n";
+$VERBOSITY = 0;
+
+# default # of columns for the indexes
+$INDEX_COLUMNS = 2;
+$MODULE_INDEX_COLUMNS = 4;
+
+
+# A little painful, but lets us clean up the top level directory a little,
+# and not be tied to the current directory (as far as I can tell). Testing
+# an existing definition of $mydir is needed since it cannot be computed when
+# run under mkhowto with recent versions of LaTeX2HTML, since this file is
+# not read directly by LaTeX2HTML any more. mkhowto is required to prepend
+# the required definition at the top of the actual input file.
+#
+if (!defined $mydir) {
+ use Cwd;
+ use File::Basename;
+ ($myname, $mydir, $myext) = fileparse(__FILE__, '\..*');
+ chop $mydir; # remove trailing '/'
+ $mydir = getcwd() . "$dd$mydir"
+ unless $mydir =~ s|^/|/|;
+}
+$LATEX2HTMLSTYLES = "$mydir$envkey$LATEX2HTMLSTYLES";
+push (@INC, $mydir);
+
+($myrootname, $myrootdir, $myext) = fileparse($mydir, '\..*');
+chop $myrootdir;
+
+
+# Hackish way to get the appropriate paper-*/ directory into $TEXINPUTS;
+# pass in the paper size (a4 or letter) as the environment variable PAPER
+# to add the right directory. If not given, the current directory is
+# added instead for use with HOWTO processing.
+#
+if (defined $ENV{'PAPER'}) {
+ $mytexinputs = "$myrootdir${dd}paper-$ENV{'PAPER'}$envkey";
+}
+else {
+ $mytexinputs = getcwd() . $envkey;
+}
+$mytexinputs .= "$myrootdir${dd}texinputs";
+
+
+# Change this variable to change the text added in "About this document...";
+# this should be an absolute pathname to get it right.
+#
+$ABOUT_FILE = "$myrootdir${dd}html${dd}stdabout.dat";
+
+
+sub custom_driver_hook {
+ #
+ # This adds the directory of the main input file to $TEXINPUTS; it
+ # seems to be sufficiently general that it should be fine for HOWTO
+ # processing.
+ #
+ my $file = @_[0];
+ my($jobname, $dir, $ext) = fileparse($file, '\..*');
+ $dir = L2hos->Make_directory_absolute($dir);
+ $dir =~ s/$dd$//;
+ $TEXINPUTS = "$dir$envkey$mytexinputs";
+ print "\nAdding $dir to \$TEXINPUTS\n";
+}
+
+
+$CUSTOM_BUTTONS = '';
+
+sub make_nav_sectref {
+ my($label,$title) = @_;
+ if ($title) {
+ if ($title =~ /\<[aA] /) {
+ $title =~ s/\<[aA] /<a class="sectref" /;
+ }
+ else {
+ $title = "<span class=\"sectref\">$title</span>";
+ }
+ return "<b class=\"navlabel\">$label:</b> $title\n";
+ }
+ return '';
+}
+
+@my_icon_tags = ();
+$my_icon_tags{'next'} = 'Next Page';
+$my_icon_tags{'next_page'} = 'Next Page';
+$my_icon_tags{'previous'} = 'Previous Page';
+$my_icon_tags{'previous_page'} = 'Previous Page';
+$my_icon_tags{'up'} = 'Up One Level';
+$my_icon_tags{'contents'} = 'Contents';
+$my_icon_tags{'index'} = 'Index';
+$my_icon_tags{'modules'} = 'Module Index';
+
+@my_icon_names = ();
+$my_icon_names{'previous_page'} = 'previous';
+$my_icon_names{'next_page'} = 'next';
+
+sub get_my_icon {
+ my $name = @_[0];
+ my $text = $my_icon_tags{$name};
+ if ($my_icon_names{$name}) {
+ $name = $my_icon_names{$name};
+ }
+ if ($text eq '') {
+ $name = 'blank';
+ }
+ my $iconserver = ($ICONSERVER eq '.') ? '' : "$ICONSERVER/";
+ return "<img src=\"$iconserver$name.$IMAGE_TYPE\"\n border=\"0\""
+ . " height=\"32\"\n alt=\"$text\" width=\"32\">";
+}
+
+sub use_my_icon {
+ my $s = @_[0];
+ if ($s =~ /\<tex2html_([a-z_]+)_visible_mark\>/) {
+ my $r = get_my_icon($1);
+ $s =~ s/\<tex2html_[a-z_]+_visible_mark\>/$r/;
+ }
+ return $s;
+}
+
+sub make_nav_panel {
+ my $s;
+ my $BLANK_ICON = get_my_icon('blank');
+ $NEXT = $NEXT_TITLE ? use_my_icon("$NEXT") : $BLANK_ICON;
+ $UP = $UP_TITLE ? use_my_icon("$UP") : $BLANK_ICON;
+ $PREVIOUS = $PREVIOUS_TITLE ? use_my_icon("$PREVIOUS") : $BLANK_ICON;
+ $CONTENTS = use_my_icon("$CONTENTS");
+ $INDEX = $INDEX ? use_my_icon("$INDEX") : $BLANK_ICON;
+ if (!$CUSTOM_BUTTONS) {
+ $CUSTOM_BUTTONS = $BLANK_ICON;
+ }
+ $s = ('<table align="center" width="100%" cellpadding="0" cellspacing="2">'
+ . "\n<tr>"
+ # left-hand side
+ . "\n<td>$PREVIOUS</td>"
+ . "\n<td>$UP</td>"
+ . "\n<td>$NEXT</td>"
+ # title box
+ . "\n<td align=\"center\" width=\"100%\">$t_title</td>"
+ # right-hand side
+ . "\n<td>$CONTENTS</td>"
+ . "\n<td>$CUSTOM_BUTTONS</td>" # module index
+ . "\n<td>$INDEX</td>"
+ . "\n</tr></table>\n"
+ # textual navigation
+ . make_nav_sectref("Previous", $PREVIOUS_TITLE)
+ . make_nav_sectref("Up", $UP_TITLE)
+ . make_nav_sectref("Next", $NEXT_TITLE)
+ );
+ # remove these; they are unnecessary and cause errors from validation
+ $s =~ s/ NAME="tex2html\d+"\n */ /g;
+ return $s;
+}
+
+sub get_version_text {
+ if ($PACKAGE_VERSION ne '' && $t_date) {
+ return ("<span class=\"release-info\">"
+ . "Release $PACKAGE_VERSION,"
+ . " documentation updated on $t_date.</span>");
+ }
+ if ($PACKAGE_VERSION ne '') {
+ return ("<span class=\"release-info\">"
+ . "Release $PACKAGE_VERSION.</span>");
+ }
+ if ($t_date) {
+ return ("<span class=\"release-info\">Documentation released on "
+ . "$t_date.</span>");
+ }
+ return '';
+}
+
+
+sub top_navigation_panel {
+ return "\n"
+ . make_nav_panel()
+ . "<br><hr>\n";
+}
+
+sub bot_navigation_panel {
+ return "\n<p><hr>\n"
+ . make_nav_panel()
+ . "<hr>\n"
+ . get_version_text()
+ . "\n";
+}
+
+sub add_link {
+ # Returns a pair (iconic link, textual link)
+ my($icon, $current_file, @link) = @_;
+ my($dummy, $file, $title) = split($delim,
+ $section_info{join(' ',@link)});
+ if ($icon =~ /\<tex2html_([_a-z]+)_visible_mark\>/) {
+ my $r = get_my_icon($1);
+ $icon =~ s/\<tex2html_[_a-z]+_visible_mark\>/$r/;
+ }
+ if ($title && ($file ne $current_file)) {
+ $title = purify($title);
+ $title = get_first_words($title, $WORDS_IN_NAVIGATION_PANEL_TITLES);
+ return (make_href($file, $icon), make_href($file, "$title"))
+ }
+ elsif ($icon eq get_my_icon('up') && $EXTERNAL_UP_LINK) {
+ return (make_href($EXTERNAL_UP_LINK, $icon),
+ make_href($EXTERNAL_UP_LINK, "$EXTERNAL_UP_TITLE"))
+ }
+ elsif ($icon eq get_my_icon('previous')
+ && $EXTERNAL_PREV_LINK && $EXTERNAL_PREV_TITLE) {
+ return (make_href($EXTERNAL_PREV_LINK, $icon),
+ make_href($EXTERNAL_PREV_LINK, "$EXTERNAL_PREV_TITLE"))
+ }
+ elsif ($icon eq get_my_icon('next')
+ && $EXTERNAL_DOWN_LINK && $EXTERNAL_DOWN_TITLE) {
+ return (make_href($EXTERNAL_DOWN_LINK, $icon),
+ make_href($EXTERNAL_DOWN_LINK, "$EXTERNAL_DOWN_TITLE"))
+ }
+ return (&inactive_img($icon), "");
+}
+
+sub add_special_link {
+ my($icon, $file, $current_file) = @_;
+ if ($icon =~ /\<tex2html_([_a-z]+)_visible_mark\>/) {
+ my $r = get_my_icon($1);
+ $icon =~ s/\<tex2html_[_a-z]+_visible_mark\>/$r/;
+ }
+ return (($file && ($file ne $current_file))
+ ? make_href($file, $icon)
+ : undef)
+}
+
+# The img_tag() function seems only to be called with the parameter
+# 'anchor_invisible_mark', which we want to turn into ''. Since
+# replace_icon_marks() is the only interesting caller, and all it really
+# does is call img_tag(), we can just define the hook alternative to be
+# a no-op instead.
+#
+sub replace_icons_hook {}
+
+sub do_cmd_arabic {
+ # get rid of that nasty <SPAN CLASS="arabic">...</SPAN>
+ my($ctr, $val, $id, $text) = &read_counter_value(@_[0]);
+ return ($val ? farabic($val) : "0") . $text;
+}
+
+
+sub gen_index_id {
+ # this is used to ensure common index key generation and a stable sort
+ my($str,$extra) = @_;
+ sprintf('%s###%s%010d', $str, $extra, ++$global{'max_id'});
+}
+
+sub insert_index {
+ my($mark,$datafile,$columns,$letters,$prefix) = @_;
+ my $prog = "$myrootdir/tools/buildindex.py";
+ my $index;
+ if ($letters) {
+ $index = `$prog --columns $columns --letters $datafile`;
+ }
+ else {
+ $index = `$prog --columns $columns $datafile`;
+ }
+ if (!s/$mark/$prefix$index/) {
+ print "\nCould not locate index mark: $mark";
+ }
+}
+
+sub add_idx {
+ print "\nBuilding HTML for the index ...";
+ close(IDXFILE);
+ insert_index($idx_mark, 'index.dat', $INDEX_COLUMNS, 1, '');
+}
+
+
+$idx_module_mark = '<tex2html_idx_module_mark>';
+$idx_module_title = 'Module Index';
+
+sub add_module_idx {
+ print "\nBuilding HTML for the module index ...";
+ my $key;
+ my $first = 1;
+ my $prevplat = '';
+ my $allthesame = 1;
+ my $prefix = '';
+ foreach $key (keys %Modules) {
+ $key =~ s/<tt>([a-zA-Z0-9._]*)<\/tt>/\1/;
+ my $plat = "$ModulePlatforms{$key}";
+ $plat = ''
+ if ($plat eq $IGNORE_PLATFORM_ANNOTATION);
+ if (!$first) {
+ $allthesame = 0
+ if ($prevplat ne $plat);
+ }
+ else { $first = 0; }
+ $prevplat = $plat;
+ }
+ open(MODIDXFILE, '>modindex.dat') || die "\n$!\n";
+ foreach $key (keys %Modules) {
+ # dump the line in the data file; just use a dummy seqno field
+ my $nkey = $1;
+ my $moditem = "$Modules{$key}";
+ my $plat = '';
+ $key =~ s/<tt>([a-zA-Z0-9._]*)<\/tt>/\1/;
+ if ($ModulePlatforms{$key} && !$allthesame) {
+ $plat = (" <em>(<span class='platform'>$ModulePlatforms{$key}"
+ . '</span>)</em>');
+ }
+ print MODIDXFILE $moditem . $IDXFILE_FIELD_SEP
+ . "<tt class='module'>$key</tt>$plat###\n";
+ }
+ close(MODIDXFILE);
+
+ if ($GLOBAL_MODULE_INDEX) {
+ $prefix = <<MODULE_INDEX_PREFIX;
+
+<p> This index only lists modules documented in this manual.
+ The <em class="citetitle"><a href="$GLOBAL_MODULE_INDEX">Global Module
+ Index</a></em> lists all modules that are documented in this set
+ of manuals.</p>
+MODULE_INDEX_PREFIX
+ }
+ if (!$allthesame) {
+ $prefix .= <<PLAT_DISCUSS;
+
+<p> Some module names are followed by an annotation indicating what
+platform they are available on.</p>
+
+PLAT_DISCUSS
+ }
+ insert_index($idx_module_mark, 'modindex.dat', $MODULE_INDEX_COLUMNS, 0,
+ $prefix);
+}
+
+# replace both indexes as needed:
+sub add_idx_hook {
+ add_idx() if (/$idx_mark/);
+ process_python_state();
+ if ($MODULE_INDEX_FILE) {
+ local ($_);
+ open(MYFILE, "<$MODULE_INDEX_FILE");
+ sysread(MYFILE, $_, 1024*1024);
+ close(MYFILE);
+ add_module_idx();
+ open(MYFILE,">$MODULE_INDEX_FILE");
+ print MYFILE $_;
+ close(MYFILE);
+ }
+}
+
+
+# In addition to the standard stuff, add label to allow named node files and
+# support suppression of the page complete (for HTML Help use).
+sub do_cmd_tableofcontents {
+ local($_) = @_;
+ $TITLE = $toc_title;
+ $tocfile = $CURRENT_FILE;
+ my($closures,$reopens) = preserve_open_tags();
+ anchor_label('contents', $CURRENT_FILE, $_); # this is added
+ join('', "<BR>\n\\tableofchildlinks[off]", $closures
+ , make_section_heading($toc_title, 'H2'), $toc_mark
+ , $reopens, $_);
+}
+# In addition to the standard stuff, add label to allow named node files.
+sub do_cmd_listoffigures {
+ local($_) = @_;
+ $TITLE = $lof_title;
+ $loffile = $CURRENT_FILE;
+ my($closures,$reopens) = preserve_open_tags();
+ anchor_label('lof', $CURRENT_FILE, $_); # this is added
+ join('', "<BR>\n", $closures
+ , make_section_heading($lof_title, 'H2'), $lof_mark
+ , $reopens, $_);
+}
+# In addition to the standard stuff, add label to allow named node files.
+sub do_cmd_listoftables {
+ local($_) = @_;
+ $TITLE = $lot_title;
+ $lotfile = $CURRENT_FILE;
+ my($closures,$reopens) = preserve_open_tags();
+ anchor_label('lot', $CURRENT_FILE, $_); # this is added
+ join('', "<BR>\n", $closures
+ , make_section_heading($lot_title, 'H2'), $lot_mark
+ , $reopens, $_);
+}
+# In addition to the standard stuff, add label to allow named node files.
+sub do_cmd_textohtmlinfopage {
+ local($_) = @_;
+ if ($INFO) { #
+ anchor_label("about",$CURRENT_FILE,$_); # this is added
+ } #
+ my $the_version = ''; # and the rest is
+ if ($t_date) { # mostly ours
+ $the_version = ",\n$t_date";
+ if ($PACKAGE_VERSION) {
+ $the_version .= ", Release $PACKAGE_VERSION";
+ }
+ }
+ $_ = (($INFO == 1)
+ ? join('',
+ $close_all,
+ "<strong>$t_title</strong>$the_version\n",
+ `cat $ABOUT_FILE`,
+ $open_all, $_)
+ : join('', $close_all, $INFO,"\n", $open_all, $_));
+ $_;
+}
+
+# $idx_mark will be replaced with the real index at the end
+sub do_cmd_textohtmlindex {
+ local($_) = @_;
+ $TITLE = $idx_title;
+ $idxfile = $CURRENT_FILE;
+ if (%index_labels) { make_index_labels(); }
+ if (($SHORT_INDEX) && (%index_segment)) { make_preindex(); }
+ else { $preindex = ''; }
+ my $heading = make_section_heading($idx_title, 'h2') . $idx_mark;
+ my($pre,$post) = minimize_open_tags($heading);
+ anchor_label('genindex',$CURRENT_FILE,$_); # this is added
+ return "<br>\n" . $pre . $_;
+}
+
+$MODULE_INDEX_FILE = '';
+
+# $idx_module_mark will be replaced with the real index at the end
+sub do_cmd_textohtmlmoduleindex {
+ local($_) = @_;
+ $TITLE = $idx_module_title;
+ anchor_label('modindex', $CURRENT_FILE, $_);
+ $MODULE_INDEX_FILE = "$CURRENT_FILE";
+ $_ = ('<p>' . make_section_heading($idx_module_title, 'h2')
+ . $idx_module_mark . $_);
+ return $_;
+}
+
+# The bibliography and the index should be treated as separate
+# sections in their own HTML files. The \bibliography{} command acts
+# as a sectioning command that has the desired effect. But when the
+# bibliography is constructed manually using the thebibliography
+# environment, or when using the theindex environment it is not
+# possible to use the normal sectioning mechanism. This subroutine
+# inserts a \bibliography{} or a dummy \textohtmlindex command just
+# before the appropriate environments to force sectioning.
+
+# XXX This *assumes* that if there are two {theindex} environments,
+# the first is the module index and the second is the standard
+# index. This is sufficient for the current Python documentation,
+# but that's about it.
+
+sub add_bbl_and_idx_dummy_commands {
+ my $id = $global{'max_id'};
+
+ s/([\\]begin\s*$O\d+$C\s*thebibliography)/$bbl_cnt++; $1/eg;
+ s/([\\]begin\s*$O\d+$C\s*thebibliography)/$id++; "\\bibliography$O$id$C$O$id$C $1"/geo;
+ my(@parts) = split(/\\begin\s*$O\d+$C\s*theindex/);
+ if (scalar(@parts) == 3) {
+ # Be careful to re-write the string in place, since $_ is *not*
+ # returned explicity; *** nasty side-effect dependency! ***
+ print "\nadd_bbl_and_idx_dummy_commands ==> adding module index";
+ my $rx = "([\\\\]begin\\s*$O\\d+$C\\s*theindex[\\s\\S]*)"
+ . "([\\\\]begin\\s*$O\\d+$C\\s*theindex)";
+ s/$rx/\\textohtmlmoduleindex \1 \\textohtmlindex \2/o;
+ # Add a button to the navigation areas:
+ $CUSTOM_BUTTONS .= ('<a href="modindex.html" title="Module Index">'
+ . get_my_icon('modules')
+ . '</a>');
+ }
+ else {
+ $CUSTOM_BUTTONS .= get_my_icon('blank');
+ $global{'max_id'} = $id; # not sure why....
+ s/([\\]begin\s*$O\d+$C\s*theindex)/\\textohtmlindex $1/o;
+ s/[\\]printindex/\\textohtmlindex /o;
+ }
+ #----------------------------------------------------------------------
+ lib_add_bbl_and_idx_dummy_commands()
+ if defined(&lib_add_bbl_and_idx_dummy_commands);
+}
+
+# The bibliographic references, the appendices, the lists of figures
+# and tables etc. must appear in the contents table at the same level
+# as the outermost sectioning command. This subroutine finds what is
+# the outermost level and sets the above to the same level;
+
+sub set_depth_levels {
+ # Sets $outermost_level
+ my $level;
+ #RRM: do not alter user-set value for $MAX_SPLIT_DEPTH
+ foreach $level ("part", "chapter", "section", "subsection",
+ "subsubsection", "paragraph") {
+ last if (($outermost_level) = /\\($level)$delimiter_rx/);
+ }
+ $level = ($outermost_level ? $section_commands{$outermost_level} :
+ do {$outermost_level = 'section'; 3;});
+
+ #RRM: but calculate value for $MAX_SPLIT_DEPTH when a $REL_DEPTH was given
+ if ($REL_DEPTH && $MAX_SPLIT_DEPTH) {
+ $MAX_SPLIT_DEPTH = $level + $MAX_SPLIT_DEPTH;
+ } elsif (!($MAX_SPLIT_DEPTH)) { $MAX_SPLIT_DEPTH = 1 };
+
+ %unnumbered_section_commands = ('tableofcontents' => $level,
+ 'listoffigures' => $level,
+ 'listoftables' => $level,
+ 'bibliography' => $level,
+ 'textohtmlindex' => $level,
+ 'textohtmlmoduleindex' => $level);
+ $section_headings{'textohtmlmoduleindex'} = 'h1';
+
+ %section_commands = (%unnumbered_section_commands,
+ %section_commands);
+
+ make_sections_rx();
+}
+
+
+# This changes the markup used for {verbatim} environments, and is the
+# best way I've found that ensures the <dl> goes on the outside of the
+# <pre>...</pre>.
+#
+# Note that this *must* be done in the init file, not the python.perl
+# style support file. The %declarations must be set before
+# initialize() is called in the main LaTeX2HTML script (which happens
+# before style files are loaded).
+#
+%declarations = ('preform' => '<dl><dd><pre class="verbatim"></pre></dl>',
+ %declarations);
+
+
+# This is added to get rid of the long comment that follows the
+# doctype declaration; MSIE5 on NT4 SP4 barfs on it and drops the
+# content of the page.
+sub make_head_and_body {
+ my($title, $body) = @_;
+ $body = " $body" unless ($body eq '');
+ my $DTDcomment = '';
+ my($version, $isolanguage) = ($HTML_VERSION, 'EN');
+ my %isolanguages = ( 'english', 'EN' , 'USenglish', 'EN.US'
+ , 'original', 'EN' , 'german' , 'DE'
+ , 'austrian', 'DE.AT', 'french' , 'FR'
+ , 'spanish', 'ES');
+ $isolanguage = $isolanguages{$default_language};
+ $isolanguage = 'EN' unless $isolanguage;
+ $title = &purify($title,1);
+ eval("\$title = ". $default_title ) unless ($title);
+
+ # allow user-modification of the <TITLE> tag; thanks Dan Young
+ if (defined &custom_TITLE_hook) {
+ $title = &custom_TITLE_hook($title, $toc_sec_title);
+ }
+
+ if ($DOCTYPE =~ /\/\/[\w\.]+\s*$/) { # language spec included
+ $DTDcomment = "<!DOCTYPE html PUBLIC \"$DOCTYPE\">\n";
+ } else {
+ $DTDcomment = "<!DOCTYPE html PUBLIC \"$DOCTYPE//"
+ . ($ISO_LANGUAGE ? $ISO_LANGUAGE : $isolanguage) . "\">\n";
+ }
+
+ $STYLESHEET = $FILE.".css" unless $STYLESHEET;
+ if (!$charset && $CHARSET) { $charset = $CHARSET; $charset =~ s/_/\-/go; }
+
+ join('', ($DOCTYPE ? $DTDcomment : '' )
+ ,"<html>\n<head>\n<title>", $title, "</title>\n"
+ , &meta_information($title)
+ , ($CHARSET && $HTML_VERSION ge "2.1" ?
+ "<meta http-equiv=\"Content-Type\" content=\"text/html; charset=$charset\">\n"
+ : "" )
+ , ($BASE ? "<base href=\"$BASE\">\n" : "" )
+ , "<link rel=\"STYLESHEET\" href=\"$STYLESHEET\">"
+ , $more_links_mark
+ , "\n</head>\n<body$body>");
+}
+
+1; # This must be the last line
diff --git a/doc/tools/perl/ltxmarkup.perl b/doc/tools/perl/ltxmarkup.perl
new file mode 100644
index 0000000..290e79b
--- /dev/null
+++ b/doc/tools/perl/ltxmarkup.perl
@@ -0,0 +1,67 @@
+# LaTeX2HTML support for the ltxmarkup package. Doesn't do indexing.
+
+package main;
+
+
+sub ltx_next_argument{
+ my $param;
+ $param = missing_braces()
+ unless ((s/$next_pair_pr_rx/$param=$2;''/eo)
+ ||(s/$next_pair_rx/$param=$2;''/eo));
+ return $param;
+}
+
+
+sub do_cmd_macro{
+ local($_) = @_;
+ my $macro = ltx_next_argument();
+ return "<tt class='macro'>\$macro</tt>" . $_;
+}
+
+sub do_cmd_env{
+ local($_) = @_;
+ my $env = ltx_next_argument();
+ return "<tt class='environment'>\$env</tt>" . $_;
+}
+
+sub ltx_process_params{
+ # Handle processing of \p and \op for parameter specifications for
+ # envdesc and macrodesc. It's done this way to avoid defining do_cmd_p()
+ # and do_cmd_op() functions, which would be interpreted outside the context
+ # in which these commands are legal, and cause LaTeX2HTML to think they're
+ # defined. This way, other uses of \p and \op are properly flagged as
+ # unknown macros.
+ my $s = @_[0];
+ $s =~ s%\\op<<(\d+)>>(.+)<<\1>>%<tt>[</tt><var>$2</var><tt>]</tt>%;
+ while ($s =~ /\\p<<(\d+)>>(.+)<<\1>>/) {
+ $s =~ s%\\p<<(\d+)>>(.+)<<\1>>%<tt>{</tt><var>$2</var><tt>}</tt>%;
+ }
+ return $s;
+}
+
+sub do_env_macrodesc{
+ local($_) = @_;
+ my $macro = ltx_next_argument();
+ my $params = ltx_process_params(ltx_next_argument());
+ return "\n<dl class='macrodesc'>"
+ . "\n<dt><b><tt class='macro'>\$macro</tt></b>"
+ . "\n $params"
+ . "\n<dd>"
+ . $_
+ . "</dl>";
+}
+
+sub do_env_envdesc{
+ local($_) = @_;
+ my $env = ltx_next_argument();
+ my $params = ltx_process_params(ltx_next_argument());
+ return "\n<dl class='envdesc'>"
+ . "\n<dt><tt>\begin{<b class='environment'>$env</b>}</tt>"
+ . "\n $params"
+ . "\n<br /><tt>\end{<b class='environment'>$env</b>}</tt>"
+ . "\n<dd>"
+ . $_
+ . "</dl>";
+}
+
+1; # Must end with this, because Perl is bogus.
diff --git a/doc/tools/perl/manual.perl b/doc/tools/perl/manual.perl
new file mode 100644
index 0000000..ea65b36
--- /dev/null
+++ b/doc/tools/perl/manual.perl
@@ -0,0 +1,15 @@
+# -*- perl -*-
+#
+# This implements the Python manual class. All it really needs to do it
+# load the "python" style. The style code is not moved into the class code
+# at this time, since we expect additional document class to be developed
+# for the Python documentation in the future. Appropriate relocations will
+# be made at that time.
+
+package main;
+
+do_require_package("report");
+do_require_package("alltt");
+do_require_package("python");
+
+1; # sheesh....
diff --git a/doc/tools/perl/python.perl b/doc/tools/perl/python.perl
new file mode 100644
index 0000000..20615cc
--- /dev/null
+++ b/doc/tools/perl/python.perl
@@ -0,0 +1,1651 @@
+# python.perl by Fred L. Drake, Jr. <fdrake@acm.org> -*- perl -*-
+#
+# Heavily based on Guido van Rossum's myformat.perl (now obsolete).
+#
+# Extension to LaTeX2HTML for documents using myformat.sty.
+# Subroutines of the form do_cmd_<name> here define translations
+# for LaTeX commands \<name> defined in the corresponding .sty file.
+
+package main;
+
+use File::Basename;
+
+
+sub next_argument{
+ my $param;
+ $param = missing_braces()
+ unless ((s/$next_pair_pr_rx/$param=$2;''/eo)
+ ||(s/$next_pair_rx/$param=$2;''/eo));
+ return $param;
+}
+
+sub next_optional_argument{
+ my($param,$rx) = ('', "^\\s*(\\[([^]]*)\\])?");
+ s/$rx/$param=$2;''/eo;
+ return $param;
+}
+
+sub make_icon_filename($){
+ my($myname, $mydir, $myext) = fileparse(@_[0], '\..*');
+ chop $mydir;
+ if ($mydir eq '.') {
+ $mydir = $ICONSERVER;
+ }
+ $myext = ".$IMAGE_TYPE"
+ unless $myext;
+ return "$mydir$dd$myname$myext";
+}
+
+sub get_link_icon($){
+ my $url = @_[0];
+ if ($OFF_SITE_LINK_ICON && ($url =~ /^[-a-zA-Z0-9.]+:/)) {
+ # absolute URL; assume it points off-site
+ my $icon = make_icon_filename($OFF_SITE_LINK_ICON);
+ return (" <img src='$icon'\n"
+ . " border='0' class='offsitelink'"
+ . ($OFF_SITE_LINK_ICON_HEIGHT
+ ? " height='$OFF_SITE_LINK_ICON_HEIGHT'"
+ : '')
+ . ($OFF_SITE_LINK_ICON_WIDTH
+ ? " width='$OFF_SITE_LINK_ICON_WIDTH'"
+ : '')
+ . " alt='[off-site link]'\n"
+ . " >");
+ }
+ return '';
+}
+
+# This is a fairly simple hack; it supports \let when it is used to create
+# (or redefine) a macro to exactly be some other macro: \let\newname=\oldname.
+# Many possible uses of \let aren't supported or aren't supported correctly.
+#
+sub do_cmd_let{
+ local($_) = @_;
+ my $matched = 0;
+ s/[\\]([a-zA-Z]+)\s*(=\s*)?[\\]([a-zA-Z]*)/$matched=1; ''/e;
+ if ($matched) {
+ my($new, $old) = ($1, $3);
+ eval "sub do_cmd_$new { do_cmd_$old" . '(@_); }';
+ print "\ndefining handler for \\$new using \\$old\n";
+ }
+ else {
+ s/[\\]([a-zA-Z]+)\s*(=\s*)?([^\\])/$matched=1; ''/es;
+ if ($matched) {
+ my($new, $char) = ($1, $3);
+ eval "sub do_cmd_$new { \"\\$char\" . \@_[0]; }";
+ print "\ndefining handler for \\$new to insert '$char'\n";
+ }
+ else {
+ write_warnings("Could not interpret \\let construct...");
+ }
+ }
+ return $_;
+}
+
+
+# the older version of LaTeX2HTML we use doesn't support this, but we use it:
+
+sub do_cmd_textasciitilde{ '~' . @_[0]; }
+
+
+# words typeset in a special way (not in HTML though)
+
+sub do_cmd_ABC{ 'ABC' . @_[0]; }
+sub do_cmd_UNIX{ 'Unix'. @_[0]; }
+sub do_cmd_ASCII{ 'ASCII' . @_[0]; }
+sub do_cmd_POSIX{ 'POSIX' . @_[0]; }
+sub do_cmd_C{ 'C' . @_[0]; }
+sub do_cmd_Cpp{ 'C++' . @_[0]; }
+sub do_cmd_EOF{ 'EOF' . @_[0]; }
+sub do_cmd_NULL{ '<tt class="constant">NULL</tt>' . @_[0]; }
+
+sub do_cmd_e{ '\' . @_[0]; }
+
+$DEVELOPER_ADDRESS = '';
+$SHORT_VERSION = '';
+$PACKAGE_VERSION = '';
+
+sub do_cmd_version{ $PACKAGE_VERSION . @_[0]; }
+sub do_cmd_shortversion{ $SHORT_VERSION . @_[0]; }
+sub do_cmd_release{
+ local($_) = @_;
+ $PACKAGE_VERSION = next_argument();
+ return $_;
+}
+
+sub do_cmd_setshortversion{
+ local($_) = @_;
+ $SHORT_VERSION = next_argument();
+ return $_;
+}
+
+sub do_cmd_authoraddress{
+ local($_) = @_;
+ $DEVELOPER_ADDRESS = next_argument();
+ return $_;
+}
+
+#sub do_cmd_developer{ do_cmd_author(@_[0]); }
+#sub do_cmd_developers{ do_cmd_author(@_[0]); }
+#sub do_cmd_developersaddress{ do_cmd_authoraddress(@_[0]); }
+
+sub do_cmd_hackscore{
+ local($_) = @_;
+ next_argument();
+ return '_' . $_;
+}
+
+sub use_wrappers{
+ local($_,$before,$after) = @_;
+ my $stuff = next_argument();
+ return $before . $stuff . $after . $_;
+}
+
+$IN_DESC_HANDLER = 0;
+sub do_cmd_optional{
+ if ($IN_DESC_HANDLER) {
+ return use_wrappers(@_[0], "</var><big>\[</big><var>",
+ "</var><big>\]</big><var>");
+ }
+ else {
+ return use_wrappers(@_[0], "<big>\[</big>", "<big>\]</big>");
+ }
+}
+
+# Logical formatting (some based on texinfo), needs to be converted to
+# minimalist HTML. The "minimalist" is primarily to reduce the size of
+# output files for users that read them over the network rather than
+# from local repositories.
+
+# \file and \samp are at the end of this file since they screw up fontlock.
+
+sub do_cmd_pytype{ return @_[0]; }
+sub do_cmd_makevar{
+ return use_wrappers(@_[0], '<span class="makevar">', '</span>'); }
+sub do_cmd_code{
+ return use_wrappers(@_[0], '<code>', '</code>'); }
+sub do_cmd_module{
+ return use_wrappers(@_[0], '<tt class="module">', '</tt>'); }
+sub do_cmd_keyword{
+ return use_wrappers(@_[0], '<tt class="keyword">', '</tt>'); }
+sub do_cmd_exception{
+ return use_wrappers(@_[0], '<tt class="exception">', '</tt>'); }
+sub do_cmd_class{
+ return use_wrappers(@_[0], '<tt class="class">', '</tt>'); }
+sub do_cmd_function{
+ return use_wrappers(@_[0], '<tt class="function">', '</tt>'); }
+sub do_cmd_constant{
+ return use_wrappers(@_[0], '<tt class="constant">', '</tt>'); }
+sub do_cmd_member{
+ return use_wrappers(@_[0], '<tt class="member">', '</tt>'); }
+sub do_cmd_method{
+ return use_wrappers(@_[0], '<tt class="method">', '</tt>'); }
+sub do_cmd_cfunction{
+ return use_wrappers(@_[0], '<tt class="cfunction">', '</tt>'); }
+sub do_cmd_cdata{
+ return use_wrappers(@_[0], '<tt class="cdata">', '</tt>'); }
+sub do_cmd_ctype{
+ return use_wrappers(@_[0], '<tt class="ctype">', '</tt>'); }
+sub do_cmd_regexp{
+ return use_wrappers(@_[0], '<tt class="regexp">', '</tt>'); }
+sub do_cmd_character{
+ return use_wrappers(@_[0], '"<tt class="character">', '</tt>"'); }
+sub do_cmd_program{
+ return use_wrappers(@_[0], '<b class="program">', '</b>'); }
+sub do_cmd_programopt{
+ return use_wrappers(@_[0], '<b class="programopt">', '</b>'); }
+sub do_cmd_longprogramopt{
+ # note that the --- will be later converted to -- by LaTeX2HTML
+ return use_wrappers(@_[0], '<b class="programopt">---', '</b>'); }
+sub do_cmd_email{
+ return use_wrappers(@_[0], '<span class="email">', '</span>'); }
+sub do_cmd_mimetype{
+ return use_wrappers(@_[0], '<span class="mimetype">', '</span>'); }
+sub do_cmd_var{
+ return use_wrappers(@_[0], "<var>", "</var>"); }
+sub do_cmd_dfn{
+ return use_wrappers(@_[0], '<i class="dfn">', '</i>'); }
+sub do_cmd_emph{
+ return use_wrappers(@_[0], '<i>', '</i>'); }
+sub do_cmd_file{
+ return use_wrappers(@_[0], '<span class="file">', '</span>'); }
+sub do_cmd_filenq{
+ return do_cmd_file(@_[0]); }
+sub do_cmd_samp{
+ return use_wrappers(@_[0], '"<tt class="samp">', '</tt>"'); }
+sub do_cmd_kbd{
+ return use_wrappers(@_[0], '<kbd>', '</kbd>'); }
+sub do_cmd_strong{
+ return use_wrappers(@_[0], '<b>', '</b>'); }
+sub do_cmd_textbf{
+ return use_wrappers(@_[0], '<b>', '</b>'); }
+sub do_cmd_textit{
+ return use_wrappers(@_[0], '<i>', '</i>'); }
+
+sub do_cmd_moreargs{
+ return '...' . @_[0]; }
+sub do_cmd_unspecified{
+ return '...' . @_[0]; }
+
+
+sub do_cmd_refmodule{
+ # Insert the right magic to jump to the module definition.
+ local($_) = @_;
+ my $key = next_optional_argument();
+ my $module = next_argument();
+ $key = $module
+ unless $key;
+ return "<tt class='module'><a href='module-$key.html'>$module</a></tt>"
+ . $_;
+}
+
+sub do_cmd_newsgroup{
+ local($_) = @_;
+ my $newsgroup = next_argument();
+ my $icon = get_link_icon("news:$newsgroup");
+ my $stuff = "<a class='newsgroup' href='news:$newsgroup'>"
+ . "$newsgroup$icon</a>";
+ return $stuff . $_;
+}
+
+sub do_cmd_envvar{
+ local($_) = @_;
+ my $envvar = next_argument();
+ my($name,$aname,$ahref) = new_link_info();
+ # The <tt> here is really to keep buildindex.py from making
+ # the variable name case-insensitive.
+ add_index_entry("environment variables!$envvar@<tt>$envvar</tt>",
+ $ahref);
+ add_index_entry("$envvar (environment variable)", $ahref);
+ $aname =~ s/<a/<a class="envvar"/;
+ return "$aname$envvar</a>" . $_;
+}
+
+sub do_cmd_url{
+ # use the URL as both text and hyperlink
+ local($_) = @_;
+ my $url = next_argument();
+ my $icon = get_link_icon($url);
+ $url =~ s/~/~/g;
+ return "<a class=\"url\" href=\"$url\">$url$icon</a>" . $_;
+}
+
+sub do_cmd_manpage{
+ # two parameters: \manpage{name}{section}
+ local($_) = @_;
+ my $page = next_argument();
+ my $section = next_argument();
+ return "<span class='manpage'><i>$page</i>($section)</span>" . $_;
+}
+
+$PEP_FORMAT = "http://python.sourceforge.net/peps/pep-XXXX.html";
+$RFC_FORMAT = "http://www.ietf.org/rfc/rfcXXXX.txt";
+
+sub get_rfc_url($$){
+ my($rfcnum, $format) = @_;
+ $rfcnum = sprintf("%04d", $rfcnum);
+ $format = "$format";
+ $format =~ s/XXXX/$rfcnum/;
+ return $format;
+}
+
+sub do_cmd_pep{
+ local($_) = @_;
+ my $rfcnumber = next_argument();
+ my $id = "rfcref-" . ++$global{'max_id'};
+ my $href = get_rfc_url($rfcnumber, $PEP_FORMAT);
+ my $icon = get_link_icon($href);
+ # Save the reference
+ my $nstr = gen_index_id("Python Enhancement Proposals!PEP $rfcnumber", '');
+ $index{$nstr} .= make_half_href("$CURRENT_FILE#$id");
+ return ("<a class=\"rfc\" name=\"$id\"\nhref=\"$href\">PEP $rfcnumber"
+ . "$icon</a>" . $_);
+}
+
+sub do_cmd_rfc{
+ local($_) = @_;
+ my $rfcnumber = next_argument();
+ my $id = "rfcref-" . ++$global{'max_id'};
+ my $href = get_rfc_url($rfcnumber, $RFC_FORMAT);
+ my $icon = get_link_icon($href);
+ # Save the reference
+ my $nstr = gen_index_id("RFC!RFC $rfcnumber", '');
+ $index{$nstr} .= make_half_href("$CURRENT_FILE#$id");
+ return ("<a class=\"rfc\" name=\"$id\"\nhref=\"$href\">RFC $rfcnumber"
+ . "$icon</a>" . $_);
+}
+
+sub do_cmd_citetitle{
+ local($_) = @_;
+ my $url = next_optional_argument();
+ my $title = next_argument();
+ my $icon = get_link_icon($url);
+ my $repl = '';
+ if ($url) {
+ $repl = ("<em class='citetitle'><a\n"
+ . " href='$url'\n"
+ . " title='$title'\n"
+ . " >$title$icon</a></em>");
+ }
+ else {
+ $repl = "<em class='citetitle'\n >$title</em>";
+ }
+ return $repl . $_;
+}
+
+sub do_cmd_deprecated{
+ # two parameters: \deprecated{version}{whattodo}
+ local($_) = @_;
+ my $release = next_argument();
+ my $reason = next_argument();
+ return ('<div class="versionnote">'
+ . "<b>Deprecated since release $release.</b>"
+ . "\n$reason</div><p>"
+ . $_);
+}
+
+sub do_cmd_versionadded{
+ # one parameter: \versionadded{version}
+ local($_) = @_;
+ my $release = next_argument();
+ return ("\n<span class='versionnote'>New in version $release.</span>\n"
+ . $_);
+}
+
+sub do_cmd_versionchanged{
+ # one parameter: \versionchanged{version}
+ local($_) = @_;
+ my $explanation = next_optional_argument();
+ my $release = next_argument();
+ my $text = "Changed in version $release.";
+ if ($explanation) {
+ $text = "Changed in version $release:\n$explanation.";
+ }
+ return "\n<span class='versionnote'>$text</span>\n" . $_;
+}
+
+#
+# These function handle platform dependency tracking.
+#
+sub do_cmd_platform{
+ local($_) = @_;
+ my $platform = next_argument();
+ $ModulePlatforms{"<tt class='module'>$THIS_MODULE</tt>"} = $platform;
+ $platform = "Macintosh"
+ if $platform eq 'Mac';
+ return "\n<p class='availability'>Availability: <span"
+ . "\n class='platform'>$platform</span>.</p>\n" . $_;
+}
+
+$IGNORE_PLATFORM_ANNOTATION = '';
+sub do_cmd_ignorePlatformAnnotation{
+ local($_) = @_;
+ $IGNORE_PLATFORM_ANNOTATION = next_argument();
+ return $_;
+}
+
+
+# index commands
+
+$INDEX_SUBITEM = "";
+
+sub get_indexsubitem{
+ return $INDEX_SUBITEM ? " $INDEX_SUBITEM" : '';
+}
+
+sub do_cmd_setindexsubitem{
+ local($_) = @_;
+ $INDEX_SUBITEM = next_argument();
+ return $_;
+}
+
+sub do_cmd_withsubitem{
+ # We can't really do the right thing, because LaTeX2HTML doesn't
+ # do things in the right order, but we need to at least strip this stuff
+ # out, and leave anything that the second argument expanded out to.
+ #
+ local($_) = @_;
+ my $oldsubitem = $INDEX_SUBITEM;
+ $INDEX_SUBITEM = next_argument();
+ my $stuff = next_argument();
+ my $br_id = ++$globals{'max_id'};
+ my $marker = "$O$br_id$C";
+ return
+ $stuff
+ . "\\setindexsubitem$marker$oldsubitem$marker"
+ . $_;
+}
+
+# This is the prologue macro which is required to start writing the
+# mod\jobname.idx file; we can just ignore it. (Defining this suppresses
+# a warning that \makemodindex is unknown.)
+#
+sub do_cmd_makemodindex{ return @_[0]; }
+
+# We're in the document subdirectory when this happens!
+#
+open(IDXFILE, '>index.dat') || die "\n$!\n";
+open(INTLABELS, '>intlabels.pl') || die "\n$!\n";
+print INTLABELS "%internal_labels = ();\n";
+print INTLABELS "1; # hack in case there are no entries\n\n";
+
+# Using \0 for this is bad because we can't use common tools to work with the
+# resulting files. Things like grep can be useful with this stuff!
+#
+$IDXFILE_FIELD_SEP = "\1";
+
+sub write_idxfile{
+ my ($ahref, $str) = @_;
+ print IDXFILE $ahref, $IDXFILE_FIELD_SEP, $str, "\n";
+}
+
+
+sub gen_link{
+ my($node,$target) = @_;
+ print INTLABELS "\$internal_labels{\"$target\"} = \"$URL/$node\";\n";
+ return "<a href='$node#$target'>";
+}
+
+sub add_index_entry{
+ # add an entry to the index structures; ignore the return value
+ my($str,$ahref) = @_;
+ $str = gen_index_id($str, '');
+ $index{$str} .= $ahref;
+ write_idxfile($ahref, $str);
+}
+
+sub new_link_info{
+ my $name = "l2h-" . ++$globals{'max_id'};
+ my $aname = "<a name='$name'>";
+ my $ahref = gen_link($CURRENT_FILE, $name);
+ return ($name, $aname, $ahref);
+}
+
+$IndexMacroPattern = '';
+sub define_indexing_macro{
+ my $count = @_;
+ my $i = 0;
+ for (; $i < $count; ++$i) {
+ my $name = @_[$i];
+ my $cmd = "idx_cmd_$name";
+ die "\nNo function $cmd() defined!\n"
+ if (!defined &$cmd);
+ eval ("sub do_cmd_$name { return process_index_macros("
+ . "\@_[0], '$name'); }");
+ if (length($IndexMacroPattern) == 0) {
+ $IndexMacroPattern = "$name";
+ }
+ else {
+ $IndexMacroPattern .= "|$name";
+ }
+ }
+}
+
+$DEBUG_INDEXING = 0;
+sub process_index_macros{
+ local($_) = @_;
+ my $cmdname = @_[1]; # This is what triggered us in the first place;
+ # we know it's real, so just process it.
+ my($name,$aname,$ahref) = new_link_info();
+ my $cmd = "idx_cmd_$cmdname";
+ print "\nIndexing: \\$cmdname"
+ if $DEBUG_INDEXING;
+ &$cmd($ahref); # modifies $_ and adds index entries
+ while (/^[\s\n]*\\($IndexMacroPattern)</) {
+ $cmdname = "$1";
+ print " \\$cmdname"
+ if $DEBUG_INDEXING;
+ $cmd = "idx_cmd_$cmdname";
+ if (!defined &$cmd) {
+ last;
+ }
+ else {
+ s/^[\s\n]*\\$cmdname//;
+ &$cmd($ahref);
+ }
+ }
+ if (/^[ \t\r\n]/) {
+ $_ = substr($_, 1);
+ }
+ return "$aname$anchor_invisible_mark</a>" . $_;
+}
+
+define_indexing_macro('index');
+sub idx_cmd_index{
+ my $str = next_argument();
+ add_index_entry("$str", @_[0]);
+}
+
+define_indexing_macro('kwindex');
+sub idx_cmd_kwindex{
+ my $str = next_argument();
+ add_index_entry("<tt>$str</tt>!keyword", @_[0]);
+ add_index_entry("keyword!<tt>$str</tt>", @_[0]);
+}
+
+define_indexing_macro('indexii');
+sub idx_cmd_indexii{
+ my $str1 = next_argument();
+ my $str2 = next_argument();
+ add_index_entry("$str1!$str2", @_[0]);
+ add_index_entry("$str2!$str1", @_[0]);
+}
+
+define_indexing_macro('indexiii');
+sub idx_cmd_indexiii{
+ my $str1 = next_argument();
+ my $str2 = next_argument();
+ my $str3 = next_argument();
+ add_index_entry("$str1!$str2 $str3", @_[0]);
+ add_index_entry("$str2!$str3, $str1", @_[0]);
+ add_index_entry("$str3!$str1 $str2", @_[0]);
+}
+
+define_indexing_macro('indexiv');
+sub idx_cmd_indexiv{
+ my $str1 = next_argument();
+ my $str2 = next_argument();
+ my $str3 = next_argument();
+ my $str4 = next_argument();
+ add_index_entry("$str1!$str2 $str3 $str4", @_[0]);
+ add_index_entry("$str2!$str3 $str4, $str1", @_[0]);
+ add_index_entry("$str3!$str4, $str1 $str2", @_[0]);
+ add_index_entry("$str4!$$str1 $str2 $str3", @_[0]);
+}
+
+define_indexing_macro('ttindex');
+sub idx_cmd_ttindex{
+ my $str = next_argument();
+ my $entry = $str . get_indexsubitem();
+ add_index_entry($entry, @_[0]);
+}
+
+sub my_typed_index_helper{
+ my($word,$ahref) = @_;
+ my $str = next_argument();
+ add_index_entry("$str $word", $ahref);
+ add_index_entry("$word!$str", $ahref);
+}
+
+define_indexing_macro('stindex', 'opindex', 'exindex', 'obindex');
+sub idx_cmd_stindex{ my_typed_index_helper('statement', @_[0]); }
+sub idx_cmd_opindex{ my_typed_index_helper('operator', @_[0]); }
+sub idx_cmd_exindex{ my_typed_index_helper('exception', @_[0]); }
+sub idx_cmd_obindex{ my_typed_index_helper('object', @_[0]); }
+
+define_indexing_macro('bifuncindex');
+sub idx_cmd_bifuncindex{
+ my $str = next_argument();
+ add_index_entry("<tt class='function'>$str()</tt> (built-in function)",
+ @_[0]);
+}
+
+
+sub make_mod_index_entry{
+ my($str,$define) = @_;
+ my($name,$aname,$ahref) = new_link_info();
+ # equivalent of add_index_entry() using $define instead of ''
+ $ahref =~ s/\#[-_a-zA-Z0-9]*\"/\"/
+ if ($define eq 'DEF');
+ $str = gen_index_id($str, $define);
+ $index{$str} .= $ahref;
+ write_idxfile($ahref, $str);
+
+ if ($define eq 'DEF') {
+ # add to the module index
+ $str =~ /(<tt.*<\/tt>)/;
+ my $nstr = $1;
+ $Modules{$nstr} .= $ahref;
+ }
+ return "$aname$anchor_invisible_mark2</a>";
+}
+
+
+$THIS_MODULE = '';
+$THIS_CLASS = '';
+
+sub define_module{
+ my($word,$name) = @_;
+ my $section_tag = join('', @curr_sec_id);
+ if ($word ne "built-in" && $word ne "extension"
+ && $word ne "standard" && $word ne "") {
+ write_warnings("Bad module type '$word'"
+ . " for \\declaremodule (module $name)");
+ $word = "";
+ }
+ $word = "$word " if $word;
+ $THIS_MODULE = "$name";
+ $INDEX_SUBITEM = "(in module $name)";
+ print "[$name]";
+ return make_mod_index_entry(
+ "<tt class='module'>$name</tt> (${word}module)", 'DEF');
+}
+
+sub my_module_index_helper{
+ local($word, $_) = @_;
+ my $name = next_argument();
+ return define_module($word, $name) . $_;
+}
+
+sub do_cmd_modindex{ return my_module_index_helper('', @_); }
+sub do_cmd_bimodindex{ return my_module_index_helper('built-in', @_); }
+sub do_cmd_exmodindex{ return my_module_index_helper('extension', @_); }
+sub do_cmd_stmodindex{ return my_module_index_helper('standard', @_); }
+
+sub ref_module_index_helper{
+ my($word, $ahref) = @_;
+ my $str = next_argument();
+ $word = "$word " if $word;
+ $str = "<tt class='module'>$str</tt> (${word}module)";
+ # can't use add_index_entry() since the 2nd arg to gen_index_id() is used;
+ # just inline it all here
+ $str = gen_index_id($str, 'REF');
+ $index{$str} .= $ahref;
+ write_idxfile($ahref, $str);
+}
+
+# these should be adjusted a bit....
+define_indexing_macro('refmodindex', 'refbimodindex',
+ 'refexmodindex', 'refstmodindex');
+sub idx_cmd_refmodindex{ return ref_module_index_helper('', @_); }
+sub idx_cmd_refbimodindex{ return ref_module_index_helper('built-in', @_); }
+sub idx_cmd_refexmodindex{ return ref_module_index_helper('extension', @_); }
+sub idx_cmd_refstmodindex{ return ref_module_index_helper('standard', @_); }
+
+sub do_cmd_nodename{ return do_cmd_label(@_); }
+
+sub init_myformat{
+ $anchor_invisible_mark = ' ';
+ $anchor_invisible_mark2 = '';
+ $anchor_mark = '';
+ $icons{'anchor_mark'} = '';
+}
+init_myformat();
+
+# Create an index entry, but include the string in the target anchor
+# instead of the dummy filler.
+#
+sub make_str_index_entry{
+ my($str) = @_;
+ my($name,$aname,$ahref) = new_link_info();
+ add_index_entry($str, $ahref);
+ return "$aname$str</a>";
+}
+
+$REFCOUNTS_LOADED = 0;
+
+sub load_refcounts{
+ $REFCOUNTS_LOADED = 1;
+
+ my $myname, $mydir, $myext;
+ ($myname, $mydir, $myext) = fileparse(__FILE__, '\..*');
+ chop $mydir; # remove trailing '/'
+ ($myname, $mydir, $myext) = fileparse($mydir, '\..*');
+ chop $mydir; # remove trailing '/'
+ $mydir = getcwd() . "$dd$mydir"
+ unless $mydir =~ s|^/|/|;
+ local $_;
+ my $filename = "$mydir${dd}api${dd}refcounts.dat";
+ open(REFCOUNT_FILE, "<$filename") || die "\n$!\n";
+ print "[loading API refcount data]";
+ while (<REFCOUNT_FILE>) {
+ if (/([a-zA-Z0-9_]+):PyObject\*:([a-zA-Z0-9_]*):(0|[-+]1|null):(.*)$/) {
+ my($func, $param, $count, $comment) = ($1, $2, $3, $4);
+ #print "\n$func($param) --> $count";
+ $REFCOUNTS{"$func:$param"} = $count;
+ }
+ }
+}
+
+sub get_refcount{
+ my ($func, $param) = @_;
+ load_refcounts()
+ unless $REFCOUNTS_LOADED;
+ return $REFCOUNTS{"$func:$param"};
+}
+
+sub do_env_cfuncdesc{
+ local($_) = @_;
+ my $return_type = next_argument();
+ my $function_name = next_argument();
+ my $arg_list = next_argument();
+ my $idx = make_str_index_entry(
+ "<tt class='cfunction'>$function_name()</tt>" . get_indexsubitem());
+ $idx =~ s/ \(.*\)//;
+ $idx =~ s/\(\)//; # ???? - why both of these?
+ my $result_rc = get_refcount($function_name, '');
+ my $rcinfo = '';
+ if ($result_rc eq '+1') {
+ $rcinfo = 'New reference';
+ }
+ elsif ($result_rc eq '0') {
+ $rcinfo = 'Borrowed reference';
+ }
+ elsif ($result_rc eq 'null') {
+ $rcinfo = 'Always <tt class="constant">NULL</tt>';
+ }
+ if ($rcinfo ne '') {
+ $rcinfo = ( "\n<div class=\"refcount-info\">"
+ . "\n <span class=\"label\">Return value:</span>"
+ . "\n <span class=\"value\">$rcinfo.</span>"
+ . "\n</div>");
+ }
+ return "<dl><dt>$return_type <b>$idx</b>(<var>$arg_list</var>)\n<dd>"
+ . $rcinfo
+ . $_
+ . '</dl>';
+}
+
+sub do_env_csimplemacrodesc{
+ local($_) = @_;
+ my $name = next_argument();
+ my $idx = make_str_index_entry("<tt class='macro'>$name</tt>");
+ return "<dl><dt><b>$idx</b>\n<dd>"
+ . $_
+ . '</dl>'
+}
+
+sub do_env_ctypedesc{
+ local($_) = @_;
+ my $index_name = next_optional_argument();
+ my $type_name = next_argument();
+ $index_name = $type_name
+ unless $index_name;
+ my($name,$aname,$ahref) = new_link_info();
+ add_index_entry("<tt class='ctype'>$index_name</tt> (C type)", $ahref);
+ return "<dl><dt><b><tt class='ctype'>$aname$type_name</a></tt></b>\n<dd>"
+ . $_
+ . '</dl>'
+}
+
+sub do_env_cvardesc{
+ local($_) = @_;
+ my $var_type = next_argument();
+ my $var_name = next_argument();
+ my $idx = make_str_index_entry("<tt class='cdata'>$var_name</tt>"
+ . get_indexsubitem());
+ $idx =~ s/ \(.*\)//;
+ return "<dl><dt>$var_type <b>$idx</b>\n"
+ . '<dd>'
+ . $_
+ . '</dl>';
+}
+
+sub convert_args($){
+ local($IN_DESC_HANDLER) = 1;
+ local($_) = @_;
+ return translate_commands($_);
+}
+
+sub do_env_funcdesc{
+ local($_) = @_;
+ my $function_name = next_argument();
+ my $arg_list = convert_args(next_argument());
+ my $idx = make_str_index_entry("<tt class='function'>$function_name()</tt>"
+ . get_indexsubitem());
+ $idx =~ s/ \(.*\)//;
+ $idx =~ s/\(\)<\/tt>/<\/tt>/;
+ return "<dl><dt><b>$idx</b>(<var>$arg_list</var>)\n<dd>" . $_ . '</dl>';
+}
+
+sub do_env_funcdescni{
+ local($_) = @_;
+ my $function_name = next_argument();
+ my $arg_list = convert_args(next_argument());
+ return "<dl><dt><b><tt class='function'>$function_name</tt></b>"
+ . "(<var>$arg_list</var>)\n"
+ . '<dd>'
+ . $_
+ . '</dl>';
+}
+
+sub do_cmd_funcline{
+ local($_) = @_;
+ my $function_name = next_argument();
+ my $arg_list = convert_args(next_argument());
+ my $prefix = "<tt class='function'>$function_name()</tt>";
+ my $idx = make_str_index_entry($prefix . get_indexsubitem());
+ $prefix =~ s/\(\)//;
+
+ return "<dt><b>$prefix</b>(<var>$arg_list</var>)\n<dd>" . $_;
+}
+
+sub do_cmd_funclineni{
+ local($_) = @_;
+ my $function_name = next_argument();
+ my $arg_list = convert_args(next_argument());
+ my $prefix = "<tt class='function'>$function_name</tt>";
+
+ return "<dt><b>$prefix</b>(<var>$arg_list</var>)\n<dd>" . $_;
+}
+
+# Change this flag to index the opcode entries. I don't think it's very
+# useful to index them, since they're only presented to describe the dis
+# module.
+#
+$INDEX_OPCODES = 0;
+
+sub do_env_opcodedesc{
+ local($_) = @_;
+ my $opcode_name = next_argument();
+ my $arg_list = next_argument();
+ my $idx;
+ if ($INDEX_OPCODES) {
+ $idx = make_str_index_entry("<tt class='opcode'>$opcode_name</tt>"
+ . " (byte code instruction)");
+ $idx =~ s/ \(byte code instruction\)//;
+ }
+ else {
+ $idx = "<tt class='opcode'>$opcode_name</tt>";
+ }
+ my $stuff = "<dl><dt><b>$idx</b>";
+ if ($arg_list) {
+ $stuff .= " <var>$arg_list</var>";
+ }
+ return $stuff . "\n<dd>" . $_ . '</dl>';
+}
+
+sub do_env_datadesc{
+ local($_) = @_;
+ my $dataname = next_argument();
+ my $idx = make_str_index_entry("<tt>$dataname</tt>" . get_indexsubitem());
+ $idx =~ s/ \(.*\)//;
+ return "<dl><dt><b>$idx</b>\n<dd>"
+ . $_
+ . '</dl>';
+}
+
+sub do_env_datadescni{
+ local($_) = @_;
+ my $idx = next_argument();
+ if (! $STRING_INDEX_TT) {
+ $idx = "<tt>$idx</tt>";
+ }
+ return "<dl><dt><b>$idx</b>\n<dd>" . $_ . '</dl>';
+}
+
+sub do_cmd_dataline{
+ local($_) = @_;
+ my $data_name = next_argument();
+ my $idx = make_str_index_entry("<tt>$data_name</tt>" . get_indexsubitem());
+ $idx =~ s/ \(.*\)//;
+ return "<dt><b>$idx</b><dd>" . $_;
+}
+
+sub do_cmd_datalineni{
+ local($_) = @_;
+ my $data_name = next_argument();
+ return "<dt><b><tt>$data_name</tt></b><dd>" . $_;
+}
+
+sub do_env_excdesc{
+ local($_) = @_;
+ my $excname = next_argument();
+ my $idx = make_str_index_entry("<tt class='exception'>$excname</tt>");
+ return "<dl><dt><b>exception $idx</b>\n<dd>" . $_ . '</dl>'
+}
+
+sub do_env_fulllineitems{ return do_env_itemize(@_); }
+
+
+sub handle_classlike_descriptor{
+ local($_, $what) = @_;
+ $THIS_CLASS = next_argument();
+ my $arg_list = convert_args(next_argument());
+ $idx = make_str_index_entry(
+ "<tt class='$what'>$THIS_CLASS</tt> ($what in $THIS_MODULE)" );
+ $idx =~ s/ \(.*\)//;
+ return ("<dl><dt><b>$what $idx</b>(<var>$arg_list</var>)\n<dd>"
+ . $_
+ . '</dl>');
+}
+
+sub do_env_classdesc{
+ return handle_classlike_descriptor(@_[0], "class");
+}
+
+sub do_env_excclassdesc{
+ return handle_classlike_descriptor(@_[0], "exception");
+}
+
+
+sub do_env_methoddesc{
+ local($_) = @_;
+ my $class_name = next_optional_argument();
+ $class_name = $THIS_CLASS
+ unless $class_name;
+ my $method = next_argument();
+ my $arg_list = convert_args(next_argument());
+ my $extra = '';
+ if ($class_name) {
+ $extra = " ($class_name method)";
+ }
+ my $idx = make_str_index_entry("<tt class='method'>$method()</tt>$extra");
+ $idx =~ s/ \(.*\)//;
+ $idx =~ s/\(\)//;
+ return "<dl><dt><b>$idx</b>(<var>$arg_list</var>)\n<dd>" . $_ . '</dl>';
+}
+
+
+sub do_cmd_methodline{
+ local($_) = @_;
+ my $class_name = next_optional_argument();
+ $class_name = $THIS_CLASS
+ unless $class_name;
+ my $method = next_argument();
+ my $arg_list = convert_args(next_argument());
+ my $extra = '';
+ if ($class_name) {
+ $extra = " ($class_name method)";
+ }
+ my $idx = make_str_index_entry("<tt class='method'>$method()</tt>$extra");
+ $idx =~ s/ \(.*\)//;
+ $idx =~ s/\(\)//;
+ return "<dt><b>$idx</b>(<var>$arg_list</var>)\n<dd>"
+ . $_;
+}
+
+
+sub do_cmd_methodlineni{
+ local($_) = @_;
+ next_optional_argument();
+ my $method = next_argument();
+ my $arg_list = convert_args(next_argument());
+ return "<dt><b>$method</b>(<var>$arg_list</var>)\n<dd>"
+ . $_;
+}
+
+sub do_env_methoddescni{
+ local($_) = @_;
+ next_optional_argument();
+ my $method = next_argument();
+ my $arg_list = convert_args(next_argument());
+ return "<dl><dt><b>$method</b>(<var>$arg_list</var>)\n<dd>"
+ . $_
+ . '</dl>';
+}
+
+
+sub do_env_memberdesc{
+ local($_) = @_;
+ my $class = next_optional_argument();
+ my $member = next_argument();
+ $class = $THIS_CLASS
+ unless $class;
+ my $extra = '';
+ $extra = " ($class attribute)"
+ if ($class ne '');
+ my $idx = make_str_index_entry("<tt class='member'>$member</tt>$extra");
+ $idx =~ s/ \(.*\)//;
+ $idx =~ s/\(\)//;
+ return "<dl><dt><b>$idx</b>\n<dd>" . $_ . '</dl>';
+}
+
+
+sub do_cmd_memberline{
+ local($_) = @_;
+ my $class = next_optional_argument();
+ my $member = next_argument();
+ $class = $THIS_CLASS
+ unless $class;
+ my $extra = '';
+ $extra = " ($class attribute)"
+ if ($class ne '');
+ my $idx = make_str_index_entry("<tt class='member'>$member</tt>$extra");
+ $idx =~ s/ \(.*\)//;
+ $idx =~ s/\(\)//;
+ return "<dt><b>$idx</b><dd>" . $_;
+}
+
+sub do_env_memberdescni{
+ local($_) = @_;
+ next_optional_argument();
+ my $member = next_argument();
+ return "<dl><dt><b><tt class='member'>$member</tt></b>\n<dd>"
+ . $_
+ . '</dl>';
+}
+
+
+sub do_cmd_memberlineni{
+ local($_) = @_;
+ next_optional_argument();
+ my $member = next_argument();
+ return "<dt><b><tt class='member'>$member</tt></b><dd>" . $_;
+}
+
+@col_aligns = ('<td>', '<td>', '<td>', '<td>');
+
+sub fix_font{
+ # do a little magic on a font name to get the right behavior in the first
+ # column of the output table
+ my $font = @_[0];
+ if ($font eq 'textrm') {
+ $font = '';
+ }
+ elsif ($font eq 'file' || $font eq 'filenq') {
+ $font = 'tt class="file"';
+ }
+ elsif ($font eq 'member') {
+ $font = 'tt class="member"';
+ }
+ elsif ($font eq 'class') {
+ $font = 'tt class="class"';
+ }
+ elsif ($font eq 'constant') {
+ $font = 'tt class="constant"';
+ }
+ elsif ($font eq 'kbd') {
+ $font = 'kbd';
+ }
+ elsif ($font eq 'programopt') {
+ $font = 'b';
+ }
+ elsif ($font eq 'exception') {
+ $font = 'tt class="exception"';
+ }
+ return $font;
+}
+
+sub figure_column_alignment{
+ my $a = @_[0];
+ my $mark = substr($a, 0, 1);
+ my $r = '';
+ if ($mark eq 'c')
+ { $r = ' align="center"'; }
+ elsif ($mark eq 'r')
+ { $r = ' align="right"'; }
+ elsif ($mark eq 'l')
+ { $r = ' align="left"'; }
+ elsif ($mark eq 'p')
+ { $r = ' align="left"'; }
+ return $r;
+}
+
+sub setup_column_alignments{
+ local($_) = @_;
+ my($s1,$s2,$s3,$s4) = split(/[|]/,$_);
+ my $a1 = figure_column_alignment($s1);
+ my $a2 = figure_column_alignment($s2);
+ my $a3 = figure_column_alignment($s3);
+ my $a4 = figure_column_alignment($s4);
+ $col_aligns[0] = "<td$a1 valign=\"baseline\">";
+ $col_aligns[1] = "<td$a2>";
+ $col_aligns[2] = "<td$a3>";
+ $col_aligns[3] = "<td$a4>";
+ # return the aligned header start tags
+ return ("<th$a1>", "<th$a2>", "<th$a3>", "<th$a4>");
+}
+
+sub get_table_col1_fonts{
+ my $font = $globals{'lineifont'};
+ my ($sfont,$efont) = ('', '');
+ if ($font) {
+ $sfont = "<$font>";
+ $efont = "</$font>";
+ $efont =~ s/ .*>/>/;
+ }
+ return ($sfont, $efont);
+}
+
+sub do_env_tableii{
+ local($_) = @_;
+ my($th1,$th2,$th3,$th4) = setup_column_alignments(next_argument());
+ my $font = fix_font(next_argument());
+ my $h1 = next_argument();
+ my $h2 = next_argument();
+ s/[\s\n]+//;
+ $globals{'lineifont'} = $font;
+ my $a1 = $col_aligns[0];
+ my $a2 = $col_aligns[1];
+ s/\\lineii</\\lineii[$a1|$a2]</g;
+ return '<table border align="center" style="border-collapse: collapse">'
+ . "\n <thead>"
+ . "\n <tr class=\"tableheader\">"
+ . "\n $th1<b>$h1</b>\ </th>"
+ . "\n $th2<b>$h2</b>\ </th>"
+ . "\n </tr>"
+ . "\n </thead>"
+ . "\n <tbody valign='baseline'>"
+ . $_
+ . "\n </tbody>"
+ . "\n</table>";
+}
+
+sub do_env_longtableii{
+ return do_env_tableii(@_);
+}
+
+sub do_cmd_lineii{
+ local($_) = @_;
+ my $aligns = next_optional_argument();
+ my $c1 = next_argument();
+ my $c2 = next_argument();
+ s/[\s\n]+//;
+ my($sfont,$efont) = get_table_col1_fonts();
+ $c2 = ' ' if ($c2 eq '');
+ my($c1align,$c2align) = split('\|', $aligns);
+ my $padding = '';
+ if ($c1align =~ /align="right"/ || $c1 eq '') {
+ $padding = ' ';
+ }
+ return "\n <tr>$c1align$sfont$c1$efont$padding</td>\n"
+ . " $c2align$c2</td>"
+ . $_;
+}
+
+sub do_env_tableiii{
+ local($_) = @_;
+ my($th1,$th2,$th3,$th4) = setup_column_alignments(next_argument());
+ my $font = fix_font(next_argument());
+ my $h1 = next_argument();
+ my $h2 = next_argument();
+ my $h3 = next_argument();
+ s/[\s\n]+//;
+ $globals{'lineifont'} = $font;
+ my $a1 = $col_aligns[0];
+ my $a2 = $col_aligns[1];
+ my $a3 = $col_aligns[2];
+ s/\\lineiii</\\lineiii[$a1|$a2|$a3]</g;
+ return '<table border align="center" style="border-collapse: collapse">'
+ . "\n <thead>"
+ . "\n <tr class=\"tableheader\">"
+ . "\n $th1<b>$h1</b>\ </th>"
+ . "\n $th2<b>$h2</b>\ </th>"
+ . "\n $th3<b>$h3</b>\ </th>"
+ . "\n </tr>"
+ . "\n </thead>"
+ . "\n <tbody valign='baseline'>"
+ . $_
+ . "\n </tbody>"
+ . "\n</table>";
+}
+
+sub do_env_longtableiii{
+ return do_env_tableiii(@_);
+}
+
+sub do_cmd_lineiii{
+ local($_) = @_;
+ my $aligns = next_optional_argument();
+ my $c1 = next_argument();
+ my $c2 = next_argument();
+ my $c3 = next_argument();
+ s/[\s\n]+//;
+ my($sfont,$efont) = get_table_col1_fonts();
+ $c3 = ' ' if ($c3 eq '');
+ my($c1align,$c2align,$c3align) = split('\|', $aligns);
+ my $padding = '';
+ if ($c1align =~ /align="right"/ || $c1 eq '') {
+ $padding = ' ';
+ }
+ return "\n <tr>$c1align$sfont$c1$efont$padding</td>\n"
+ . " $c2align$c2</td>\n"
+ . " $c3align$c3</td>"
+ . $_;
+}
+
+sub do_env_tableiv{
+ local($_) = @_;
+ my($th1,$th2,$th3,$th4) = setup_column_alignments(next_argument());
+ my $font = fix_font(next_argument());
+ my $h1 = next_argument();
+ my $h2 = next_argument();
+ my $h3 = next_argument();
+ my $h4 = next_argument();
+ s/[\s\n]+//;
+ $globals{'lineifont'} = $font;
+ my $a1 = $col_aligns[0];
+ my $a2 = $col_aligns[1];
+ my $a3 = $col_aligns[2];
+ my $a4 = $col_aligns[3];
+ s/\\lineiv</\\lineiv[$a1|$a2|$a3|$a4]</g;
+ return '<table border align="center" style="border-collapse: collapse">'
+ . "\n <thead>"
+ . "\n <tr class=\"tableheader\">"
+ . "\n $th1<b>$h1</b>\ </th>"
+ . "\n $th2<b>$h2</b>\ </th>"
+ . "\n $th3<b>$h3</b>\ </th>"
+ . "\n $th4<b>$h4</b>\ </th>"
+ . "\n </tr>"
+ . "\n </thead>"
+ . "\n <tbody valign='baseline'>"
+ . $_
+ . "\n </tbody>"
+ . "\n</table>";
+}
+
+sub do_env_longtableiv{
+ return do_env_tableiv(@_);
+}
+
+sub do_cmd_lineiv{
+ local($_) = @_;
+ my $aligns = next_optional_argument();
+ my $c1 = next_argument();
+ my $c2 = next_argument();
+ my $c3 = next_argument();
+ my $c4 = next_argument();
+ s/[\s\n]+//;
+ my($sfont,$efont) = get_table_col1_fonts();
+ $c4 = ' ' if ($c4 eq '');
+ my($c1align,$c2align,$c3align,$c4align) = split('\|', $aligns);
+ my $padding = '';
+ if ($c1align =~ /align="right"/ || $c1 eq '') {
+ $padding = ' ';
+ }
+ return "\n <tr>$c1align$sfont$c1$efont$padding</td>\n"
+ . " $c2align$c2</td>\n"
+ . " $c3align$c3</td>\n"
+ . " $c4align$c4</td>"
+ . $_;
+}
+
+
+# These can be used to control the title page appearance;
+# they need a little bit of documentation.
+#
+# If $TITLE_PAGE_GRAPHIC is set, it should be the name of a file in the
+# $ICONSERVER directory, or include path information (other than "./"). The
+# default image type will be assumed if an extension is not provided.
+#
+# If specified, the "title page" will contain two colums: one containing the
+# title/author/etc., and the other containing the graphic. Use the other
+# four variables listed here to control specific details of the layout; all
+# are optional.
+#
+# $TITLE_PAGE_GRAPHIC = "my-company-logo";
+# $TITLE_PAGE_GRAPHIC_COLWIDTH = "30%";
+# $TITLE_PAGE_GRAPHIC_WIDTH = 150;
+# $TITLE_PAGE_GRAPHIC_HEIGHT = 150;
+# $TITLE_PAGE_GRAPHIC_ON_RIGHT = 0;
+
+sub make_my_titlepage() {
+ my $the_title = "";
+ if ($t_title) {
+ $the_title .= "\n<h1>$t_title</h1>";
+ }
+ else {
+ write_warnings("\nThis document has no title.");
+ }
+ if ($t_author) {
+ if ($t_authorURL) {
+ my $href = translate_commands($t_authorURL);
+ $href = make_named_href('author', $href,
+ "<b><font size='+2'>$t_author</font></b>");
+ $the_title .= "\n<p>$href</p>";
+ }
+ else {
+ $the_title .= ("\n<p><b><font size='+2'>$t_author</font></b></p>");
+ }
+ }
+ else {
+ write_warnings("\nThere is no author for this document.");
+ }
+ if ($t_institute) {
+ $the_title .= "\n<p>$t_institute</p>";
+ }
+ if ($DEVELOPER_ADDRESS) {
+ $the_title .= "\n<p>$DEVELOPER_ADDRESS</p>";
+ }
+ if ($t_affil) {
+ $the_title .= "\n<p><i>$t_affil</i></p>";
+ }
+ if ($t_date) {
+ $the_title .= "\n<p>";
+ if ($PACKAGE_VERSION) {
+ $the_title .= "<strong>Release $PACKAGE_VERSION</strong><br>\n";
+ }
+ $the_title .= "<strong>$t_date</strong></p>"
+ }
+ if ($t_address) {
+ $the_title .= "\n<p>$t_address</p>";
+ }
+ else {
+ $the_title .= "\n<p>";
+ }
+ if ($t_email) {
+ $the_title .= "\n<p>$t_email</p>";
+ }
+ return $the_title;
+}
+
+sub make_my_titlegraphic() {
+ my $filename = make_icon_filename($TITLE_PAGE_GRAPHIC);
+ my $graphic = "<td class=\"titlegraphic\"";
+ $graphic .= " width=\"$TITLE_PAGE_GRAPHIC_COLWIDTH\""
+ if ($TITLE_PAGE_GRAPHIC_COLWIDTH);
+ $graphic .= "><img";
+ $graphic .= " width=\"$TITLE_PAGE_GRAPHIC_WIDTH\""
+ if ($TITLE_PAGE_GRAPHIC_WIDTH);
+ $graphic .= " height=\"$TITLE_PAGE_GRAPHIC_HEIGHT\""
+ if ($TITLE_PAGE_GRAPHIC_HEIGHT);
+ $graphic .= "\n src=\"$filename\"></td>\n";
+ return $graphic;
+}
+
+sub do_cmd_maketitle {
+ local($_) = @_;
+ my $the_title = "\n<div class=\"titlepage\">";
+ if ($TITLE_PAGE_GRAPHIC) {
+ if ($TITLE_PAGE_GRAPHIC_ON_RIGHT) {
+ $the_title .= ("\n<table border=\"0\" width=\"100%\">"
+ . "<tr align=\"right\">\n<td>"
+ . make_my_titlepage()
+ . "</td>\n"
+ . make_my_titlegraphic()
+ . "</tr>\n</table>");
+ }
+ else {
+ $the_title .= ("\n<table border=\"0\" width=\"100%\"><tr>\n"
+ . make_my_titlegraphic()
+ . "<td>"
+ . make_my_titlepage()
+ . "</td></tr>\n</table>");
+ }
+ }
+ else {
+ $the_title .= ("\n<center>"
+ . make_my_titlepage()
+ . "\n</center>");
+ }
+ $the_title .= "\n</div>";
+ return $the_title . $_;
+ $the_title .= "\n</center></div>";
+ return $the_title . $_ ;
+}
+
+
+#
+# Module synopsis support
+#
+
+require SynopsisTable;
+
+sub get_chapter_id(){
+ my $id = do_cmd_thechapter('');
+ $id =~ s/<SPAN CLASS="arabic">(\d+)<\/SPAN>/\1/;
+ $id =~ s/\.//;
+ return $id;
+}
+
+# 'chapter' => 'SynopsisTable instance'
+%ModuleSynopses = ();
+
+sub get_synopsis_table($){
+ my($chap) = @_;
+ my $key;
+ foreach $key (keys %ModuleSynopses) {
+ if ($key eq $chap) {
+ return $ModuleSynopses{$chap};
+ }
+ }
+ my $st = SynopsisTable->new();
+ $ModuleSynopses{$chap} = $st;
+ return $st;
+}
+
+sub do_cmd_moduleauthor{
+ local($_) = @_;
+ next_argument();
+ next_argument();
+ return $_;
+}
+
+sub do_cmd_sectionauthor{
+ local($_) = @_;
+ next_argument();
+ next_argument();
+ return $_;
+}
+
+sub do_cmd_declaremodule{
+ local($_) = @_;
+ my $key = next_optional_argument();
+ my $type = next_argument();
+ my $name = next_argument();
+ my $st = get_synopsis_table(get_chapter_id());
+ #
+ $key = $name unless $key;
+ $type = 'built-in' if $type eq 'builtin';
+ $st->declare($name, $key, $type);
+ define_module($type, $name);
+ return anchor_label("module-$key",$CURRENT_FILE,$_)
+}
+
+sub do_cmd_modulesynopsis{
+ local($_) = @_;
+ my $st = get_synopsis_table(get_chapter_id());
+ $st->set_synopsis($THIS_MODULE, translate_commands(next_argument()));
+ return $_;
+}
+
+sub do_cmd_localmoduletable{
+ local($_) = @_;
+ my $chap = get_chapter_id();
+ my $st = get_synopsis_table($chap);
+ $st->set_file("$CURRENT_FILE");
+ return "<tex2html-localmoduletable><$chap>\\tableofchildlinks[off]" . $_;
+}
+
+sub process_all_localmoduletables{
+ my $key;
+ my $st, $file;
+ foreach $key (keys %ModuleSynopses) {
+ $st = $ModuleSynopses{$key};
+ $file = $st->get_file();
+ if ($file) {
+ process_localmoduletables_in_file($file);
+ }
+ else {
+ print "\nsynopsis table $key has no file association";
+ }
+ }
+}
+
+sub process_localmoduletables_in_file{
+ my $file = @_[0];
+ open(MYFILE, "<$file");
+ local($_);
+ sysread(MYFILE, $_, 1024*1024);
+ close(MYFILE);
+ # need to get contents of file in $_
+ while (/<tex2html-localmoduletable><(\d+)>/) {
+ my $match = $&;
+ my $chap = $1;
+ my $st = get_synopsis_table($chap);
+ my $data = $st->tohtml();
+ s/$match/$data/;
+ }
+ open(MYFILE,">$file");
+ print MYFILE $_;
+ close(MYFILE);
+}
+sub process_python_state{
+ process_all_localmoduletables();
+}
+
+
+#
+# "See also:" -- references placed at the end of a \section
+#
+
+sub do_env_seealso{
+ return "<div class='seealso'>\n "
+ . "<p class='heading'><b>See Also:</b></p>\n"
+ . @_[0]
+ . '</div>';
+}
+
+sub do_cmd_seemodule{
+ # Insert the right magic to jump to the module definition. This should
+ # work most of the time, at least for repeat builds....
+ local($_) = @_;
+ my $key = next_optional_argument();
+ my $module = next_argument();
+ my $text = next_argument();
+ my $period = '.';
+ $key = $module
+ unless $key;
+ if ($text =~ /\.$/) {
+ $period = '';
+ }
+ return '<dl compact class="seemodule">'
+ . "\n <dt>Module <b><tt class='module'><a href='module-$key.html'>"
+ . "$module</a></tt>:</b>"
+ . "\n <dd>$text$period\n </dl>"
+ . $_;
+}
+
+sub strip_html_markup($){
+ my $str = @_[0];
+ my $s = "$str";
+ $s =~ s/<[a-zA-Z0-9]+(\s+[a-zA-Z0-9]+(\s*=\s*(\'[^\']*\'|\"[^\"]*\"|[a-zA-Z0-9]+))?)*\s*>//g;
+ $s =~ s/<\/[a-zA-Z0-9]+>//g;
+ return $s;
+}
+
+sub handle_rfclike_reference{
+ local($_, $what, $format) = @_;
+ my $rfcnum = next_argument();
+ my $title = next_argument();
+ my $text = next_argument();
+ my $url = get_rfc_url($rfcnum, $format);
+ my $icon = get_link_icon($url);
+ my $attrtitle = strip_html_markup($title);
+ return '<dl compact class="seerfc">'
+ . "\n <dt><a href=\"$url\""
+ . "\n title=\"$attrtitle\""
+ . "\n >$what $rfcnum, <em>$title</em>$icon</a>"
+ . "\n <dd>$text\n </dl>"
+ . $_;
+}
+
+sub do_cmd_seepep{
+ return handle_rfclike_reference(@_[0], "PEP", $PEP_FORMAT);
+}
+
+sub do_cmd_seerfc{
+ return handle_rfclike_reference(@_[0], "RFC", $RFC_FORMAT);
+}
+
+sub do_cmd_seetitle{
+ local($_) = @_;
+ my $url = next_optional_argument();
+ my $title = next_argument();
+ my $text = next_argument();
+ if ($url) {
+ my $icon = get_link_icon($url);
+ return '<dl compact class="seetitle">'
+ . "\n <dt><em class=\"citetitle\"><a href=\"$url\""
+ . "\n >$title$icon</a></em>"
+ . "\n <dd>$text\n </dl>"
+ . $_;
+ }
+ return '<dl compact class="seetitle">'
+ . "\n <dt><em class=\"citetitle\""
+ . "\n >$title</em>"
+ . "\n <dd>$text\n </dl>"
+ . $_;
+}
+
+sub do_cmd_seeurl{
+ local($_) = @_;
+ my $url = next_argument();
+ my $text = next_argument();
+ my $icon = get_link_icon($url);
+ return '<dl compact class="seeurl">'
+ . "\n <dt><a href=\"$url\""
+ . "\n class=\"url\">$url$icon</a>"
+ . "\n <dd>$text\n </dl>"
+ . $_;
+}
+
+sub do_cmd_seetext{
+ local($_) = @_;
+ my $content = next_argument();
+ return '<div class="seetext"><p>' . $content . '</div>' . $_;
+}
+
+
+#
+# Definition list support.
+#
+
+sub do_env_definitions{
+ return "<dl class='definitions'>" . @_[0] . "</dl>\n";
+}
+
+sub do_cmd_term{
+ local($_) = @_;
+ my $term = next_argument();
+ my($name,$aname,$ahref) = new_link_info();
+ # could easily add an index entry here...
+ return "<dt><b>$aname" . $term . "</a></b>\n<dd>" . $_;
+}
+
+
+# I don't recall exactly why this was needed, but it was very much needed.
+# We'll see if anything breaks when I move the "code" line out -- some
+# things broke with it in.
+
+#code # {}
+process_commands_wrap_deferred(<<_RAW_ARG_DEFERRED_CMDS_);
+declaremodule # [] # {} # {}
+memberline # [] # {}
+methodline # [] # {} # {}
+modulesynopsis # {}
+platform # {}
+samp # {}
+setindexsubitem # {}
+withsubitem # {} # {}
+_RAW_ARG_DEFERRED_CMDS_
+
+
+$alltt_start = '<dl><dd><pre class="verbatim">';
+$alltt_end = '</pre></dl>';
+
+sub do_env_alltt {
+ local ($_) = @_;
+ local($closures,$reopens,@open_block_tags);
+
+ # get the tag-strings for all open tags
+ local(@keep_open_tags) = @$open_tags_R;
+ ($closures,$reopens) = &preserve_open_tags() if (@$open_tags_R);
+
+ # get the tags for text-level tags only
+ $open_tags_R = [ @keep_open_tags ];
+ local($local_closures, $local_reopens);
+ ($local_closures, $local_reopens,@open_block_tags)
+ = &preserve_open_block_tags
+ if (@$open_tags_R);
+
+ $open_tags_R = [ @open_block_tags ];
+
+ do {
+ local($open_tags_R) = [ @open_block_tags ];
+ local(@save_open_tags) = ();
+
+ local($cnt) = ++$global{'max_id'};
+ $_ = join('',"$O$cnt$C\\tt$O", ++$global{'max_id'}, $C
+ , $_ , $O, $global{'max_id'}, "$C$O$cnt$C");
+
+ $_ = &translate_environments($_);
+ $_ = &translate_commands($_) if (/\\/);
+
+ # preserve space-runs, using
+ while (s/(\S) ( +)/$1$2;SPMnbsp;/g){};
+ s/(<BR>) /$1;SPMnbsp;/g;
+
+ $_ = join('', $closures, $alltt_start, $local_reopens
+ , $_
+ , &balance_tags() #, $local_closures
+ , $alltt_end, $reopens);
+ undef $open_tags_R; undef @save_open_tags;
+ };
+ $open_tags_R = [ @keep_open_tags ];
+ $_;
+}
+
+
+1; # This must be the last line
diff --git a/doc/tools/push-docs.sh b/doc/tools/push-docs.sh
new file mode 100755
index 0000000..c227bcf
--- /dev/null
+++ b/doc/tools/push-docs.sh
@@ -0,0 +1,42 @@
+#! /bin/sh
+
+# Script to push docs from my development area to SourceForge, where the
+# update-docs.sh script unpacks them into their final destination.
+
+TARGET=python.sourceforge.net:/home/users/fdrake/tmp
+
+ADDRESSES='python-dev@python.org doc-sig@python.org python-list@python.org'
+
+EXPLANATION=''
+
+if [ "$1" = '-m' ] ; then
+ EXPLANATION="$2"
+ shift 2
+elif [ "$1" ] ; then
+ EXPLANATION="`cat $1`"
+ shift 1
+fi
+
+START="`pwd`"
+MYDIR="`dirname $0`"
+cd "$MYDIR"
+MYDIR="`pwd`"
+
+cd ..
+
+# now in .../Doc/
+make --no-print-directory || exit $?
+make --no-print-directory bziphtml || exit $?
+RELEASE=`grep '^RELEASE=' Makefile | sed 's|RELEASE=||'`
+PACKAGE="html-$RELEASE.tar.bz2"
+scp "$PACKAGE" tools/update-docs.sh $TARGET/ || exit $?
+ssh python.sourceforge.net tmp/update-docs.sh $PACKAGE '&&' rm tmp/update-docs.sh || exit $?
+
+Mail -s '[development doc updates]' $ADDRESSES <<EOF
+The development version of the documentation has been updated:
+
+ http://python.sourceforge.net/devel-docs/
+
+$EXPLANATION
+EOF
+exit $?
diff --git a/doc/tools/refcounts.py b/doc/tools/refcounts.py
new file mode 100644
index 0000000..d1c9007
--- /dev/null
+++ b/doc/tools/refcounts.py
@@ -0,0 +1,97 @@
+"""Support functions for loading the reference count data file."""
+__version__ = '$Revision: 1.1.1.1 $'
+
+import os
+import string
+import sys
+
+
+# Determine the expected location of the reference count file:
+try:
+ p = os.path.dirname(__file__)
+except NameError:
+ p = sys.path[0]
+p = os.path.normpath(os.path.join(os.getcwd(), p, os.pardir,
+ "api", "refcounts.dat"))
+DEFAULT_PATH = p
+del p
+
+
+def load(path=DEFAULT_PATH):
+ return loadfile(open(path))
+
+
+def loadfile(fp):
+ d = {}
+ while 1:
+ line = fp.readline()
+ if not line:
+ break
+ line = string.strip(line)
+ if line[:1] in ("", "#"):
+ # blank lines and comments
+ continue
+ parts = string.split(line, ":", 4)
+ function, type, arg, refcount, comment = parts
+ if refcount == "null":
+ refcount = None
+ elif refcount:
+ refcount = int(refcount)
+ else:
+ refcount = None
+ #
+ # Get the entry, creating it if needed:
+ #
+ try:
+ entry = d[function]
+ except KeyError:
+ entry = d[function] = Entry(function)
+ #
+ # Update the entry with the new parameter or the result information.
+ #
+ if arg:
+ entry.args.append((arg, type, refcount))
+ else:
+ entry.result_type = type
+ entry.result_refs = refcount
+ return d
+
+
+class Entry:
+ def __init__(self, name):
+ self.name = name
+ self.args = []
+ self.result_type = ''
+ self.result_refs = None
+
+
+def dump(d):
+ """Dump the data in the 'canonical' format, with functions in
+ sorted order."""
+ items = d.items()
+ items.sort()
+ first = 1
+ for k, entry in items:
+ if first:
+ first = 0
+ else:
+ print
+ s = entry.name + ":%s:%s:%s:"
+ if entry.result_refs is None:
+ r = ""
+ else:
+ r = entry.result_refs
+ print s % (entry.result_type, "", r)
+ for t, n, r in entry.args:
+ if r is None:
+ r = ""
+ print s % (t, n, r)
+
+
+def main():
+ d = load()
+ dump(d)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/doc/tools/sgmlconv/Makefile b/doc/tools/sgmlconv/Makefile
new file mode 100644
index 0000000..30a846e
--- /dev/null
+++ b/doc/tools/sgmlconv/Makefile
@@ -0,0 +1,67 @@
+# Simple makefile to control XML generation for the entire document tree.
+# This should be used from the top-level directory (Doc/), not the directory
+# that actually contains this file:
+#
+# $ pwd
+# .../Doc
+# $ make -f tools/sgmlconv/Makefile
+
+TOPDIR=.
+TOOLSDIR=tools
+
+SGMLRULES=../$(TOOLSDIR)/sgmlconv/make.rules
+# The 'inst' directory breaks the conversion, so skip it for now.
+SUBDIRS=api dist ext lib mac ref tut
+SUBMAKE=$(MAKE) -f $(SGMLRULES) TOOLSDIR=../$(TOOLSDIR)
+
+all: xml
+
+.PHONY: esis xml
+.PHONY: $(SUBDIRS)
+
+xml:
+ for DIR in $(SUBDIRS) ; do \
+ (cd $$DIR; $(SUBMAKE) xml) || exit $$? ; done
+
+esis:
+ for DIR in $(SUBDIRS) ; do \
+ (cd $$DIR; $(SUBMAKE) esis) || exit $$? ; done
+
+esis1:
+ for DIR in $(SUBDIRS) ; do \
+ (cd $$DIR; $(SUBMAKE) esis1) || exit $$? ; done
+
+tarball: xml
+ tar cf - tools/sgmlconv */*.xml | gzip -9 >xml-1.5.2b2.tgz
+
+api:
+ cd api; $(SUBMAKE)
+
+dist:
+ cd dist; $(SUBMAKE)
+
+ext:
+ cd ext; $(SUBMAKE)
+
+inst:
+ cd inst; $(SUBMAKE)
+
+lib:
+ cd lib; $(SUBMAKE)
+
+mac:
+ cd mac; $(SUBMAKE)
+
+ref:
+ cd ref; $(SUBMAKE)
+
+tut:
+ cd tut; $(SUBMAKE)
+
+clean:
+ for DIR in $(SUBDIRS) ; do \
+ (cd $$DIR; $(SUBMAKE) clean) ; done
+
+clobber:
+ for DIR in $(SUBDIRS) ; do \
+ (cd $$DIR; $(SUBMAKE) clobber) ; done
diff --git a/doc/tools/sgmlconv/README b/doc/tools/sgmlconv/README
new file mode 100644
index 0000000..1546293
--- /dev/null
+++ b/doc/tools/sgmlconv/README
@@ -0,0 +1,58 @@
+These scripts and Makefile fragment are used to convert the Python
+documentation in LaTeX format to XML.
+
+This material is preliminary and incomplete. Python 2.0 is required.
+
+To convert all documents to XML:
+
+ cd Doc/
+ make -f tools/sgmlconv/Makefile
+
+To convert one document to XML:
+
+ cd Doc/<document-dir>
+ make -f ../tools/sgmlconv/make.rules TOOLSDIR=../tools
+
+Please send comments and bug reports to python-docs@python.org.
+
+
+What do the tools do?
+---------------------
+
+latex2esis.py
+ Reads in a conversion specification written in XML
+ (conversion.xml), reads a LaTeX document fragment, and interprets
+ the markup according to the specification. The output is a stream
+ of ESIS events like those created by the nsgmls SGML parser, but
+ is *not* guaranteed to represent a single tree! This is done to
+ allow conversion per entity rather than per document. Since many
+ of the LaTeX files for the Python documentation contain two
+ sections on closely related modules, it is important to allow both
+ of the resulting <section> elements to exist in the same output
+ stream. Additionally, since comments are not supported in ESIS,
+ comments are converted to <COMMENT> elements, which might exist at
+ the same level as the top-level content elements.
+
+ The output of latex2esis.py gets saved as <filename>.esis1.
+
+docfixer.py
+ This is the really painful part of the conversion. Well, it's the
+ second really painful part, but more of the pain is specific to
+ the structure of the Python documentation and desired output
+ rather than to the parsing of LaTeX markup.
+
+ This script loads the ESIS data created by latex2esis.py into a
+ DOM document *fragment* (remember, the latex2esis.py output may
+ not be well-formed). Once loaded, it walks over the tree many
+ times looking for a variety of possible specific
+ micro-conversions. Most of the code is not in any way "general".
+ After processing the fragment, a new ESIS data stream is written
+ out. Like the input, it may not represent a well-formed
+ document, but does represent a parsed entity.
+
+ The output of docfixer.py is what gets saved in <filename>.esis.
+
+esis2sgml.py
+ Reads an ESIS stream and convert to SGML or XML. This also
+ converts <COMMENT> elements to real comments. This works quickly
+ because there's not much to actually do.
diff --git a/doc/tools/sgmlconv/conversion.xml b/doc/tools/sgmlconv/conversion.xml
new file mode 100644
index 0000000..7759bad
--- /dev/null
+++ b/doc/tools/sgmlconv/conversion.xml
@@ -0,0 +1,757 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<conversion>
+ <!-- Miscellaneous. -->
+ <macro name="declaremodule">
+ <attribute name="id" optional="yes"/>
+ <attribute name="type"/>
+ <attribute name="name"/>
+ </macro>
+ <macro name="modulesynopsis">
+ <content/>
+ </macro>
+ <macro name="platform">
+ <content/>
+ </macro>
+ <macro name="deprecated">
+ <attribute name="version"/>
+ <content/>
+ </macro>
+ <macro name="label">
+ <attribute name="id"/>
+ </macro>
+ <macro name="nodename" outputname="label">
+ <attribute name="id"/>
+ </macro>
+ <macro name="localmoduletable"/>
+ <macro name="manpage">
+ <attribute name="name"/>
+ <attribute name="section"/>
+ </macro>
+ <macro name="module">
+ <content/>
+ </macro>
+ <macro name="moduleauthor">
+ <attribute name="name"/>
+ <attribute name="email"/>
+ </macro>
+ <macro name="citetitle">
+ <attribute name="href" optional="yes"/>
+ <content/>
+ </macro>
+ <macro name="rfc">
+ <attribute name="num"/>
+ </macro>
+ <macro name="sectionauthor" outputname="author">
+ <attribute name="name"/>
+ <attribute name="email"/>
+ </macro>
+ <macro name="author">
+ <attribute name="name"/>
+ </macro>
+ <macro name="authoraddress">
+ <content/>
+ </macro>
+ <macro name="shortversion"/>
+ <macro name="versionadded">
+ <attribute name="version"/>
+ </macro>
+ <!-- This is broken: we need to re-order the optional and required
+ parameters, making the optional parameter the content for the
+ element. The processor is not powerful enough to handle this.
+ -->
+ <macro name="versionchanged">
+ <attribute name="how" optional="yes"/>
+ <attribute name="version"/>
+ </macro>
+
+ <!-- Module referencing. -->
+ <macro name="refmodule" outputname="module">
+ <attribute name="" optional="yes"/>
+ <attribute name="link">yes</attribute>
+ <content/>
+ </macro>
+
+ <!-- Information units. -->
+ <!-- C things. -->
+ <environment name="cfuncdesc">
+ <attribute name="type"/>
+ <attribute name="name"/>
+ <child name="args"/>
+ </environment>
+ <environment name="ctypedesc">
+ <attribute name="tag" optional="yes"/>
+ <attribute name="name"/>
+ </environment>
+ <environment name="cvardesc">
+ <attribute name="type"/>
+ <attribute name="name"/>
+ </environment>
+
+ <!-- Python things. -->
+ <macro name="optional">
+ <content/>
+ </macro>
+ <macro name="unspecified"/>
+ <macro name="moreargs"/>
+ <environment name="classdesc">
+ <attribute name="name"/>
+ <child name="args"/>
+ </environment>
+ <environment name="datadesc">
+ <attribute name="name"/>
+ </environment>
+ <macro name="dataline">
+ <attribute name="name"/>
+ </macro>
+ <environment name="excdesc">
+ <attribute name="name"/>
+ </environment>
+
+ <environment name="funcdesc">
+ <attribute name="name"/>
+ <child name="args"/>
+ </environment>
+ <macro name="funcline">
+ <attribute name="name"/>
+ <child name="args"/>
+ </macro>
+ <environment name="funcdescni" outputname="funcdesc">
+ <attribute name="index">no</attribute>
+ <attribute name="name"/>
+ <child name="args"/>
+ </environment>
+ <macro name="funclineni" outputname="funcline">
+ <attribute name="index">no</attribute>
+ <attribute name="name"/>
+ <child name="args"/>
+ </macro>
+
+ <environment name="memberdesc">
+ <attribute name="class" optional="yes"/>
+ <attribute name="name"/>
+ </environment>
+ <environment name="memberdescni" outputname="memberdesc">
+ <attribute name="index">no</attribute>
+ <attribute name="class" optional="yes"/>
+ <attribute name="name"/>
+ </environment>
+
+ <environment name="methoddesc">
+ <attribute name="class" optional="yes"/>
+ <attribute name="name"/>
+ <child name="args"/>
+ </environment>
+ <macro name="methodline">
+ <attribute name="class" optional="yes"/>
+ <attribute name="name"/>
+ <child name="args"/>
+ </macro>
+ <environment name="methoddescni">
+ <attribute name="index">no</attribute>
+ <attribute name="class" optional="yes"/>
+ <attribute name="name"/>
+ <child name="args"/>
+ </environment>
+ <macro name="methodlineni" outputname="methodline">
+ <attribute name="index">no</attribute>
+ <attribute name="class" optional="yes"/>
+ <attribute name="name"/>
+ <child name="args"/>
+ </macro>
+
+ <environment name="opcodedesc">
+ <attribute name="name"/>
+ <attribute name="var"/>
+ </environment>
+
+ <!-- "See also:" sections. -->
+ <macro name="seemodule">
+ <attribute name="ref" optional="yes"/>
+ <attribute name="name"/>
+ <child name="description"/>
+ </macro>
+ <macro name="seepep">
+ <attribute name="number"/>
+ <child name="title"/>
+ <child name="description"/>
+ </macro>
+ <macro name="seerfc">
+ <attribute name="number"/>
+ <child name="title"/>
+ <child name="description"/>
+ </macro>
+ <macro name="seetext">
+ <child name="description"/>
+ </macro>
+ <macro name="seetitle">
+ <attribute name="href" optional="yes"/>
+ <child name="title"/>
+ <child name="description"/>
+ </macro>
+ <macro name="seeurl">
+ <attribute name="href"/>
+ <child name="description"/>
+ </macro>
+
+ <!-- Index-generating markup. -->
+ <macro name="index" outputname="indexterm">
+ <attribute name="term1"/>
+ </macro>
+ <macro name="indexii" outputname="indexterm">
+ <attribute name="term1"/>
+ <attribute name="term2"/>
+ </macro>
+ <macro name="indexiii" outputname="indexterm">
+ <attribute name="term1"/>
+ <attribute name="term2"/>
+ <attribute name="term3"/>
+ </macro>
+ <macro name="indexiv" outputname="indexterm">
+ <attribute name="term1"/>
+ <attribute name="term2"/>
+ <attribute name="term3"/>
+ <attribute name="term4"/>
+ </macro>
+
+ <macro name="ttindex" outputname="indexterm">
+ <attribute name="style">tt</attribute>
+ <attribute name="term1"/>
+ </macro>
+
+ <macro name="refmodindex">
+ <attribute name="module"/>
+ </macro>
+ <macro name="stmodindex">
+ <attribute name="module"/>
+ </macro>
+ <macro name="refbimodindex" outputname="refmodindex">
+ <attribute name="module"/>
+ </macro>
+ <macro name="refexmodindex" outputname="refmodindex">
+ <attribute name="module"/>
+ </macro>
+ <macro name="refstmodindex" outputname="refmodindex">
+ <attribute name="module"/>
+ </macro>
+
+ <macro name="bifuncindex">
+ <attribute name="name"/>
+ </macro>
+ <macro name="exindex">
+ <attribute name="name"/>
+ </macro>
+ <macro name="obindex">
+ <attribute name="name"/>
+ </macro>
+ <macro name="kwindex">
+ <attribute name="name"/>
+ </macro>
+ <macro name="opindex">
+ <attribute name="type"/>
+ </macro>
+ <macro name="stindex">
+ <attribute name="type"/>
+ </macro>
+ <macro name="withsubitem">
+ <attribute name="text"/>
+ <content/>
+ </macro>
+ <macro name="setindexsubitem">
+ <attribute name="text"/>
+ </macro>
+
+ <!-- Entity management. -->
+ <macro name="include">
+ <attribute name="source"/>
+ </macro>
+ <macro name="input">
+ <attribute name="source"/>
+ </macro>
+
+ <!-- Large-scale document structure. -->
+ <macro name="documentclass">
+ <attribute name="classname"/>
+ </macro>
+
+ <macro name="usepackage">
+ <attribute name="options" optional="yes"/>
+ <attribute name="pkg"/>
+ </macro>
+
+ <environment name="document"
+ endcloses="chapter chapter* section section*
+ subsection subsection*
+ subsubsection subsubsection*
+ paragraph paragraph* subparagraph subparagraph*"/>
+
+ <macro name="chapter"
+ closes="chapter chapter* section section* subsection subsection*
+ subsubsection subsubsection*
+ paragraph paragraph* subparagraph subparagraph*">
+ <text>
+</text>
+ <child name="title"/>
+ <content implied="yes"/>
+ </macro>
+ <macro name="chapter*" outputname="chapter"
+ closes="chapter chapter* section section* subsection subsection*
+ subsubsection subsubsection*
+ paragraph paragraph* subparagraph subparagraph*">
+ <attribute name="numbered">no</attribute>
+ <text>
+</text>
+ <child name="title"/>
+ <content implied="yes"/>
+ </macro>
+
+ <macro name="section"
+ closes="section section* subsection subsection*
+ subsubsection subsubsection*
+ paragraph paragraph* subparagraph subparagraph*">
+ <text>
+</text>
+ <child name="title"/>
+ <content implied="yes"/>
+ </macro>
+ <macro name="section*" outputname="section"
+ closes="section section* subsection subsection*
+ subsubsection subsubsection*
+ paragraph paragraph* subparagraph subparagraph*">
+ <attribute name="numbered">no</attribute>
+ <text>
+</text>
+ <child name="title"/>
+ <content implied="yes"/>
+ </macro>
+
+ <macro name="subsection"
+ closes="subsection subsection* subsubsection subsubsection*
+ paragraph paragraph* subparagraph subparagraph*">
+ <text>
+</text>
+ <child name="title"/>
+ <content implied="yes"/>
+ </macro>
+ <macro name="subsection*" outputname="subsection"
+ closes="subsection subsection* subsubsection subsubsection*
+ paragraph paragraph* subparagraph subparagraph*">
+ <attribute name="numbered">no</attribute>
+ <text>
+</text>
+ <child name="title"/>
+ <content implied="yes"/>
+ </macro>
+
+ <macro name="subsubsection"
+ closes="subsubsection subsubsection*
+ paragraph paragraph* subparagraph subparagraph*">
+ <text>
+</text>
+ <child name="title"/>
+ <content implied="yes"/>
+ </macro>
+ <macro name="subsubsection*" outputname="subsubsection"
+ closes="subsubsection subsubsection*
+ paragraph paragraph* subparagraph subparagraph*">
+ <attribute name="numbered">no</attribute>
+ <text>
+</text>
+ <child name="title"/>
+ <content implied="yes"/>
+ </macro>
+
+ <macro name="paragraph"
+ closes="paragraph paragraph* subparagraph subparagraph*">
+ <text>
+</text>
+ <child name="title"/>
+ <content implied="yes"/>
+ </macro>
+ <macro name="paragraph*" outputname="paragraph"
+ closes="paragraph paragraph* subparagraph subparagraph*">
+ <attribute name="numbered">no</attribute>
+ <text>
+</text>
+ <child name="title"/>
+ <content implied="yes"/>
+ </macro>
+
+ <macro name="subparagraph"
+ closes="subparagraph subparagraph*">
+ <text>
+</text>
+ <child name="title"/>
+ <content implied="yes"/>
+ </macro>
+ <macro name="subparagraph*" outputname="subparagraph"
+ closes="subparagraph subparagraph*">
+ <attribute name="numbered">no</attribute>
+ <text>
+</text>
+ <child name="title"/>
+ <content implied="yes"/>
+ </macro>
+ <macro name="title">
+ <content/>
+ </macro>
+
+ <macro name="appendix" outputname="back-matter"
+ closes="chapter chapter* section subsection subsubsection
+ paragraph subparagraph"/>
+
+ <environment name="list"
+ endcloses="item">
+ <attribute name="bullet"/>
+ <attribute name="init"/>
+ </environment>
+ <macro name="item" closes="item">
+ <child name="leader" optional="yes"/>
+ <content implied="yes"/>
+ </macro>
+
+ <macro name="ref">
+ <attribute name="ref"/>
+ </macro>
+
+ <environment name="description" outputname="descriptionlist"
+ endcloses="item"/>
+
+ <environment name="enumerate" outputname="enumeration"
+ endcloses="item"/>
+
+ <environment name="fulllineitems"
+ endcloses="item"/>
+
+ <environment name="itemize"
+ endcloses="item"/>
+
+ <environment name="definitions" outputname="definitionlist"
+ encloses="term"/>
+ <macro name="term" closes="definition">
+ <!-- not really optional, but uses the [] syntax -->
+ <child name="term" optional="yes"/>
+ <child name="definition" implied="yes"/>
+ </macro>
+
+ <environment name="alltt" outputname="verbatim"/>
+ <environment name="comment" verbatim="yes"/>
+ <environment name="verbatim" verbatim="yes"/>
+ <environment name="verbatim*" verbatim="yes">
+ <!-- not used anywhere, but it's a standard LaTeXism -->
+ <attribute name="spaces">visible</attribute>
+ </environment>
+
+ <!-- Table markup. -->
+ <macro name="hline"/>
+ <environment name="tableii" outputname="table">
+ <attribute name="cols">2</attribute>
+ <attribute name="colspec"/>
+ <attribute name="style"/>
+ <child name="entry"/>
+ <text>
+ </text>
+ <child name="entry"/>
+ </environment>
+ <environment name="longtableii" outputname="table">
+ <attribute name="cols">2</attribute>
+ <attribute name="colspec"/>
+ <attribute name="style"/>
+ <child name="entry"/>
+ <text>
+ </text>
+ <child name="entry"/>
+ </environment>
+ <macro name="lineii" outputname="row">
+ <child name="entry"/>
+ <text>
+ </text>
+ <child name="entry"/>
+ </macro>
+
+ <environment name="tableiii" outputname="table">
+ <attribute name="cols">3</attribute>
+ <attribute name="colspec"/>
+ <attribute name="style"/>
+ <child name="entry"/>
+ <text>
+ </text>
+ <child name="entry"/>
+ <text>
+ </text>
+ <child name="entry"/>
+ </environment>
+ <environment name="longtableiii" outputname="table">
+ <attribute name="cols">3</attribute>
+ <attribute name="colspec"/>
+ <attribute name="style"/>
+ <child name="entry"/>
+ <text>
+ </text>
+ <child name="entry"/>
+ <text>
+ </text>
+ <child name="entry"/>
+ </environment>
+ <macro name="lineiii" outputname="row">
+ <child name="entry"/>
+ <text>
+ </text>
+ <child name="entry"/>
+ <text>
+ </text>
+ <child name="entry"/>
+ </macro>
+
+ <environment name="tableiv" outputname="table">
+ <attribute name="cols">4</attribute>
+ <attribute name="colspec"/>
+ <attribute name="style"/>
+ <child name="entry"/>
+ <text>
+ </text>
+ <child name="entry"/>
+ <text>
+ </text>
+ <child name="entry"/>
+ <text>
+ </text>
+ <child name="entry"/>
+ </environment>
+ <environment name="longtableiv" outputname="table">
+ <attribute name="cols">4</attribute>
+ <attribute name="colspec"/>
+ <attribute name="style"/>
+ <child name="entry"/>
+ <text>
+ </text>
+ <child name="entry"/>
+ <text>
+ </text>
+ <child name="entry"/>
+ <text>
+ </text>
+ <child name="entry"/>
+ </environment>
+ <macro name="lineiv" outputname="row">
+ <child name="entry"/>
+ <text>
+ </text>
+ <child name="entry"/>
+ <text>
+ </text>
+ <child name="entry"/>
+ <text>
+ </text>
+ <child name="entry"/>
+ </macro>
+
+ <!-- These are handled at a later translation stage, at least for now. -->
+ <macro name="Cpp" outputname="">
+ <text>C++</text>
+ </macro>
+ <macro name="geq" outputname="">
+ <entityref name="geq"/>
+ </macro>
+ <macro name="LaTeX" outputname="">
+ <text>LaTeX</text>
+ </macro>
+ <macro name="ldots" outputname="">
+ <text>...</text>
+ </macro>
+ <macro name="leq" outputname="">
+ <entityref name="leq"/>
+ </macro>
+ <macro name="TeX" outputname="">
+ <text>TeX</text>
+ </macro>
+ <macro name="version"/>
+
+ <!-- Distutils things. -->
+ <macro name="command">
+ <content/>
+ </macro>
+ <macro name="option">
+ <content/>
+ </macro>
+ <macro name="filevar" outputname="var">
+ <content/>
+ </macro>
+ <macro name="XXX" outputname="editorial-comment">
+ <content/>
+ </macro>
+
+ <!-- Misc. -->
+ <macro name="emph">
+ <content/>
+ </macro>
+ <macro name="strong">
+ <content/>
+ </macro>
+ <macro name="textrm">
+ <content/>
+ </macro>
+ <macro name="texttt">
+ <content/>
+ </macro>
+ <macro name="code">
+ <content/>
+ </macro>
+ <macro name="exception">
+ <content/>
+ </macro>
+ <macro name="keyword">
+ <content/>
+ </macro>
+ <macro name="samp">
+ <content/>
+ </macro>
+ <macro name="class">
+ <content/>
+ </macro>
+ <macro name="cdata">
+ <content/>
+ </macro>
+ <macro name="cfunction">
+ <content/>
+ </macro>
+ <macro name="ctype">
+ <content/>
+ </macro>
+ <macro name="pytype">
+ <content/>
+ </macro>
+ <macro name="character">
+ <content/>
+ </macro>
+ <macro name="constant">
+ <content/>
+ </macro>
+ <macro name="envvar" outputname="envar">
+ <content/>
+ </macro>
+ <macro name="file" outputname="filename">
+ <content/>
+ </macro>
+ <macro name="filenq" outputname="filename">
+ <attribute name="quote">no</attribute>
+ <content/>
+ </macro>
+ <macro name="function">
+ <content/>
+ </macro>
+ <macro name="kbd">
+ <content/>
+ </macro>
+ <macro name="makevar">
+ <content/>
+ </macro>
+ <macro name="method">
+ <content/>
+ </macro>
+ <macro name="member">
+ <content/>
+ </macro>
+ <macro name="mimetype">
+ <content/>
+ </macro>
+ <macro name="newsgroup">
+ <content/>
+ </macro>
+ <macro name="program" outputname="command">
+ <content/>
+ </macro>
+ <macro name="programopt" outputname="option">
+ <content/>
+ </macro>
+ <macro name="longprogramopt" outputname="longoption">
+ <content/>
+ </macro>
+ <macro name="regexp">
+ <content/>
+ </macro>
+ <macro name="var">
+ <content/>
+ </macro>
+ <macro name="email">
+ <content/>
+ </macro>
+ <macro name="url">
+ <content/>
+ </macro>
+ <macro name="footnote">
+ <content/>
+ </macro>
+ <macro name="dfn" outputname="definedterm">
+ <content/>
+ </macro>
+
+ <macro name="mbox">
+ <content/>
+ </macro>
+
+ <!-- minimal math stuff to get by -->
+ <macro name="pi"/>
+ <macro name="sqrt">
+ <content/>
+ </macro>
+ <macro name="frac" outputname="fraction">
+ <child name="numerator"/>
+ <child name="denominator"/>
+ </macro>
+ <macro name="sum">
+ <content/>
+ </macro>
+
+ <!-- Conversions to text; perhaps could be different? There's -->
+ <!-- no way for a style sheet to work with these this way. -->
+ <macro name="ABC" outputname="">
+ <text>ABC</text>
+ </macro>
+ <macro name="ASCII" outputname="">
+ <text>ASCII</text>
+ </macro>
+ <macro name="C" outputname="">
+ <text>C</text>
+ </macro>
+ <macro name="EOF" outputname="">
+ <text>EOF</text>
+ </macro>
+ <macro name="e" outputname="">
+ <text>\</text>
+ </macro>
+ <macro name="NULL" outputname="constant">
+ <text>NULL</text>
+ </macro>
+ <macro name="POSIX" outputname="">
+ <text>POSIX</text>
+ </macro>
+ <macro name="UNIX" outputname="">
+ <text>Unix</text>
+ </macro>
+ <macro name="textasciitilde" outputname="">
+ <text>~</text>
+ </macro>
+
+ <!-- These will end up disappearing as well! -->
+ <macro name="catcode" outputname=""/>
+ <macro name="fi" outputname=""/>
+ <macro name="ifhtml" outputname=""/>
+ <macro name="indexname" outputname=""/>
+ <macro name="labelwidth" outputname=""/>
+ <macro name="large" outputname=""/>
+ <macro name="leftmargin" outputname=""/>
+ <macro name="makeindex" outputname=""/>
+ <macro name="makemodindex" outputname=""/>
+ <macro name="maketitle" outputname=""/>
+ <macro name="noindent" outputname=""/>
+ <macro name="protect" outputname=""/>
+ <macro name="renewcommand">
+ <attribute name="macro"/>
+ <attribute name="nargs" optional="yes"/>
+ <content/>
+ </macro>
+ <macro name="tableofcontents" outputname=""/>
+ <macro name="vspace">
+ <attribute name="size"/>
+ </macro>
+</conversion>
diff --git a/doc/tools/sgmlconv/docfixer.py b/doc/tools/sgmlconv/docfixer.py
new file mode 100755
index 0000000..463276b
--- /dev/null
+++ b/doc/tools/sgmlconv/docfixer.py
@@ -0,0 +1,1033 @@
+#! /usr/bin/env python
+
+"""Perform massive transformations on a document tree created from the LaTeX
+of the Python documentation, and dump the ESIS data for the transformed tree.
+"""
+
+
+import errno
+import esistools
+import re
+import string
+import sys
+import xml.dom
+import xml.dom.minidom
+
+ELEMENT = xml.dom.Node.ELEMENT_NODE
+ENTITY_REFERENCE = xml.dom.Node.ENTITY_REFERENCE_NODE
+TEXT = xml.dom.Node.TEXT_NODE
+
+
+class ConversionError(Exception):
+ pass
+
+
+ewrite = sys.stderr.write
+try:
+ # We can only do this trick on Unix (if tput is on $PATH)!
+ if sys.platform != "posix" or not sys.stderr.isatty():
+ raise ImportError
+ import commands
+except ImportError:
+ bwrite = ewrite
+else:
+ def bwrite(s, BOLDON=commands.getoutput("tput bold"),
+ BOLDOFF=commands.getoutput("tput sgr0")):
+ ewrite("%s%s%s" % (BOLDON, s, BOLDOFF))
+
+
+PARA_ELEMENT = "para"
+
+DEBUG_PARA_FIXER = 0
+
+if DEBUG_PARA_FIXER:
+ def para_msg(s):
+ ewrite("*** %s\n" % s)
+else:
+ def para_msg(s):
+ pass
+
+
+def get_first_element(doc, gi):
+ for n in doc.childNodes:
+ if n.nodeName == gi:
+ return n
+
+def extract_first_element(doc, gi):
+ node = get_first_element(doc, gi)
+ if node is not None:
+ doc.removeChild(node)
+ return node
+
+
+def get_documentElement(node):
+ result = None
+ for child in node.childNodes:
+ if child.nodeType == ELEMENT:
+ result = child
+ return result
+
+
+def set_tagName(elem, gi):
+ elem.nodeName = elem.tagName = gi
+
+
+def find_all_elements(doc, gi):
+ nodes = []
+ if doc.nodeName == gi:
+ nodes.append(doc)
+ for child in doc.childNodes:
+ if child.nodeType == ELEMENT:
+ if child.tagName == gi:
+ nodes.append(child)
+ for node in child.getElementsByTagName(gi):
+ nodes.append(node)
+ return nodes
+
+def find_all_child_elements(doc, gi):
+ nodes = []
+ for child in doc.childNodes:
+ if child.nodeName == gi:
+ nodes.append(child)
+ return nodes
+
+
+def find_all_elements_from_set(doc, gi_set):
+ return __find_all_elements_from_set(doc, gi_set, [])
+
+def __find_all_elements_from_set(doc, gi_set, nodes):
+ if doc.nodeName in gi_set:
+ nodes.append(doc)
+ for child in doc.childNodes:
+ if child.nodeType == ELEMENT:
+ __find_all_elements_from_set(child, gi_set, nodes)
+ return nodes
+
+
+def simplify(doc, fragment):
+ # Try to rationalize the document a bit, since these things are simply
+ # not valid SGML/XML documents as they stand, and need a little work.
+ documentclass = "document"
+ inputs = []
+ node = extract_first_element(fragment, "documentclass")
+ if node is not None:
+ documentclass = node.getAttribute("classname")
+ node = extract_first_element(fragment, "title")
+ if node is not None:
+ inputs.append(node)
+ # update the name of the root element
+ node = get_first_element(fragment, "document")
+ if node is not None:
+ set_tagName(node, documentclass)
+ while 1:
+ node = extract_first_element(fragment, "input")
+ if node is None:
+ break
+ inputs.append(node)
+ if inputs:
+ docelem = get_documentElement(fragment)
+ inputs.reverse()
+ for node in inputs:
+ text = doc.createTextNode("\n")
+ docelem.insertBefore(text, docelem.firstChild)
+ docelem.insertBefore(node, text)
+ docelem.insertBefore(doc.createTextNode("\n"), docelem.firstChild)
+ while fragment.firstChild and fragment.firstChild.nodeType == TEXT:
+ fragment.removeChild(fragment.firstChild)
+
+
+def cleanup_root_text(doc):
+ discards = []
+ skip = 0
+ for n in doc.childNodes:
+ prevskip = skip
+ skip = 0
+ if n.nodeType == TEXT and not prevskip:
+ discards.append(n)
+ elif n.nodeName == "COMMENT":
+ skip = 1
+ for node in discards:
+ doc.removeChild(node)
+
+
+DESCRIPTOR_ELEMENTS = (
+ "cfuncdesc", "cvardesc", "ctypedesc",
+ "classdesc", "memberdesc", "memberdescni", "methoddesc", "methoddescni",
+ "excdesc", "funcdesc", "funcdescni", "opcodedesc",
+ "datadesc", "datadescni",
+ )
+
+def fixup_descriptors(doc, fragment):
+ sections = find_all_elements(fragment, "section")
+ for section in sections:
+ find_and_fix_descriptors(doc, section)
+
+
+def find_and_fix_descriptors(doc, container):
+ children = container.childNodes
+ for child in children:
+ if child.nodeType == ELEMENT:
+ tagName = child.tagName
+ if tagName in DESCRIPTOR_ELEMENTS:
+ rewrite_descriptor(doc, child)
+ elif tagName == "subsection":
+ find_and_fix_descriptors(doc, child)
+
+
+def rewrite_descriptor(doc, descriptor):
+ #
+ # Do these things:
+ # 1. Add an "index='no'" attribute to the element if the tagName
+ # ends in 'ni', removing the 'ni' from the name.
+ # 2. Create a <signature> from the name attribute
+ # 2a.Create an <args> if it appears to be available.
+ # 3. Create additional <signature>s from <*line{,ni}> elements,
+ # if found.
+ # 4. If a <versionadded> is found, move it to an attribute on the
+ # descriptor.
+ # 5. Move remaining child nodes to a <description> element.
+ # 6. Put it back together.
+ #
+ # 1.
+ descname = descriptor.tagName
+ index = 1
+ if descname[-2:] == "ni":
+ descname = descname[:-2]
+ descriptor.setAttribute("index", "no")
+ set_tagName(descriptor, descname)
+ index = 0
+ desctype = descname[:-4] # remove 'desc'
+ linename = desctype + "line"
+ if not index:
+ linename = linename + "ni"
+ # 2.
+ signature = doc.createElement("signature")
+ name = doc.createElement("name")
+ signature.appendChild(doc.createTextNode("\n "))
+ signature.appendChild(name)
+ name.appendChild(doc.createTextNode(descriptor.getAttribute("name")))
+ descriptor.removeAttribute("name")
+ # 2a.
+ if descriptor.hasAttribute("var"):
+ if descname != "opcodedesc":
+ raise RuntimeError, \
+ "got 'var' attribute on descriptor other than opcodedesc"
+ variable = descriptor.getAttribute("var")
+ if variable:
+ args = doc.createElement("args")
+ args.appendChild(doc.createTextNode(variable))
+ signature.appendChild(doc.createTextNode("\n "))
+ signature.appendChild(args)
+ descriptor.removeAttribute("var")
+ newchildren = [signature]
+ children = descriptor.childNodes
+ pos = skip_leading_nodes(children)
+ if pos < len(children):
+ child = children[pos]
+ if child.nodeName == "args":
+ # move <args> to <signature>, or remove if empty:
+ child.parentNode.removeChild(child)
+ if len(child.childNodes):
+ signature.appendChild(doc.createTextNode("\n "))
+ signature.appendChild(child)
+ signature.appendChild(doc.createTextNode("\n "))
+ # 3, 4.
+ pos = skip_leading_nodes(children, pos)
+ while pos < len(children) \
+ and children[pos].nodeName in (linename, "versionadded"):
+ if children[pos].tagName == linename:
+ # this is really a supplemental signature, create <signature>
+ oldchild = children[pos].cloneNode(1)
+ try:
+ sig = methodline_to_signature(doc, children[pos])
+ except KeyError:
+ print oldchild.toxml()
+ raise
+ newchildren.append(sig)
+ else:
+ # <versionadded added=...>
+ descriptor.setAttribute(
+ "added", children[pos].getAttribute("version"))
+ pos = skip_leading_nodes(children, pos + 1)
+ # 5.
+ description = doc.createElement("description")
+ description.appendChild(doc.createTextNode("\n"))
+ newchildren.append(description)
+ move_children(descriptor, description, pos)
+ last = description.childNodes[-1]
+ if last.nodeType == TEXT:
+ last.data = string.rstrip(last.data) + "\n "
+ # 6.
+ # should have nothing but whitespace and signature lines in <descriptor>;
+ # discard them
+ while descriptor.childNodes:
+ descriptor.removeChild(descriptor.childNodes[0])
+ for node in newchildren:
+ descriptor.appendChild(doc.createTextNode("\n "))
+ descriptor.appendChild(node)
+ descriptor.appendChild(doc.createTextNode("\n"))
+
+
+def methodline_to_signature(doc, methodline):
+ signature = doc.createElement("signature")
+ signature.appendChild(doc.createTextNode("\n "))
+ name = doc.createElement("name")
+ name.appendChild(doc.createTextNode(methodline.getAttribute("name")))
+ methodline.removeAttribute("name")
+ signature.appendChild(name)
+ if len(methodline.childNodes):
+ args = doc.createElement("args")
+ signature.appendChild(doc.createTextNode("\n "))
+ signature.appendChild(args)
+ move_children(methodline, args)
+ signature.appendChild(doc.createTextNode("\n "))
+ return signature
+
+
+def move_children(origin, dest, start=0):
+ children = origin.childNodes
+ while start < len(children):
+ node = children[start]
+ origin.removeChild(node)
+ dest.appendChild(node)
+
+
+def handle_appendix(doc, fragment):
+ # must be called after simplfy() if document is multi-rooted to begin with
+ docelem = get_documentElement(fragment)
+ toplevel = docelem.tagName == "manual" and "chapter" or "section"
+ appendices = 0
+ nodes = []
+ for node in docelem.childNodes:
+ if appendices:
+ nodes.append(node)
+ elif node.nodeType == ELEMENT:
+ appnodes = node.getElementsByTagName("appendix")
+ if appnodes:
+ appendices = 1
+ parent = appnodes[0].parentNode
+ parent.removeChild(appnodes[0])
+ parent.normalize()
+ if nodes:
+ map(docelem.removeChild, nodes)
+ docelem.appendChild(doc.createTextNode("\n\n\n"))
+ back = doc.createElement("back-matter")
+ docelem.appendChild(back)
+ back.appendChild(doc.createTextNode("\n"))
+ while nodes and nodes[0].nodeType == TEXT \
+ and not string.strip(nodes[0].data):
+ del nodes[0]
+ map(back.appendChild, nodes)
+ docelem.appendChild(doc.createTextNode("\n"))
+
+
+def handle_labels(doc, fragment):
+ for label in find_all_elements(fragment, "label"):
+ id = label.getAttribute("id")
+ if not id:
+ continue
+ parent = label.parentNode
+ parentTagName = parent.tagName
+ if parentTagName == "title":
+ parent.parentNode.setAttribute("id", id)
+ else:
+ parent.setAttribute("id", id)
+ # now, remove <label id="..."/> from parent:
+ parent.removeChild(label)
+ if parentTagName == "title":
+ parent.normalize()
+ children = parent.childNodes
+ if children[-1].nodeType == TEXT:
+ children[-1].data = string.rstrip(children[-1].data)
+
+
+def fixup_trailing_whitespace(doc, wsmap):
+ queue = [doc]
+ while queue:
+ node = queue[0]
+ del queue[0]
+ if wsmap.has_key(node.nodeName):
+ ws = wsmap[node.tagName]
+ children = node.childNodes
+ children.reverse()
+ if children[0].nodeType == TEXT:
+ data = string.rstrip(children[0].data) + ws
+ children[0].data = data
+ children.reverse()
+ # hack to get the title in place:
+ if node.tagName == "title" \
+ and node.parentNode.firstChild.nodeType == ELEMENT:
+ node.parentNode.insertBefore(doc.createText("\n "),
+ node.parentNode.firstChild)
+ for child in node.childNodes:
+ if child.nodeType == ELEMENT:
+ queue.append(child)
+
+
+def normalize(doc):
+ for node in doc.childNodes:
+ if node.nodeType == ELEMENT:
+ node.normalize()
+
+
+def cleanup_trailing_parens(doc, element_names):
+ d = {}
+ for gi in element_names:
+ d[gi] = gi
+ rewrite_element = d.has_key
+ queue = []
+ for node in doc.childNodes:
+ if node.nodeType == ELEMENT:
+ queue.append(node)
+ while queue:
+ node = queue[0]
+ del queue[0]
+ if rewrite_element(node.tagName):
+ children = node.childNodes
+ if len(children) == 1 \
+ and children[0].nodeType == TEXT:
+ data = children[0].data
+ if data[-2:] == "()":
+ children[0].data = data[:-2]
+ else:
+ for child in node.childNodes:
+ if child.nodeType == ELEMENT:
+ queue.append(child)
+
+
+def contents_match(left, right):
+ left_children = left.childNodes
+ right_children = right.childNodes
+ if len(left_children) != len(right_children):
+ return 0
+ for l, r in map(None, left_children, right_children):
+ nodeType = l.nodeType
+ if nodeType != r.nodeType:
+ return 0
+ if nodeType == ELEMENT:
+ if l.tagName != r.tagName:
+ return 0
+ # should check attributes, but that's not a problem here
+ if not contents_match(l, r):
+ return 0
+ elif nodeType == TEXT:
+ if l.data != r.data:
+ return 0
+ else:
+ # not quite right, but good enough
+ return 0
+ return 1
+
+
+def create_module_info(doc, section):
+ # Heavy.
+ node = extract_first_element(section, "modulesynopsis")
+ if node is None:
+ return
+ set_tagName(node, "synopsis")
+ lastchild = node.childNodes[-1]
+ if lastchild.nodeType == TEXT \
+ and lastchild.data[-1:] == ".":
+ lastchild.data = lastchild.data[:-1]
+ modauthor = extract_first_element(section, "moduleauthor")
+ if modauthor:
+ set_tagName(modauthor, "author")
+ modauthor.appendChild(doc.createTextNode(
+ modauthor.getAttribute("name")))
+ modauthor.removeAttribute("name")
+ platform = extract_first_element(section, "platform")
+ if section.tagName == "section":
+ modinfo_pos = 2
+ modinfo = doc.createElement("moduleinfo")
+ moddecl = extract_first_element(section, "declaremodule")
+ name = None
+ if moddecl:
+ modinfo.appendChild(doc.createTextNode("\n "))
+ name = moddecl.attributes["name"].value
+ namenode = doc.createElement("name")
+ namenode.appendChild(doc.createTextNode(name))
+ modinfo.appendChild(namenode)
+ type = moddecl.attributes.get("type")
+ if type:
+ type = type.value
+ modinfo.appendChild(doc.createTextNode("\n "))
+ typenode = doc.createElement("type")
+ typenode.appendChild(doc.createTextNode(type))
+ modinfo.appendChild(typenode)
+ versionadded = extract_first_element(section, "versionadded")
+ if versionadded:
+ modinfo.setAttribute("added", versionadded.getAttribute("version"))
+ title = get_first_element(section, "title")
+ if title:
+ children = title.childNodes
+ if len(children) >= 2 \
+ and children[0].nodeName == "module" \
+ and children[0].childNodes[0].data == name:
+ # this is it; morph the <title> into <short-synopsis>
+ first_data = children[1]
+ if first_data.data[:4] == " ---":
+ first_data.data = string.lstrip(first_data.data[4:])
+ set_tagName(title, "short-synopsis")
+ if children[-1].nodeType == TEXT \
+ and children[-1].data[-1:] == ".":
+ children[-1].data = children[-1].data[:-1]
+ section.removeChild(title)
+ section.removeChild(section.childNodes[0])
+ title.removeChild(children[0])
+ modinfo_pos = 0
+ else:
+ ewrite("module name in title doesn't match"
+ " <declaremodule/>; no <short-synopsis/>\n")
+ else:
+ ewrite("Unexpected condition: <section/> without <title/>\n")
+ modinfo.appendChild(doc.createTextNode("\n "))
+ modinfo.appendChild(node)
+ if title and not contents_match(title, node):
+ # The short synopsis is actually different,
+ # and needs to be stored:
+ modinfo.appendChild(doc.createTextNode("\n "))
+ modinfo.appendChild(title)
+ if modauthor:
+ modinfo.appendChild(doc.createTextNode("\n "))
+ modinfo.appendChild(modauthor)
+ if platform:
+ modinfo.appendChild(doc.createTextNode("\n "))
+ modinfo.appendChild(platform)
+ modinfo.appendChild(doc.createTextNode("\n "))
+ section.insertBefore(modinfo, section.childNodes[modinfo_pos])
+ section.insertBefore(doc.createTextNode("\n "), modinfo)
+ #
+ # The rest of this removes extra newlines from where we cut out
+ # a lot of elements. A lot of code for minimal value, but keeps
+ # keeps the generated *ML from being too funny looking.
+ #
+ section.normalize()
+ children = section.childNodes
+ for i in range(len(children)):
+ node = children[i]
+ if node.nodeName == "moduleinfo":
+ nextnode = children[i+1]
+ if nextnode.nodeType == TEXT:
+ data = nextnode.data
+ if len(string.lstrip(data)) < (len(data) - 4):
+ nextnode.data = "\n\n\n" + string.lstrip(data)
+
+
+def cleanup_synopses(doc, fragment):
+ for node in find_all_elements(fragment, "section"):
+ create_module_info(doc, node)
+
+
+def fixup_table_structures(doc, fragment):
+ for table in find_all_elements(fragment, "table"):
+ fixup_table(doc, table)
+
+
+def fixup_table(doc, table):
+ # create the table head
+ thead = doc.createElement("thead")
+ row = doc.createElement("row")
+ move_elements_by_name(doc, table, row, "entry")
+ thead.appendChild(doc.createTextNode("\n "))
+ thead.appendChild(row)
+ thead.appendChild(doc.createTextNode("\n "))
+ # create the table body
+ tbody = doc.createElement("tbody")
+ prev_row = None
+ last_was_hline = 0
+ children = table.childNodes
+ for child in children:
+ if child.nodeType == ELEMENT:
+ tagName = child.tagName
+ if tagName == "hline" and prev_row is not None:
+ prev_row.setAttribute("rowsep", "1")
+ elif tagName == "row":
+ prev_row = child
+ # save the rows:
+ tbody.appendChild(doc.createTextNode("\n "))
+ move_elements_by_name(doc, table, tbody, "row", sep="\n ")
+ # and toss the rest:
+ while children:
+ child = children[0]
+ nodeType = child.nodeType
+ if nodeType == TEXT:
+ if string.strip(child.data):
+ raise ConversionError("unexpected free data in <%s>: %r"
+ % (table.tagName, child.data))
+ table.removeChild(child)
+ continue
+ if nodeType == ELEMENT:
+ if child.tagName != "hline":
+ raise ConversionError(
+ "unexpected <%s> in table" % child.tagName)
+ table.removeChild(child)
+ continue
+ raise ConversionError(
+ "unexpected %s node in table" % child.__class__.__name__)
+ # nothing left in the <table>; add the <thead> and <tbody>
+ tgroup = doc.createElement("tgroup")
+ tgroup.appendChild(doc.createTextNode("\n "))
+ tgroup.appendChild(thead)
+ tgroup.appendChild(doc.createTextNode("\n "))
+ tgroup.appendChild(tbody)
+ tgroup.appendChild(doc.createTextNode("\n "))
+ table.appendChild(tgroup)
+ # now make the <entry>s look nice:
+ for row in table.getElementsByTagName("row"):
+ fixup_row(doc, row)
+
+
+def fixup_row(doc, row):
+ entries = []
+ map(entries.append, row.childNodes[1:])
+ for entry in entries:
+ row.insertBefore(doc.createTextNode("\n "), entry)
+# row.appendChild(doc.createTextNode("\n "))
+
+
+def move_elements_by_name(doc, source, dest, name, sep=None):
+ nodes = []
+ for child in source.childNodes:
+ if child.nodeName == name:
+ nodes.append(child)
+ for node in nodes:
+ source.removeChild(node)
+ dest.appendChild(node)
+ if sep:
+ dest.appendChild(doc.createTextNode(sep))
+
+
+RECURSE_INTO_PARA_CONTAINERS = (
+ "chapter", "abstract", "enumerate",
+ "section", "subsection", "subsubsection",
+ "paragraph", "subparagraph", "back-matter",
+ "howto", "manual",
+ "item", "itemize", "fulllineitems", "enumeration", "descriptionlist",
+ "definitionlist", "definition",
+ )
+
+PARA_LEVEL_ELEMENTS = (
+ "moduleinfo", "title", "verbatim", "enumerate", "item",
+ "interpreter-session", "back-matter", "interactive-session",
+ "opcodedesc", "classdesc", "datadesc",
+ "funcdesc", "methoddesc", "excdesc", "memberdesc", "membderdescni",
+ "funcdescni", "methoddescni", "excdescni",
+ "tableii", "tableiii", "tableiv", "localmoduletable",
+ "sectionauthor", "seealso", "itemize",
+ # include <para>, so we can just do it again to get subsequent paras:
+ PARA_ELEMENT,
+ )
+
+PARA_LEVEL_PRECEEDERS = (
+ "setindexsubitem", "author",
+ "stindex", "obindex", "COMMENT", "label", "input", "title",
+ "versionadded", "versionchanged", "declaremodule", "modulesynopsis",
+ "moduleauthor", "indexterm", "leader",
+ )
+
+
+def fixup_paras(doc, fragment):
+ for child in fragment.childNodes:
+ if child.nodeName in RECURSE_INTO_PARA_CONTAINERS:
+ fixup_paras_helper(doc, child)
+ descriptions = find_all_elements(fragment, "description")
+ for description in descriptions:
+ fixup_paras_helper(doc, description)
+
+
+def fixup_paras_helper(doc, container, depth=0):
+ # document is already normalized
+ children = container.childNodes
+ start = skip_leading_nodes(children)
+ while len(children) > start:
+ if children[start].nodeName in RECURSE_INTO_PARA_CONTAINERS:
+ # Something to recurse into:
+ fixup_paras_helper(doc, children[start])
+ else:
+ # Paragraph material:
+ build_para(doc, container, start, len(children))
+ if DEBUG_PARA_FIXER and depth == 10:
+ sys.exit(1)
+ start = skip_leading_nodes(children, start + 1)
+
+
+def build_para(doc, parent, start, i):
+ children = parent.childNodes
+ after = start + 1
+ have_last = 0
+ BREAK_ELEMENTS = PARA_LEVEL_ELEMENTS + RECURSE_INTO_PARA_CONTAINERS
+ # Collect all children until \n\n+ is found in a text node or a
+ # member of BREAK_ELEMENTS is found.
+ for j in range(start, i):
+ after = j + 1
+ child = children[j]
+ nodeType = child.nodeType
+ if nodeType == ELEMENT:
+ if child.tagName in BREAK_ELEMENTS:
+ after = j
+ break
+ elif nodeType == TEXT:
+ pos = string.find(child.data, "\n\n")
+ if pos == 0:
+ after = j
+ break
+ if pos >= 1:
+ child.splitText(pos)
+ break
+ else:
+ have_last = 1
+ if (start + 1) > after:
+ raise ConversionError(
+ "build_para() could not identify content to turn into a paragraph")
+ if children[after - 1].nodeType == TEXT:
+ # we may need to split off trailing white space:
+ child = children[after - 1]
+ data = child.data
+ if string.rstrip(data) != data:
+ have_last = 0
+ child.splitText(len(string.rstrip(data)))
+ para = doc.createElement(PARA_ELEMENT)
+ prev = None
+ indexes = range(start, after)
+ indexes.reverse()
+ for j in indexes:
+ node = parent.childNodes[j]
+ parent.removeChild(node)
+ para.insertBefore(node, prev)
+ prev = node
+ if have_last:
+ parent.appendChild(para)
+ parent.appendChild(doc.createTextNode("\n\n"))
+ return len(parent.childNodes)
+ else:
+ nextnode = parent.childNodes[start]
+ if nextnode.nodeType == TEXT:
+ if nextnode.data and nextnode.data[0] != "\n":
+ nextnode.data = "\n" + nextnode.data
+ else:
+ newnode = doc.createTextNode("\n")
+ parent.insertBefore(newnode, nextnode)
+ nextnode = newnode
+ start = start + 1
+ parent.insertBefore(para, nextnode)
+ return start + 1
+
+
+def skip_leading_nodes(children, start=0):
+ """Return index into children of a node at which paragraph building should
+ begin or a recursive call to fixup_paras_helper() should be made (for
+ subsections, etc.).
+
+ When the return value >= len(children), we've built all the paras we can
+ from this list of children.
+ """
+ i = len(children)
+ while i > start:
+ # skip over leading comments and whitespace:
+ child = children[start]
+ nodeType = child.nodeType
+ if nodeType == TEXT:
+ data = child.data
+ shortened = string.lstrip(data)
+ if shortened:
+ if data != shortened:
+ # break into two nodes: whitespace and non-whitespace
+ child.splitText(len(data) - len(shortened))
+ return start + 1
+ return start
+ # all whitespace, just skip
+ elif nodeType == ELEMENT:
+ tagName = child.tagName
+ if tagName in RECURSE_INTO_PARA_CONTAINERS:
+ return start
+ if tagName not in PARA_LEVEL_ELEMENTS + PARA_LEVEL_PRECEEDERS:
+ return start
+ start = start + 1
+ return start
+
+
+def fixup_rfc_references(doc, fragment):
+ for rfcnode in find_all_elements(fragment, "rfc"):
+ rfcnode.appendChild(doc.createTextNode(
+ "RFC " + rfcnode.getAttribute("num")))
+
+
+def fixup_signatures(doc, fragment):
+ for child in fragment.childNodes:
+ if child.nodeType == ELEMENT:
+ args = child.getElementsByTagName("args")
+ for arg in args:
+ fixup_args(doc, arg)
+ arg.normalize()
+ args = child.getElementsByTagName("constructor-args")
+ for arg in args:
+ fixup_args(doc, arg)
+ arg.normalize()
+
+
+def fixup_args(doc, arglist):
+ for child in arglist.childNodes:
+ if child.nodeName == "optional":
+ # found it; fix and return
+ arglist.insertBefore(doc.createTextNode("["), child)
+ optkids = child.childNodes
+ while optkids:
+ k = optkids[0]
+ child.removeChild(k)
+ arglist.insertBefore(k, child)
+ arglist.insertBefore(doc.createTextNode("]"), child)
+ arglist.removeChild(child)
+ return fixup_args(doc, arglist)
+
+
+def fixup_sectionauthors(doc, fragment):
+ for sectauth in find_all_elements(fragment, "sectionauthor"):
+ section = sectauth.parentNode
+ section.removeChild(sectauth)
+ set_tagName(sectauth, "author")
+ sectauth.appendChild(doc.createTextNode(
+ sectauth.getAttribute("name")))
+ sectauth.removeAttribute("name")
+ after = section.childNodes[2]
+ title = section.childNodes[1]
+ if title.nodeName != "title":
+ after = section.childNodes[0]
+ section.insertBefore(doc.createTextNode("\n "), after)
+ section.insertBefore(sectauth, after)
+
+
+def fixup_verbatims(doc):
+ for verbatim in find_all_elements(doc, "verbatim"):
+ child = verbatim.childNodes[0]
+ if child.nodeType == TEXT \
+ and string.lstrip(child.data)[:3] == ">>>":
+ set_tagName(verbatim, "interactive-session")
+
+
+def add_node_ids(fragment, counter=0):
+ fragment.node_id = counter
+ for node in fragment.childNodes:
+ counter = counter + 1
+ if node.nodeType == ELEMENT:
+ counter = add_node_ids(node, counter)
+ else:
+ node.node_id = counter
+ return counter + 1
+
+
+REFMODINDEX_ELEMENTS = ('refmodindex', 'refbimodindex',
+ 'refexmodindex', 'refstmodindex')
+
+def fixup_refmodindexes(fragment):
+ # Locate <ref*modindex>...</> co-located with <module>...</>, and
+ # remove the <ref*modindex>, replacing it with index=index on the
+ # <module> element.
+ nodes = find_all_elements_from_set(fragment, REFMODINDEX_ELEMENTS)
+ d = {}
+ for node in nodes:
+ parent = node.parentNode
+ d[parent.node_id] = parent
+ del nodes
+ map(fixup_refmodindexes_chunk, d.values())
+
+
+def fixup_refmodindexes_chunk(container):
+ # node is probably a <para>; let's see how often it isn't:
+ if container.tagName != PARA_ELEMENT:
+ bwrite("--- fixup_refmodindexes_chunk(%s)\n" % container)
+ module_entries = find_all_elements(container, "module")
+ if not module_entries:
+ return
+ index_entries = find_all_elements_from_set(container, REFMODINDEX_ELEMENTS)
+ removes = []
+ for entry in index_entries:
+ children = entry.childNodes
+ if len(children) != 0:
+ bwrite("--- unexpected number of children for %s node:\n"
+ % entry.tagName)
+ ewrite(entry.toxml() + "\n")
+ continue
+ found = 0
+ module_name = entry.getAttribute("module")
+ for node in module_entries:
+ if len(node.childNodes) != 1:
+ continue
+ this_name = node.childNodes[0].data
+ if this_name == module_name:
+ found = 1
+ node.setAttribute("index", "yes")
+ if found:
+ removes.append(entry)
+ for node in removes:
+ container.removeChild(node)
+
+
+def fixup_bifuncindexes(fragment):
+ nodes = find_all_elements(fragment, 'bifuncindex')
+ d = {}
+ # make sure that each parent is only processed once:
+ for node in nodes:
+ parent = node.parentNode
+ d[parent.node_id] = parent
+ del nodes
+ map(fixup_bifuncindexes_chunk, d.values())
+
+
+def fixup_bifuncindexes_chunk(container):
+ removes = []
+ entries = find_all_child_elements(container, "bifuncindex")
+ function_entries = find_all_child_elements(container, "function")
+ for entry in entries:
+ function_name = entry.getAttribute("name")
+ found = 0
+ for func_entry in function_entries:
+ t2 = func_entry.childNodes[0].data
+ if t2[-2:] != "()":
+ continue
+ t2 = t2[:-2]
+ if t2 == function_name:
+ func_entry.setAttribute("index", "yes")
+ func_entry.setAttribute("module", "__builtin__")
+ if not found:
+ found = 1
+ removes.append(entry)
+ for entry in removes:
+ container.removeChild(entry)
+
+
+def join_adjacent_elements(container, gi):
+ queue = [container]
+ while queue:
+ parent = queue.pop()
+ i = 0
+ children = parent.childNodes
+ nchildren = len(children)
+ while i < (nchildren - 1):
+ child = children[i]
+ if child.nodeName == gi:
+ if children[i+1].nodeName == gi:
+ ewrite("--- merging two <%s/> elements\n" % gi)
+ child = children[i]
+ nextchild = children[i+1]
+ nextchildren = nextchild.childNodes
+ while len(nextchildren):
+ node = nextchildren[0]
+ nextchild.removeChild(node)
+ child.appendChild(node)
+ parent.removeChild(nextchild)
+ continue
+ if child.nodeType == ELEMENT:
+ queue.append(child)
+ i = i + 1
+
+
+_token_rx = re.compile(r"[a-zA-Z][a-zA-Z0-9.-]*$")
+
+def write_esis(doc, ofp, knownempty):
+ for node in doc.childNodes:
+ nodeType = node.nodeType
+ if nodeType == ELEMENT:
+ gi = node.tagName
+ if knownempty(gi):
+ if node.hasChildNodes():
+ raise ValueError, \
+ "declared-empty node <%s> has children" % gi
+ ofp.write("e\n")
+ for k, value in node.attributes.items():
+ if _token_rx.match(value):
+ dtype = "TOKEN"
+ else:
+ dtype = "CDATA"
+ ofp.write("A%s %s %s\n" % (k, dtype, esistools.encode(value)))
+ ofp.write("(%s\n" % gi)
+ write_esis(node, ofp, knownempty)
+ ofp.write(")%s\n" % gi)
+ elif nodeType == TEXT:
+ ofp.write("-%s\n" % esistools.encode(node.data))
+ elif nodeType == ENTITY_REFERENCE:
+ ofp.write("&%s\n" % node.nodeName)
+ else:
+ raise RuntimeError, "unsupported node type: %s" % nodeType
+
+
+def convert(ifp, ofp):
+ events = esistools.parse(ifp)
+ toktype, doc = events.getEvent()
+ fragment = doc.createDocumentFragment()
+ events.expandNode(fragment)
+
+ normalize(fragment)
+ simplify(doc, fragment)
+ handle_labels(doc, fragment)
+ handle_appendix(doc, fragment)
+ fixup_trailing_whitespace(doc, {
+ "abstract": "\n",
+ "title": "",
+ "chapter": "\n\n",
+ "section": "\n\n",
+ "subsection": "\n\n",
+ "subsubsection": "\n\n",
+ "paragraph": "\n\n",
+ "subparagraph": "\n\n",
+ })
+ cleanup_root_text(doc)
+ cleanup_trailing_parens(fragment, ["function", "method", "cfunction"])
+ cleanup_synopses(doc, fragment)
+ fixup_descriptors(doc, fragment)
+ fixup_verbatims(fragment)
+ normalize(fragment)
+ fixup_paras(doc, fragment)
+ fixup_sectionauthors(doc, fragment)
+ fixup_table_structures(doc, fragment)
+ fixup_rfc_references(doc, fragment)
+ fixup_signatures(doc, fragment)
+ add_node_ids(fragment)
+ fixup_refmodindexes(fragment)
+ fixup_bifuncindexes(fragment)
+ # Take care of ugly hacks in the LaTeX markup to avoid LaTeX and
+ # LaTeX2HTML screwing with GNU-style long options (the '--' problem).
+ join_adjacent_elements(fragment, "option")
+ #
+ d = {}
+ for gi in events.parser.get_empties():
+ d[gi] = gi
+ if d.has_key("author"):
+ del d["author"]
+ if d.has_key("rfc"):
+ del d["rfc"]
+ knownempty = d.has_key
+ #
+ try:
+ write_esis(fragment, ofp, knownempty)
+ except IOError, (err, msg):
+ # Ignore EPIPE; it just means that whoever we're writing to stopped
+ # reading. The rest of the output would be ignored. All other errors
+ # should still be reported,
+ if err != errno.EPIPE:
+ raise
+
+
+def main():
+ if len(sys.argv) == 1:
+ ifp = sys.stdin
+ ofp = sys.stdout
+ elif len(sys.argv) == 2:
+ ifp = open(sys.argv[1])
+ ofp = sys.stdout
+ elif len(sys.argv) == 3:
+ ifp = open(sys.argv[1])
+ import StringIO
+ ofp = StringIO.StringIO()
+ else:
+ usage()
+ sys.exit(2)
+ convert(ifp, ofp)
+ if len(sys.argv) == 3:
+ fp = open(sys.argv[2], "w")
+ fp.write(ofp.getvalue())
+ fp.close()
+ ofp.close()
+
+
+if __name__ == "__main__":
+ main()
diff --git a/doc/tools/sgmlconv/esis2sgml.py b/doc/tools/sgmlconv/esis2sgml.py
new file mode 100755
index 0000000..7bda929
--- /dev/null
+++ b/doc/tools/sgmlconv/esis2sgml.py
@@ -0,0 +1,263 @@
+#! /usr/bin/env python
+
+"""Convert ESIS events to SGML or XML markup.
+
+This is limited, but seems sufficient for the ESIS generated by the
+latex2esis.py script when run over the Python documentation.
+"""
+
+# This should have an explicit option to indicate whether the *INPUT* was
+# generated from an SGML or an XML application.
+
+import errno
+import esistools
+import os
+import re
+import string
+
+from xml.sax.saxutils import escape
+
+
+AUTOCLOSE = ()
+
+EMPTIES_FILENAME = "../sgml/empties.dat"
+LIST_EMPTIES = 0
+
+
+_elem_map = {}
+_attr_map = {}
+_token_map = {}
+
+_normalize_case = str
+
+def map_gi(sgmlgi, map):
+ uncased = _normalize_case(sgmlgi)
+ try:
+ return map[uncased]
+ except IndexError:
+ map[uncased] = sgmlgi
+ return sgmlgi
+
+def null_map_gi(sgmlgi, map):
+ return sgmlgi
+
+
+def format_attrs(attrs, xml=0):
+ attrs = attrs.items()
+ attrs.sort()
+ parts = []
+ append = parts.append
+ for name, value in attrs:
+ if xml:
+ append('%s="%s"' % (name, escape(value)))
+ else:
+ # this is a little bogus, but should do for now
+ if name == value and isnmtoken(value):
+ append(value)
+ elif istoken(value):
+ if value == "no" + name:
+ append(value)
+ else:
+ append("%s=%s" % (name, value))
+ else:
+ append('%s="%s"' % (name, escape(value)))
+ if parts:
+ parts.insert(0, '')
+ return string.join(parts)
+
+
+_nmtoken_rx = re.compile("[a-z][-._a-z0-9]*$", re.IGNORECASE)
+def isnmtoken(s):
+ return _nmtoken_rx.match(s) is not None
+
+_token_rx = re.compile("[a-z0-9][-._a-z0-9]*$", re.IGNORECASE)
+def istoken(s):
+ return _token_rx.match(s) is not None
+
+
+def convert(ifp, ofp, xml=0, autoclose=(), verbatims=()):
+ if xml:
+ autoclose = ()
+ attrs = {}
+ lastopened = None
+ knownempties = []
+ knownempty = 0
+ lastempty = 0
+ inverbatim = 0
+ while 1:
+ line = ifp.readline()
+ if not line:
+ break
+
+ type = line[0]
+ data = line[1:]
+ if data and data[-1] == "\n":
+ data = data[:-1]
+ if type == "-":
+ data = esistools.decode(data)
+ data = escape(data)
+ if not inverbatim:
+ data = string.replace(data, "---", "—")
+ ofp.write(data)
+ if "\n" in data:
+ lastopened = None
+ knownempty = 0
+ lastempty = 0
+ elif type == "(":
+ if data == "COMMENT":
+ ofp.write("<!--")
+ continue
+ data = map_gi(data, _elem_map)
+ if knownempty and xml:
+ ofp.write("<%s%s/>" % (data, format_attrs(attrs, xml)))
+ else:
+ ofp.write("<%s%s>" % (data, format_attrs(attrs, xml)))
+ if knownempty and data not in knownempties:
+ # accumulate knowledge!
+ knownempties.append(data)
+ attrs = {}
+ lastopened = data
+ lastempty = knownempty
+ knownempty = 0
+ inverbatim = data in verbatims
+ elif type == ")":
+ if data == "COMMENT":
+ ofp.write("-->")
+ continue
+ data = map_gi(data, _elem_map)
+ if xml:
+ if not lastempty:
+ ofp.write("</%s>" % data)
+ elif data not in knownempties:
+ if data in autoclose:
+ pass
+ elif lastopened == data:
+ ofp.write("</>")
+ else:
+ ofp.write("</%s>" % data)
+ lastopened = None
+ lastempty = 0
+ inverbatim = 0
+ elif type == "A":
+ name, type, value = string.split(data, " ", 2)
+ name = map_gi(name, _attr_map)
+ attrs[name] = esistools.decode(value)
+ elif type == "e":
+ knownempty = 1
+ elif type == "&":
+ ofp.write("&%s;" % data)
+ knownempty = 0
+ else:
+ raise RuntimeError, "unrecognized ESIS event type: '%s'" % type
+
+ if LIST_EMPTIES:
+ dump_empty_element_names(knownempties)
+
+
+def dump_empty_element_names(knownempties):
+ d = {}
+ for gi in knownempties:
+ d[gi] = gi
+ knownempties.append("")
+ if os.path.isfile(EMPTIES_FILENAME):
+ fp = open(EMPTIES_FILENAME)
+ while 1:
+ line = fp.readline()
+ if not line:
+ break
+ gi = string.strip(line)
+ if gi:
+ d[gi] = gi
+ fp = open(EMPTIES_FILENAME, "w")
+ gilist = d.keys()
+ gilist.sort()
+ fp.write(string.join(gilist, "\n"))
+ fp.write("\n")
+ fp.close()
+
+
+def update_gi_map(map, names, fromsgml=1):
+ for name in string.split(names, ","):
+ if fromsgml:
+ uncased = string.lower(name)
+ else:
+ uncased = name
+ map[uncased] = name
+
+
+def main():
+ import getopt
+ import sys
+ #
+ autoclose = AUTOCLOSE
+ xml = 1
+ xmldecl = 0
+ elem_names = ''
+ attr_names = ''
+ value_names = ''
+ verbatims = ('verbatim', 'interactive-session')
+ opts, args = getopt.getopt(sys.argv[1:], "adesx",
+ ["autoclose=", "declare", "sgml", "xml",
+ "elements-map=", "attributes-map",
+ "values-map="])
+ for opt, arg in opts:
+ if opt in ("-d", "--declare"):
+ xmldecl = 1
+ elif opt == "-e":
+ global LIST_EMPTIES
+ LIST_EMPTIES = 1
+ elif opt in ("-s", "--sgml"):
+ xml = 0
+ elif opt in ("-x", "--xml"):
+ xml = 1
+ elif opt in ("-a", "--autoclose"):
+ autoclose = string.split(arg, ",")
+ elif opt == "--elements-map":
+ elem_names = ("%s,%s" % (elem_names, arg))[1:]
+ elif opt == "--attributes-map":
+ attr_names = ("%s,%s" % (attr_names, arg))[1:]
+ elif opt == "--values-map":
+ value_names = ("%s,%s" % (value_names, arg))[1:]
+ #
+ # open input streams:
+ #
+ if len(args) == 0:
+ ifp = sys.stdin
+ ofp = sys.stdout
+ elif len(args) == 1:
+ ifp = open(args[0])
+ ofp = sys.stdout
+ elif len(args) == 2:
+ ifp = open(args[0])
+ ofp = open(args[1], "w")
+ else:
+ usage()
+ sys.exit(2)
+ #
+ # setup the name maps:
+ #
+ if elem_names or attr_names or value_names:
+ # assume the origin was SGML; ignore case of the names from the ESIS
+ # stream but set up conversion tables to get the case right on output
+ global _normalize_case
+ _normalize_case = string.lower
+ update_gi_map(_elem_map, string.split(elem_names, ","))
+ update_gi_map(_attr_map, string.split(attr_names, ","))
+ update_gi_map(_values_map, string.split(value_names, ","))
+ else:
+ global map_gi
+ map_gi = null_map_gi
+ #
+ # run the conversion:
+ #
+ try:
+ if xml and xmldecl:
+ opf.write('<?xml version="1.0" encoding="iso8859-1"?>\n')
+ convert(ifp, ofp, xml=xml, autoclose=autoclose, verbatims=verbatims)
+ except IOError, (err, msg):
+ if err != errno.EPIPE:
+ raise
+
+
+if __name__ == "__main__":
+ main()
diff --git a/doc/tools/sgmlconv/esistools.py b/doc/tools/sgmlconv/esistools.py
new file mode 100644
index 0000000..893af76
--- /dev/null
+++ b/doc/tools/sgmlconv/esistools.py
@@ -0,0 +1,309 @@
+"""Miscellaneous utility functions useful for dealing with ESIS streams."""
+
+import re
+import string
+
+import xml.dom.pulldom
+
+import xml.sax
+import xml.sax.handler
+import xml.sax.xmlreader
+
+
+_data_match = re.compile(r"[^\\][^\\]*").match
+
+def decode(s):
+ r = ''
+ while s:
+ m = _data_match(s)
+ if m:
+ r = r + m.group()
+ s = s[m.end():]
+ elif s[1] == "\\":
+ r = r + "\\"
+ s = s[2:]
+ elif s[1] == "n":
+ r = r + "\n"
+ s = s[2:]
+ elif s[1] == "%":
+ s = s[2:]
+ n, s = s.split(";", 1)
+ r = r + unichr(int(n))
+ else:
+ raise ValueError, "can't handle " + `s`
+ return r
+
+
+_charmap = {}
+for c in map(chr, range(256)):
+ _charmap[c] = c
+_charmap["\n"] = r"\n"
+_charmap["\\"] = r"\\"
+del c
+
+_null_join = ''.join
+def encode(s):
+ return _null_join(map(_charmap.get, s))
+
+
+class ESISReader(xml.sax.xmlreader.XMLReader):
+ """SAX Reader which reads from an ESIS stream.
+
+ No verification of the document structure is performed by the
+ reader; a general verifier could be used as the target
+ ContentHandler instance.
+
+ """
+ _decl_handler = None
+ _lexical_handler = None
+
+ _public_id = None
+ _system_id = None
+
+ _buffer = ""
+ _is_empty = 0
+ _lineno = 0
+ _started = 0
+
+ def __init__(self, contentHandler=None, errorHandler=None):
+ xml.sax.xmlreader.XMLReader.__init__(self)
+ self._attrs = {}
+ self._attributes = Attributes(self._attrs)
+ self._locator = Locator()
+ self._empties = {}
+ if contentHandler:
+ self.setContentHandler(contentHandler)
+ if errorHandler:
+ self.setErrorHandler(errorHandler)
+
+ def get_empties(self):
+ return self._empties.keys()
+
+ #
+ # XMLReader interface
+ #
+
+ def parse(self, source):
+ raise RuntimeError
+ self._locator._public_id = source.getPublicId()
+ self._locator._system_id = source.getSystemId()
+ fp = source.getByteStream()
+ handler = self.getContentHandler()
+ if handler:
+ handler.startDocument()
+ lineno = 0
+ while 1:
+ token, data = self._get_token(fp)
+ if token is None:
+ break
+ lineno = lineno + 1
+ self._locator._lineno = lineno
+ self._handle_token(token, data)
+ handler = self.getContentHandler()
+ if handler:
+ handler.startDocument()
+
+ def feed(self, data):
+ if not self._started:
+ handler = self.getContentHandler()
+ if handler:
+ handler.startDocument()
+ self._started = 1
+ data = self._buffer + data
+ self._buffer = None
+ lines = data.split("\n")
+ if lines:
+ for line in lines[:-1]:
+ self._lineno = self._lineno + 1
+ self._locator._lineno = self._lineno
+ if not line:
+ e = xml.sax.SAXParseException(
+ "ESIS input line contains no token type mark",
+ None, self._locator)
+ self.getErrorHandler().error(e)
+ else:
+ self._handle_token(line[0], line[1:])
+ self._buffer = lines[-1]
+ else:
+ self._buffer = ""
+
+ def close(self):
+ handler = self.getContentHandler()
+ if handler:
+ handler.endDocument()
+ self._buffer = ""
+
+ def _get_token(self, fp):
+ try:
+ line = fp.readline()
+ except IOError, e:
+ e = SAXException("I/O error reading input stream", e)
+ self.getErrorHandler().fatalError(e)
+ return
+ if not line:
+ return None, None
+ if line[-1] == "\n":
+ line = line[:-1]
+ if not line:
+ e = xml.sax.SAXParseException(
+ "ESIS input line contains no token type mark",
+ None, self._locator)
+ self.getErrorHandler().error(e)
+ return
+ return line[0], line[1:]
+
+ def _handle_token(self, token, data):
+ handler = self.getContentHandler()
+ if token == '-':
+ if data and handler:
+ handler.characters(decode(data))
+ elif token == ')':
+ if handler:
+ handler.endElement(decode(data))
+ elif token == '(':
+ if self._is_empty:
+ self._empties[data] = 1
+ if handler:
+ handler.startElement(data, self._attributes)
+ self._attrs.clear()
+ self._is_empty = 0
+ elif token == 'A':
+ name, value = data.split(' ', 1)
+ if value != "IMPLIED":
+ type, value = value.split(' ', 1)
+ self._attrs[name] = (decode(value), type)
+ elif token == '&':
+ # entity reference in SAX?
+ pass
+ elif token == '?':
+ if handler:
+ if ' ' in data:
+ target, data = string.split(data, None, 1)
+ else:
+ target, data = data, ""
+ handler.processingInstruction(target, decode(data))
+ elif token == 'N':
+ handler = self.getDTDHandler()
+ if handler:
+ handler.notationDecl(data, self._public_id, self._system_id)
+ self._public_id = None
+ self._system_id = None
+ elif token == 'p':
+ self._public_id = decode(data)
+ elif token == 's':
+ self._system_id = decode(data)
+ elif token == 'e':
+ self._is_empty = 1
+ elif token == 'C':
+ pass
+ else:
+ e = SAXParseException("unknown ESIS token in event stream",
+ None, self._locator)
+ self.getErrorHandler().error(e)
+
+ def setContentHandler(self, handler):
+ old = self.getContentHandler()
+ if old:
+ old.setDocumentLocator(None)
+ if handler:
+ handler.setDocumentLocator(self._locator)
+ xml.sax.xmlreader.XMLReader.setContentHandler(self, handler)
+
+ def getProperty(self, property):
+ if property == xml.sax.handler.property_lexical_handler:
+ return self._lexical_handler
+
+ elif property == xml.sax.handler.property_declaration_handler:
+ return self._decl_handler
+
+ else:
+ raise xml.sax.SAXNotRecognizedException("unknown property %s"
+ % `property`)
+
+ def setProperty(self, property, value):
+ if property == xml.sax.handler.property_lexical_handler:
+ if self._lexical_handler:
+ self._lexical_handler.setDocumentLocator(None)
+ if value:
+ value.setDocumentLocator(self._locator)
+ self._lexical_handler = value
+
+ elif property == xml.sax.handler.property_declaration_handler:
+ if self._decl_handler:
+ self._decl_handler.setDocumentLocator(None)
+ if value:
+ value.setDocumentLocator(self._locator)
+ self._decl_handler = value
+
+ else:
+ raise xml.sax.SAXNotRecognizedException()
+
+ def getFeature(self, feature):
+ if feature == xml.sax.handler.feature_namespaces:
+ return 1
+ else:
+ return xml.sax.xmlreader.XMLReader.getFeature(self, feature)
+
+ def setFeature(self, feature, enabled):
+ if feature == xml.sax.handler.feature_namespaces:
+ pass
+ else:
+ xml.sax.xmlreader.XMLReader.setFeature(self, feature, enabled)
+
+
+class Attributes(xml.sax.xmlreader.AttributesImpl):
+ # self._attrs has the form {name: (value, type)}
+
+ def getType(self, name):
+ return self._attrs[name][1]
+
+ def getValue(self, name):
+ return self._attrs[name][0]
+
+ def getValueByQName(self, name):
+ return self._attrs[name][0]
+
+ def __getitem__(self, name):
+ return self._attrs[name][0]
+
+ def get(self, name, default=None):
+ if self._attrs.has_key(name):
+ return self._attrs[name][0]
+ return default
+
+ def items(self):
+ L = []
+ for name, (value, type) in self._attrs.items():
+ L.append((name, value))
+ return L
+
+ def values(self):
+ L = []
+ for value, type in self._attrs.values():
+ L.append(value)
+ return L
+
+
+class Locator(xml.sax.xmlreader.Locator):
+ _lineno = -1
+ _public_id = None
+ _system_id = None
+
+ def getLineNumber(self):
+ return self._lineno
+
+ def getPublicId(self):
+ return self._public_id
+
+ def getSystemId(self):
+ return self._system_id
+
+
+def parse(stream_or_string, parser=None):
+ if type(stream_or_string) in [type(""), type(u"")]:
+ stream = open(stream_or_string)
+ else:
+ stream = stream_or_string
+ if not parser:
+ parser = ESISReader()
+ return xml.dom.pulldom.DOMEventStream(stream, parser, (2 ** 14) - 20)
diff --git a/doc/tools/sgmlconv/latex2esis.py b/doc/tools/sgmlconv/latex2esis.py
new file mode 100755
index 0000000..74e1dc7
--- /dev/null
+++ b/doc/tools/sgmlconv/latex2esis.py
@@ -0,0 +1,555 @@
+#! /usr/bin/env python
+
+"""Generate ESIS events based on a LaTeX source document and
+configuration data.
+
+The conversion is not strong enough to work with arbitrary LaTeX
+documents; it has only been designed to work with the highly stylized
+markup used in the standard Python documentation. A lot of
+information about specific markup is encoded in the control table
+passed to the convert() function; changing this table can allow this
+tool to support additional LaTeX markups.
+
+The format of the table is largely undocumented; see the commented
+headers where the table is specified in main(). There is no provision
+to load an alternate table from an external file.
+"""
+
+import errno
+import getopt
+import os
+import re
+import string
+import sys
+import UserList
+import xml.sax.saxutils
+
+from types import ListType, StringType, TupleType
+
+try:
+ from xml.parsers.xmllib import XMLParser
+except ImportError:
+ from xmllib import XMLParser
+
+
+from esistools import encode
+
+
+DEBUG = 0
+
+
+class LaTeXFormatError(Exception):
+ pass
+
+
+class LaTeXStackError(LaTeXFormatError):
+ def __init__(self, found, stack):
+ msg = "environment close for %s doesn't match;\n stack = %s" \
+ % (found, stack)
+ self.found = found
+ self.stack = stack[:]
+ LaTeXFormatError.__init__(self, msg)
+
+
+_begin_env_rx = re.compile(r"[\\]begin{([^}]*)}")
+_end_env_rx = re.compile(r"[\\]end{([^}]*)}")
+_begin_macro_rx = re.compile(r"[\\]([a-zA-Z]+[*]?) ?({|\s*\n?)")
+_comment_rx = re.compile("%+ ?(.*)\n[ \t]*")
+_text_rx = re.compile(r"[^]~%\\{}]+")
+_optional_rx = re.compile(r"\s*[[]([^]]*)[]]")
+# _parameter_rx is this complicated to allow {...} inside a parameter;
+# this is useful to match tabular layout specifications like {c|p{24pt}}
+_parameter_rx = re.compile("[ \n]*{(([^{}}]|{[^}]*})*)}")
+_token_rx = re.compile(r"[a-zA-Z][a-zA-Z0-9.-]*$")
+_start_group_rx = re.compile("[ \n]*{")
+_start_optional_rx = re.compile("[ \n]*[[]")
+
+
+ESCAPED_CHARS = "$%#^ {}&~"
+
+
+def dbgmsg(msg):
+ if DEBUG:
+ sys.stderr.write(msg + "\n")
+
+def pushing(name, point, depth):
+ dbgmsg("pushing <%s> at %s" % (name, point))
+
+def popping(name, point, depth):
+ dbgmsg("popping </%s> at %s" % (name, point))
+
+
+class _Stack(UserList.UserList):
+ def append(self, entry):
+ if type(entry) is not StringType:
+ raise LaTeXFormatError("cannot push non-string on stack: "
+ + `entry`)
+ #dbgmsg("%s<%s>" % (" "*len(self.data), entry))
+ self.data.append(entry)
+
+ def pop(self, index=-1):
+ entry = self.data[index]
+ del self.data[index]
+ #dbgmsg("%s</%s>" % (" "*len(self.data), entry))
+
+ def __delitem__(self, index):
+ entry = self.data[index]
+ del self.data[index]
+ #dbgmsg("%s</%s>" % (" "*len(self.data), entry))
+
+
+def new_stack():
+ if DEBUG:
+ return _Stack()
+ return []
+
+
+class Conversion:
+ def __init__(self, ifp, ofp, table):
+ self.write = ofp.write
+ self.ofp = ofp
+ self.table = table
+ self.line = string.join(map(string.rstrip, ifp.readlines()), "\n")
+ self.preamble = 1
+
+ def convert(self):
+ self.subconvert()
+
+ def subconvert(self, endchar=None, depth=0):
+ #
+ # Parses content, including sub-structures, until the character
+ # 'endchar' is found (with no open structures), or until the end
+ # of the input data is endchar is None.
+ #
+ stack = new_stack()
+ line = self.line
+ while line:
+ if line[0] == endchar and not stack:
+ self.line = line
+ return line
+ m = _comment_rx.match(line)
+ if m:
+ text = m.group(1)
+ if text:
+ self.write("(COMMENT\n- %s \n)COMMENT\n-\\n\n"
+ % encode(text))
+ line = line[m.end():]
+ continue
+ m = _begin_env_rx.match(line)
+ if m:
+ name = m.group(1)
+ entry = self.get_env_entry(name)
+ # re-write to use the macro handler
+ line = r"\%s %s" % (name, line[m.end():])
+ continue
+ m = _end_env_rx.match(line)
+ if m:
+ # end of environment
+ envname = m.group(1)
+ entry = self.get_entry(envname)
+ while stack and envname != stack[-1] \
+ and stack[-1] in entry.endcloses:
+ self.write(")%s\n" % stack.pop())
+ if stack and envname == stack[-1]:
+ self.write(")%s\n" % entry.outputname)
+ del stack[-1]
+ else:
+ raise LaTeXStackError(envname, stack)
+ line = line[m.end():]
+ continue
+ m = _begin_macro_rx.match(line)
+ if m:
+ # start of macro
+ macroname = m.group(1)
+ if macroname == "c":
+ # Ugh! This is a combining character...
+ endpos = m.end()
+ self.combining_char("c", line[endpos])
+ line = line[endpos + 1:]
+ continue
+ entry = self.get_entry(macroname)
+ if entry.verbatim:
+ # magic case!
+ pos = string.find(line, "\\end{%s}" % macroname)
+ text = line[m.end(1):pos]
+ stack.append(entry.name)
+ self.write("(%s\n" % entry.outputname)
+ self.write("-%s\n" % encode(text))
+ self.write(")%s\n" % entry.outputname)
+ stack.pop()
+ line = line[pos + len("\\end{%s}" % macroname):]
+ continue
+ while stack and stack[-1] in entry.closes:
+ top = stack.pop()
+ topentry = self.get_entry(top)
+ if topentry.outputname:
+ self.write(")%s\n-\\n\n" % topentry.outputname)
+ #
+ if entry.outputname:
+ if entry.empty:
+ self.write("e\n")
+ #
+ params, optional, empty, environ = self.start_macro(macroname)
+ # rip off the macroname
+ if params:
+ line = line[m.end(1):]
+ elif empty:
+ line = line[m.end(1):]
+ else:
+ line = line[m.end():]
+ opened = 0
+ implied_content = 0
+
+ # handle attribute mappings here:
+ for pentry in params:
+ if pentry.type == "attribute":
+ if pentry.optional:
+ m = _optional_rx.match(line)
+ if m and entry.outputname:
+ line = line[m.end():]
+ self.dump_attr(pentry, m.group(1))
+ elif pentry.text and entry.outputname:
+ # value supplied by conversion spec:
+ self.dump_attr(pentry, pentry.text)
+ else:
+ m = _parameter_rx.match(line)
+ if not m:
+ raise LaTeXFormatError(
+ "could not extract parameter %s for %s: %s"
+ % (pentry.name, macroname, `line[:100]`))
+ if entry.outputname:
+ self.dump_attr(pentry, m.group(1))
+ line = line[m.end():]
+ elif pentry.type == "child":
+ if pentry.optional:
+ m = _optional_rx.match(line)
+ if m:
+ line = line[m.end():]
+ if entry.outputname and not opened:
+ opened = 1
+ self.write("(%s\n" % entry.outputname)
+ stack.append(macroname)
+ stack.append(pentry.name)
+ self.write("(%s\n" % pentry.name)
+ self.write("-%s\n" % encode(m.group(1)))
+ self.write(")%s\n" % pentry.name)
+ stack.pop()
+ else:
+ if entry.outputname and not opened:
+ opened = 1
+ self.write("(%s\n" % entry.outputname)
+ stack.append(entry.name)
+ self.write("(%s\n" % pentry.name)
+ stack.append(pentry.name)
+ self.line = skip_white(line)[1:]
+ line = self.subconvert(
+ "}", len(stack) + depth + 1)[1:]
+ self.write(")%s\n" % stack.pop())
+ elif pentry.type == "content":
+ if pentry.implied:
+ implied_content = 1
+ else:
+ if entry.outputname and not opened:
+ opened = 1
+ self.write("(%s\n" % entry.outputname)
+ stack.append(entry.name)
+ line = skip_white(line)
+ if line[0] != "{":
+ raise LaTeXFormatError(
+ "missing content for " + macroname)
+ self.line = line[1:]
+ line = self.subconvert("}", len(stack) + depth + 1)
+ if line and line[0] == "}":
+ line = line[1:]
+ elif pentry.type == "text" and pentry.text:
+ if entry.outputname and not opened:
+ opened = 1
+ stack.append(entry.name)
+ self.write("(%s\n" % entry.outputname)
+ #dbgmsg("--- text: %s" % `pentry.text`)
+ self.write("-%s\n" % encode(pentry.text))
+ elif pentry.type == "entityref":
+ self.write("&%s\n" % pentry.name)
+ if entry.outputname:
+ if not opened:
+ self.write("(%s\n" % entry.outputname)
+ stack.append(entry.name)
+ if not implied_content:
+ self.write(")%s\n" % entry.outputname)
+ stack.pop()
+ continue
+ if line[0] == endchar and not stack:
+ self.line = line[1:]
+ return self.line
+ if line[0] == "}":
+ # end of macro or group
+ macroname = stack[-1]
+ if macroname:
+ conversion = self.table[macroname]
+ if conversion.outputname:
+ # otherwise, it was just a bare group
+ self.write(")%s\n" % conversion.outputname)
+ del stack[-1]
+ line = line[1:]
+ continue
+ if line[0] == "~":
+ # don't worry about the "tie" aspect of this command
+ line = line[1:]
+ self.write("- \n")
+ continue
+ if line[0] == "{":
+ stack.append("")
+ line = line[1:]
+ continue
+ if line[0] == "\\" and line[1] in ESCAPED_CHARS:
+ self.write("-%s\n" % encode(line[1]))
+ line = line[2:]
+ continue
+ if line[:2] == r"\\":
+ self.write("(BREAK\n)BREAK\n")
+ line = line[2:]
+ continue
+ if line[:2] == r"\_":
+ line = "_" + line[2:]
+ continue
+ if line[:2] in (r"\'", r'\"'):
+ # combining characters...
+ self.combining_char(line[1], line[2])
+ line = line[3:]
+ continue
+ m = _text_rx.match(line)
+ if m:
+ text = encode(m.group())
+ self.write("-%s\n" % text)
+ line = line[m.end():]
+ continue
+ # special case because of \item[]
+ # XXX can we axe this???
+ if line[0] == "]":
+ self.write("-]\n")
+ line = line[1:]
+ continue
+ # avoid infinite loops
+ extra = ""
+ if len(line) > 100:
+ extra = "..."
+ raise LaTeXFormatError("could not identify markup: %s%s"
+ % (`line[:100]`, extra))
+ while stack:
+ entry = self.get_entry(stack[-1])
+ if entry.closes:
+ self.write(")%s\n-%s\n" % (entry.outputname, encode("\n")))
+ del stack[-1]
+ else:
+ break
+ if stack:
+ raise LaTeXFormatError("elements remain on stack: "
+ + string.join(stack, ", "))
+ # otherwise we just ran out of input here...
+
+ # This is a really limited table of combinations, but it will have
+ # to do for now.
+ _combinations = {
+ ("c", "c"): 0x00E7,
+ ("'", "e"): 0x00E9,
+ ('"', "o"): 0x00F6,
+ }
+
+ def combining_char(self, prefix, char):
+ ordinal = self._combinations[(prefix, char)]
+ self.write("-\\%%%d;\n" % ordinal)
+
+ def start_macro(self, name):
+ conversion = self.get_entry(name)
+ parameters = conversion.parameters
+ optional = parameters and parameters[0].optional
+ return parameters, optional, conversion.empty, conversion.environment
+
+ def get_entry(self, name):
+ entry = self.table.get(name)
+ if entry is None:
+ dbgmsg("get_entry(%s) failing; building default entry!" % `name`)
+ # not defined; build a default entry:
+ entry = TableEntry(name)
+ entry.has_content = 1
+ entry.parameters.append(Parameter("content"))
+ self.table[name] = entry
+ return entry
+
+ def get_env_entry(self, name):
+ entry = self.table.get(name)
+ if entry is None:
+ # not defined; build a default entry:
+ entry = TableEntry(name, 1)
+ entry.has_content = 1
+ entry.parameters.append(Parameter("content"))
+ entry.parameters[-1].implied = 1
+ self.table[name] = entry
+ elif not entry.environment:
+ raise LaTeXFormatError(
+ name + " is defined as a macro; expected environment")
+ return entry
+
+ def dump_attr(self, pentry, value):
+ if not (pentry.name and value):
+ return
+ if _token_rx.match(value):
+ dtype = "TOKEN"
+ else:
+ dtype = "CDATA"
+ self.write("A%s %s %s\n" % (pentry.name, dtype, encode(value)))
+
+
+def convert(ifp, ofp, table):
+ c = Conversion(ifp, ofp, table)
+ try:
+ c.convert()
+ except IOError, (err, msg):
+ if err != errno.EPIPE:
+ raise
+
+
+def skip_white(line):
+ while line and line[0] in " %\n\t\r":
+ line = string.lstrip(line[1:])
+ return line
+
+
+
+class TableEntry:
+ def __init__(self, name, environment=0):
+ self.name = name
+ self.outputname = name
+ self.environment = environment
+ self.empty = not environment
+ self.has_content = 0
+ self.verbatim = 0
+ self.auto_close = 0
+ self.parameters = []
+ self.closes = []
+ self.endcloses = []
+
+class Parameter:
+ def __init__(self, type, name=None, optional=0):
+ self.type = type
+ self.name = name
+ self.optional = optional
+ self.text = ''
+ self.implied = 0
+
+
+class TableParser(XMLParser):
+ def __init__(self, table=None):
+ if table is None:
+ table = {}
+ self.__table = table
+ self.__current = None
+ self.__buffer = ''
+ XMLParser.__init__(self)
+
+ def get_table(self):
+ for entry in self.__table.values():
+ if entry.environment and not entry.has_content:
+ p = Parameter("content")
+ p.implied = 1
+ entry.parameters.append(p)
+ entry.has_content = 1
+ return self.__table
+
+ def start_environment(self, attrs):
+ name = attrs["name"]
+ self.__current = TableEntry(name, environment=1)
+ self.__current.verbatim = attrs.get("verbatim") == "yes"
+ if attrs.has_key("outputname"):
+ self.__current.outputname = attrs.get("outputname")
+ self.__current.endcloses = string.split(attrs.get("endcloses", ""))
+ def end_environment(self):
+ self.end_macro()
+
+ def start_macro(self, attrs):
+ name = attrs["name"]
+ self.__current = TableEntry(name)
+ self.__current.closes = string.split(attrs.get("closes", ""))
+ if attrs.has_key("outputname"):
+ self.__current.outputname = attrs.get("outputname")
+ def end_macro(self):
+ self.__table[self.__current.name] = self.__current
+ self.__current = None
+
+ def start_attribute(self, attrs):
+ name = attrs.get("name")
+ optional = attrs.get("optional") == "yes"
+ if name:
+ p = Parameter("attribute", name, optional=optional)
+ else:
+ p = Parameter("attribute", optional=optional)
+ self.__current.parameters.append(p)
+ self.__buffer = ''
+ def end_attribute(self):
+ self.__current.parameters[-1].text = self.__buffer
+
+ def start_entityref(self, attrs):
+ name = attrs["name"]
+ p = Parameter("entityref", name)
+ self.__current.parameters.append(p)
+
+ def start_child(self, attrs):
+ name = attrs["name"]
+ p = Parameter("child", name, attrs.get("optional") == "yes")
+ self.__current.parameters.append(p)
+ self.__current.empty = 0
+
+ def start_content(self, attrs):
+ p = Parameter("content")
+ p.implied = attrs.get("implied") == "yes"
+ if self.__current.environment:
+ p.implied = 1
+ self.__current.parameters.append(p)
+ self.__current.has_content = 1
+ self.__current.empty = 0
+
+ def start_text(self, attrs):
+ self.__current.empty = 0
+ self.__buffer = ''
+ def end_text(self):
+ p = Parameter("text")
+ p.text = self.__buffer
+ self.__current.parameters.append(p)
+
+ def handle_data(self, data):
+ self.__buffer = self.__buffer + data
+
+
+def load_table(fp, table=None):
+ parser = TableParser(table=table)
+ parser.feed(fp.read())
+ parser.close()
+ return parser.get_table()
+
+
+def main():
+ global DEBUG
+ #
+ opts, args = getopt.getopt(sys.argv[1:], "D", ["debug"])
+ for opt, arg in opts:
+ if opt in ("-D", "--debug"):
+ DEBUG = DEBUG + 1
+ if len(args) == 0:
+ ifp = sys.stdin
+ ofp = sys.stdout
+ elif len(args) == 1:
+ ifp = open(args)
+ ofp = sys.stdout
+ elif len(args) == 2:
+ ifp = open(args[0])
+ ofp = open(args[1], "w")
+ else:
+ usage()
+ sys.exit(2)
+
+ table = load_table(open(os.path.join(sys.path[0], 'conversion.xml')))
+ convert(ifp, ofp, table)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/doc/tools/sgmlconv/make.rules b/doc/tools/sgmlconv/make.rules
new file mode 100644
index 0000000..93579c5
--- /dev/null
+++ b/doc/tools/sgmlconv/make.rules
@@ -0,0 +1,48 @@
+# -*- makefile -*-
+#
+# Extra magic needed by the LaTeX->XML conversion process. This requires
+# $(TOOLSDIR) to be properly defined.
+
+DOCFIXER= $(TOOLSDIR)/sgmlconv/docfixer.py
+ESIS2ML= $(TOOLSDIR)/sgmlconv/esis2sgml.py
+LATEX2ESIS= $(TOOLSDIR)/sgmlconv/latex2esis.py
+CONVERSION= $(TOOLSDIR)/sgmlconv/conversion.xml
+
+ESISTARGETS= $(patsubst %.tex,%.esis,$(wildcard *.tex))
+ESIS1TARGETS= $(patsubst %.tex,%.esis1,$(wildcard *.tex))
+XMLTARGETS= $(patsubst %.tex,%.xml,$(wildcard *.tex))
+
+L2EFLAGS=
+
+all: xml
+
+esis: $(ESISTARGETS)
+esis1: $(ESIS1TARGETS)
+xml: $(XMLTARGETS)
+
+ESISTOOLS= $(TOOLSDIR)/sgmlconv/esistools.py
+
+$(ESISTARGETS): $(LATEX2ESIS) $(DOCFIXER) $(ESISTOOLS) $(CONVERSION)
+$(ESIS1TARGETS): $(LATEX2ESIS) $(CONVERSION)
+# This variant is easier to work with while debugging the conversion spec:
+#$(ESISTARGETS): $(LATEX2ESIS) $(DOCFIXER) $(ESISTOOLS)
+$(XMLTARGETS): $(ESIS2ML)
+
+
+.SUFFIXES: .esis .esis1 .tex .xml
+
+.tex.esis1:
+ $(LATEX2ESIS) $(L2EFLAGS) $< $@
+
+.esis1.esis:
+ $(DOCFIXER) $< $@
+
+.esis.xml:
+ $(ESIS2ML) --xml $< $@
+
+
+clean:
+ rm -f *.esis *.esis1
+
+clobber: clean
+ rm -f *.xml
diff --git a/doc/tools/support.py b/doc/tools/support.py
new file mode 100644
index 0000000..8df04a3
--- /dev/null
+++ b/doc/tools/support.py
@@ -0,0 +1,149 @@
+"""Miscellaneous support code shared by some of the tool scripts.
+
+This includes option parsing code, HTML formatting code, and a couple of
+useful helpers.
+
+"""
+__version__ = '$Revision: 1.1.1.1 $'
+
+
+import getopt
+import string
+import sys
+
+
+class Options:
+ __short_args = "a:c:ho:"
+ __long_args = [
+ # script controls
+ "columns=", "help", "output=",
+
+ # content components
+ "address=", "iconserver=",
+ "title=", "uplink=", "uptitle="]
+
+ outputfile = "-"
+ columns = 1
+ letters = 0
+ uplink = "./"
+ uptitle = "Python Documentation Index"
+
+ def __init__(self):
+ self.args = []
+ self.variables = {"address": "",
+ "iconserver": "icons",
+ "imgtype": "gif",
+ "title": "Global Module Index",
+ }
+
+ def add_args(self, short=None, long=None):
+ if short:
+ self.__short_args = self.__short_args + short
+ if long:
+ self.__long_args = self.__long_args + long
+
+ def parse(self, args):
+ try:
+ opts, args = getopt.getopt(args, self.__short_args,
+ self.__long_args)
+ except getopt.error:
+ sys.stdout = sys.stderr
+ self.usage()
+ sys.exit(2)
+ self.args = self.args + args
+ for opt, val in opts:
+ if opt in ("-a", "--address"):
+ val = string.strip(val)
+ if val:
+ val = "<address>\n%s\n</address>\n" % val
+ self.variables["address"] = val
+ elif opt in ("-h", "--help"):
+ self.usage()
+ sys.exit()
+ elif opt in ("-o", "--output"):
+ self.outputfile = val
+ elif opt in ("-c", "--columns"):
+ self.columns = int(val)
+ elif opt == "--title":
+ self.variables["title"] = val.strip()
+ elif opt == "--uplink":
+ self.uplink = val.strip()
+ elif opt == "--uptitle":
+ self.uptitle = val.strip()
+ elif opt == "--iconserver":
+ self.variables["iconserver"] = val.strip() or "."
+ else:
+ self.handle_option(opt, val)
+ if self.uplink and self.uptitle:
+ self.variables["uplinkalt"] = "up"
+ self.variables["uplinkicon"] = "up"
+ else:
+ self.variables["uplinkalt"] = ""
+ self.variables["uplinkicon"] = "blank"
+ self.variables["uplink"] = self.uplink
+ self.variables["uptitle"] = self.uptitle
+
+ def handle_option(self, opt, val):
+ raise getopt.error("option %s not recognized" % opt)
+
+ def get_header(self):
+ return HEAD % self.variables
+
+ def get_footer(self):
+ return TAIL % self.variables
+
+ def get_output_file(self, filename=None):
+ if filename is None:
+ filename = self.outputfile
+ if filename == "-":
+ return sys.stdout
+ else:
+ return open(filename, "w")
+
+
+NAVIGATION = '''\
+<div class="navigation">
+<table width="100%%" cellpadding="0" cellspacing="2">
+<tr>
+<td><img width="32" height="32" align="bottom" border="0" alt=""
+ src="%(iconserver)s/blank.%(imgtype)s"></td>
+<td><a href="%(uplink)s"
+ title="%(uptitle)s"><img width="32" height="32" align="bottom" border="0"
+ alt="%(uplinkalt)s"
+ src="%(iconserver)s/%(uplinkicon)s.%(imgtype)s"></a></td>
+<td><img width="32" height="32" align="bottom" border="0" alt=""
+ src="%(iconserver)s/blank.%(imgtype)s"></td>
+<td align="center" width="100%%">%(title)s</td>
+<td><img width="32" height="32" align="bottom" border="0" alt=""
+ src="%(iconserver)s/blank.%(imgtype)s"></td>
+<td><img width="32" height="32" align="bottom" border="0" alt=""
+ src="%(iconserver)s/blank.%(imgtype)s"></td>
+<td><img width="32" height="32" align="bottom" border="0" alt=""
+ src="%(iconserver)s/blank.%(imgtype)s"></td>
+</tr></table>
+<b class="navlabel">Up:</b> <span class="sectref"><a href="%(uplink)s"
+ title="%(uptitle)s">%(uptitle)s</A></span>
+<br></div>
+'''
+
+HEAD = '''\
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+ <title>%(title)s</title>
+ <meta name="description" content="%(title)s">
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+ <link rel="STYLESHEET" href="lib/lib.css">
+</head>
+<body>
+''' + NAVIGATION + '''\
+<hr>
+
+<h2>%(title)s</h2>
+
+'''
+
+TAIL = "<hr>\n" + NAVIGATION + '''\
+%(address)s</body>
+</html>
+'''
diff --git a/doc/tools/templates/howto.tex b/doc/tools/templates/howto.tex
new file mode 100644
index 0000000..fcb213a
--- /dev/null
+++ b/doc/tools/templates/howto.tex
@@ -0,0 +1,105 @@
+\documentclass{howto}
+
+% This is a template for short or medium-size Python-related documents,
+% mostly notably the series of HOWTOs, but it can be used for any
+% document you like.
+
+% The title should be descriptive enough for people to be able to find
+% the relevant document.
+\title{Spammifying Sprockets in Python}
+
+% Increment the release number whenever significant changes are made.
+% The author and/or editor can define 'significant' however they like.
+\release{0.00}
+
+% At minimum, give your name and an e-mail address. You can include a
+% snail-mail address if you like.
+\author{Me, 'cause I wrote it}
+\authoraddress{Me, 'cause I'm self-employed.}
+
+\begin{document}
+\maketitle
+
+% This makes the Abstract go on a separate page in the HTML version;
+% if a copyright notice is used, it should go immediately after this.
+%
+\ifhtml
+\chapter*{Front Matter\label{front}}
+\fi
+
+% Copyright statement should go here, if needed.
+% ...
+
+% The abstract should be a paragraph or two long, and describe the
+% scope of the document.
+\begin{abstract}
+\noindent
+This document describes how to spammify sprockets. It is a useful
+example of a Python HOWTO document. It is not dependent on any
+particular sprocket implementation, and includes a Python-based
+implementation in the \module{sprunkit} module.
+\end{abstract}
+
+\tableofcontents
+
+Spammifying sprockets from Python is both fun and entertaining.
+Applying the techniques described here, you can also fill your hard
+disk quite effectively.
+
+\section{What is Sprocket Spammification?}
+
+You have to ask? It's the only thing to do to your sprockets!
+
+
+\section{Why Use Python?}
+
+Python is an excellent language from which to spammify your sprockets
+since you can do it on any platform.
+
+
+\section{Software Requirements}
+
+You need to have the following software installed:
+
+% The {itemize} environment uses a bullet for each \item. If you want the
+% \item's numbered, use the {enumerate} environment instead.
+\begin{itemize}
+ \item Python 1.9.
+ \item Some sprocket definition files.
+ \item At least one sprocket system implementation.
+\end{itemize}
+
+Note that the \module{sprunkit} is provided with this package and
+implements ActiveSprockets in Python.
+
+
+% The preceding sections will have been written in a gentler,
+% introductory style. You may also wish to include a reference
+% section, documenting all the functions/exceptions/constants.
+% Often, these will be placed in separate files and input like this:
+
+\input{module}
+
+
+\appendix
+
+\section{This is an Appendix}
+
+To create an appendix in a Python HOWTO document, use markup like
+this:
+
+\begin{verbatim}
+\appendix
+
+\section{This is an Appendix}
+
+To create an appendix in a Python HOWTO document, ....
+
+
+\section{This is another}
+
+Just add another \section{}, but don't say \appendix again.
+\end{verbatim}
+
+
+\end{document}
diff --git a/doc/tools/templates/manual.tex b/doc/tools/templates/manual.tex
new file mode 100644
index 0000000..a8c8ec2
--- /dev/null
+++ b/doc/tools/templates/manual.tex
@@ -0,0 +1,82 @@
+\documentclass{manual}
+
+\title{Big Python Manual}
+
+\author{Your Name Here}
+
+% Please at least include a long-lived email address;
+% the rest is at your discretion.
+\authoraddress{
+ Organization name, if applicable \\
+ Street address, if you want to use it \\
+ E-mail: \email{your-email@your.domain}
+}
+
+\date{April 30, 1999} % update before release!
+ % Use an explicit date so that reformatting
+ % doesn't cause a new date to be used. Setting
+ % the date to \today can be used during draft
+ % stages to make it easier to handle versions.
+
+\release{x.y} % release version; this is used to define the
+ % \version macro
+
+\makeindex % tell \index to actually write the .idx file
+\makemodindex % If this contains a lot of module sections.
+
+
+\begin{document}
+
+\maketitle
+
+% This makes the contents more accessible from the front page of the HTML.
+\ifhtml
+\chapter*{Front Matter\label{front}}
+\fi
+
+%\input{copyright}
+
+\begin{abstract}
+
+\noindent
+Big Python is a special version of Python for users who require larger
+keys on their keyboards. It accomodates their special needs by ...
+
+\end{abstract}
+
+\tableofcontents
+
+
+\chapter{...}
+
+My chapter.
+
+
+\appendix
+\chapter{...}
+
+My appendix.
+
+The \code{\e appendix} markup need not be repeated for additional
+appendices.
+
+
+%
+% The ugly "%begin{latexonly}" pseudo-environments are really just to
+% keep LaTeX2HTML quiet during the \renewcommand{} macros; they're
+% not really valuable.
+%
+% If you don't want the Module Index, you can remove all of this up
+% until the second \input line.
+%
+%begin{latexonly}
+\renewcommand{\indexname}{Module Index}
+%end{latexonly}
+\input{mod\jobname.ind} % Module Index
+
+%begin{latexonly}
+\renewcommand{\indexname}{Index}
+%end{latexonly}
+\input{\jobname.ind} % Index
+
+\end{document}
diff --git a/doc/tools/templates/module.tex b/doc/tools/templates/module.tex
new file mode 100644
index 0000000..33d769d
--- /dev/null
+++ b/doc/tools/templates/module.tex
@@ -0,0 +1,163 @@
+% Template for a library manual section.
+% PLEASE REMOVE THE COMMENTS AFTER USING THE TEMPLATE
+
+% ==== 0. ====
+% Copy this file to <mydir>/lib<mymodule>.tex, and edit that file
+% according to the instructions below.
+
+
+% ==== 1. ====
+% The section prologue. Give the section a title and provide some
+% meta-information. References to the module should use
+% \refbimodindex, \refstmodindex, \refexmodindex or \refmodindex, as
+% appropriate.
+
+\section{\module{spam} ---
+ Short descrition, for section title}
+
+% Choose one of these to specify the module module name. If there's
+% an underscore in the name, use
+% \declaremodule[modname]{...}{mod_name} instead.
+%
+\declaremodule{builtin}{spam} % standard library, in C
+\declaremodule{standard}{spam} % standard library, in Python
+\declaremodule{extension}{spam} % not standard, in C
+\declaremodule{}{spam} % not standard, in Python
+
+% Portability statement: Uncomment and fill in the parameter to specify the
+% availability of the module. The parameter can be Unix, IRIX, SunOS, Mac,
+% Windows, or lots of other stuff. When ``Mac'' is specified, the availability
+% statement will say ``Macintosh'' and the Module Index may say ``Mac''.
+% Please use a name that has already been used whenever applicable. If this
+% is omitted, no availability statement is produced or implied.
+%
+% \platform{UNIX}
+
+% These apply to all modules:
+
+\moduleauthor{name}{email} % Author of the module code;
+ % omit if not known.
+\sectionauthor{name}{email} % Author of the documentation,
+ % even if not a module section.
+
+
+% Leave at least one blank line after this, to simplify ad-hoc tools
+% that are sometimes used to massage these files.
+\modulesynopsis{This is a one-line descrition, for the chapter header.}
+
+
+% ==== 2. ====
+% Give a short overview of what the module does.
+% If it is platform specific, mention this.
+% Mention other important restrictions or general operating principles.
+% For example:
+
+The \module{spam} module defines operations for handling cans of Spam.
+It knows the four generally available Spam varieties and understands
+both can sizes.
+
+Because spamification requires \UNIX{} process management, the module
+is only available on genuine \UNIX{} systems.
+
+
+% ==== 3. ====
+% List the public functions defined by the module. Begin with a
+% standard phrase. You may also list the exceptions and other data
+% items defined in the module, insofar as they are important for the
+% user.
+
+The \module{spam} module defines the following functions:
+
+% ---- 3.1. ----
+% For each function, use a ``funcdesc'' block. This has exactly two
+% parameters (each parameters is contained in a set of curly braces):
+% the first parameter is the function name (this automatically
+% generates an index entry); the second parameter is the function's
+% argument list. If there are no arguments, use an empty pair of
+% curly braces. If there is more than one argument, separate the
+% arguments with backslash-comma. Optional parts of the parameter
+% list are contained in \optional{...} (this generates a set of square
+% brackets around its parameter). Arguments are automatically set in
+% italics in the parameter list. Each argument should be mentioned at
+% least once in the description; each usage (even inside \code{...})
+% should be enclosed in \var{...}.
+
+\begin{funcdesc}{open}{filename\optional{, mode\optional{, buffersize}}}
+Open the file \var{filename} as a can of Spam. The optional
+\var{mode} and \var{buffersize} arguments specify the read/write mode
+(\code{'r'} (default) or \code{'w'}) and the buffer size (default:
+system dependent).
+\end{funcdesc}
+
+% ---- 3.2. ----
+% Data items are described using a ``datadesc'' block. This has only
+% one parameter: the item's name.
+
+\begin{datadesc}{cansize}
+The default can size, in ounces. Legal values are 7 and 12. The
+default varies per supermarket. This variable should not be changed
+once the \function{open()} function has been called.
+\end{datadesc}
+
+% --- 3.3. ---
+% Exceptions are described using a ``excdesc'' block. This has only
+% one parameter: the exception name. Exceptions defined as classes in
+% the source code should be documented using this environment, but
+% constructor parameters must be ommitted.
+
+\begin{excdesc}{error}
+Exception raised when an operation fails for a Spam specific reason.
+The exception argument is a string describing the reason of the
+failure.
+\end{excdesc}
+
+% ---- 3.4. ----
+% Other standard environments:
+%
+% classdesc - Python classes; same arguments are funcdesc
+% methoddesc - methods, like funcdesc but has an optional parameter
+% to give the type name: \begin{methoddesc}[mytype]{name}{args}
+% By default, the type name will be the name of the
+% last class defined using classdesc. The type name
+% is required if the type is implemented in C (because
+% there's no classdesc) or if the class isn't directly
+% documented (if it's private).
+% memberdesc - data members, like datadesc, but with an optional
+% type name like methoddesc.
+
+
+% ==== 4. ====
+% Now is probably a good time for a complete example. (Alternatively,
+% an example giving the flavor of the module may be given before the
+% detailed list of functions.)
+
+\subsection{Example \label{spam-example}}
+
+The following example demonstrates how to open a can of spam using the
+\module{spam} module.
+
+\begin{verbatim}
+>>> import spam
+>>> can = spam.open('/etc/passwd')
+>>> can.empty()
+>>> can.close()
+\end{verbatim}
+% Note that there is no trailing ">>> " prompt shown.
+
+% ==== 5. ====
+% If your module defines new object types (for a built-in module) or
+% classes (for a module written in Python), you should list the
+% methods and instance variables (if any) of each type or class in a
+% separate subsection.
+
+\subsection{Spam Objects}
+\label{spam-objects}
+% This label is generally useful for referencing this section, but is
+% also used to give a filename when generating HTML.
+
+Spam objects, as returned by \function{open()} above, have the
+following methods:
+
+\begin{methoddesc}[spam]{empty}{}
+Empty the can into the trash.
+\end{methoddesc}
diff --git a/doc/tools/texinputs/boilerplate.tex b/doc/tools/texinputs/boilerplate.tex
new file mode 100644
index 0000000..e296dbd
--- /dev/null
+++ b/doc/tools/texinputs/boilerplate.tex
@@ -0,0 +1,10 @@
+\author{Guido van Rossum\\
+ Fred L. Drake, Jr., editor}
+\authoraddress{
+ \strong{PythonLabs}\\
+ E-mail: \email{python-docs@python.org}
+}
+
+\date{April 15, 2001} % XXX update before release!
+\release{2.1} % software release, not documentation
+\setshortversion{2.1} % major.minor only for software
diff --git a/doc/tools/texinputs/copyright.tex b/doc/tools/texinputs/copyright.tex
new file mode 100644
index 0000000..7b45dce
--- /dev/null
+++ b/doc/tools/texinputs/copyright.tex
@@ -0,0 +1,108 @@
+\begin{small}
+Copyright \copyright{} 2001 Python Software Foundation.
+All rights reserved.
+
+Copyright \copyright{} 2000 BeOpen.com.
+All rights reserved.
+
+Copyright \copyright{} 1995-2000 Corporation for National Research Initiatives.
+All rights reserved.
+
+Copyright \copyright{} 1991-1995 Stichting Mathematisch Centrum.
+All rights reserved.
+
+%%begin{latexonly}
+\vskip 4mm
+%%end{latexonly}
+
+\centerline{\strong{BEOPEN.COM TERMS AND CONDITIONS FOR PYTHON 2.0}}
+
+\centerline{\strong{BEOPEN PYTHON OPEN SOURCE LICENSE AGREEMENT VERSION 1}}
+
+\begin{enumerate}
+
+\item
+This LICENSE AGREEMENT is between BeOpen.com (``BeOpen''), having an
+office at 160 Saratoga Avenue, Santa Clara, CA 95051, and the
+Individual or Organization (``Licensee'') accessing and otherwise
+using this software in source or binary form and its associated
+documentation (``the Software'').
+
+\item
+Subject to the terms and conditions of this BeOpen Python License
+Agreement, BeOpen hereby grants Licensee a non-exclusive,
+royalty-free, world-wide license to reproduce, analyze, test, perform
+and/or display publicly, prepare derivative works, distribute, and
+otherwise use the Software alone or in any derivative version,
+provided, however, that the BeOpen Python License is retained in the
+Software, alone or in any derivative version prepared by Licensee.
+
+\item
+BeOpen is making the Software available to Licensee on an ``AS IS''
+basis. BEOPEN MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
+IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, BEOPEN MAKES NO AND
+DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS
+FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE WILL NOT
+INFRINGE ANY THIRD PARTY RIGHTS.
+
+\item
+BEOPEN SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF THE
+SOFTWARE FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS
+AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THE SOFTWARE, OR ANY
+DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
+
+\item
+This License Agreement will automatically terminate upon a material
+breach of its terms and conditions.
+
+\item
+This License Agreement shall be governed by and interpreted in all
+respects by the law of the State of California, excluding conflict of
+law provisions. Nothing in this License Agreement shall be deemed to
+create any relationship of agency, partnership, or joint venture
+between BeOpen and Licensee. This License Agreement does not grant
+permission to use BeOpen trademarks or trade names in a trademark
+sense to endorse or promote products or services of Licensee, or any
+third party. As an exception, the ``BeOpen Python'' logos available
+at http://www.pythonlabs.com/logos.html may be used according to the
+permissions granted on that web page.
+
+\item
+By copying, installing or otherwise using the software, Licensee
+agrees to be bound by the terms and conditions of this License
+Agreement.
+\end{enumerate}
+
+
+\centerline{\strong{CNRI OPEN SOURCE GPL-COMPATIBLE LICENSE AGREEMENT}}
+
+Python 1.6.1 is made available subject to the terms and conditions in
+CNRI's License Agreement. This Agreement together with Python 1.6.1 may
+be located on the Internet using the following unique, persistent
+identifier (known as a handle): 1895.22/1013. This Agreement may also
+be obtained from a proxy server on the Internet using the following
+URL: \url{http://hdl.handle.net/1895.22/1013}.
+
+
+\centerline{\strong{CWI PERMISSIONS STATEMENT AND DISCLAIMER}}
+
+Copyright \copyright{} 1991 - 1995, Stichting Mathematisch Centrum
+Amsterdam, The Netherlands. All rights reserved.
+
+Permission to use, copy, modify, and distribute this software and its
+documentation for any purpose and without fee is hereby granted,
+provided that the above copyright notice appear in all copies and that
+both that copyright notice and this permission notice appear in
+supporting documentation, and that the name of Stichting Mathematisch
+Centrum or CWI not be used in advertising or publicity pertaining to
+distribution of the software without specific, written prior
+permission.
+
+STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO
+THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE
+FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
+OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+\end{small}
diff --git a/doc/tools/texinputs/distutils.sty b/doc/tools/texinputs/distutils.sty
new file mode 100644
index 0000000..20980cf
--- /dev/null
+++ b/doc/tools/texinputs/distutils.sty
@@ -0,0 +1,33 @@
+%
+% LaTeX commands and macros needed for the two Distutils manuals,
+% inst.tex and dist.tex.
+%
+% $Id: distutils.sty,v 1.1.1.1 2001/07/16 11:53:03 msjogren Exp $
+%
+
+% My gripe list about the Python style files:
+% * I want italics in verbatim environments for variable
+% text (verbatim.sty?)
+% * I hate escaping underscores (url.sty fixes this)
+
+% '\command' is for Distutils commands which, depending on your
+% perspective, are just arguments to the setup script, or sub-
+% commands of the setup script, or the classes that implement
+% each "command".
+\newcommand{\command}[1]{\code{#1}}
+
+% '\option' is for Distutils options *in* the setup script. Command-
+% line options *to* the setup script are marked up in the usual
+% way, ie. with '\programopt' or '\longprogramopt'
+\newcommand{\option}[1]{\textsf{\small{#1}}}
+
+% '\filevar' is for variable components of file/path names -- eg.
+% when you put 'prefix' in a pathname, you mark it up with
+% '\filevar' so that it still looks pathname-ish, but is
+% distinguished from the literal part of the path. Fred says
+% this can be accomplished just fine with '\var', but I violently
+% disagree. Pistols at dawn will sort this one out.
+\newcommand{\filevar}[1]{{\textsl{\filenq{#1}}}}
+
+% Just while the code and docs are still under development.
+\newcommand{\XXX}[1]{\textbf{**#1**}}
diff --git a/doc/tools/texinputs/fncychap.sty b/doc/tools/texinputs/fncychap.sty
new file mode 100644
index 0000000..b0d7b76
--- /dev/null
+++ b/doc/tools/texinputs/fncychap.sty
@@ -0,0 +1,433 @@
+%%% Derived from the original fncychap.sty,
+%%% but changed ``TWELV'' to ``TWELVE''.
+
+%%% Copyright Ulf A. Lindgren
+%%% Department of Applied Electronics
+%%% Chalmers University of Technology
+%%% S-412 96 Gothenburg, Sweden
+%%% E-mail lindgren@ae.chalmers.se
+%%%
+%%% Note Permission is granted to modify this file under
+%%% the condition that it is saved using another
+%%% file and package name.
+%%%
+%%% Revision 1.1
+%%%
+%%% Jan. 8th Modified package name base date option
+%%% Jan. 22th Modified FmN and FmTi for error in book.cls
+%%% \MakeUppercase{#}->{\MakeUppercase#}
+%%% Apr. 6th Modified Lenny option to prevent undesired
+%%% skip of line.
+%%% Nov. 8th Fixed \@chapapp for AMS
+%%% Feb. 11th Fixed appendix problem related to Bjarne
+%%% Last modified Feb. 11th 1998
+
+\NeedsTeXFormat{LaTeX2e}[1995/12/01]
+\ProvidesPackage{fncychap}
+ [1997/04/06 v1.11
+ LaTeX package (Revised chapters)]
+
+%%%% DEFINITION OF Chapapp variables
+\newcommand{\CNV}{\huge\bfseries}
+\newcommand{\ChNameVar}[1]{\renewcommand{\CNV}{#1}}
+
+
+%%%% DEFINITION OF TheChapter variables
+\newcommand{\CNoV}{\huge\bfseries}
+\newcommand{\ChNumVar}[1]{\renewcommand{\CNoV}{#1}}
+
+\newif\ifUCN
+\UCNfalse
+\newif\ifLCN
+\LCNfalse
+\def\ChNameLowerCase{\LCNtrue\UCNfalse}
+\def\ChNameUpperCase{\UCNtrue\LCNfalse}
+\def\ChNameAsIs{\UCNfalse\LCNfalse}
+
+%%%%% Fix for AMSBook 971008
+
+\@ifundefined{@chapapp}{\let\@chapapp\chaptername}{}
+
+
+%%%%% Fix for Bjarne and appendix 980211
+
+\newif\ifinapp
+\inappfalse
+\renewcommand\appendix{\par
+ \setcounter{chapter}{0}%
+ \setcounter{section}{0}%
+ \inapptrue%
+ \renewcommand\@chapapp{\appendixname}%
+ \renewcommand\thechapter{\@Alph\c@chapter}}
+
+%%%%%
+
+\newcommand{\FmN}[1]{%
+\ifUCN
+ {\MakeUppercase#1}\LCNfalse
+\else
+ \ifLCN
+ {\MakeLowercase#1}\UCNfalse
+ \else #1
+ \fi
+\fi}
+
+
+%%%% DEFINITION OF Title variables
+\newcommand{\CTV}{\Huge\bfseries}
+\newcommand{\ChTitleVar}[1]{\renewcommand{\CTV}{#1}}
+
+%%%% DEFINITION OF the basic rule width
+\newlength{\RW}
+\setlength{\RW}{1pt}
+\newcommand{\ChRuleWidth}[1]{\setlength{\RW}{#1}}
+
+\newif\ifUCT
+\UCTfalse
+\newif\ifLCT
+\LCTfalse
+\def\ChTitleLowerCase{\LCTtrue\UCTfalse}
+\def\ChTitleUpperCase{\UCTtrue\LCTfalse}
+\def\ChTitleAsIs{\UCTfalse\LCTfalse}
+\newcommand{\FmTi}[1]{%
+\ifUCT
+
+ {\MakeUppercase#1}\LCTfalse
+\else
+ \ifLCT
+ {\MakeLowercase#1}\UCTfalse
+ \else #1
+ \fi
+\fi}
+
+
+
+\newlength{\mylen}
+\newlength{\myhi}
+\newlength{\px}
+\newlength{\py}
+\newlength{\pyy}
+\newlength{\pxx}
+
+
+\def\mghrulefill#1{\leavevmode\leaders\hrule\@height #1\hfill\kern\z@}
+
+\newcommand{\DOCH}{%
+ \CNV\FmN{\@chapapp}\space \CNoV\thechapter
+ \par\nobreak
+ \vskip 20\p@
+ }
+\newcommand{\DOTI}[1]{%
+ \CTV\FmTi{#1}\par\nobreak
+ \vskip 40\p@
+ }
+\newcommand{\DOTIS}[1]{%
+ \CTV\FmTi{#1}\par\nobreak
+ \vskip 40\p@
+ }
+
+%%%%%% SONNY DEF
+
+\DeclareOption{Sonny}{%
+ \ChNameVar{\Large\sf}
+ \ChNumVar{\Huge}
+ \ChTitleVar{\Large\sf}
+ \ChRuleWidth{0.5pt}
+ \ChNameUpperCase
+ \renewcommand{\DOCH}{%
+ \raggedleft
+ \CNV\FmN{\@chapapp}\space \CNoV\thechapter
+ \par\nobreak
+ \vskip 40\p@}
+ \renewcommand{\DOTI}[1]{%
+ \CTV\raggedleft\mghrulefill{\RW}\par\nobreak
+ \vskip 5\p@
+ \CTV\FmTi{#1}\par\nobreak
+ \mghrulefill{\RW}\par\nobreak
+ \vskip 40\p@}
+ \renewcommand{\DOTIS}[1]{%
+ \CTV\raggedleft\mghrulefill{\RW}\par\nobreak
+ \vskip 5\p@
+ \CTV\FmTi{#1}\par\nobreak
+ \mghrulefill{\RW}\par\nobreak
+ \vskip 40\p@}
+}
+
+%%%%%% LENNY DEF
+
+\DeclareOption{Lenny}{%
+
+ \ChNameVar{\fontsize{14}{16}\usefont{OT1}{phv}{m}{n}\selectfont}
+ \ChNumVar{\fontsize{60}{62}\usefont{OT1}{ptm}{m}{n}\selectfont}
+ \ChTitleVar{\Huge\bfseries\rm}
+ \ChRuleWidth{1pt}
+ \renewcommand{\DOCH}{%
+ \settowidth{\px}{\CNV\FmN{\@chapapp}}
+ \addtolength{\px}{2pt}
+ \settoheight{\py}{\CNV\FmN{\@chapapp}}
+ \addtolength{\py}{1pt}
+
+ \settowidth{\mylen}{\CNV\FmN{\@chapapp}\space\CNoV\thechapter}
+ \addtolength{\mylen}{1pt}
+ \settowidth{\pxx}{\CNoV\thechapter}
+ \addtolength{\pxx}{-1pt}
+
+ \settoheight{\pyy}{\CNoV\thechapter}
+ \addtolength{\pyy}{-2pt}
+ \setlength{\myhi}{\pyy}
+ \addtolength{\myhi}{-1\py}
+ \par
+ \parbox[b]{\textwidth}{%
+ \rule[\py]{\RW}{\myhi}%
+ \hskip -\RW%
+ \rule[\pyy]{\px}{\RW}%
+ \hskip -\px%
+ \raggedright%
+ \CNV\FmN{\@chapapp}\space\CNoV\thechapter%
+ \hskip1pt%
+ \mghrulefill{\RW}%
+ \rule{\RW}{\pyy}\par\nobreak%
+ \vskip -\baselineskip%
+ \vskip -\pyy%
+ \hskip \mylen%
+ \mghrulefill{\RW}\par\nobreak%
+ \vskip \pyy}%
+ \vskip 20\p@}
+
+
+ \renewcommand{\DOTI}[1]{%
+ \raggedright
+ \CTV\FmTi{#1}\par\nobreak
+ \vskip 40\p@}
+
+ \renewcommand{\DOTIS}[1]{%
+ \raggedright
+ \CTV\FmTi{#1}\par\nobreak
+ \vskip 40\p@}
+ }
+
+
+%%%%%%% GLENN DEF
+
+
+\DeclareOption{Glenn}{%
+ \ChNameVar{\bfseries\Large\sf}
+ \ChNumVar{\Huge}
+ \ChTitleVar{\bfseries\Large\rm}
+ \ChRuleWidth{1pt}
+ \ChNameUpperCase
+ \ChTitleUpperCase
+ \renewcommand{\DOCH}{%
+ \settoheight{\myhi}{\CTV\FmTi{Test}}
+ \setlength{\py}{\baselineskip}
+ \addtolength{\py}{\RW}
+ \addtolength{\py}{\myhi}
+ \setlength{\pyy}{\py}
+ \addtolength{\pyy}{-1\RW}
+
+ \raggedright
+ \CNV\FmN{\@chapapp}\space\CNoV\thechapter
+ \hskip 3pt\mghrulefill{\RW}\rule[-1\pyy]{2\RW}{\py}\par\nobreak}
+
+ \renewcommand{\DOTI}[1]{%
+ \addtolength{\pyy}{-4pt}
+ \settoheight{\myhi}{\CTV\FmTi{#1}}
+ \addtolength{\myhi}{\py}
+ \addtolength{\myhi}{-1\RW}
+ \vskip -1\pyy
+ \rule{2\RW}{\myhi}\mghrulefill{\RW}\hskip 2pt
+ \raggedleft\CTV\FmTi{#1}\par\nobreak
+ \vskip 80\p@}
+
+ \renewcommand{\DOTIS}[1]{%
+ \setlength{\py}{10pt}
+ \setlength{\pyy}{\py}
+ \addtolength{\pyy}{\RW}
+ \setlength{\myhi}{\baselineskip}
+ \addtolength{\myhi}{\pyy}
+ \mghrulefill{\RW}\rule[-1\py]{2\RW}{\pyy}\par\nobreak
+% \addtolength{}{}
+\vskip -1\baselineskip
+ \rule{2\RW}{\myhi}\mghrulefill{\RW}\hskip 2pt
+ \raggedleft\CTV\FmTi{#1}\par\nobreak
+ \vskip 60\p@}
+ }
+
+%%%%%%% CONNY DEF
+
+\DeclareOption{Conny}{%
+ \ChNameUpperCase
+ \ChTitleUpperCase
+ \ChNameVar{\centering\Huge\rm\bfseries}
+ \ChNumVar{\Huge}
+ \ChTitleVar{\centering\Huge\rm}
+ \ChRuleWidth{2pt}
+
+ \renewcommand{\DOCH}{%
+ \mghrulefill{3\RW}\par\nobreak
+ \vskip -0.5\baselineskip
+ \mghrulefill{\RW}\par\nobreak
+ \CNV\FmN{\@chapapp}\space \CNoV\thechapter
+ \par\nobreak
+ \vskip -0.5\baselineskip
+ }
+ \renewcommand{\DOTI}[1]{%
+ \mghrulefill{\RW}\par\nobreak
+ \CTV\FmTi{#1}\par\nobreak
+ \vskip 60\p@
+ }
+ \renewcommand{\DOTIS}[1]{%
+ \mghrulefill{\RW}\par\nobreak
+ \CTV\FmTi{#1}\par\nobreak
+ \vskip 60\p@
+ }
+ }
+
+%%%%%%% REJNE DEF
+
+\DeclareOption{Rejne}{%
+
+ \ChNameUpperCase
+ \ChTitleUpperCase
+ \ChNameVar{\centering\Large\rm}
+ \ChNumVar{\Huge}
+ \ChTitleVar{\centering\Huge\rm}
+ \ChRuleWidth{1pt}
+ \renewcommand{\DOCH}{%
+ \settoheight{\py}{\CNoV\thechapter}
+ \addtolength{\py}{-1pt}
+ \CNV\FmN{\@chapapp}\par\nobreak
+ \vskip 20\p@
+ \setlength{\myhi}{2\baselineskip}
+ \setlength{\px}{\myhi}
+ \addtolength{\px}{-1\RW}
+ \rule[-1\px]{\RW}{\myhi}\mghrulefill{\RW}\hskip
+ 10pt\raisebox{-0.5\py}{\CNoV\thechapter}\hskip
+10pt\mghrulefill{\RW}\rule[-1\px]{\RW}{\myhi}\par\nobreak
+ \vskip -1\p@
+ }
+ \renewcommand{\DOTI}[1]{%
+ \setlength{\mylen}{\textwidth}
+ \addtolength{\mylen}{-2\RW}
+ {\vrule width\RW}\parbox{\mylen}{\CTV\FmTi{#1}}{\vrule
+width\RW}\par\nobreak
+ \vskip
+-1pt\rule{\RW}{2\baselineskip}\mghrulefill{\RW}\rule{\RW}{2\baselineskip}
+ \vskip 60\p@
+ }
+ \renewcommand{\DOTIS}[1]{%
+ \setlength{\py}{\fboxrule}
+ \setlength{\fboxrule}{\RW}
+ \setlength{\mylen}{\textwidth}
+ \addtolength{\mylen}{-2\RW}
+ \fbox{\parbox{\mylen}{\vskip
+2\baselineskip\CTV\FmTi{#1}\par\nobreak\vskip \baselineskip}}
+ \setlength{\fboxrule}{\py}
+ \vskip 60\p@
+ }
+ }
+
+
+%%%%%%% BJARNE DEF
+
+\DeclareOption{Bjarne}{%
+ \ChNameUpperCase
+ \ChTitleUpperCase
+ \ChNameVar{\raggedleft\normalsize\rm}
+ \ChNumVar{\raggedleft \bfseries\Large}
+ \ChTitleVar{\raggedleft \Large\rm}
+ \ChRuleWidth{1pt}
+
+
+%% Note thechapter -> c@chapter fix appendix bug
+
+ \newcounter{AlphaCnt}
+ \newcounter{AlphaDecCnt}
+ \newcommand{\AlphaNo}{%
+ \ifcase\number\theAlphaCnt
+ \ifnum\c@chapter=0
+ ZERO\else{}\fi
+ \or ONE\or TWO\or THREE\or FOUR\or FIVE
+ \or SIX\or SEVEN\or EIGHT\or NINE\or TEN
+ \or ELEVEN\or TWELVE\or THIRTEEN\or FOURTEEN\or FIFTEEN
+ \or SIXTEEN\or SEVENTEEN\or EIGHTEEN\or NINETEEN\fi
+}
+
+ \newcommand{\AlphaDecNo}{%
+ \setcounter{AlphaDecCnt}{0}
+ \@whilenum\number\theAlphaCnt>0\do
+ {\addtocounter{AlphaCnt}{-10}
+ \addtocounter{AlphaDecCnt}{1}}
+ \ifnum\number\theAlphaCnt=0
+ \else
+ \addtocounter{AlphaDecCnt}{-1}
+ \addtocounter{AlphaCnt}{10}
+ \fi
+
+
+ \ifcase\number\theAlphaDecCnt\or TEN\or TWENTY\or THIRTY\or
+ FORTY\or FIFTY\or SIXTY\or SEVENTY\or EIGHTY\or NINETY\fi
+ }
+ \newcommand{\TheAlphaChapter}{%
+
+ \ifinapp
+ \thechapter
+ \else
+ \setcounter{AlphaCnt}{\c@chapter}
+ \ifnum\c@chapter<20
+ \AlphaNo
+ \else
+ \AlphaDecNo\AlphaNo
+ \fi
+ \fi
+ }
+ \renewcommand{\DOCH}{%
+ \mghrulefill{\RW}\par\nobreak
+ \CNV\FmN{\@chapapp}\par\nobreak
+ \CNoV\TheAlphaChapter\par\nobreak
+ \vskip -1\baselineskip\vskip 5pt\mghrulefill{\RW}\par\nobreak
+ \vskip 20\p@
+ }
+ \renewcommand{\DOTI}[1]{%
+ \CTV\FmTi{#1}\par\nobreak
+ \vskip 40\p@
+ }
+ \renewcommand{\DOTIS}[1]{%
+ \CTV\FmTi{#1}\par\nobreak
+ \vskip 40\p@
+ }
+}
+
+\DeclareOption*{%
+ \PackageWarning{fancychapter}{unknown style option}
+ }
+
+\ProcessOptions* \relax
+
+\def\@makechapterhead#1{%
+ \vspace*{50\p@}%
+ {\parindent \z@ \raggedright \normalfont
+ \ifnum \c@secnumdepth >\m@ne
+ \DOCH
+ \fi
+ \interlinepenalty\@M
+ \DOTI{#1}
+ }}
+\def\@schapter#1{\if@twocolumn
+ \@topnewpage[\@makeschapterhead{#1}]%
+ \else
+ \@makeschapterhead{#1}%
+ \@afterheading
+ \fi}
+\def\@makeschapterhead#1{%
+ \vspace*{50\p@}%
+ {\parindent \z@ \raggedright
+ \normalfont
+ \interlinepenalty\@M
+ \DOTIS{#1}
+ \vskip 40\p@
+ }}
+
+\endinput
+
+
diff --git a/doc/tools/texinputs/howto.cls b/doc/tools/texinputs/howto.cls
new file mode 100644
index 0000000..899b4ae
--- /dev/null
+++ b/doc/tools/texinputs/howto.cls
@@ -0,0 +1,106 @@
+%
+% howto.cls for the Python documentation
+%
+
+\NeedsTeXFormat{LaTeX2e}[1995/12/01]
+\ProvidesClass{howto}
+ [1998/02/25 Document class (Python HOWTO)]
+
+\RequirePackage{pypaper}
+
+% Change the options here to get a different set of basic options, This
+% is where to add things like "a4paper" or "10pt".
+%
+\LoadClass[twoside]{article}
+
+\setcounter{secnumdepth}{1}
+
+% Optional packages:
+%
+% If processing of these documents fails at your TeX installation,
+% these may be commented out (independently) to make things work.
+% These are both supplied with the current version of the teTeX
+% distribution.
+%
+% The "fancyhdr" package makes nicer page footers reasonable to
+% implement, and is used to put the chapter and section information in
+% the footers.
+%
+\RequirePackage{fancyhdr}\typeout{Using fancier footers than usual.}
+
+
+% Required package:
+%
+% This gives us all the Python-specific markup that we really want.
+% This should come last. Do not change this.
+%
+\RequirePackage{python}
+
+% support for module synopsis sections:
+\newcommand{\py@ModSynopsisFilename}{\jobname.syn}
+
+
+% need to do one of these....
+\newcommand{\py@doHorizontalRule}{\rule{\textwidth}{1pt}}
+
+
+% Change the title page to look a bit better, and fit in with the
+% fncychap ``Bjarne'' style a bit better.
+%
+\renewcommand{\maketitle}{
+ \py@doHorizontalRule
+ \@ifundefined{pdfinfo}{}{{
+ % This \def is required to deal with multi-line authors; it
+ % changes \\ to ', ' (comma-space), making it pass muster for
+ % generating document info in the PDF file.
+ \def\\{, }
+ \pdfinfo{
+ /Author (\@author)
+ /Title (\@title)
+ }
+ }}
+ \begin{flushright}
+ {\rm\Huge\py@HeaderFamily \@title} \par
+ {\em\large\py@HeaderFamily \py@release} \par
+ \vspace{25pt}
+ {\Large\py@HeaderFamily \@author} \par
+ \vspace{25pt}
+ \@date \par
+ \py@authoraddress \par
+ \end{flushright}
+ \@thanks
+ \setcounter{footnote}{0}
+ \let\thanks\relax\let\maketitle\relax
+ \gdef\@thanks{}\gdef\@author{}\gdef\@title{}
+}
+
+
+\let\py@OldTableofcontents=\tableofcontents
+\renewcommand{\tableofcontents}{
+ \begingroup
+ \parskip = 0mm
+ \py@OldTableofcontents
+ \endgroup
+ \py@doHorizontalRule
+ \vspace{12pt}
+ \py@doing@page@targetstrue
+}
+
+% Fix the theindex environment to add an entry to the Table of
+% Contents; this is much nicer than just having to jump to the end of
+% the book and flip around, especially with multiple indexes.
+%
+\let\py@OldTheindex=\theindex
+\renewcommand{\theindex}{
+ \clearpage
+ \py@OldTheindex
+ \addcontentsline{toc}{section}{\indexname}
+}
+
+\@ifundefined{fancyhf}{
+ \pagestyle{plain}}{
+ \pagestyle{normal}} % start this way; change for
+\pagenumbering{arabic} % ToC & chapters
+\setcounter{secnumdepth}{2}
+
+\thispagestyle{empty}
diff --git a/doc/tools/texinputs/ltxmarkup.sty b/doc/tools/texinputs/ltxmarkup.sty
new file mode 100644
index 0000000..d461d70
--- /dev/null
+++ b/doc/tools/texinputs/ltxmarkup.sty
@@ -0,0 +1,40 @@
+% Created by Fred L. Drake, Jr. <fdrake@acm.org>, as part of the
+% Python Documentation Project.
+%
+% Define some simple markup for the LaTeX command documentation:
+
+\ProvidesPackage{ltxmarkup}
+\RequirePackage{python} % fulllineitems environment
+
+% These two macros are used in constructing the last parameter to the
+% envdesc and macrodesc environments.
+
+\newcommand{\py@ltx@optparam}[1]{{[}\var{#1}{]}}
+\newcommand{\py@ltx@param}[1]{\{\var{#1}\}}
+
+\newenvironment{envdesc}[2]{
+ \begin{fulllineitems}
+ \item[\code{\e begin\{{\bfseries #1}\}{%
+ \let\op=\py@ltx@optparam%
+ \let\p=\py@ltx@param%
+ \let\unspecified=\py@unspecified%
+ \let\moreargs=\py@moreargs%
+ #2}}]
+ \item[\code{\e end\{{\bfseries #1}\}}]
+ \index{#1 environment@\idxcode{#1} environment}
+ \index{environments!#1@\idxcode{#1}}
+}{\end{fulllineitems}}
+
+\newenvironment{macrodesc}[2]{
+ \begin{fulllineitems}
+ \item[\code{{\e\bfseries#1}{%
+ \let\op=\py@ltx@optparam%
+ \let\p=\py@ltx@param%
+ \let\unspecified=\py@unspecified%
+ \let\moreargs=\py@moreargs%
+ #2}}]
+ \index{#1@\idxcode{\e #1}}
+}{\end{fulllineitems}}
+
+\newcommand{\env}[1]{\code{#1}}
+\newcommand{\macro}[1]{\code{\e#1}}
diff --git a/doc/tools/texinputs/manual.cls b/doc/tools/texinputs/manual.cls
new file mode 100644
index 0000000..789cae1
--- /dev/null
+++ b/doc/tools/texinputs/manual.cls
@@ -0,0 +1,152 @@
+%
+% manual.cls for the Python documentation
+%
+
+\NeedsTeXFormat{LaTeX2e}[1995/12/01]
+\ProvidesClass{manual}
+ [1998/03/03 Document class (Python manual)]
+
+\RequirePackage{pypaper}
+
+% Change the options here to get a different set of basic options, but only
+% if you have to. Paper and font size should be adjusted in pypaper.sty.
+%
+\LoadClass[\py@paper,\py@ptsize,twoside,openright]{report}
+
+\setcounter{secnumdepth}{2}
+
+% Optional packages:
+%
+% If processing of these documents fails at your TeX installation,
+% these may be commented out (independently) to make things work.
+% These are both supplied with the current version of the teTeX
+% distribution.
+%
+% The "fancyhdr" package makes nicer page footers reasonable to
+% implement, and is used to put the chapter and section information in
+% the footers.
+%
+\RequirePackage{fancyhdr}\typeout{Using fancier footers than usual.}
+
+
+% Required packages:
+%
+% The "fncychap" package is used to get the nice chapter headers. The
+% .sty file is distributed with Python, so you should not need to disable
+% it. You'd also end up with a mixed page style; uglier than stock LaTeX!
+%
+\RequirePackage[Bjarne]{fncychap}\typeout{Using fancy chapter headings.}
+% Do horizontal rules it this way to match:
+\newcommand{\py@doHorizontalRule}{\mghrulefill{\RW}}
+%
+%
+% This gives us all the Python-specific markup that we really want.
+% This should come last. Do not change this.
+%
+\RequirePackage{python}
+
+% support for module synopsis sections:
+\newcommand{\py@ModSynopsisFilename}{\jobname\thechapter.syn}
+\let\py@OldChapter=\chapter
+\renewcommand{\chapter}{
+ \py@ProcessModSynopsis
+ \py@closeModSynopsisFile
+ \py@OldChapter
+}
+
+
+% Change the title page to look a bit better, and fit in with the
+% fncychap ``Bjarne'' style a bit better.
+%
+\renewcommand{\maketitle}{%
+ \begin{titlepage}%
+ \let\footnotesize\small
+ \let\footnoterule\relax
+ \py@doHorizontalRule%
+ \@ifundefined{pdfinfo}{}{{
+ % This \def is required to deal with multi-line authors; it
+ % changes \\ to ', ' (comma-space), making it pass muster for
+ % generating document info in the PDF file.
+ \def\\{, }
+ \pdfinfo{
+ /Author (\@author)
+ /Title (\@title)
+ }
+ }}
+ \begin{flushright}%
+ {\rm\Huge\py@HeaderFamily \@title \par}%
+ {\em\LARGE\py@HeaderFamily \py@release \par}
+ \vfill
+ {\LARGE\py@HeaderFamily \@author \par}
+ \vfill\vfill
+ {\large
+ \@date \par
+ \vfill
+ \py@authoraddress \par
+ }%
+ \end{flushright}%\par
+ \@thanks
+ \end{titlepage}%
+ \setcounter{footnote}{0}%
+ \let\thanks\relax\let\maketitle\relax
+ \gdef\@thanks{}\gdef\@author{}\gdef\@title{}
+}
+
+
+% Catch the end of the {abstract} environment, but here make sure the
+% abstract is followed by a blank page if the 'openright' option is used.
+%
+\let\py@OldEndAbstract=\endabstract
+\renewcommand{\endabstract}{
+ \if@openright
+ \ifodd\value{page}
+ \typeout{Adding blank page after the abstract.}
+ \vfil\pagebreak
+ \fi
+ \fi
+ \py@OldEndAbstract
+}
+
+% This wraps the \tableofcontents macro with all the magic to get the
+% spacing right and have the right number of pages if the 'openright'
+% option has been used. This eliminates a fair amount of crud in the
+% individual document files.
+%
+\let\py@OldTableofcontents=\tableofcontents
+\renewcommand{\tableofcontents}{%
+ \setcounter{page}{1}%
+ \pagebreak%
+ \pagestyle{plain}%
+ {%
+ \parskip = 0mm%
+ \py@OldTableofcontents%
+ \if@openright%
+ \ifodd\value{page}%
+ \typeout{Adding blank page after the table of contents.}%
+ \pagebreak\hspace{0pt}%
+ \fi%
+ \fi%
+ \cleardoublepage%
+ }%
+ \pagenumbering{arabic}%
+ \@ifundefined{fancyhf}{}{\pagestyle{normal}}%
+ \py@doing@page@targetstrue%
+}
+% This is needed to get the width of the section # area wide enough in the
+% library reference. Doing it here keeps it the same for all the manuals.
+%
+\renewcommand*\l@section{\@dottedtocline{1}{1.5em}{2.6em}}
+\renewcommand*\l@subsection{\@dottedtocline{2}{4.1em}{3.5em}}
+\setcounter{tocdepth}{1}
+
+
+% Fix the theindex environment to add an entry to the Table of
+% Contents; this is much nicer than just having to jump to the end of
+% the book and flip around, especially with multiple indexes.
+%
+\let\py@OldTheindex=\theindex
+\renewcommand{\theindex}{
+ \cleardoublepage
+ \py@OldTheindex
+ \addcontentsline{toc}{chapter}{\indexname}
+}
diff --git a/doc/tools/texinputs/pypaper.sty b/doc/tools/texinputs/pypaper.sty
new file mode 100644
index 0000000..3959637
--- /dev/null
+++ b/doc/tools/texinputs/pypaper.sty
@@ -0,0 +1,18 @@
+%
+% Change this to say a4paper instead of letterpaper if you want A4. These
+% are the latex defaults.
+%
+\newcommand{\py@paper}{letterpaper}
+\newcommand{\py@ptsize}{10pt}
+
+% These set up the fonts for the documents.
+%
+% The "times" package makes the default font the PostScript Times
+% font, which makes for smaller PostScript and a font that more people
+% like.
+%
+% The "avant" package causes the AvantGarde font to be used for
+% sans-serif text, instead of the uglier Helvetica set up by the "times"
+% package.
+%
+\RequirePackage{times}\typeout{Using Times instead of Computer Modern.}
diff --git a/doc/tools/texinputs/python.ist b/doc/tools/texinputs/python.ist
new file mode 100644
index 0000000..9ffa0f9
--- /dev/null
+++ b/doc/tools/texinputs/python.ist
@@ -0,0 +1,11 @@
+line_max 100
+headings_flag 1
+heading_prefix " \\bigletter "
+
+preamble "\\begin{theindex}
+\\def\\bigletter#1{{\\Large\\sffamily#1}\\nopagebreak\\vspace{1mm}}
+
+"
+
+symhead_positive "{Symbols}"
+numhead_positive "{Numbers}"
diff --git a/doc/tools/texinputs/python.sty b/doc/tools/texinputs/python.sty
new file mode 100644
index 0000000..8a61d87
--- /dev/null
+++ b/doc/tools/texinputs/python.sty
@@ -0,0 +1,1082 @@
+%
+% python.sty for the Python docummentation [works only with with Latex2e]
+%
+
+\NeedsTeXFormat{LaTeX2e}[1995/12/01]
+\ProvidesPackage{python}
+ [1998/01/11 LaTeX package (Python markup)]
+
+\RequirePackage{longtable}
+
+% Uncomment these two lines to ignore the paper size and make the page
+% size more like a typical published manual.
+%\renewcommand{\paperheight}{9in}
+%\renewcommand{\paperwidth}{8.5in} % typical squarish manual
+%\renewcommand{\paperwidth}{7in} % O'Reilly ``Programmming Python''
+
+% These packages can be used to add marginal annotations which indicate
+% index entries and labels; useful for reviewing this messy documentation!
+%
+%\RequirePackage{showkeys}
+%\RequirePackage{showidx}
+
+% for PDF output, use maximal compression & a lot of other stuff
+% (test for PDF recommended by Tanmoy Bhattacharya <tanmoy@qcd.lanl.gov>)
+%
+\newif\ifpy@doing@page@targets
+\py@doing@page@targetsfalse
+
+\ifx\pdfoutput\undefined\else\ifcase\pdfoutput
+\else
+ \input{pdfcolor}
+ \let\py@LinkColor=\NavyBlue
+ \let\py@NormalColor=\Black
+ \pdfcompresslevel=9
+ \pdfpagewidth=\paperwidth % page width of PDF output
+ \pdfpageheight=\paperheight % page height of PDF output
+ %
+ % Pad the number with '0' to 3 digits wide so no page name is a prefix
+ % of any other.
+ %
+ \newcommand{\py@targetno}[1]{\ifnum#1<100 0\fi\ifnum#1<10 0\fi#1}
+ \newcommand{\py@pageno}{\py@targetno\thepage}
+ %
+ % This definition allows the entries in the page-view of the ToC to be
+ % active links. Some work, some don't.
+ %
+ \let\py@OldContentsline=\contentsline
+ %
+ % Macro that takes two args: the name to link to and the content of
+ % the link. This takes care of the PDF magic, getting the colors
+ % the same for each link, and avoids having lots of garbage all over
+ % this style file.
+ \newcommand{\py@linkToName}[2]{%
+ \pdfannotlink attr{/Border [0 0 0]} goto name{#1}%
+ \py@LinkColor#2\py@NormalColor%
+ \pdfendlink%
+ }
+ % Compute the padded page number separately since we end up with a pair of
+ % \relax tokens; this gets the right string computed and works.
+ \renewcommand{\contentsline}[3]{%
+ \def\my@pageno{\py@targetno{#3}}%
+ \py@OldContentsline{#1}{\py@linkToName{page\my@pageno}{#2}}{#3}%
+ }
+ \AtEndDocument{
+ \InputIfFileExists{\jobname.bkm}{\pdfcatalog{/PageMode /UseOutlines}}{}
+ }
+ \newcommand{\py@target}[1]{%
+ \ifpy@doing@page@targets%
+ {\pdfdest name{#1} xyz}%
+ \fi%
+ }
+ \let\py@OldLabel=\label
+ \renewcommand{\label}[1]{%
+ \py@OldLabel{#1}%
+ \py@target{label-#1}%
+ }
+ % This stuff adds a page# destination to every PDF page, where # is three
+ % digits wide, padded with leading zeros. This doesn't really help with
+ % the frontmatter, but does fine with the body.
+ %
+ % This is *heavily* based on the hyperref package.
+ %
+ \def\@begindvi{%
+ \unvbox \@begindvibox
+ \@hyperfixhead
+ }
+ \def\@hyperfixhead{%
+ \let\H@old@thehead\@thehead
+ \global\def\@foo{\py@target{page\py@pageno}}%
+ \expandafter\ifx\expandafter\@empty\H@old@thehead
+ \def\H@old@thehead{\hfil}\fi
+ \def\@thehead{\@foo\relax\H@old@thehead}%
+ }
+\fi\fi
+
+% Increase printable page size (copied from fullpage.sty)
+\topmargin 0pt
+\advance \topmargin by -\headheight
+\advance \topmargin by -\headsep
+
+% attempt to work a little better for A4 users
+\textheight \paperheight
+\advance\textheight by -2in
+
+\oddsidemargin 0pt
+\evensidemargin 0pt
+%\evensidemargin -.25in % for ``manual size'' documents
+\marginparwidth 0.5in
+
+\textwidth \paperwidth
+\advance\textwidth by -2in
+
+
+% Style parameters and macros used by most documents here
+\raggedbottom
+\sloppy
+\parindent = 0mm
+\parskip = 2mm
+\hbadness = 5000 % don't print trivial gripes
+
+\pagestyle{empty} % start this way; change for
+\pagenumbering{roman} % ToC & chapters
+
+% Use this to set the font family for headers and other decor:
+\newcommand{\py@HeaderFamily}{\sffamily}
+
+% Redefine the 'normal' header/footer style when using "fancyhdr" package:
+\@ifundefined{fancyhf}{}{
+ % Use \pagestyle{normal} as the primary pagestyle for text.
+ \fancypagestyle{normal}{
+ \fancyhf{}
+ \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}}
+ \fancyfoot[LO]{{\py@HeaderFamily\nouppercase{\rightmark}}}
+ \fancyfoot[RE]{{\py@HeaderFamily\nouppercase{\leftmark}}}
+ \renewcommand{\headrulewidth}{0pt}
+ \renewcommand{\footrulewidth}{0.4pt}
+ }
+ % Update the plain style so we get the page number & footer line,
+ % but not a chapter or section title. This is to keep the first
+ % page of a chapter and the blank page between chapters `clean.'
+ \fancypagestyle{plain}{
+ \fancyhf{}
+ \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}}
+ \renewcommand{\headrulewidth}{0pt}
+ \renewcommand{\footrulewidth}{0.4pt}
+ }
+ % Redefine \cleardoublepage so that the blank page between chapters
+ % gets the plain style and not the fancy style. This is described
+ % in the documentation for the fancyhdr package by Piet von Oostrum.
+ \@ifundefined{chapter}{}{
+ \renewcommand{\cleardoublepage}{
+ \clearpage\if@openright \ifodd\c@page\else
+ \hbox{}
+ \thispagestyle{plain}
+ \newpage
+ \if@twocolumn\hbox{}\newpage\fi\fi\fi
+ }
+ }
+}
+
+% This sets up the {verbatim} environment to be indented and a minipage,
+% and to have all the other mostly nice properties that we want for
+% code samples.
+
+\let\py@OldVerbatim=\verbatim
+\let\py@OldEndVerbatim=\endverbatim
+\RequirePackage{verbatim}
+
+% Variable used by begin code command
+\newlength{\py@codewidth}
+
+\renewcommand{\verbatim}{%
+ \setlength{\parindent}{1cm}%
+ % Calculate the text width for the minipage:
+ \setlength{\py@codewidth}{\linewidth}%
+ \addtolength{\py@codewidth}{-\parindent}%
+ %
+ \par\indent%
+ \begin{minipage}[t]{\py@codewidth}%
+ \small%
+ \py@OldVerbatim%
+}
+\renewcommand{\endverbatim}{%
+ \py@OldEndVerbatim%
+ \end{minipage}%
+}
+
+% This does a similar thing for the {alltt} environment:
+\RequirePackage{alltt}
+\let\py@OldAllTT=\alltt
+\let\py@OldEndAllTT=\endalltt
+
+\renewcommand{\alltt}{%
+ \setlength{\parindent}{1cm}%
+ % Calculate the text width for the minipage:
+ \setlength{\py@codewidth}{\linewidth}%
+ \addtolength{\py@codewidth}{-\parindent}%
+ %
+ \par\indent%
+ \begin{minipage}[t]{\py@codewidth}%
+ \small%
+ \py@OldAllTT%
+}
+\renewcommand{\endalltt}{%
+ \py@OldEndAllTT%
+ \end{minipage}%
+}
+
+
+\newcommand{\py@modulebadkey}{{--just-some-junk--}}
+
+
+%% Lots of index-entry generation support.
+
+% Command to wrap around stuff that refers to function / module /
+% attribute names in the index. Default behavior: like \code{}. To
+% just keep the index entries in the roman font, uncomment the second
+% definition; it matches O'Reilly style more.
+%
+\newcommand{\py@idxcode}[1]{\texttt{#1}}
+%\renewcommand{\py@idxcode}[1]{#1}
+
+% Command to generate two index entries (using subentries)
+\newcommand{\indexii}[2]{\index{#1!#2}\index{#2!#1}}
+
+% And three entries (using only one level of subentries)
+\newcommand{\indexiii}[3]{\index{#1!#2 #3}\index{#2!#3, #1}\index{#3!#1 #2}}
+
+% And four (again, using only one level of subentries)
+\newcommand{\indexiv}[4]{
+\index{#1!#2 #3 #4}
+\index{#2!#3 #4, #1}
+\index{#3!#4, #1 #2}
+\index{#4!#1 #2 #3}
+}
+
+% Command to generate a reference to a function, statement, keyword,
+% operator.
+\newcommand{\kwindex}[1]{\indexii{keyword}{#1@{\py@idxcode{#1}}}}
+\newcommand{\stindex}[1]{\indexii{statement}{#1@{\py@idxcode{#1}}}}
+\newcommand{\opindex}[1]{\indexii{operator}{#1@{\py@idxcode{#1}}}}
+\newcommand{\exindex}[1]{\indexii{exception}{#1@{\py@idxcode{#1}}}}
+\newcommand{\obindex}[1]{\indexii{object}{#1}}
+\newcommand{\bifuncindex}[1]{%
+ \index{#1@{\py@idxcode{#1()}} (built-in function)}}
+
+% Add an index entry for a module
+\newcommand{\py@refmodule}[2]{\index{#1@{\py@idxcode{#1}} (#2module)}}
+\newcommand{\refmodindex}[1]{\py@refmodule{#1}{}}
+\newcommand{\refbimodindex}[1]{\py@refmodule{#1}{built-in }}
+\newcommand{\refexmodindex}[1]{\py@refmodule{#1}{extension }}
+\newcommand{\refstmodindex}[1]{\py@refmodule{#1}{standard }}
+
+% Refer to a module's documentation using a hyperlink of the module's
+% name, at least if we're building PDF:
+\@ifundefined{pdfannotlink}{%
+ \newcommand{\refmodule}[2][\py@modulebadkey]{\module{#2}}
+}{%
+ \newcommand{\refmodule}[2][\py@modulebadkey]{%
+ \ifx\py@modulebadkey#1\def\py@modulekey{#2}\else\def\py@modulekey{#1}\fi%
+ \py@linkToName{label-module-\py@modulekey}{\module{#2}}%
+ }
+}
+
+% support for the module index
+\newif\ifpy@UseModuleIndex
+\py@UseModuleIndexfalse
+
+\newcommand{\makemodindex}{
+ \newwrite\modindexfile
+ \openout\modindexfile=mod\jobname.idx
+ \py@UseModuleIndextrue
+}
+
+% Add the defining entry for a module
+\newcommand{\py@modindex}[2]{%
+ \renewcommand{\py@thismodule}{#1}
+ \setindexsubitem{(in module #1)}%
+ \index{#1@{\py@idxcode{#1}} (#2module)|textbf}%
+ \ifpy@UseModuleIndex%
+ \@ifundefined{py@modplat@\py@thismodulekey}{
+ \write\modindexfile{\protect\indexentry{#1@{\texttt{#1}}}{\thepage}}%
+ }{\write\modindexfile{\protect\indexentry{#1@{\texttt{#1} %
+ \emph{(\py@platformof[\py@thismodulekey]{})}}}{\thepage}}%
+ }
+ \fi%
+}
+
+% *** XXX *** THE NEXT FOUR MACROS ARE NOW OBSOLETE !!! ***
+
+% built-in & Python modules in the main distribution
+\newcommand{\bimodindex}[1]{\py@modindex{#1}{built-in }%
+ \typeout{*** MACRO bimodindex IS OBSOLETE -- USE declaremodule INSTEAD!}}
+\newcommand{\stmodindex}[1]{\py@modindex{#1}{standard }%
+ \typeout{*** MACRO stmodindex IS OBSOLETE -- USE declaremodule INSTEAD!}}
+
+% Python & extension modules outside the main distribution
+\newcommand{\modindex}[1]{\py@modindex{#1}{}%
+ \typeout{*** MACRO modindex IS OBSOLETE -- USE declaremodule INSTEAD!}}
+\newcommand{\exmodindex}[1]{\py@modindex{#1}{extension }%
+ \typeout{*** MACRO exmodindex IS OBSOLETE -- USE declaremodule INSTEAD!}}
+
+% Additional string for an index entry
+\newif\ifpy@usingsubitem\py@usingsubitemfalse
+\newcommand{\py@indexsubitem}{}
+\newcommand{\setindexsubitem}[1]{\renewcommand{\py@indexsubitem}{ #1}%
+ \py@usingsubitemtrue}
+\newcommand{\ttindex}[1]{%
+ \ifpy@usingsubitem
+ \index{#1@{\py@idxcode{#1}}\py@indexsubitem}%
+ \else%
+ \index{#1@{\py@idxcode{#1}}}%
+ \fi%
+}
+\newcommand{\withsubitem}[2]{%
+ \begingroup%
+ \def\ttindex##1{\index{##1@{\py@idxcode{##1}} #1}}%
+ #2%
+ \endgroup%
+}
+
+
+% Module synopsis processing -----------------------------------------------
+%
+\newcommand{\py@thisclass}{}
+\newcommand{\py@thismodule}{}
+\newcommand{\py@thismodulekey}{}
+\newcommand{\py@thismoduletype}{}
+
+\newcommand{\py@standardIndexModule}[1]{\py@modindex{#1}{standard }}
+\newcommand{\py@builtinIndexModule}[1]{\py@modindex{#1}{built-in }}
+\newcommand{\py@extensionIndexModule}[1]{\py@modindex{#1}{extension }}
+\newcommand{\py@IndexModule}[1]{\py@modindex{#1}{}}
+
+\newif\ifpy@HaveModSynopsis \py@HaveModSynopsisfalse
+\newif\ifpy@ModSynopsisFileIsOpen \py@ModSynopsisFileIsOpenfalse
+\newif\ifpy@HaveModPlatform \py@HaveModPlatformfalse
+
+% \declaremodule[key]{type}{name}
+\newcommand{\declaremodule}[3][\py@modulebadkey]{
+ \py@openModSynopsisFile
+ \renewcommand{\py@thismoduletype}{#2}
+ \ifx\py@modulebadkey#1
+ \renewcommand{\py@thismodulekey}{#3}
+ \else
+ \renewcommand{\py@thismodulekey}{#1}
+ \fi
+ \@ifundefined{py@#2IndexModule}{%
+ \typeout{*** MACRO declaremodule called with unknown module type: `#2'}
+ \py@IndexModule{#3}%
+ }{%
+ \csname py@#2IndexModule\endcsname{#3}%
+ }
+ \label{module-\py@thismodulekey}
+}
+\newif\ifpy@ModPlatformFileIsOpen \py@ModPlatformFileIsOpenfalse
+\newcommand{\py@ModPlatformFilename}{\jobname.pla}
+\newcommand{\platform}[1]{
+ \ifpy@ModPlatformFileIsOpen\else
+ \newwrite\py@ModPlatformFile
+ \openout\py@ModPlatformFile=\py@ModPlatformFilename
+ \py@ModPlatformFileIsOpentrue
+ \fi
+}
+\InputIfFileExists{\jobname.pla}{}{}
+\newcommand{\py@platformof}[2][\py@modulebadkey]{%
+ \ifx\py@modulebadkey#1 \def\py@key{#2}%
+ \else \def\py@key{#1}%
+ \fi%
+ \csname py@modplat@\py@key\endcsname%
+}
+\newcommand{\ignorePlatformAnnotation}[1]{}
+
+% \moduleauthor{name}{email}
+\newcommand{\moduleauthor}[2]{}
+
+% \sectionauthor{name}{email}
+\newcommand{\sectionauthor}[2]{}
+
+
+\newcommand{\py@defsynopsis}{Module has no synopsis.}
+\newcommand{\py@modulesynopsis}{\py@defsynopsis}
+\newcommand{\modulesynopsis}[1]{
+ \py@HaveModSynopsistrue
+ \renewcommand{\py@modulesynopsis}{#1}
+}
+
+% define the file
+\newwrite\py@ModSynopsisFile
+
+% hacked from \addtocontents from latex.ltx:
+\long\def\py@writeModSynopsisFile#1{%
+ \protected@write\py@ModSynopsisFile%
+ {\let\label\@gobble \let\index\@gobble \let\glossary\@gobble}%
+ {\string#1}%
+}
+\newcommand{\py@closeModSynopsisFile}{
+ \ifpy@ModSynopsisFileIsOpen
+ \closeout\py@ModSynopsisFile
+ \py@ModSynopsisFileIsOpenfalse
+ \fi
+}
+\newcommand{\py@openModSynopsisFile}{
+ \ifpy@ModSynopsisFileIsOpen\else
+ \openout\py@ModSynopsisFile=\py@ModSynopsisFilename
+ \py@ModSynopsisFileIsOpentrue
+ \fi
+}
+
+\newcommand{\py@ProcessModSynopsis}{
+ \ifpy@HaveModSynopsis
+ \py@writeModSynopsisFile{\modulesynopsis%
+ {\py@thismodulekey}{\py@thismodule}%
+ {\py@thismoduletype}{\py@modulesynopsis}}%
+ \py@HaveModSynopsisfalse
+ \fi
+ \renewcommand{\py@modulesynopsis}{\py@defsynopsis}
+}
+\AtEndDocument{\py@ProcessModSynopsis\py@closeModSynopsisFile}
+
+
+\long\def\py@writeModPlatformFile#1{%
+ \protected@write\py@ModPlatformFile%
+ {\let\label\@gobble \let\index\@gobble \let\glossary\@gobble}%
+ {\string#1}%
+}
+
+
+\newcommand{\localmoduletable}{
+ \IfFileExists{\py@ModSynopsisFilename}{
+ \begin{synopsistable}
+ \input{\py@ModSynopsisFilename}
+ \end{synopsistable}
+ }{}
+}
+
+\@ifundefined{pdfoutput}{
+ \newcommand{\py@ModSynopsisSummary}[4]{\bfcode{#2} & #4\\}
+}{
+ \newcommand{\py@ModSynopsisSummary}[4]{%
+ \py@linkToName{label-module-#1}{\bfcode{#2}} & #4\\
+ }
+}
+\newenvironment{synopsistable}{
+ % key, name, type, synopsis
+ \let\modulesynopsis=\py@ModSynopsisSummary
+ \begin{tabular}{ll}
+}{
+ \end{tabular}
+}
+%
+% --------------------------------------------------------------------------
+
+
+\newcommand{\py@reset}{
+ \py@usingsubitemfalse
+ \py@ProcessModSynopsis
+ \renewcommand{\py@thisclass}{}
+ \renewcommand{\py@thismodule}{}
+ \renewcommand{\py@thismodulekey}{}
+ \renewcommand{\py@thismoduletype}{}
+}
+
+% Augment the sectioning commands used to get our own font family in place,
+% and reset some internal data items:
+\renewcommand{\section}{\py@reset%
+ \@startsection{section}{1}{\z@}%
+ {-3.5ex \@plus -1ex \@minus -.2ex}%
+ {2.3ex \@plus.2ex}%
+ {\reset@font\Large\py@HeaderFamily}}
+\renewcommand{\subsection}{\@startsection{subsection}{2}{\z@}%
+ {-3.25ex\@plus -1ex \@minus -.2ex}%
+ {1.5ex \@plus .2ex}%
+ {\reset@font\large\py@HeaderFamily}}
+\renewcommand{\subsubsection}{\@startsection{subsubsection}{3}{\z@}%
+ {-3.25ex\@plus -1ex \@minus -.2ex}%
+ {1.5ex \@plus .2ex}%
+ {\reset@font\normalsize\py@HeaderFamily}}
+\renewcommand{\paragraph}{\@startsection{paragraph}{4}{\z@}%
+ {3.25ex \@plus1ex \@minus.2ex}%
+ {-1em}%
+ {\reset@font\normalsize\py@HeaderFamily}}
+\renewcommand{\subparagraph}{\@startsection{subparagraph}{5}{\parindent}%
+ {3.25ex \@plus1ex \@minus .2ex}%
+ {-1em}%
+ {\reset@font\normalsize\py@HeaderFamily}}
+
+
+% This gets the underscores closer to the right width; the only change
+% from standard LaTeX is the width specified.
+
+\DeclareTextCommandDefault{\textunderscore}{%
+ \leavevmode \kern.06em\vbox{\hrule\@width.55em}}
+
+% Underscore hack (only act like subscript operator if in math mode)
+%
+% The following is due to Mark Wooding (the old version didn't work with
+% Latex 2e.
+
+\DeclareRobustCommand\hackscore{%
+ \ifmmode_\else\textunderscore\fi%
+}
+\begingroup
+\catcode`\_\active
+\def\next{%
+ \AtBeginDocument{\catcode`\_\active\def_{\hackscore{}}}%
+}
+\expandafter\endgroup\next
+
+
+% Now for a lot of semantically-loaded environments that do a ton of magical
+% things to get the right formatting and index entries for the stuff in
+% Python modules and C API.
+
+
+% {fulllineitems} is used in one place in libregex.tex, but is really for
+% internal use in this file.
+%
+\newcommand{\py@itemnewline}[1]{%
+ \@tempdima\linewidth%
+ \advance\@tempdima \leftmargin\makebox[\@tempdima][l]{#1}%
+}
+
+\newenvironment{fulllineitems}{
+ \begin{list}{}{\labelwidth \leftmargin \labelsep 0pt
+ \rightmargin 0pt \topsep -\parskip \partopsep \parskip
+ \itemsep -\parsep
+ \let\makelabel=\py@itemnewline}
+}{\end{list}}
+
+% \optional is mostly for use in the arguments parameters to the various
+% {*desc} environments defined below, but may be used elsewhere. Known to
+% be used in the debugger chapter.
+%
+% Typical usage:
+%
+% \begin{funcdesc}{myfunc}{reqparm\optional{, optparm}}
+% ^^^ ^^^
+% No space here No space here
+%
+% When a function has multiple optional parameters, \optional should be
+% nested, not chained. This is right:
+%
+% \begin{funcdesc}{myfunc}{\optional{parm1\optional{, parm2}}}
+%
+\let\py@badkey=\@undefined
+
+\newcommand{\optional}[1]{%
+ {\textnormal{\Large[}}{#1}\hspace{0.5mm}{\textnormal{\Large]}}}
+
+% This can be used when a function or method accepts an varying number
+% of arguments, such as by using the *args syntax in the parameter list.
+\newcommand{\py@moreargs}{...}
+
+% This can be used when you don't want to document the parameters to a
+% function or method, but simply state that it's an alias for
+% something else.
+\newcommand{\py@unspecified}{...}
+
+% C functions ------------------------------------------------------------
+% \begin{cfuncdesc}[refcount]{type}{name}{arglist}
+% Note that the [refcount] slot should only be filled in by
+% tools/anno-api.py; it pulls the value from the refcounts database.
+\newenvironment{cfuncdesc}[4][\py@badkey]{
+ \begin{fulllineitems}
+ \item[\code{#2 \bfcode{#3}(\py@varvars{#4})}\index{#3@{\py@idxcode{#3()}}}]
+ \ifx#1\@undefined\else%
+ \emph{Return value: \textbf{#1}.}\\
+ \fi
+}{\end{fulllineitems}}
+
+% C variables ------------------------------------------------------------
+% \begin{cvardesc}{type}{name}
+\newenvironment{cvardesc}[2]{
+ \begin{fulllineitems}
+ \item[\code{#1 \bfcode{#2}}\index{#2@{\py@idxcode{#2}}}]
+}{\end{fulllineitems}}
+
+% C data types -----------------------------------------------------------
+% \begin{ctypedesc}[index name]{typedef name}
+\newenvironment{ctypedesc}[2][\py@badkey]{
+ \begin{fulllineitems}
+ \item[\bfcode{#2}%
+ \ifx#1\@undefined%
+ \index{#2@{\py@idxcode{#2}} (C type)}
+ \else%
+ \index{#2@{\py@idxcode{#1}} (C type)}
+ \fi]
+}{\end{fulllineitems}}
+
+% Funky macros -----------------------------------------------------------
+% \begin{csimplemacro}{name}
+% -- "simple" because it has no args; NOT for constant definitions!
+\newenvironment{csimplemacrodesc}[1]{
+ \begin{fulllineitems}
+ \item[\bfcode{#1}\index{#1@{\py@idxcode{#1}} (macro)}]
+}{\end{fulllineitems}}
+
+% simple functions (not methods) -----------------------------------------
+% \begin{funcdesc}{name}{args}
+\newcommand{\funcline}[2]{%
+ \funclineni{#1}{#2}%
+ \index{#1@{\py@idxcode{#1()}} (in module \py@thismodule)}}
+\newenvironment{funcdesc}[2]{
+ \begin{fulllineitems}
+ \funcline{#1}{#2}
+}{\end{fulllineitems}}
+
+% similar to {funcdesc}, but doesn't add to the index
+\newcommand{\funclineni}[2]{\item[\code{\bfcode{#1}(\py@varvars{#2})}]}
+\newenvironment{funcdescni}[2]{
+ \begin{fulllineitems}
+ \funclineni{#1}{#2}
+}{\end{fulllineitems}}
+
+% classes ----------------------------------------------------------------
+% \begin{classdesc}{name}{constructor args}
+\newenvironment{classdesc}[2]{
+ % Using \renewcommand doesn't work for this, for unknown reasons:
+ \global\def\py@thisclass{#1}
+ \begin{fulllineitems}
+ \item[\strong{class }\code{\bfcode{#1}(\py@varvars{#2})}%
+ \index{#1@{\py@idxcode{#1}} (class in \py@thismodule)}]
+}{\end{fulllineitems}}
+
+% \begin{excclassdesc}{name}{constructor args}
+% but indexes as an exception
+\newenvironment{excclassdesc}[2]{
+ % Using \renewcommand doesn't work for this, for unknown reasons:
+ \global\def\py@thisclass{#1}
+ \begin{fulllineitems}
+ \item[\strong{exception }\code{\bfcode{#1}(\py@varvars{#2})}%
+ \index{#1@{\py@idxcode{#1}} (exception in \py@thismodule)}]
+}{\end{fulllineitems}}
+
+
+\let\py@classbadkey=\@undefined
+
+% object method ----------------------------------------------------------
+% \begin{methoddesc}[classname]{methodname}{args}
+\newcommand{\methodline}[3][\@undefined]{
+ \methodlineni{#2}{#3}
+ \ifx#1\@undefined
+ \index{#2@{\py@idxcode{#2()}} (\py@thisclass\ method)}
+ \else
+ \index{#2@{\py@idxcode{#2()}} (#1 method)}
+ \fi
+}
+\newenvironment{methoddesc}[3][\@undefined]{
+ \begin{fulllineitems}
+ \ifx#1\@undefined
+ \methodline{#2}{#3}
+ \else
+ \def\py@thisclass{#1}
+ \methodline{#2}{#3}
+ \fi
+}{\end{fulllineitems}}
+
+% similar to {methoddesc}, but doesn't add to the index
+% (never actually uses the optional argument)
+\newcommand{\methodlineni}[3][\py@classbadkey]{%
+ \item[\code{\bfcode{#2}(\py@varvars{#3})}]}
+\newenvironment{methoddescni}[3][\py@classbadkey]{
+ \begin{fulllineitems}
+ \methodlineni{#2}{#3}
+}{\end{fulllineitems}}
+
+% object data attribute --------------------------------------------------
+% \begin{memberdesc}[classname]{membername}
+\newcommand{\memberline}[2][\py@classbadkey]{%
+ \ifx#1\@undefined
+ \memberlineni{#2}
+ \index{#2@{\py@idxcode{#2}} (\py@thisclass\ attribute)}
+ \else
+ \memberlineni{#2}
+ \index{#2@{\py@idxcode{#2}} (#1 attribute)}
+ \fi
+}
+\newenvironment{memberdesc}[2][\py@classbadkey]{
+ \begin{fulllineitems}
+ \ifx#1\@undefined
+ \memberline{#2}
+ \else
+ \def\py@thisclass{#1}
+ \memberline{#2}
+ \fi
+}{\end{fulllineitems}}
+
+% similar to {memberdesc}, but doesn't add to the index
+% (never actually uses the optional argument)
+\newcommand{\memberlineni}[2][\py@classbadkey]{\item[\bfcode{#2}]}
+\newenvironment{memberdescni}[2][\py@classbadkey]{
+ \begin{fulllineitems}
+ \memberlineni{#2}
+}{\end{fulllineitems}}
+
+% For exceptions: --------------------------------------------------------
+% \begin{excdesc}{name}
+% -- for constructor information, use excclassdesc instead
+\newenvironment{excdesc}[1]{
+ \begin{fulllineitems}
+ \item[\strong{exception }\bfcode{#1}%
+ \index{#1@{\py@idxcode{#1}} (exception in \py@thismodule)}]
+}{\end{fulllineitems}}
+
+% Module data or constants: ----------------------------------------------
+% \begin{datadesc}{name}
+\newcommand{\dataline}[1]{%
+ \datalineni{#1}\index{#1@{\py@idxcode{#1}} (data in \py@thismodule)}}
+\newenvironment{datadesc}[1]{
+ \begin{fulllineitems}
+ \dataline{#1}
+}{\end{fulllineitems}}
+
+% similar to {datadesc}, but doesn't add to the index
+\newcommand{\datalineni}[1]{\item[\bfcode{#1}]\nopagebreak}
+\newenvironment{datadescni}[1]{
+ \begin{fulllineitems}
+ \datalineni{#1}
+}{\end{fulllineitems}}
+
+% bytecode instruction ---------------------------------------------------
+% \begin{opcodedesc}{name}{var}
+% -- {var} may be {}
+\newenvironment{opcodedesc}[2]{
+ \begin{fulllineitems}
+ \item[\bfcode{#1}\quad\var{#2}]
+}{\end{fulllineitems}}
+
+
+\newcommand{\nodename}[1]{\label{#1}}
+
+% For these commands, use \command{} to get the typography right, not
+% {\command}. This works better with the texinfo translation.
+\newcommand{\ABC}{{\sc abc}}
+\newcommand{\UNIX}{{\sc Unix}}
+\newcommand{\POSIX}{POSIX}
+\newcommand{\ASCII}{{\sc ascii}}
+\newcommand{\Cpp}{C\protect\raisebox{.18ex}{++}}
+\newcommand{\C}{C}
+\newcommand{\EOF}{{\sc eof}}
+\newcommand{\NULL}{\constant{NULL}}
+
+% Also for consistency: spell Python "Python", not "python"!
+
+% code is the most difficult one...
+\newcommand{\code}[1]{\textrm{\@vobeyspaces\@noligs\def\{{\char`\{}\def\}{\char`\}}\def\~{\char`\~}\def\^{\char`\^}\def\e{\char`\\}\def\${\char`\$}\def\#{\char`\#}\def\&{\char`\&}\def\%{\char`\%}%
+\texttt{#1}}}
+
+\newcommand{\bfcode}[1]{\code{\bfseries#1}} % bold-faced code font
+\newcommand{\kbd}[1]{\code{#1}}
+\newcommand{\samp}[1]{`\code{#1}'}
+% This weird definition of \var{} allows it to always appear in roman
+% italics, and won't get funky in code fragments when we play around
+% with fonts. This also works directly in math mode.
+\newcommand{\var}[1]{%
+ \ifmmode%
+ \hbox{\normalsize\textrm{\textit{#1\/}}}%
+ \else%
+ \normalsize\textrm{\textit{#1\/}}%
+ \fi%
+}
+\renewcommand{\emph}[1]{{\em #1}}
+\newcommand{\dfn}[1]{\emph{#1}}
+\newcommand{\strong}[1]{{\bf #1}}
+% let's experiment with a new font:
+\newcommand{\file}[1]{`{\small\textsf{#1}}'}
+\newcommand{\filenq}[1]{{\small\textsf{#1}}}
+
+% Use this def/redef approach for \url{} since hyperref defined this already,
+% but only if we actually used hyperref:
+\@ifundefined{pdfannotlink}{
+ \newcommand{\py@url}[1]{\mbox{\small\textsf{#1}}}
+}{
+ \newcommand{\py@url}[1]{{%
+ \pdfannotlink attr{/Border [0 0 0]} user{/S /URI /URI (#1)}%
+ \py@LinkColor% color of the link text
+ \mbox{\small\textsf{#1}}%
+ \py@NormalColor% Turn it back off; these are declarative
+ \pdfendlink}% and don't appear bound to the current
+ }% formatting "box".
+}
+\let\url=\py@url
+\newcommand{\email}[1]{{\small\textsf{#1}}}
+\newcommand{\newsgroup}[1]{{\small\textsf{#1}}}
+
+\newcommand{\py@varvars}[1]{{%
+ {\let\unspecified=\py@unspecified%
+ \let\moreargs=\py@moreargs%
+ \var{#1}}}}
+
+% I'd really like to get rid of this!
+\newif\iftexi\texifalse
+
+% This is used to get l2h to put the copyright and abstract on
+% a separate HTML page.
+\newif\ifhtml\htmlfalse
+
+
+% These should be used for all references to identifiers which are
+% used to refer to instances of specific language constructs. See the
+% names for specific semantic assignments.
+%
+% For now, don't do anything really fancy with them; just use them as
+% logical markup. This might change in the future.
+%
+\newcommand{\module}[1]{\texttt{#1}}
+\newcommand{\keyword}[1]{\texttt{#1}}
+\newcommand{\exception}[1]{\texttt{#1}}
+\newcommand{\class}[1]{\texttt{#1}}
+\newcommand{\function}[1]{\texttt{#1}}
+\newcommand{\member}[1]{\texttt{#1}}
+\newcommand{\method}[1]{\texttt{#1}}
+
+\newcommand{\pytype}[1]{#1} % built-in Python type
+
+\newcommand{\cfunction}[1]{\texttt{#1}}
+\newcommand{\ctype}[1]{\texttt{#1}} % C struct or typedef name
+\newcommand{\cdata}[1]{\texttt{#1}} % C variable, typically global
+
+\newcommand{\mimetype}[1]{{\small\textsf{#1}}}
+% The \! is a "negative thin space" in math mode.
+\newcommand{\regexp}[1]{%
+ {\tiny$^{^\lceil}\!\!$%
+ {\normalsize\code{#1}}%
+ $\!\rfloor\!$%
+ }}
+\newcommand{\envvar}[1]{%
+ #1%
+ \index{#1@{#1}}%
+ \index{environment variables!{#1}}%
+}
+\newcommand{\makevar}[1]{#1} % variable in a Makefile
+\newcommand{\character}[1]{\samp{#1}}
+
+% constants defined in Python modules or C headers, not language constants:
+\newcommand{\constant}[1]{\code{#1}} % manifest constant, not syntactic
+
+\newcommand{\manpage}[2]{{\emph{#1}(#2)}}
+\newcommand{\pep}[1]{PEP #1\index{Python Enhancement Proposals!PEP #1}}
+\newcommand{\rfc}[1]{RFC #1\index{RFC!RFC #1}}
+\newcommand{\program}[1]{\strong{#1}}
+\newcommand{\programopt}[1]{\strong{#1}}
+% Note that \longprogramopt provides the '--'!
+\newcommand{\longprogramopt}[1]{\strong{-{}-#1}}
+
+% cited titles: \citetitle{Title of Work}
+% online: \citetitle[url-to-resource]{Title of Work}
+\newcommand{\citetitle}[2][URL]{\emph{#2}}
+
+
+% Deprecation stuff.
+% Should be extended to allow an index / list of deprecated stuff. But
+% there's a lot of stuff that needs to be done to make that automatable.
+%
+% First parameter is the release number that deprecates the feature, the
+% second is the action the should be taken by users of the feature.
+%
+% Example:
+% \deprecated{1.5.1}{Use \method{frobnicate()} instead.}
+%
+\newcommand{\deprecated}[2]{%
+ \strong{Deprecated since release #1.} #2\par}
+
+% New stuff.
+% This should be used to mark things which have been added to the
+% development tree but that aren't in the release, but are documented.
+% This allows release of documentation that already includes updated
+% descriptions. Place at end of descriptor environment.
+%
+% Example:
+% \versionadded{1.5.2}
+% \versionchanged[short explanation]{2.0}
+%
+\newcommand{\versionadded}[1]{%
+ { New in version #1. }}
+\newcommand{\versionchanged}[2][\py@badkey]{%
+ \ifx#1\@undefined%
+ { Changed in version #2. }%
+ \else%
+ { Changed in version #2:\ #1. }%
+ \fi%
+}
+
+
+% Tables.
+%
+\newenvironment{tableii}[4]{%
+ \begin{center}%
+ \def\lineii##1##2{\csname#2\endcsname{##1}&##2\\}%
+ \begin{tabular}{#1}\strong{#3}&\strong{#4} \\* \hline%
+}{%
+ \end{tabular}%
+ \end{center}%
+}
+
+\newenvironment{longtableii}[4]{%
+ \begin{center}%
+ \def\lineii##1##2{\csname#2\endcsname{##1}&##2\\}%
+ \begin{longtable}[c]{#1}\strong{#3}&\strong{#4} \\* \hline\endhead%
+}{%
+ \end{longtable}%
+ \end{center}%
+}
+
+\newenvironment{tableiii}[5]{%
+ \begin{center}%
+ \def\lineiii##1##2##3{\csname#2\endcsname{##1}&##2&##3\\}%
+ \begin{tabular}{#1}\strong{#3}&\strong{#4}&\strong{#5} \\%
+ \hline%
+}{%
+ \end{tabular}%
+ \end{center}%
+}
+
+\newenvironment{longtableiii}[5]{%
+ \begin{center}%
+ \def\lineiii##1##2##3{\csname#2\endcsname{##1}&##2&##3\\}%
+ \begin{longtable}[c]{#1}\strong{#3}&\strong{#4}&\strong{#5} \\%
+ \hline\endhead%
+}{%
+ \end{longtable}%
+ \end{center}%
+}
+
+\newenvironment{tableiv}[6]{%
+ \begin{center}%
+ \def\lineiv##1##2##3##4{\csname#2\endcsname{##1}&##2&##3&##4\\}%
+ \begin{tabular}{#1}\strong{#3}&\strong{#4}&\strong{#5}&\strong{#6} \\%
+ \hline%
+}{%
+ \end{tabular}%
+ \end{center}%
+}
+
+\newenvironment{longtableiv}[6]{%
+ \begin{center}%
+ \def\lineiv##1##2##3##4{\csname#2\endcsname{##1}&##2&##3&##4\\}%
+ \begin{longtable}[c]{#1}\strong{#3}&\strong{#4}&\strong{#5}&\strong{#6}%
+ \\%
+ \hline\endhead%
+}{%
+ \end{longtable}%
+ \end{center}%
+}
+
+% Cross-referencing (AMK, new impl. FLD)
+% Sample usage:
+% \begin{seealso}
+% \seemodule{rand}{Uniform random number generator.}; % Module xref
+% \seetext{\emph{Encyclopedia Britannica}}. % Ref to a book
+%
+% % A funky case: module name contains '_'; have to supply an optional key
+% \seemodule[copyreg]{copy_reg}{Interface constructor registration for
+% \module{pickle}.}
+% \end{seealso}
+%
+% Note that the last parameter for \seemodule and \seetext should be complete
+% sentences and be terminated with the proper punctuation.
+
+\@ifundefined{pdfannotlink}{%
+ \newcommand{\py@seemodule}[3][\py@modulebadkey]{%
+ \par%
+ \ifx\py@modulebadkey#1\def\py@modulekey{#2}\else\def\py@modulekey{#1}\fi%
+ \begin{fulllineitems}
+ \item[Module \module{#2} (section \ref{module-\py@modulekey}):]
+ #3
+ \end{fulllineitems}
+ }
+}{\newcommand{\py@seemodule}[3][\py@modulebadkey]{%
+ \par%
+ \ifx\py@modulebadkey#1\def\py@modulekey{#2}\else\def\py@modulekey{#1}\fi%
+ \begin{fulllineitems}
+ \item[\py@linkToName{label-module-\py@modulekey}{Module \module{#2}}
+ (section \ref{module-\py@modulekey}):]
+ #3
+ \end{fulllineitems}
+ }
+}
+% \seetitle[url]{title}{why it's interesting}
+\newcommand{\py@seetitle}[3][\py@modulebadkey]{%
+ \par
+ \begin{fulllineitems}
+ \item[\citetitle{#2}]
+ \ifx\py@modulebadkey#1\else
+ \item[{\small{(\url{#1})}}]
+ \fi
+ #3
+ \end{fulllineitems}
+}
+% \seepep{number}{title}{why it's interesting}
+\newcommand{\py@seepep}[3]{%
+ \par%
+ \begin{fulllineitems}
+ \item[\pep{#1}, ``\emph{#2}'']
+ #3
+ \end{fulllineitems}
+}
+% \seerfc{number}{title}{why it's interesting}
+\newcommand{\py@seerfc}[3]{%
+ \par%
+ \begin{fulllineitems}
+ \item[\rfc{#1}, ``\emph{#2}'']
+ #3
+ \end{fulllineitems}
+}
+% \seeurl{url}{why it's interesting}
+\newcommand{\py@seeurl}[2]{%
+ \par%
+ \begin{fulllineitems}
+ \item[\url{#1}]
+ #2
+ \end{fulllineitems}
+}
+\newenvironment{seealso}[0]{
+ \par
+ \strong{See Also:}\par
+ \def\seetext##1{\par{##1}}
+ \let\seemodule=\py@seemodule
+ \let\seepep=\py@seepep
+ \let\seerfc=\py@seerfc
+ \let\seetitle=\py@seetitle
+ \let\seeurl=\py@seeurl
+}{\par}
+
+
+% Allow the Python release number to be specified independently of the
+% \date{}. This allows the date to reflect the document's date and
+% release to specify the Python release that is documented.
+%
+\newcommand{\py@release}{}
+\newcommand{\version}{}
+\newcommand{\shortversion}{}
+\newcommand{\releasename}{Release}
+\newcommand{\release}[1]{%
+ \renewcommand{\py@release}{\releasename\space\version}%
+ \renewcommand{\version}{#1}}
+\newcommand{\setshortversion}[1]{%
+ \renewcommand{\shortversion}{#1}}
+
+% Allow specification of the author's address separately from the
+% author's name. This can be used to format them differently, which
+% is a good thing.
+%
+\newcommand{\py@authoraddress}{}
+\newcommand{\authoraddress}[1]{\renewcommand{\py@authoraddress}{#1}}
+\let\developersaddress=\authoraddress
+\let\developer=\author
+\let\developers=\author
+
+% This sets up the fancy chapter headings that make the documents look
+% at least a little better than the usual LaTeX output.
+%
+\@ifundefined{ChTitleVar}{}{
+ \ChNameVar{\raggedleft\normalsize\py@HeaderFamily}
+ \ChNumVar{\raggedleft \bfseries\Large\py@HeaderFamily}
+ \ChTitleVar{\raggedleft \rm\Huge\py@HeaderFamily}
+ % This creates chapter heads without the leading \vspace*{}:
+ \def\@makechapterhead#1{%
+ {\parindent \z@ \raggedright \normalfont
+ \ifnum \c@secnumdepth >\m@ne
+ \DOCH
+ \fi
+ \interlinepenalty\@M
+ \DOTI{#1}
+ }
+ }
+}
+
+
+% Definition lists; requested by AMK for HOWTO documents. Probably useful
+% elsewhere as well, so keep in in the general style support.
+%
+\newenvironment{definitions}{%
+ \begin{description}%
+ \def\term##1{\item[##1]\mbox{}\\*[0mm]}
+}{%
+ \end{description}%
+}
+
+% Tell TeX about pathological hyphenation cases:
+\hyphenation{Base-HTTP-Re-quest-Hand-ler}
diff --git a/doc/tools/texinputs/reportingbugs.tex b/doc/tools/texinputs/reportingbugs.tex
new file mode 100644
index 0000000..c06470a
--- /dev/null
+++ b/doc/tools/texinputs/reportingbugs.tex
@@ -0,0 +1,65 @@
+\label{reporting-bugs}
+
+Python is a mature programming language which has established a
+reputation for stability. In order to maintain this reputation, the
+developers would like to know of any deficiencies you find in Python
+or its documentation.
+
+All bug reports should be submitted via the Python Bug Tracker on
+SourceForge (\url{http://sourceforge.net/bugs/?group_id=5470}). The
+bug tracker offers a Web form which allows pertinent information to be
+entered and submitted to the developers.
+
+Before submitting a report, please log into SourceForge if you are a
+member; this will make it possible for the developers to contact you
+for additional information if needed. If you are not a SourceForge
+member but would not mind the developers contacting you, you may
+include your email address in your bug description. In this case,
+please realize that the information is publically available and cannot
+be protected.
+
+The first step in filing a report is to determine whether the problem
+has already been reported. The advantage in doing so, aside from
+saving the developers time, is that you learn what has been done to
+fix it; it may be that the problem has already been fixed for the next
+release, or additional information is needed (in which case you are
+welcome to provide it if you can!). To do this, search the bug
+database using the search box near the bottom of the page.
+
+If the problem you're reporting is not already in the bug tracker, go
+back to the Python Bug Tracker
+(\url{http://sourceforge.net/bugs/?group_id=5470}). Select the
+``Submit a Bug'' link at the top of the page to open the bug reporting
+form.
+
+The submission form has a number of fields. The only fields that are
+required are the ``Summary'' and ``Details'' fields. For the summary,
+enter a \emph{very} short description of the problem; less than ten
+words is good. In the Details field, describe the problem in detail,
+including what you expected to happen and what did happen. Be sure to
+include the version of Python you used, whether any extension modules
+were involved, and what hardware and software platform you were using
+(including version information as appropriate).
+
+The only other field that you may want to set is the ``Category''
+field, which allows you to place the bug report into a broad category
+(such as ``Documentation'' or ``Library'').
+
+Each bug report will be assigned to a developer who will determine
+what needs to be done to correct the problem. If you have a
+SourceForge account and logged in to report the problem, you will
+receive an update each time action is taken on the bug.
+
+
+\begin{seealso}
+ \seetitle[http://www-mice.cs.ucl.ac.uk/multimedia/software/documentation/ReportingBugs.html]{How
+ to Report Bugs Effectively}{Article which goes into some
+ detail about how to create a useful bug report. This
+ describes what kind of information is useful and why it is
+ useful.}
+
+ \seetitle[http://www.mozilla.org/quality/bug-writing-guidelines.html]{Bug
+ Writing Guidelines}{Information about writing a good bug
+ report. Some of this is specific to the Mozilla project, but
+ describes general good practices.}
+\end{seealso}
diff --git a/doc/tools/toc2bkm.py b/doc/tools/toc2bkm.py
new file mode 100755
index 0000000..45c7ef8
--- /dev/null
+++ b/doc/tools/toc2bkm.py
@@ -0,0 +1,143 @@
+#! /usr/bin/env python
+
+"""Convert a LaTeX .toc file to some PDFTeX magic to create that neat outline.
+
+The output file has an extension of '.bkm' instead of '.out', since hyperref
+already uses that extension.
+"""
+
+import getopt
+import os
+import re
+import string
+import sys
+
+
+# Ench item in an entry is a tuple of:
+#
+# Section #, Title String, Page #, List of Sub-entries
+#
+# The return value of parse_toc() is such a tuple.
+
+cline_re = r"""^
+\\contentsline\ \{([a-z]*)} # type of section in $1
+\{(?:\\numberline\ \{([0-9.A-Z]+)})? # section number
+(.*)} # title string
+\{(\d+)}$""" # page number
+
+cline_rx = re.compile(cline_re, re.VERBOSE)
+
+OUTER_TO_INNER = -1
+
+_transition_map = {
+ ('chapter', 'section'): OUTER_TO_INNER,
+ ('section', 'subsection'): OUTER_TO_INNER,
+ ('subsection', 'subsubsection'): OUTER_TO_INNER,
+ ('subsubsection', 'subsection'): 1,
+ ('subsection', 'section'): 1,
+ ('section', 'chapter'): 1,
+ ('subsection', 'chapter'): 2,
+ ('subsubsection', 'section'): 2,
+ ('subsubsection', 'chapter'): 3,
+ }
+
+INCLUDED_LEVELS = ("chapter", "section", "subsection", "subsubsection")
+
+
+def parse_toc(fp, bigpart=None):
+ toc = top = []
+ stack = [toc]
+ level = bigpart or 'chapter'
+ lineno = 0
+ while 1:
+ line = fp.readline()
+ if not line:
+ break
+ lineno = lineno + 1
+ m = cline_rx.match(line)
+ if m:
+ stype, snum, title, pageno = m.group(1, 2, 3, 4)
+ title = clean_title(title)
+ entry = (stype, snum, title, string.atoi(pageno), [])
+ if stype == level:
+ toc.append(entry)
+ else:
+ if stype not in INCLUDED_LEVELS:
+ # we don't want paragraphs & subparagraphs
+ continue
+ direction = _transition_map[(level, stype)]
+ if direction == OUTER_TO_INNER:
+ toc = toc[-1][-1]
+ stack.insert(0, toc)
+ toc.append(entry)
+ else:
+ for i in range(direction):
+ del stack[0]
+ toc = stack[0]
+ toc.append(entry)
+ level = stype
+ else:
+ sys.stderr.write("l.%s: " + line)
+ return top
+
+
+hackscore_rx = re.compile(r"\\hackscore\s*{[^}]*}")
+raisebox_rx = re.compile(r"\\raisebox\s*{[^}]*}")
+title_rx = re.compile(r"\\([a-zA-Z])+\s+")
+title_trans = string.maketrans("", "")
+
+def clean_title(title):
+ title = raisebox_rx.sub("", title)
+ title = hackscore_rx.sub(r"\\_", title)
+ pos = 0
+ while 1:
+ m = title_rx.search(title, pos)
+ if m:
+ start = m.start()
+ if title[start:start+15] != "\\textunderscore":
+ title = title[:start] + title[m.end():]
+ pos = start + 1
+ else:
+ break
+ title = string.translate(title, title_trans, "{}")
+ return title
+
+
+def write_toc(toc, fp):
+ for entry in toc:
+ write_toc_entry(entry, fp, 0)
+
+def write_toc_entry(entry, fp, layer):
+ stype, snum, title, pageno, toc = entry
+ s = "\\pdfoutline goto name{page%03d}" % pageno
+ if toc:
+ s = "%s count -%d" % (s, len(toc))
+ if snum:
+ title = "%s %s" % (snum, title)
+ s = "%s {%s}\n" % (s, title)
+ fp.write(s)
+ for entry in toc:
+ write_toc_entry(entry, fp, layer + 1)
+
+
+def process(ifn, ofn, bigpart=None):
+ toc = parse_toc(open(ifn), bigpart)
+ write_toc(toc, open(ofn, "w"))
+
+
+def main():
+ bigpart = None
+ opts, args = getopt.getopt(sys.argv[1:], "c:")
+ if opts:
+ bigpart = opts[0][1]
+ if not args:
+ usage()
+ sys.exit(2)
+ for filename in args:
+ base, ext = os.path.splitext(filename)
+ ext = ext or ".toc"
+ process(base + ext, base + ".bkm", bigpart)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/doc/tools/update-docs.sh b/doc/tools/update-docs.sh
new file mode 100755
index 0000000..79652ac
--- /dev/null
+++ b/doc/tools/update-docs.sh
@@ -0,0 +1,21 @@
+#! /bin/sh
+
+# Script which installs a development snapshot of the documentation
+# into the "Python @ SourceForge" website.
+#
+# The push-docs.sh script pushes this to the SourceForge when needed
+# and removes it when done.
+
+if [ -z "$HOME" ] ; then
+ HOME=`grep fdrake /etc/passwd | sed 's|^.*:\([^:]*\):[^:]*$|\1|'`
+ export HOME
+fi
+
+UPDATES="$HOME/tmp/$1"
+
+cd /home/groups/python/htdocs || exit $?
+rm -rf devel-docs || exit $?
+mkdir devel-docs || exit $?
+cd devel-docs || exit $?
+(bzip2 -dc "$UPDATES" | tar xf -) || exit $?
+rm "$UPDATES" || exit $?
diff --git a/doc/tools/whichlibs b/doc/tools/whichlibs
new file mode 100755
index 0000000..10d44ee
--- /dev/null
+++ b/doc/tools/whichlibs
@@ -0,0 +1,2 @@
+#!/bin/sh
+sed -n 's%^\\input{\(lib[a-zA-Z0-9_]*\)}.*%../lib/\1.tex%p' ../lib/lib.tex
