README 7.9 KB
Newer Older
Fred Drake's avatar
Fred Drake committed
1
Python main documentation -- in LaTeX
2 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>).
14

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

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

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

Fred Drake's avatar
Fred Drake committed
32
There's a Makefile to call LaTeX and the other utilities in the right
33 34 35
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
36 37
the dvips tool.  Printing depends on local conventions; at our site,
we use lpr.  For example:
38

39 40 41
	make lib	# create lib.dvi and lib.ps
	xdvi lib	# preview lib.dvi
	lpr lib.ps	# print on default printer
42 43


44 45 46
What if I find a bug?
---------------------

47 48 49
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.
50 51 52 53 54

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

58 59 60 61 62 63
	http://sourceforge.net/projects/python

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

	python-docs@python.org
64 65 66 67

Thanks!


68 69 70 71
What happened to the Macintosh chapter of the Python Library Reference?
-----------------------------------------------------------------------

The directory mac/ contains the LaTeX sources for the "Macintosh
72 73 74
Library Modules" manual; this is built using the standard build
targets, so check the proper output directory for your chosen format
and paper size.
75 76


Fred Drake's avatar
Fred Drake committed
77 78 79 80
What tools do I need?
---------------------

You need to install Python; some of the scripts used to produce the
81 82 83
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
84 85

The simplest way to get the rest of the tools in the configuration we
86 87 88 89 90 91
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
92

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

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:

105 106 107 108 109
	- 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
110 111 112 113

To create PostScript files:

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

To create info files:

118 119
	Note that info support is currently being revised using new
	conversion tools by Michael Ernst <mernst@cs.washington.edu>.
120

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

123 124 125
	- emacs or xemacs.  Emacs is available from the same place as
	  makeinfo, and xemacs is available from ftp.xemacs.org.

126 127 128
	- Perl.  Find the software at
	  <http://language.perl.com/info/software.html>.

129 130 131 132 133 134 135
	- 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
136 137
To create HTML files:

138 139
	- Perl 5.004_04 or newer.  Find the software at
	  <http://language.perl.com/info/software.html>.
Fred Drake's avatar
Fred Drake committed
140

141 142 143 144
	- LaTeX2HTML 99.2b8.  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.  ;-(
145
	  Releases are available at: <http://www.latex2html.org/>.
Fred Drake's avatar
Fred Drake committed
146

147

Fred Drake's avatar
Fred Drake committed
148 149
What if Times fonts are not available?
--------------------------------------
150

Fred Drake's avatar
Fred Drake committed
151 152 153
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 
Fred Drake's avatar
Fred Drake committed
154 155
them, they may be easily disabled.  Edit the file
texiinputs/manual.cls and comment out the line that starts
Fred Drake's avatar
Fred Drake committed
156 157 158
"\RequirePackage{times}" by inserting a "%" character at the beginning
of the line.  An alternative is to install the right fonts and LaTeX
style file.
Fred Drake's avatar
Fred Drake committed
159 160 161 162 163


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

164
Instead of building the PostScript by giving the command "make", give
165 166 167
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.)
168 169


170 171
Making HTML files
-----------------
172

Fred Drake's avatar
Fred Drake committed
173 174
The LaTeX documents can be converted to HTML using Nikos Drakos'
LaTeX2HTML converter.  See the Makefile; after some twiddling, "make
Fred Drake's avatar
Fred Drake committed
175
html" should do the trick.
176

Fred Drake's avatar
Fred Drake committed
177

178 179 180 181
What else is in here?
---------------------

There is a new LaTeX document class called "howto".  This is used for
182
the new series of Python HOWTO documents which is being coordinated by
183 184 185 186 187 188
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.
189 190 191 192 193 194 195

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


Fred Drake's avatar
Fred Drake committed
198 199 200 201 202 203 204
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:

----------------------------------------------------------------------
205 206
Copyright (c) 2000, 2001 Guido van Rossum.
All rights reserved.
Fred Drake's avatar
Fred Drake committed
207

208 209 210 211 212
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
213

214
Copyright (c) 1991-1995 Stichting Mathematisch Centrum.
215 216
All rights reserved.

217
See the file "LICENSE" for information on usage and
218
redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES.
Fred Drake's avatar
Fred Drake committed
219
----------------------------------------------------------------------