| 1 | Python standard documentation -- in LaTeX
|
|---|
| 2 | -----------------------------------------
|
|---|
| 3 |
|
|---|
| 4 | This directory contains the LaTeX sources to the Python documentation
|
|---|
| 5 | and tools required to support the formatting process. The documents
|
|---|
| 6 | now require LaTeX2e; LaTeX 2.09 compatibility has been dropped.
|
|---|
| 7 |
|
|---|
| 8 | If you don't have LaTeX, or if you'd rather not format the
|
|---|
| 9 | documentation yourself, you can ftp a tar file containing HTML, PDF,
|
|---|
| 10 | or PostScript versions of all documents. Additional formats may be
|
|---|
| 11 | available. These should be in the same place where you fetched the
|
|---|
| 12 | main Python distribution (try <http://www.python.org/> or
|
|---|
| 13 | <ftp://ftp.python.org/pub/python/>).
|
|---|
| 14 |
|
|---|
| 15 | The following are the LaTeX source files:
|
|---|
| 16 |
|
|---|
| 17 | api/*.tex Python/C API Reference Manual
|
|---|
| 18 | doc/*.tex Documenting Python
|
|---|
| 19 | ext/*.tex Extending and Embedding the Python Interpreter
|
|---|
| 20 | lib/*.tex Python Library Reference
|
|---|
| 21 | mac/*.tex Macintosh Library Modules
|
|---|
| 22 | ref/*.tex Python Reference Manual
|
|---|
| 23 | tut/*.tex Python Tutorial
|
|---|
| 24 | inst/*.tex Installing Python Modules
|
|---|
| 25 | dist/*.tex Distributing Python Modules
|
|---|
| 26 |
|
|---|
| 27 | Most use the "manual" document class and "python" package, derived from
|
|---|
| 28 | the old "myformat.sty" style file. The Macintosh Library Modules
|
|---|
| 29 | document uses the "howto" document class instead. These contains many
|
|---|
| 30 | macro definitions useful in documenting Python, and set some style
|
|---|
| 31 | parameters.
|
|---|
| 32 |
|
|---|
| 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 | also be made. To view the generated HTML, point your favorite browser
|
|---|
| 37 | at the top-level index (html/index.html) after running "make".
|
|---|
| 38 |
|
|---|
| 39 | The Makefile can also produce DVI files for each document made; to
|
|---|
| 40 | preview them, use xdvi. PostScript is produced by the same Makefile
|
|---|
| 41 | target that produces the DVI files. This uses the dvips tool.
|
|---|
| 42 | Printing depends on local conventions; at our site, we use lpr. For
|
|---|
| 43 | example:
|
|---|
| 44 |
|
|---|
| 45 | make paper-letter/lib.ps # create lib.dvi and lib.ps
|
|---|
| 46 | xdvi paper-letter/lib.dvi # preview lib.dvi
|
|---|
| 47 | lpr paper-letter/lib.ps # print on default printer
|
|---|
| 48 |
|
|---|
| 49 |
|
|---|
| 50 | What if I find a bug?
|
|---|
| 51 | ---------------------
|
|---|
| 52 |
|
|---|
| 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 | If we haven't, tell us about it. We'd like the documentation to be
|
|---|
| 58 | complete and accurate, but have limited time. If you discover any
|
|---|
| 59 | inconsistencies between the documentation and implementation, or just
|
|---|
| 60 | have suggestions as to how to improve the documentation, let is know!
|
|---|
| 61 | Specific bugs and patches should be reported using our bug & patch
|
|---|
| 62 | databases at:
|
|---|
| 63 |
|
|---|
| 64 | http://sourceforge.net/projects/python
|
|---|
| 65 |
|
|---|
| 66 | Other suggestions or questions should be sent to the Python
|
|---|
| 67 | Documentation Team:
|
|---|
| 68 |
|
|---|
| 69 | docs@python.org
|
|---|
| 70 |
|
|---|
| 71 | Thanks!
|
|---|
| 72 |
|
|---|
| 73 |
|
|---|
| 74 | What tools do I need?
|
|---|
| 75 | ---------------------
|
|---|
| 76 |
|
|---|
| 77 | You need to install Python; some of the scripts used to produce the
|
|---|
| 78 | documentation are written in Python. You don't need this
|
|---|
| 79 | documentation to install Python; instructions are included in the
|
|---|
| 80 | README file in the Python distribution.
|
|---|
| 81 |
|
|---|
| 82 | The simplest way to get the rest of the tools in the configuration we
|
|---|
| 83 | used is to install the teTeX TeX distribution, versions 0.9 or newer.
|
|---|
| 84 | More information is available on teTeX at <http://www.tug.org/tetex/>.
|
|---|
| 85 | This is a Unix-only TeX distribution at this time. This documentation
|
|---|
| 86 | release was tested with the 1.0.7 release, but there have been no
|
|---|
| 87 | substantial changes since late in the 0.9 series, which we used
|
|---|
| 88 | extensively for previous versions without any difficulty.
|
|---|
| 89 |
|
|---|
| 90 | If you don't want to get teTeX, here is what you'll need:
|
|---|
| 91 |
|
|---|
| 92 | To create DVI, PDF, or PostScript files:
|
|---|
| 93 |
|
|---|
| 94 | - LaTeX2e, 1995/12/01 or newer. Older versions are likely to
|
|---|
| 95 | choke.
|
|---|
| 96 |
|
|---|
| 97 | - makeindex. This is used to produce the indexes for the
|
|---|
| 98 | library reference and Python/C API reference.
|
|---|
| 99 |
|
|---|
| 100 | To create PDF files:
|
|---|
| 101 |
|
|---|
| 102 | - pdflatex. We used the one in the teTeX distribution (pdfTeX
|
|---|
| 103 | version 3.14159-13d (Web2C 7.3.1) at the time of this
|
|---|
| 104 | writing). Versions even a couple of patchlevels earlier are
|
|---|
| 105 | highly likely to fail due to syntax changes for some of the
|
|---|
| 106 | pdftex primitives.
|
|---|
| 107 |
|
|---|
| 108 | To create PostScript files:
|
|---|
| 109 |
|
|---|
| 110 | - dvips. Most TeX installations include this. If you don't
|
|---|
| 111 | have one, check CTAN (<ftp://ctan.tug.org/tex-archive/>).
|
|---|
| 112 |
|
|---|
| 113 | To create info files:
|
|---|
| 114 |
|
|---|
| 115 | Note that info support is currently being revised using new
|
|---|
| 116 | conversion tools by Michael Ernst <mernst@cs.washington.edu>.
|
|---|
| 117 |
|
|---|
| 118 | - makeinfo. This is available from any GNU mirror.
|
|---|
| 119 |
|
|---|
| 120 | - emacs or xemacs. Emacs is available from the same place as
|
|---|
| 121 | makeinfo, and xemacs is available from ftp.xemacs.org.
|
|---|
| 122 |
|
|---|
| 123 | - Perl. Find the software at
|
|---|
| 124 | <http://language.perl.com/info/software.html>.
|
|---|
| 125 |
|
|---|
| 126 | - HTML::Element. If you don't have this installed, you can get
|
|---|
| 127 | this from CPAN. Use the command:
|
|---|
| 128 |
|
|---|
| 129 | perl -e 'use CPAN; CPAN::install("HTML::Element");'
|
|---|
| 130 |
|
|---|
| 131 | You may need to be root to do this.
|
|---|
| 132 |
|
|---|
| 133 | To create HTML files:
|
|---|
| 134 |
|
|---|
| 135 | - Perl 5.6.0 or newer. Find the software at
|
|---|
| 136 | <http://language.perl.com/info/software.html>.
|
|---|
| 137 |
|
|---|
| 138 | - LaTeX2HTML 99.2b8 or newer. Older versions are not
|
|---|
| 139 | supported; each version changes enough that supporting
|
|---|
| 140 | multiple versions is not likely to work. Many older
|
|---|
| 141 | versions don't work with Perl 5.6 as well. This also screws
|
|---|
| 142 | up code fragments. ;-( Releases are available at:
|
|---|
| 143 | <http://www.latex2html.org/>.
|
|---|
| 144 |
|
|---|
| 145 |
|
|---|
| 146 | I got a make error: "make: don't know how to make commontex/patchlevel.tex."
|
|---|
| 147 | ----------------------------------------------------------------------------
|
|---|
| 148 |
|
|---|
| 149 | Your version of make doesn't support the 'shell' function. You will need to
|
|---|
| 150 | use a version which does, e.g. GNU make.
|
|---|
| 151 |
|
|---|
| 152 |
|
|---|
| 153 | LaTeX (or pdfLaTeX) ran out of memory; how can I fix it?
|
|---|
| 154 | --------------------------------------------------------
|
|---|
| 155 |
|
|---|
| 156 | This is known to be a problem at least on Mac OS X, but it has been
|
|---|
| 157 | observed on other systems in the past.
|
|---|
| 158 |
|
|---|
| 159 | On some systems, the default sizes of some of the memory pools
|
|---|
| 160 | allocated by TeX needs to be changed; this is a configuration setting
|
|---|
| 161 | for installations based on web2c (most if not all installations).
|
|---|
| 162 | This is usually set in a file named texmf/web2c/texmf.cnf (where the
|
|---|
| 163 | top-level texmf/ directory is part of the TeX installation). If you
|
|---|
| 164 | get a "buffer overflow" warning from LaTeX, open that configuration
|
|---|
| 165 | file and look for the "main_memory.pdflatex" setting. If there is not
|
|---|
| 166 | one, you can add a line with the setting. The value 1500000 seems to
|
|---|
| 167 | be sufficient for formatting the Python documetantion.
|
|---|
| 168 |
|
|---|
| 169 |
|
|---|
| 170 | What if Times fonts are not available?
|
|---|
| 171 | --------------------------------------
|
|---|
| 172 |
|
|---|
| 173 | As distributed, the LaTeX documents use PostScript Times fonts. This
|
|---|
| 174 | is done since they are much better looking and produce smaller
|
|---|
| 175 | PostScript files. If, however, your TeX installation does not support
|
|---|
| 176 | them, they may be easily disabled. Edit the file
|
|---|
| 177 | texinputs/pypaper.sty and comment out the line that starts
|
|---|
| 178 | "\RequirePackage{times}" by inserting a "%" character at the beginning
|
|---|
| 179 | of the line. If you're formatting the docs for A4 paper instead of
|
|---|
| 180 | US-Letter paper, change paper-a4/pypaper.sty instead. An alternative
|
|---|
| 181 | is to install the right fonts and LaTeX style file.
|
|---|
| 182 |
|
|---|
| 183 |
|
|---|
| 184 | What if I want to use A4 paper?
|
|---|
| 185 | -------------------------------
|
|---|
| 186 |
|
|---|
| 187 | Instead of building the PostScript by giving the command "make ps",
|
|---|
| 188 | give the command "make PAPER=a4 ps"; the output will be produced in
|
|---|
| 189 | the paper-a4/ subdirectory. (You can use "make PAPER=a4 pdf" if you'd
|
|---|
| 190 | rather have PDF output.)
|
|---|
| 191 |
|
|---|
| 192 |
|
|---|
| 193 | Making HTML files
|
|---|
| 194 | -----------------
|
|---|
| 195 |
|
|---|
| 196 | The LaTeX documents can be converted to HTML using Nikos Drakos'
|
|---|
| 197 | LaTeX2HTML converter. See the Makefile; after some twiddling, "make"
|
|---|
| 198 | should do the trick.
|
|---|
| 199 |
|
|---|
| 200 |
|
|---|
| 201 | What else is in here?
|
|---|
| 202 | ---------------------
|
|---|
| 203 |
|
|---|
| 204 | 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 | Andrew Kuchling <akuchlin@mems-exchange.org>. The file
|
|---|
| 207 | templates/howto.tex is a commented example which may be used as a
|
|---|
| 208 | template. A Python script to "do the right thing" to format a howto
|
|---|
| 209 | document is included as tools/mkhowto. These documents can be
|
|---|
| 210 | formatted as HTML, PDF, PostScript, or ASCII files. Use "mkhowto
|
|---|
| 211 | --help" for information on using the formatting tool.
|
|---|
| 212 |
|
|---|
| 213 | For authors of module documentation, there is a file
|
|---|
| 214 | templates/module.tex which may be used as a template for a module
|
|---|
| 215 | section. This may be used in conjunction with either the howto or
|
|---|
| 216 | manual document class. Create the documentation for a new module by
|
|---|
| 217 | copying the template to lib<mymodule>.tex and editing according to the
|
|---|
| 218 | instructions in the comments.
|
|---|
| 219 |
|
|---|
| 220 | Documentation on the authoring Python documentation, including
|
|---|
| 221 | information about both style and markup, is available in the
|
|---|
| 222 | "Documenting Python" manual.
|
|---|
| 223 |
|
|---|
| 224 |
|
|---|
| 225 | Copyright notice
|
|---|
| 226 | ================
|
|---|
| 227 |
|
|---|
| 228 | The Python source is copyrighted, but you can freely use and copy it
|
|---|
| 229 | as long as you don't change or remove the copyright notice:
|
|---|
| 230 |
|
|---|
| 231 | ----------------------------------------------------------------------
|
|---|
| 232 | Copyright (c) 2000-2006 Python Software Foundation.
|
|---|
| 233 | All rights reserved.
|
|---|
| 234 |
|
|---|
| 235 | Copyright (c) 2000 BeOpen.com.
|
|---|
| 236 | All rights reserved.
|
|---|
| 237 |
|
|---|
| 238 | Copyright (c) 1995-2000 Corporation for National Research Initiatives.
|
|---|
| 239 | All rights reserved.
|
|---|
| 240 |
|
|---|
| 241 | Copyright (c) 1991-1995 Stichting Mathematisch Centrum.
|
|---|
| 242 | All rights reserved.
|
|---|
| 243 |
|
|---|
| 244 | See the file "commontex/license.tex" for information on usage and
|
|---|
| 245 | redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
|---|
| 246 | ----------------------------------------------------------------------
|
|---|
