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 documnetation, 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://python.sourceforge.net/devel-docs/>; 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:

[email protected]

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 <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 <[email protected]>.

- 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.004_04 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/>.

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 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 <[email protected]>. 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, 2001 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 "texinputs/license.tex" for information on usage and

redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES.

----------------------------------------------------------------------