diff options
| -rw-r--r-- | Doc/texinputs/boilerplate.tex | 4 | ||||
| -rw-r--r-- | Doc/texinputs/ltxmarkup.sty | 2 | ||||
| -rw-r--r-- | Doc/texinputs/python.sty | 70 | ||||
| -rwxr-xr-x | Doc/tools/buildindex.py | 28 | ||||
| -rwxr-xr-x | Doc/tools/getpagecounts | 15 | ||||
| -rwxr-xr-x | Doc/tools/mkdvi.sh | 2 | ||||
| -rwxr-xr-x | Doc/tools/mkhowto | 2 | ||||
| -rwxr-xr-x | Doc/tools/mkhtml.sh | 4 | ||||
| -rwxr-xr-x | Doc/tools/mkmodindex | 5 | ||||
| -rwxr-xr-x | Doc/tools/mksourcepkg | 4 | ||||
| -rwxr-xr-x | Doc/tools/node2label.pl | 10 |
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"; } } |