Merged changes from the 1.5.2p2 release.

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}
 }
 

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}}

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}}