README 9.23 KB
Newer Older
1 2
Python standard documentation -- in LaTeX
-----------------------------------------
3

Fred Drake's avatar
Fred Drake committed
4 5 6
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.
7

Fred Drake's avatar
Fred Drake committed
8 9 10 11
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
12 13
main Python distribution (try <http://www.python.org/> or
<ftp://ftp.python.org/pub/python/>).
14

Fred Drake's avatar
Fred Drake committed
15
The following are the LaTeX source files:
16

17
	api/*.tex	Python/C API Reference Manual
18
	doc/*.tex	Documenting Python
19 20
	ext/*.tex	Extending and Embedding the Python Interpreter
	lib/*.tex	Python Library Reference
Fred Drake's avatar
Fred Drake committed
21
	mac/*.tex	Macintosh Library Modules
22 23
	ref/*.tex	Python Reference Manual
	tut/*.tex	Python Tutorial
24 25
        inst/*.tex      Installing Python Modules
        dist/*.tex      Distributing Python Modules
26

Fred Drake's avatar
Fred Drake committed
27 28 29 30 31
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.
32

Fred Drake's avatar
Fred Drake committed
33
There's a Makefile to call LaTeX and the other utilities in the right
34
order and the right number of times.  By default, it will build the
35
HTML version of the documentation, but DVI, PDF, and PostScript can
36 37
also be made.  To view the generated HTML, point your favorite browser
at the top-level index (html/index.html) after running "make".
38

39 40 41 42 43 44 45 46 47
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
48 49


50 51 52
What if I find a bug?
---------------------

53
First, check that the bug is present in the development version of the
54
documentation at <http://www.python.org/dev/doc/devel/>; we may
55
have already fixed it.
56 57 58 59 60

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!
61 62
Specific bugs and patches should be reported using our bug & patch
databases at:
63

64 65 66 67 68
	http://sourceforge.net/projects/python

Other suggestions or questions should be sent to the Python
Documentation Team:

69
	docs@python.org
70 71 72 73

Thanks!


Fred Drake's avatar
Fred Drake committed
74 75 76 77
What tools do I need?
---------------------

You need to install Python; some of the scripts used to produce the
78 79 80
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.
Fred Drake's avatar
Fred Drake committed
81 82

The simplest way to get the rest of the tools in the configuration we
83 84 85 86 87 88
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.
Fred Drake's avatar
Fred Drake committed
89

90
If you don't want to get teTeX, here is what you'll need:
Fred Drake's avatar
Fred Drake committed
91 92 93 94 95 96 97 98 99 100 101

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:

102 103 104 105 106
	- 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.
Fred Drake's avatar
Fred Drake committed
107 108 109 110

To create PostScript files:

	- dvips.  Most TeX installations include this.  If you don't
111
	  have one, check CTAN (<ftp://ctan.tug.org/tex-archive/>).
Fred Drake's avatar
Fred Drake committed
112 113 114

To create info files:

115 116
	Note that info support is currently being revised using new
	conversion tools by Michael Ernst <mernst@cs.washington.edu>.
117

Fred Drake's avatar
Fred Drake committed
118 119
	- makeinfo.  This is available from any GNU mirror.

120 121 122
	- emacs or xemacs.  Emacs is available from the same place as
	  makeinfo, and xemacs is available from ftp.xemacs.org.

123 124 125
	- Perl.  Find the software at
	  <http://language.perl.com/info/software.html>.

126 127 128 129 130 131 132
	- 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.

Fred Drake's avatar
Fred Drake committed
133 134
To create HTML files:

135
	- Perl 5.6.0 or newer.  Find the software at
136
	  <http://language.perl.com/info/software.html>.
Fred Drake's avatar
Fred Drake committed
137

138 139 140 141 142 143
	- 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/>.
Fred Drake's avatar
Fred Drake committed
144

145

146 147 148 149 150 151 152
I got a make error: "make: don't know how to make commontex/patchlevel.tex."
----------------------------------------------------------------------------

Your version of make doesn't support the 'shell' function.  You will need to
use a version which does, e.g. GNU make.


153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169
LaTeX (or pdfLaTeX) ran out of memory; how can I fix it?
--------------------------------------------------------

This is known to be a problem at least on Mac OS X, but it has been
observed on other systems in the past.

On some systems, the default sizes of some of the memory pools
allocated by TeX needs to be changed; this is a configuration setting
for installations based on web2c (most if not all installations).
This is usually set in a file named texmf/web2c/texmf.cnf (where the
top-level texmf/ directory is part of the TeX installation).  If you
get a "buffer overflow" warning from LaTeX, open that configuration
file and look for the "main_memory.pdflatex" setting.  If there is not
one, you can add a line with the setting.  The value 1500000 seems to
be sufficient for formatting the Python documetantion.


Fred Drake's avatar
Fred Drake committed
170 171
What if Times fonts are not available?
--------------------------------------
172

Fred Drake's avatar
Fred Drake committed
173 174
As distributed, the LaTeX documents use PostScript Times fonts.  This
is done since they are much better looking and produce smaller
175
PostScript files.  If, however, your TeX installation does not support
Fred Drake's avatar
Fred Drake committed
176
them, they may be easily disabled.  Edit the file
177
texinputs/pypaper.sty and comment out the line that starts
Fred Drake's avatar
Fred Drake committed
178
"\RequirePackage{times}" by inserting a "%" character at the beginning
179 180 181
of the line.  If you're formatting the docs for A4 paper instead of
US-Letter paper, change paper-a4/pypaper.sty instead.  An alternative
is to install the right fonts and LaTeX style file.
Fred Drake's avatar
Fred Drake committed
182 183 184 185 186


What if I want to use A4 paper?
-------------------------------

187 188 189
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
190
rather have PDF output.)
191 192


193 194
Making HTML files
-----------------
195

Fred Drake's avatar
Fred Drake committed
196
The LaTeX documents can be converted to HTML using Nikos Drakos'
197 198
LaTeX2HTML converter.  See the Makefile; after some twiddling, "make"
should do the trick.
199

Fred Drake's avatar
Fred Drake committed
200

201 202 203 204
What else is in here?
---------------------

There is a new LaTeX document class called "howto".  This is used for
205
the new series of Python HOWTO documents which is being coordinated by
206 207 208 209 210 211
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.
212 213 214 215 216 217 218

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

220 221 222 223
Documentation on the authoring Python documentation, including
information about both style and markup, is available in the
"Documenting Python" manual.

224

Fred Drake's avatar
Fred Drake committed
225 226 227 228 229 230 231
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:

----------------------------------------------------------------------
232
Copyright (c) 2000-2004 Python Software Foundation.
233
All rights reserved.
Fred Drake's avatar
Fred Drake committed
234

235 236 237 238 239
Copyright (c) 2000 BeOpen.com.
All rights reserved.

Copyright (c) 1995-2000 Corporation for National Research Initiatives.
All rights reserved.
Fred Drake's avatar
Fred Drake committed
240

241
Copyright (c) 1991-1995 Stichting Mathematisch Centrum.
242 243
All rights reserved.

244
See the file "commontex/license.tex" for information on usage and
245
redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES.
Fred Drake's avatar
Fred Drake committed
246
----------------------------------------------------------------------