Merged changes from the 1.5.2p2 release.

11 files changed, 118 insertions, 28 deletions

diff --git a/Doc/texinputs/boilerplate.tex b/Doc/texinputs/boilerplate.tex
index 30bc37c..b1a07a4 100644
--- a/Doc/texinputs/boilerplate.tex
+++ b/Doc/texinputs/boilerplate.tex
@@ -1,8 +1,8 @@
 \author{Guido van Rossum}
 
 \authoraddress{
-	Corporation for National Research Initiatives (CNRI) \\
-	1895 Preston White Drive, Reston, Va 20191, USA \\
+	Corporation for National Research Initiatives \\
+	1895 Preston White Drive, Reston, VA 20191, USA \\
 	E-mail: \email{guido@python.org}
 }
 
diff --git a/Doc/texinputs/ltxmarkup.sty b/Doc/texinputs/ltxmarkup.sty
index 62ef4f3..4b769be 100644
--- a/Doc/texinputs/ltxmarkup.sty
+++ b/Doc/texinputs/ltxmarkup.sty
@@ -18,7 +18,7 @@
       \let\op=\py@ltx@optparam%
       \let\p=\py@ltx@param%
       #2}}]
-    %\item[\code{\e end\{{\bfseries #1}\}}]
+    \item[\code{\e end\{{\bfseries #1}\}}]
     \index{#1 environment@\idxcode{#1} environment}
     \index{environments!#1@\idxcode{#1}}
 }{\end{fulllineitems}}
diff --git a/Doc/texinputs/python.sty b/Doc/texinputs/python.sty
index 76ae86f..3ec42c5 100644
--- a/Doc/texinputs/python.sty
+++ b/Doc/texinputs/python.sty
@@ -277,13 +277,25 @@
   \typeout{*** MACRO exmodindex IS OBSOLETE -- USE declaremodule INSTEAD!}}
 
 % Additional string for an index entry
-\newcommand{\index@subitem}{}
-\newcommand{\setindexsubitem}[1]{\renewcommand{\index@subitem}{#1}}
-\newcommand{\ttindex}[1]{\index{#1@{\py@idxcode{#1}} \index@subitem}}
-
+\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\index@subitem{#1}#2%
+    \ifpy@usingsubitem%
+      \def\index@subitem{#1}#2%
+    \else%
+      \def\index@subitem{#1}#2%
+      \py@usingsubitemfalse%
+    \fi
   \endgroup%
 }
 
@@ -421,6 +433,7 @@
 
 
 \newcommand{\py@reset}{
+  \py@usingsubitemfalse
   \py@ProcessModSynopsis
   \renewcommand{\py@thisclass}{}
   \renewcommand{\py@thismodule}{}
@@ -510,14 +523,30 @@
 %
 %     \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}{type}{name}{arglist}
-\newenvironment{cfuncdesc}[3]{
+% \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{#1 \bfcode{#2}(\py@varvars{#3})}\index{#2@{\py@idxcode{#2()}}}]
+    \item[\code{#2 \bfcode{#3}(\py@varvars{#4})}\index{#3@{\py@idxcode{#3()}}}]
+    \ifx#1\@undefined\else%
+      \emph{Return value: \textbf{#1 reference}.}\\
+    \fi
 }{\end{fulllineitems}}
 
 % C variables ------------------------------------------------------------
@@ -528,10 +557,23 @@
 }{\end{fulllineitems}}
 
 % C data types -----------------------------------------------------------
-% \begin{ctypedesc}{typedef name}
-\newenvironment{ctypedesc}[1]{
+% \begin{ctypedesc}[index name]{typedef name}
+\newenvironment{ctypedesc}[2][\py@badkey]{
   \begin{fulllineitems}
-    \item[\bfcode{#1}\ttindex{#1}]
+    \item[\bfcode{#2}%
+    \ifx#1\@undefined%
+      \withsubitem{(C type)}{\ttindex{#2}}%
+    \else%
+      \withsubitem{(C type)}{\ttindex{#1}}%
+    \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}\withsubitem{(macro)}{\ttindex{#1}}]
 }{\end{fulllineitems}}
 
 % simple functions (not methods) -----------------------------------------
@@ -708,7 +750,11 @@
 \newcommand{\email}[1]{{\small\textsf{#1}}}
 \newcommand{\newsgroup}[1]{{\small\textsf{#1}}}
 
-\newcommand{\py@varvars}[1]{{\def\,{\/{\char`\,}}\var{#1}}}
+%\newcommand{\py@varvars}[1]{{\def\,{\/{\char`\,}}\var{#1}}}
+\newcommand{\py@varvars}[1]{%
+  {\let\unspecified=\py@unspecified%
+   \let\moreargs=\py@moreargs%
+   \def\,{\/{\char`\,}}\var{#1}}}
 % let's see if this breaks anything now; we may be able to simplify...
 \renewcommand{\py@varvars}[1]{\var{#1}}
 
diff --git a/Doc/tools/buildindex.py b/Doc/tools/buildindex.py
index 81bd311..2451221 100755
--- a/Doc/tools/buildindex.py
+++ b/Doc/tools/buildindex.py
@@ -11,6 +11,8 @@ import sys
 class Node:
     __rmjunk = re.compile("<#\d+#>")
 
+    continuation = 0
+
     def __init__(self, link, str, seqno):
         self.links = [link]
         self.seqno = seqno
@@ -77,7 +79,7 @@ def split_entry(str, which):
     return stuff
 
 
-_rmtt = re.compile(r"(.*)<tt(?: class=[a-z0-9]+)?>(.*)</tt>(.*)$",
+_rmtt = re.compile(r"""(.*)<tt(?: class=['"][a-z0-9]+["'])?>(.*)</tt>(.*)$""",
                    re.IGNORECASE)
 _rmparens = re.compile(r"\(\)")
 
@@ -175,6 +177,22 @@ def split_columns(nodes, columns=1):
             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
 
 
@@ -204,8 +222,12 @@ def format_column(nodes):
         for i in range(count, len(current) - 1):
             term = node.text[i]
             level = level + 1
-            append("\n<dt>%s\n<dd>\n%s<dl compact>"
-                   % (term, level * DL_LEVEL_INDENT))
+            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:]:
diff --git a/Doc/tools/getpagecounts b/Doc/tools/getpagecounts
index ef14053..53a28e1 100755
--- a/Doc/tools/getpagecounts
+++ b/Doc/tools/getpagecounts
@@ -43,13 +43,26 @@ class PageCounter:
     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.  The following manuals are included:
+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):
diff --git a/Doc/tools/mkdvi.sh b/Doc/tools/mkdvi.sh
index 3269a28..880192d 100755
--- a/Doc/tools/mkdvi.sh
+++ b/Doc/tools/mkdvi.sh
@@ -34,7 +34,7 @@ fi
 
 part=$1; shift 1
 
-TEXINPUTS=$srcdir/$part:$TEXINPUTS
+TEXINPUTS=.:$srcdir/$part:$TEXINPUTS
 export TEXINPUTS
 
 echo $srcdir'/tools/newind.py >'$part'.ind'
diff --git a/Doc/tools/mkhowto b/Doc/tools/mkhowto
index 621aa8e..043ac57 100755
--- a/Doc/tools/mkhowto
+++ b/Doc/tools/mkhowto
@@ -330,6 +330,8 @@ class Job:
         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)
         args = [LATEX2HTML_BINARY,
                 "-init_file", L2H_INIT_FILE,
                 "-init_file", self.l2h_aux_init_file,
diff --git a/Doc/tools/mkhtml.sh b/Doc/tools/mkhtml.sh
index 85a66b7..304839c 100755
--- a/Doc/tools/mkhtml.sh
+++ b/Doc/tools/mkhtml.sh
@@ -27,12 +27,16 @@ export TEXINPUTS
 
 if [ -d $part ] ; then
     rm -f $part/*.html
+else
+    mkdir $part
 fi
 
 echo "latex2html -init_file $srcdir/perl/l2hinit.perl -dir $part" \
  "${1:+$@} $srcdir/$part/$part.tex"
 latex2html \
  -no_auto_link \
+ -up_url '../index.html' \
+ -up_title 'Documentation Index' \
  -init_file $srcdir/perl/l2hinit.perl \
  -address '<hr>See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.' \
  -dir $part \
diff --git a/Doc/tools/mkmodindex b/Doc/tools/mkmodindex
index 4400cea..14568d1 100755
--- a/Doc/tools/mkmodindex
+++ b/Doc/tools/mkmodindex
@@ -47,8 +47,9 @@ def error(msg, rc=2):
 
 
 _rx = re.compile(
-    '<dt><a href="(module-.*\.html)">'
-    '([a-zA-Z_][a-zA-Z0-9_.]*(\s*<em>\(.*\)</em>)?)</a>')
+    "<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():
     outputfile = "-"
diff --git a/Doc/tools/mksourcepkg b/Doc/tools/mksourcepkg
index 00c6c50..260ae6d 100755
--- a/Doc/tools/mksourcepkg
+++ b/Doc/tools/mksourcepkg
@@ -105,7 +105,9 @@ def main():
                run("tar cf - Python-%s | gzip -9 >%s.tgz"
                    % (release, archive))
           elif format == "zip":
-               run("zip -r9 %s.zip Python-%s"
+               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:
diff --git a/Doc/tools/node2label.pl b/Doc/tools/node2label.pl
index a59d68e..f8bc1a6 100755
--- a/Doc/tools/node2label.pl
+++ b/Doc/tools/node2label.pl
@@ -32,16 +32,16 @@ foreach $label (keys %internal_labels) {
 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)\=\"/);
+  if (/(HREF|href)=[\"\']([^\#\"\']*)html[\#\"\']/) {
+    @parts = split(/(HREF|href)\=[\"\']/);
     shift @parts;
     for $node (@parts) {
-      $node =~ s/[\#\"].*$//g;
+      $node =~ s/[\#\"\'].*$//g;
       chop($node);
       if (defined($nodes{$node})) {
 	$label = $nodes{$node};
-	if (s/(HREF|href)=\"$node([\#\"])/$1=\"$label.html$2/g) {
-	  s/(HREF|href)=\"$label.html#(l2h-)?SECTION\d+/$1=\"$label.html/g;
+	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";
 	}
       }