mirror of
https://github.com/python/cpython.git
synced 2024-12-12 11:23:56 +08:00
222 lines
8.3 KiB
Plaintext
222 lines
8.3 KiB
Plaintext
THIS IS A *TEST* RELEASE. It includes a significantly revised
|
|
directory organization for the documentation, and much of the
|
|
formatting process has been adjusted. The documentation itself is not
|
|
necessarily consistent with any released version of Python.
|
|
|
|
The only purpose for this release is to test the usability of the new
|
|
directory structure. Please attempt to *format* the documentation to
|
|
determine if the new processes are suitable for your purposes; the
|
|
basic targets have been extensively tested, but variations may require
|
|
some work. Please let us know if there are any problems with the new
|
|
organization or processes; send email to:
|
|
|
|
python-docs@python.org
|
|
|
|
|
|
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:
|
|
|
|
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 not currently included in the build
|
|
system. To build, do the following:
|
|
|
|
cd Doc/mac
|
|
../tools/mkhowto.sh --ps --pdf --html mac
|
|
|
|
(Any combination of --ps, --pdf, and --html may be used depending on
|
|
your needs; the default is --pdf.)
|
|
|
|
|
|
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 python-docs@python.org. 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.1p5 or newer. Older version will fail with
|
|
the new directory layout. Releases are available at
|
|
<http://dc-server.cdc.informatik.tu-darmstadt.de/~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 <amk@acm.org>. 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.
|
|
----------------------------------------------------------------------
|