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 documnetation, 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://python.sourceforge.net/devel-docs/>; 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         python-docs@python.org
  70
  71 Thanks!
  72
  73
  74 What happened to the Macintosh chapter of the Python Library Reference?
  75 -----------------------------------------------------------------------
  76
  77 The directory mac/ contains the LaTeX sources for the "Macintosh
  78 Library Modules" manual; this is built using the standard build
  79 targets, so check the proper output directory for your chosen format
  80 and paper size.
  81
  82
  83 What tools do I need?
  84 ---------------------
  85
  86 You need to install Python; some of the scripts used to produce the
  87 documentation are written in Python.  You don't need this
  88 documentation to install Python; instructions are included in the
  89 README file in the Python distribution.
  90
  91 The simplest way to get the rest of the tools in the configuration we
  92 used is to install the teTeX TeX distribution, versions 0.9 or newer.
  93 More information is available on teTeX at <http://www.tug.org/tetex/>.
  94 This is a Unix-only TeX distribution at this time.  This documentation
  95 release was tested with the 1.0.7 release, but there have been no
  96 substantial changes since late in the 0.9 series, which we used
  97 extensively for previous versions without any difficulty.
  98
  99 If you don't want to get teTeX, here is what you'll need:
 100
 101 To create DVI, PDF, or PostScript files:
 102
 103         - LaTeX2e, 1995/12/01 or newer.  Older versions are likely to
 104           choke.
 105
 106         - makeindex.  This is used to produce the indexes for the
 107           library reference and Python/C API reference.
 108
 109 To create PDF files:
 110
 111         - pdflatex.  We used the one in the teTeX distribution (pdfTeX
 112           version 3.14159-13d (Web2C 7.3.1) at the time of this
 113           writing).  Versions even a couple of patchlevels earlier are
 114           highly likely to fail due to syntax changes for some of the
 115           pdftex primitives.
 116
 117 To create PostScript files:
 118
 119         - dvips.  Most TeX installations include this.  If you don't
 120           have one, check CTAN (<ftp://ctan.tug.org/tex-archive/>).
 121
 122 To create info files:
 123
 124         Note that info support is currently being revised using new
 125         conversion tools by Michael Ernst <mernst@cs.washington.edu>.
 126
 127         - makeinfo.  This is available from any GNU mirror.
 128
 129         - emacs or xemacs.  Emacs is available from the same place as
 130           makeinfo, and xemacs is available from ftp.xemacs.org.
 131
 132         - Perl.  Find the software at
 133           <http://language.perl.com/info/software.html>.
 134
 135         - HTML::Element.  If you don't have this installed, you can get
 136           this from CPAN.  Use the command:
 137
 138           perl -e 'use CPAN; CPAN::install("HTML::Element");'
 139
 140           You may need to be root to do this.
 141
 142 To create HTML files:
 143
 144         - Perl 5.004_04 or newer.  Find the software at
 145           <http://language.perl.com/info/software.html>.
 146
 147         - LaTeX2HTML 99.2b8 or newer.  Older versions are not
 148           supported; each version changes enough that supporting
 149           multiple versions is not likely to work.  Many older
 150           versions don't work with Perl 5.6 as well.  This also screws
 151           up code fragments.  ;-(  Releases are available at:
 152           <http://www.latex2html.org/>.
 153
 154
 155 What if Times fonts are not available?
 156 --------------------------------------
 157
 158 As distributed, the LaTeX documents use PostScript Times fonts.  This
 159 is done since they are much better looking and produce smaller
 160 PostScript files.  If, however, your TeX installation does not support
 161 them, they may be easily disabled.  Edit the file
 162 texiinputs/manual.cls and comment out the line that starts
 163 "\RequirePackage{times}" by inserting a "%" character at the beginning
 164 of the line.  An alternative is to install the right fonts and LaTeX
 165 style file.
 166
 167
 168 What if I want to use A4 paper?
 169 -------------------------------
 170
 171 Instead of building the PostScript by giving the command "make ps",
 172 give the command "make PAPER=a4 ps"; the output will be produced in
 173 the paper-a4/ subdirectory.  (You can use "make PAPER=a4 pdf" if you'd
 174 rather have PDF output.)
 175
 176
 177 Making HTML files
 178 -----------------
 179
 180 The LaTeX documents can be converted to HTML using Nikos Drakos'
 181 LaTeX2HTML converter.  See the Makefile; after some twiddling, "make"
 182 should do the trick.
 183
 184
 185 What else is in here?
 186 ---------------------
 187
 188 There is a new LaTeX document class called "howto".  This is used for
 189 the new series of Python HOWTO documents which is being coordinated by
 190 Andrew Kuchling <akuchlin@mems-exchange.org>.  The file
 191 templates/howto.tex is a commented example which may be used as a
 192 template.  A Python script to "do the right thing" to format a howto
 193 document is included as tools/mkhowto.  These documents can be
 194 formatted as HTML, PDF, PostScript, or ASCII files.  Use "mkhowto
 195 --help" for information on using the formatting tool.
 196
 197 For authors of module documentation, there is a file
 198 templates/module.tex which may be used as a template for a module
 199 section.  This may be used in conjunction with either the howto or
 200 manual document class.  Create the documentation for a new module by
 201 copying the template to lib<mymodule>.tex and editing according to the
 202 instructions in the comments.
 203
 204 Documentation on the authoring Python documentation, including
 205 information about both style and markup, is available in the
 206 "Documenting Python" manual.
 207
 208
 209 Copyright notice
 210 ================
 211
 212 The Python source is copyrighted, but you can freely use and copy it
 213 as long as you don't change or remove the copyright notice:
 214
 215 ----------------------------------------------------------------------
 216 Copyright (c) 2000-2002 Python Software Foundation.
 217 All rights reserved.
 218
 219 Copyright (c) 2000 BeOpen.com.
 220 All rights reserved.
 221
 222 Copyright (c) 1995-2000 Corporation for National Research Initiatives.
 223 All rights reserved.
 224
 225 Copyright (c) 1991-1995 Stichting Mathematisch Centrum.
 226 All rights reserved.
 227
 228 See the file "texinputs/license.tex" for information on usage and
 229 redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 230 ----------------------------------------------------------------------