Doc/README

   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-2007 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 ----------------------------------------------------------------------