Python standard documentation -- in LaTeX----------------------------------------- This directory contains the LaTeX sources to the Python documentationand tools required to support the formatting process.  The documentsnow require LaTeX2e; LaTeX 2.09 compatibility has been dropped. If you don't have LaTeX, or if you'd rather not format thedocumentation yourself, you can ftp a tar file containing HTML, PDF,or PostScript versions of all documents.  Additional formats may beavailable.  These should be in the same place where you fetched themain 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 Modulesdocument uses the "howto" document class instead.  These contains manymacro definitions useful in documenting Python, and set some styleparameters. There's a Makefile to call LaTeX and the other utilities in the rightorder and the right number of times.  By default, it will build theHTML version of the documentation, but DVI, PDF, and PostScript canalso be made.  To view the generated HTML, point your favorite browserat the top-level index (html/index.html) after running "make". The Makefile can also produce DVI files for each document made; topreview them, use xdvi.  PostScript is produced by the same Makefiletarget that produces the DVI files.  This uses the dvips tool.Printing depends on local conventions; at our site, we use lpr.  Forexample: 	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 thedocumentation at <http://www.python.org/dev/doc/devel/>; we mayhave already fixed it. If we haven't, tell us about it.  We'd like the documentation to becomplete and accurate, but have limited time.  If you discover anyinconsistencies between the documentation and implementation, or justhave suggestions as to how to improve the documentation, let is know!Specific bugs and patches should be reported using our bug & patchdatabases at: 	http://sourceforge.net/projects/python Other suggestions or questions should be sent to the PythonDocumentation Team: 	docs@python.org Thanks!  What tools do I need?--------------------- You need to install Python; some of the scripts used to produce thedocumentation are written in Python.  You don't need thisdocumentation to install Python; instructions are included in theREADME file in the Python distribution. The simplest way to get the rest of the tools in the configuration weused 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 documentationrelease was tested with the 1.0.7 release, but there have been nosubstantial changes since late in the 0.9 series, which we usedextensively 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 touse 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 beenobserved on other systems in the past. On some systems, the default sizes of some of the memory poolsallocated by TeX needs to be changed; this is a configuration settingfor installations based on web2c (most if not all installations).This is usually set in a file named texmf/web2c/texmf.cnf (where thetop-level texmf/ directory is part of the TeX installation).  If youget a "buffer overflow" warning from LaTeX, open that configurationfile and look for the "main_memory.pdflatex" setting.  If there is notone, you can add a line with the setting.  The value 1500000 seems tobe sufficient for formatting the Python documetantion.  What if Times fonts are not available?-------------------------------------- As distributed, the LaTeX documents use PostScript Times fonts.  Thisis done since they are much better looking and produce smallerPostScript files.  If, however, your TeX installation does not supportthem, they may be easily disabled.  Edit the filetexinputs/pypaper.sty and comment out the line that starts"\RequirePackage{times}" by inserting a "%" character at the beginningof the line.  If you're formatting the docs for A4 paper instead ofUS-Letter paper, change paper-a4/pypaper.sty instead.  An alternativeis 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 inthe paper-a4/ subdirectory.  (You can use "make PAPER=a4 pdf" if you'drather 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 forthe new series of Python HOWTO documents which is being coordinated byAndrew Kuchling <akuchlin@mems-exchange.org>.  The filetemplates/howto.tex is a commented example which may be used as atemplate.  A Python script to "do the right thing" to format a howtodocument is included as tools/mkhowto.  These documents can beformatted 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 filetemplates/module.tex which may be used as a template for a modulesection.  This may be used in conjunction with either the howto ormanual document class.  Create the documentation for a new module bycopying the template to lib<mymodule>.tex and editing according to the instructions in the comments. Documentation on the authoring Python documentation, includinginformation 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 itas 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 andredistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES.----------------------------------------------------------------------