Python main 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 or ). The following are the LaTeX source files: api/*.tex Python/C API Reference Manual 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. This will 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 lib # create lib.dvi and lib.ps xdvi lib # preview lib.dvi lpr lib.ps # print on default printer What if I find a bug? --------------------- First, check that the bug is present in the online version of the documentation at ; 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! Send comments and patches to the Python Documentation Team: python-docs@python.org Thanks! What happened to the Macintosh chapter of the Python Library Reference? ----------------------------------------------------------------------- The directory mac/ contains the LaTeX sources for the "Macintosh Library Modules" manual; this is built using the standard build targets, so check the proper output directory for your chosen format and paper size. 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 . 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 (). To create info files: Note that info support is currently being revised using new conversion tools by Michael Ernst . - 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 . To create HTML files: - Perl 5.004_04 or newer. Find the software at . - LaTeX2HTML 99.2b8. 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: . 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 texiinputs/manual.cls and comment out the line that starts "\RequirePackage{times}" by inserting a "%" character at the beginning of the line. 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", give the command "make PAPER=a4"; the output will be produced in the paper-a4/ subdirectory. Making HTML files ----------------- The LaTeX documents can be converted to HTML using Nikos Drakos' LaTeX2HTML converter. See the Makefile; after some twiddling, "make html" 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 . The file templates/howto.tex is a commented example which may be used a template. A 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. Support for this document class is still new, but is expected to evolve rapidly. 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.tex and editing according to the instructions in the comments. 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 1991-1995 by Stichting Mathematisch Centrum, Amsterdam, The Netherlands. All Rights Reserved Copyright (c) 2000, BeOpen.com. Copyright (c) 1995-2000, Corporation for National Research Initiatives. Copyright (c) 1990-1995, Stichting Mathematisch Centrum. All rights reserved. See the file "Misc/COPYRIGHT" for information on usage and redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES. ----------------------------------------------------------------------