cpython/Doc
Guido van Rossum d59da4b432 Merged revisions 55407-55513 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/branches/p3yk

................
  r55413 | fred.drake | 2007-05-17 12:30:10 -0700 (Thu, 17 May 2007) | 1 line

  fix argument name in documentation; match the implementation
................
  r55430 | jack.diederich | 2007-05-18 06:39:59 -0700 (Fri, 18 May 2007) | 1 line

  Implements class decorators, PEP 3129.
................
  r55432 | guido.van.rossum | 2007-05-18 08:09:41 -0700 (Fri, 18 May 2007) | 2 lines

  obsubmit.
................
  r55434 | guido.van.rossum | 2007-05-18 09:39:10 -0700 (Fri, 18 May 2007) | 3 lines

  Fix bug in test_inspect.  (I presume this is how it should be fixed;
  Jack Diedrich, please verify.)
................
  r55460 | brett.cannon | 2007-05-20 00:31:57 -0700 (Sun, 20 May 2007) | 4 lines

  Remove the imageop module.  With imgfile already removed in Python 3.0 and
  rgbimg gone in Python 2.6 the unit tests themselves were made worthless.  Plus
  third-party libraries perform the same function much better.
................
  r55469 | neal.norwitz | 2007-05-20 11:28:20 -0700 (Sun, 20 May 2007) | 118 lines

  Merged revisions 55324-55467 via svnmerge from
  svn+ssh://pythondev@svn.python.org/python/trunk

  ........
    r55348 | georg.brandl | 2007-05-15 13:19:34 -0700 (Tue, 15 May 2007) | 4 lines

    HTML-escape the plain traceback in cgitb's HTML output, to prevent
    the traceback inadvertently or maliciously closing the comment and
    injecting HTML into the error page.
  ........
    r55372 | neal.norwitz | 2007-05-15 21:33:50 -0700 (Tue, 15 May 2007) | 6 lines

    Port rev 55353 from Guido:
    Add what looks like a necessary call to PyErr_NoMemory() when PyMem_MALLOC()
    fails.

    Will backport.
  ........
    r55377 | neal.norwitz | 2007-05-15 22:06:33 -0700 (Tue, 15 May 2007) | 1 line

    Mention removal of some directories for obsolete platforms
  ........
    r55380 | brett.cannon | 2007-05-15 22:50:03 -0700 (Tue, 15 May 2007) | 2 lines

    Change the maintainer of the BeOS port.
  ........
    r55383 | georg.brandl | 2007-05-16 06:44:18 -0700 (Wed, 16 May 2007) | 2 lines

    Bug #1719995: don't use deprecated method in sets example.
  ........
    r55386 | neal.norwitz | 2007-05-16 13:05:11 -0700 (Wed, 16 May 2007) | 5 lines

    Fix bug in marshal where bad data would cause a segfault due to
    lack of an infinite recursion check.

    Contributed by Damien Miller at Google.
  ........
    r55389 | brett.cannon | 2007-05-16 15:42:29 -0700 (Wed, 16 May 2007) | 6 lines

    Remove the gopherlib module.  It has been raising a DeprecationWarning since
    Python 2.5.

    Also remove gopher support from urllib/urllib2.  As both imported gopherlib the
    usage of the support would have raised a DeprecationWarning.
  ........
    r55394 | raymond.hettinger | 2007-05-16 18:08:04 -0700 (Wed, 16 May 2007) | 1 line

    calendar.py gets no benefit from xrange() instead of range()
  ........
    r55395 | brett.cannon | 2007-05-16 19:02:56 -0700 (Wed, 16 May 2007) | 3 lines

    Complete deprecation of BaseException.message.  Some subclasses were directly
    accessing the message attribute instead of using the descriptor.
  ........
    r55396 | neal.norwitz | 2007-05-16 23:11:36 -0700 (Wed, 16 May 2007) | 4 lines

    Reduce the max stack depth to see if this fixes the segfaults on
    Windows and some other boxes.  If this is successful, this rev should
    be backported.  I'm not sure how close to the limit we should push this.
  ........
    r55397 | neal.norwitz | 2007-05-16 23:23:50 -0700 (Wed, 16 May 2007) | 4 lines

    Set the depth to something very small to try to determine if the
    crashes on Windows are really due to the stack size or possibly
    some other problem.
  ........
    r55398 | neal.norwitz | 2007-05-17 00:04:46 -0700 (Thu, 17 May 2007) | 4 lines

    Last try for tweaking the max stack depth.  5000 was the original value,
    4000 didn't work either.  1000 does work on Windows.  If 2000 works,
    that will hopefully be a reasonable balance.
  ........
    r55412 | fred.drake | 2007-05-17 12:29:58 -0700 (Thu, 17 May 2007) | 1 line

    fix argument name in documentation; match the implementation
  ........
    r55427 | neal.norwitz | 2007-05-17 22:47:16 -0700 (Thu, 17 May 2007) | 1 line

    Verify neither dumps or loads overflow the stack and segfault.
  ........
    r55446 | collin.winter | 2007-05-18 16:11:24 -0700 (Fri, 18 May 2007) | 1 line

    Backport PEP 3110's new 'except' syntax to 2.6.
  ........
    r55448 | raymond.hettinger | 2007-05-18 18:11:16 -0700 (Fri, 18 May 2007) | 1 line

    Improvements to NamedTuple's implementation, tests, and documentation
  ........
    r55449 | raymond.hettinger | 2007-05-18 18:50:11 -0700 (Fri, 18 May 2007) | 1 line

    Fix beginner mistake -- don't mix spaces and tabs.
  ........
    r55450 | neal.norwitz | 2007-05-18 20:48:47 -0700 (Fri, 18 May 2007) | 1 line

    Clear data so random memory does not get freed.  Will backport.
  ........
    r55452 | neal.norwitz | 2007-05-18 21:34:55 -0700 (Fri, 18 May 2007) | 3 lines

    Whoops, need to pay attention to those test failures.
    Move the clear to *before* the first use, not after.
  ........
    r55453 | neal.norwitz | 2007-05-18 21:35:52 -0700 (Fri, 18 May 2007) | 1 line

    Give some clue as to what happened if the test fails.
  ........
    r55455 | georg.brandl | 2007-05-19 11:09:26 -0700 (Sat, 19 May 2007) | 2 lines

    Fix docstring for add_package in site.py.
  ........
    r55458 | brett.cannon | 2007-05-20 00:09:50 -0700 (Sun, 20 May 2007) | 2 lines

    Remove the rgbimg module.  It has been deprecated since Python 2.5.
  ........
    r55465 | nick.coghlan | 2007-05-20 04:12:49 -0700 (Sun, 20 May 2007) | 1 line

    Fix typo in example (should be backported, but my maintenance branch is woefully out of date)
  ........
