mirror of
https://github.com/python/cpython.git
synced 2025-10-31 05:31:20 +00:00
230 lines
8.4 KiB
Text
230 lines
8.4 KiB
Text
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:
|
|
|
|
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 <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.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 <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, 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.
|
|
----------------------------------------------------------------------
|