Python main documentation -- in LaTeX

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

This directory contains the LaTeX sources to the Python documentation.

They now require LaTeX2e (LaTeX 2.09 compatibility is 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>).

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

ref/*.tex Python Reference Manual

tut/*.tex Python Tutorial

All use the "manual" document class and "python" package, derived from

the old "myformat.sty" style file. 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 <http://www.python.org/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!

Send comments and patches to the Python Documentation Team:

[email protected]

Thanks!

What tools do I need?

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

You need to install Python; some of the scripts used to produce the

documentation are written in Python.

The simplest way to get the rest of the tools in the configuration we

used is to install the teTeX TeX distribution, version 0.4 or 0.9. More

information is available on teTeX at <http://www.tug.org/tetex/>.

This is a UNIX-only TeX distribution at this time. Note that the 0.9

release is still in testing; this documentation release was tested

with the 21 Apr 1998 release. We'll be upgrading to the final version

when it becomes available. Except for the PDF generation, it also works

with the (stable) teTeX 0.4 release.

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 0.9 distribution

(version 0.12h 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 is not currently supported. If you need it,

please fix or replace tools/partparse.py and send the new

version to [email protected]. We'll be glad to provide

free copies of the info files to anyone who can support the

process. ;-)

- 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.

To create HTML files:

- Perl 5.004_04 or newer. Find the software at

<http://language.perl.com/info/software.html>.

- LaTeX2HTML 98.1p1, or newer. Releases are available at

<http://www-dsed.llnl.gov/files/programs/unix/latex2html/>.

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}" using 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

l2h" 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 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.sh.

Support for this document class is still new, but is expected to

evolve rapidly. Use "mkhowto.sh --help" for information on using the

formatting tool.

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

Permission to use, copy, modify, and distribute this software and its

documentation for any purpose and without fee is hereby granted,

provided that the above copyright notice appear in all copies and that

both that copyright notice and this permission notice appear in

supporting documentation, and that the names of Stichting Mathematisch

Centrum or CWI or Corporation for National Research Initiatives or

CNRI not be used in advertising or publicity pertaining to

distribution of the software without specific, written prior

permission.

While CWI is the initial source for this software, a modified version

is made available by the Corporation for National Research Initiatives

(CNRI) at the Internet address ftp://ftp.python.org.

STICHTING MATHEMATISCH CENTRUM AND CNRI DISCLAIM ALL WARRANTIES WITH

REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF

MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH

CENTRUM OR CNRI BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL

DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR

PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER

TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR

PERFORMANCE OF THIS SOFTWARE.

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