................
  r55472 | brett.cannon | 2007-05-20 12:06:18 -0700 (Sun, 20 May 2007) | 2 lines

  Remove imageop from the Windows build process.
................
  r55486 | neal.norwitz | 2007-05-20 23:59:52 -0700 (Sun, 20 May 2007) | 1 line

  Remove callable() builtin
................
  r55506 | neal.norwitz | 2007-05-22 00:43:29 -0700 (Tue, 22 May 2007) | 78 lines

  Merged revisions 55468-55505 via svnmerge from
  svn+ssh://pythondev@svn.python.org/python/trunk

  ........
    r55468 | neal.norwitz | 2007-05-20 11:06:27 -0700 (Sun, 20 May 2007) | 1 line

    rotor is long gone.
  ........
    r55470 | neal.norwitz | 2007-05-20 11:43:00 -0700 (Sun, 20 May 2007) | 1 line

    Update directories/files at the top-level.
  ........
    r55471 | brett.cannon | 2007-05-20 12:05:06 -0700 (Sun, 20 May 2007) | 2 lines

    Try to remove rgbimg from Windows builds.
  ........
    r55474 | brett.cannon | 2007-05-20 16:17:38 -0700 (Sun, 20 May 2007) | 4 lines

    Remove the macfs module.  This led to the deprecation of macostools.touched();
    it completely relied on macfs and is a no-op on OS X according to code
    comments.
  ........
    r55476 | brett.cannon | 2007-05-20 16:56:18 -0700 (Sun, 20 May 2007) | 3 lines

    Move imgfile import to the global namespace to trigger an import error ASAP to
    prevent creation of a test file.
  ........
    r55477 | brett.cannon | 2007-05-20 16:57:38 -0700 (Sun, 20 May 2007) | 3 lines

    Cause posixfile to raise a DeprecationWarning.  Documented as deprecated since
    Ptyhon 1.5.
  ........
    r55479 | andrew.kuchling | 2007-05-20 17:03:15 -0700 (Sun, 20 May 2007) | 1 line

    Note removed modules
  ........
    r55481 | martin.v.loewis | 2007-05-20 21:35:47 -0700 (Sun, 20 May 2007) | 2 lines

    Add Alexandre Vassalotti.
  ........
    r55482 | george.yoshida | 2007-05-20 21:41:21 -0700 (Sun, 20 May 2007) | 4 lines

    fix against r55474 [Remove the macfs module]

    Remove "libmacfs.tex" from Makefile.deps and mac/mac.tex.
  ........
    r55487 | raymond.hettinger | 2007-05-21 01:13:35 -0700 (Mon, 21 May 2007) | 1 line

    Replace assertion with straight error-checking.
  ........
    r55489 | raymond.hettinger | 2007-05-21 09:40:10 -0700 (Mon, 21 May 2007) | 1 line

    Allow all alphanumeric and underscores in type and field names.
  ........
    r55490 | facundo.batista | 2007-05-21 10:32:32 -0700 (Mon, 21 May 2007) | 5 lines


    Added timeout support to HTTPSConnection, through the
    socket.create_connection function. Also added a small
    test for this, and updated NEWS file.
  ........
    r55495 | georg.brandl | 2007-05-21 13:34:16 -0700 (Mon, 21 May 2007) | 2 lines

    Patch #1686487: you can now pass any mapping after '**' in function calls.
  ........
    r55502 | neal.norwitz | 2007-05-21 23:03:36 -0700 (Mon, 21 May 2007) | 1 line

    Document new params to HTTPSConnection
  ........
    r55504 | neal.norwitz | 2007-05-22 00:16:10 -0700 (Tue, 22 May 2007) | 1 line

    Stop using METH_OLDARGS
  ........
    r55505 | neal.norwitz | 2007-05-22 00:16:44 -0700 (Tue, 22 May 2007) | 1 line

    Stop using METH_OLDARGS implicitly
  ........
................
2007-05-22 18:11:13 +00:00
..
api Add 'U'/'U#' format characters to Py_BuildValue (and thus 2007-05-18 16:29:38 +00:00
commontex Merged revisions 53952-54987 via svnmerge from 2007-04-27 19:54:29 +00:00
dist Merged revisions 55325-55327 via svnmerge from 2007-05-14 22:51:27 +00:00
doc Merged revisions 46753-51188 via svnmerge from 2006-08-11 14:57:12 +00:00
ext Change UnicodeDecodeError objects so that the 'object' attribute 2007-05-04 19:28:21 +00:00
howto PEP 3114: rename .next() to .__next__() and add next() builtin. 2007-04-21 15:47:16 +00:00
html hide version notes for 1.x and 2.x from the HTML version 2006-12-19 22:06:09 +00:00
info Bug #1368481: python.dir refers to whatsnew23 2005-12-02 13:43:08 +00:00
inst Merged revisions 53952-54987 via svnmerge from 2007-04-27 19:54:29 +00:00
lib Merged revisions 55407-55513 via svnmerge from 2007-05-22 18:11:13 +00:00
mac Merged revisions 55407-55513 via svnmerge from 2007-05-22 18:11:13 +00:00
paper-a4 Remove .cvsignore files, as they live in svn:ignore 2005-10-30 22:01:41 +00:00
perl hide version notes for 1.x and 2.x from the HTML version 2006-12-19 22:06:09 +00:00
ref Merged revisions 55407-55513 via svnmerge from 2007-05-22 18:11:13 +00:00
templates SF Patch #1093896: miscellaneous doc typos 2005-01-01 00:28:46 +00:00
tests clean up the underscore mess for the typeset formats so that subscripts 2005-03-24 06:21:37 +00:00
texinputs Merged revisions 53952-54987 via svnmerge from 2007-04-27 19:54:29 +00:00
tools Merged revisions 55325-55327 via svnmerge from 2007-05-14 22:51:27 +00:00
tut Merged revisions 55407-55513 via svnmerge from 2007-05-22 18:11:13 +00:00
whatsnew Merged revisions 55407-55513 via svnmerge from 2007-05-22 18:11:13 +00:00
ACKS Merged revisions 46753-51188 via svnmerge from 2006-08-11 14:57:12 +00:00
Makefile Use the local python binary to build the docs, not whatever 'python' is on the PATH (which is probably Python 2.x, and we need 3.x). 2007-03-21 02:14:12 +00:00
Makefile.deps Merged revisions 55407-55513 via svnmerge from 2007-05-22 18:11:13 +00:00
README Merged revisions 53005-53303 via svnmerge from 2007-01-09 23:18:33 +00:00
TODO
python-docs.txt Merge p3yk branch with the trunk up to revision 45595. This breaks a fair 2006-04-21 10:40:58 +00:00

README

Python standard documentation -- in LaTeX
-----------------------------------------

This directory contains the LaTeX sources to the Python documentation
and tools required to support the formatting process.  The documents
now require LaTeX2e; LaTeX 2.09 compatibility has been dropped.

If you don't have LaTeX, or if you'd rather not format the
documentation yourself, you can ftp a tar file containing HTML, PDF,
or PostScript versions of all documents.  Additional formats may be
available.  These should be in the same place where you fetched the
main Python distribution (try <http://www.python.org/> or
<ftp://ftp.python.org/pub/python/>).

The following are the LaTeX source files:

	api/*.tex	Python/C API Reference Manual
	doc/*.tex	Documenting Python
	ext/*.tex	Extending and Embedding the Python Interpreter
	lib/*.tex	Python Library Reference
	mac/*.tex	Macintosh Library Modules
	ref/*.tex	Python Reference Manual
	tut/*.tex	Python Tutorial
        inst/*.tex      Installing Python Modules
        dist/*.tex      Distributing Python Modules

Most use the "manual" document class and "python" package, derived from 
the old "myformat.sty" style file.  The Macintosh Library Modules
document uses the "howto" document class instead.  These contains many
macro definitions useful in documenting Python, and set some style
parameters.

There's a Makefile to call LaTeX and the other utilities in the right
order and the right number of times.  By default, it will build the
HTML version of the documentation, but DVI, PDF, and PostScript can
also be made.  To view the generated HTML, point your favorite browser
at the top-level index (html/index.html) after running "make".

The Makefile can also produce DVI files for each document made; to
preview them, use xdvi.  PostScript is produced by the same Makefile
target that produces the DVI files.  This uses the dvips tool.
Printing depends on local conventions; at our site, we use lpr.  For
example:

	make paper-letter/lib.ps	# create lib.dvi and lib.ps
	xdvi paper-letter/lib.dvi	# preview lib.dvi
	lpr paper-letter/lib.ps		# print on default printer


What if I find a bug?
---------------------

First, check that the bug is present in the development version of the
documentation at <http://www.python.org/dev/doc/devel/>; we may
have already fixed it.

If we haven't, tell us about it.  We'd like the documentation to be
complete and accurate, but have limited time.  If you discover any
inconsistencies between the documentation and implementation, or just
have suggestions as to how to improve the documentation, let is know!
Specific bugs and patches should be reported using our bug & patch
databases at:

	http://sourceforge.net/projects/python

Other suggestions or questions should be sent to the Python
Documentation Team:

	docs@python.org

Thanks!


What tools do I need?
---------------------

You need to install Python; some of the scripts used to produce the
documentation are written in Python.  You don't need this
documentation to install Python; instructions are included in the
README file in the Python distribution.

The simplest way to get the rest of the tools in the configuration we
used is to install the teTeX TeX distribution, versions 0.9 or newer.
More information is available on teTeX at <http://www.tug.org/tetex/>.
This is a Unix-only TeX distribution at this time.  This documentation
release was tested with the 1.0.7 release, but there have been no
substantial changes since late in the 0.9 series, which we used
extensively for previous versions without any difficulty.

If you don't want to get teTeX, here is what you'll need:

To create DVI, PDF, or PostScript files:

	- LaTeX2e, 1995/12/01 or newer.  Older versions are likely to 
	  choke.

	- makeindex.  This is used to produce the indexes for the
	  library reference and Python/C API reference.

To create PDF files:

	- pdflatex.  We used the one in the teTeX distribution (pdfTeX
          version 3.14159-13d (Web2C 7.3.1) at the time of this
          writing).  Versions even a couple of patchlevels earlier are
          highly likely to fail due to syntax changes for some of the
          pdftex primitives.

To create PostScript files:

	- dvips.  Most TeX installations include this.  If you don't
	  have one, check CTAN (<ftp://ctan.tug.org/tex-archive/>).

To create info files:

	Note that info support is currently being revised using new
	conversion tools by Michael Ernst <mernst@cs.washington.edu>.

	- makeinfo.  This is available from any GNU mirror.

	- emacs or xemacs.  Emacs is available from the same place as
	  makeinfo, and xemacs is available from ftp.xemacs.org.

	- Perl.  Find the software at
	  <http://language.perl.com/info/software.html>.

	- HTML::Element.  If you don't have this installed, you can get
	  this from CPAN.  Use the command:

	  perl -e 'use CPAN; CPAN::install("HTML::Element");'

	  You may need to be root to do this.

To create HTML files:

	- Perl 5.6.0 or newer.  Find the software at
	  <http://language.perl.com/info/software.html>.

	- LaTeX2HTML 99.2b8 or newer.  Older versions are not
	  supported; each version changes enough that supporting
	  multiple versions is not likely to work.  Many older
	  versions don't work with Perl 5.6 as well.  This also screws
	  up code fragments.  ;-(  Releases are available at:
	  <http://www.latex2html.org/>.


I got a make error: "make: don't know how to make commontex/patchlevel.tex."
----------------------------------------------------------------------------

Your version of make doesn't support the 'shell' function.  You will need to
use a version which does, e.g. GNU make.


LaTeX (or pdfLaTeX) ran out of memory; how can I fix it?
--------------------------------------------------------

This is known to be a problem at least on Mac OS X, but it has been
observed on other systems in the past.

On some systems, the default sizes of some of the memory pools
allocated by TeX needs to be changed; this is a configuration setting
for installations based on web2c (most if not all installations).
This is usually set in a file named texmf/web2c/texmf.cnf (where the
top-level texmf/ directory is part of the TeX installation).  If you
get a "buffer overflow" warning from LaTeX, open that configuration
file and look for the "main_memory.pdflatex" setting.  If there is not
one, you can add a line with the setting.  The value 1500000 seems to
be sufficient for formatting the Python documetantion.


What if Times fonts are not available?
--------------------------------------

As distributed, the LaTeX documents use PostScript Times fonts.  This
is done since they are much better looking and produce smaller
PostScript files.  If, however, your TeX installation does not support
them, they may be easily disabled.  Edit the file
texinputs/pypaper.sty and comment out the line that starts
"\RequirePackage{times}" by inserting a "%" character at the beginning
of the line.  If you're formatting the docs for A4 paper instead of
US-Letter paper, change paper-a4/pypaper.sty instead.  An alternative
is to install the right fonts and LaTeX style file.


What if I want to use A4 paper?
-------------------------------

Instead of building the PostScript by giving the command "make ps",
give the command "make PAPER=a4 ps"; the output will be produced in
the paper-a4/ subdirectory.  (You can use "make PAPER=a4 pdf" if you'd
rather have PDF output.)


Making HTML files
-----------------

The LaTeX documents can be converted to HTML using Nikos Drakos'
LaTeX2HTML converter.  See the Makefile; after some twiddling, "make"
should do the trick.


What else is in here?
---------------------

There is a new LaTeX document class called "howto".  This is used for
the new series of Python HOWTO documents which is being coordinated by
Andrew Kuchling <akuchlin@mems-exchange.org>.  The file
templates/howto.tex is a commented example which may be used as a
template.  A Python script to "do the right thing" to format a howto
document is included as tools/mkhowto.  These documents can be
formatted as HTML, PDF, PostScript, or ASCII files.  Use "mkhowto
--help" for information on using the formatting tool.

For authors of module documentation, there is a file
templates/module.tex which may be used as a template for a module
section.  This may be used in conjunction with either the howto or
manual document class.  Create the documentation for a new module by
copying the template to lib<mymodule>.tex and editing according to the 
instructions in the comments.

Documentation on the authoring Python documentation, including
information about both style and markup, is available in the
"Documenting Python" manual.


Copyright notice
================

The Python source is copyrighted, but you can freely use and copy it
as long as you don't change or remove the copyright notice:

----------------------------------------------------------------------
Copyright (c) 2000-2007 Python Software Foundation.
All rights reserved.

Copyright (c) 2000 BeOpen.com.
All rights reserved.

Copyright (c) 1995-2000 Corporation for National Research Initiatives.
All rights reserved.

Copyright (c) 1991-1995 Stichting Mathematisch Centrum.
All rights reserved.

See the file "commontex/license.tex" for information on usage and
redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES.
----------------------------------------------------------------------