Doc/README

   1 Python main 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>).
  14
  15 The following are the LaTeX source files:
  16
  17         api/*.tex       Python/C API Reference Manual
  18         ext/*.tex       Extending and Embedding the Python Interpreter
  19         lib/*.tex       Python Library Reference
  20         mac/*.tex       Macintosh Library Modules
  21         ref/*.tex       Python Reference Manual
  22         tut/*.tex       Python Tutorial
  23         inst/*.tex      Installing Python Modules
  24         dist/*.tex      Distributing Python Modules
  25
  26 Most use the "manual" document class and "python" package, derived from
  27 the old "myformat.sty" style file.  The Macintosh Library Modules
  28 document uses the "howto" document class instead.  These contains many
  29 macro definitions useful in documenting Python, and set some style
  30 parameters.
  31
  32 There's a Makefile to call LaTeX and the other utilities in the right
  33 order and the right number of times.  This will produce DVI files for
  34 each document made; to preview them, use xdvi.  PostScript is produced
  35 by the same Makefile target that produces the DVI files.  This uses
  36 the dvips tool.  Printing depends on local conventions; at our site,
  37 we use lpr.  For example:
  38
  39         make lib        # create lib.dvi and lib.ps
  40         xdvi lib        # preview lib.dvi
  41         lpr lib.ps      # print on default printer
  42
  43
  44 What if I find a bug?
  45 ---------------------
  46
  47 First, check that the bug is present in the development version of the
  48 documentation at <http://python.sourceforge.net/devel-docs/>; we may
  49 have already fixed it.
  50
  51 If we haven't, tell us about it.  We'd like the documentation to be
  52 complete and accurate, but have limited time.  If you discover any
  53 inconsistencies between the documentation and implementation, or just
  54 have suggestions as to how to improve the documentation, let is know!
  55 Specific bugs and patches should be reported using our bug & patch
  56 databases at:
  57
  58         http://sourceforge.net/projects/python
  59
  60 Other suggestions or questions should be sent to the Python
  61 Documentation Team:
  62
  63         python-docs@python.org
  64
  65 Thanks!
  66
  67
  68 What happened to the Macintosh chapter of the Python Library Reference?
  69 -----------------------------------------------------------------------
  70
  71 The directory mac/ contains the LaTeX sources for the "Macintosh
  72 Library Modules" manual; this is built using the standard build
  73 targets, so check the proper output directory for your chosen format
  74 and paper size.
  75
  76
  77 What tools do I need?
  78 ---------------------
  79
  80 You need to install Python; some of the scripts used to produce the
  81 documentation are written in Python.  You don't need this
  82 documentation to install Python; instructions are included in the
  83 README file in the Python distribution.
  84
  85 The simplest way to get the rest of the tools in the configuration we
  86 used is to install the teTeX TeX distribution, versions 0.9 or newer.
  87 More information is available on teTeX at <http://www.tug.org/tetex/>.
  88 This is a Unix-only TeX distribution at this time.  This documentation
  89 release was tested with the 1.0.7 release, but there have been no
  90 substantial changes since late in the 0.9 series, which we used
  91 extensively for previous versions without any difficulty.
  92
  93 If you don't want to get teTeX, here is what you'll need:
  94
  95 To create DVI, PDF, or PostScript files:
  96
  97         - LaTeX2e, 1995/12/01 or newer.  Older versions are likely to
  98           choke.
  99
 100         - makeindex.  This is used to produce the indexes for the
 101           library reference and Python/C API reference.
 102
 103 To create PDF files:
 104
 105         - pdflatex.  We used the one in the teTeX distribution (pdfTeX
 106           version 3.14159-13d (Web2C 7.3.1) at the time of this
 107           writing).  Versions even a couple of patchlevels earlier are
 108           highly likely to fail due to syntax changes for some of the
 109           pdftex primitives.
 110
 111 To create PostScript files:
 112
 113         - dvips.  Most TeX installations include this.  If you don't
 114           have one, check CTAN (<ftp://ctan.tug.org/tex-archive/>).
 115
 116 To create info files:
 117
 118         Note that info support is currently being revised using new
 119         conversion tools by Michael Ernst <mernst@cs.washington.edu>.
 120
 121         - makeinfo.  This is available from any GNU mirror.
 122
 123         - emacs or xemacs.  Emacs is available from the same place as
 124           makeinfo, and xemacs is available from ftp.xemacs.org.
 125
 126         - Perl.  Find the software at
 127           <http://language.perl.com/info/software.html>.
 128
 129         - HTML::Element.  If you don't have this installed, you can get
 130           this from CPAN.  Use the command:
 131
 132           perl -e 'use CPAN; CPAN::install("HTML::Element");'
 133
 134           You may need to be root to do this.
 135
 136 To create HTML files:
 137
 138         - Perl 5.004_04 or newer.  Find the software at
 139           <http://language.perl.com/info/software.html>.
 140
 141         - LaTeX2HTML 99.2b8.  Older versions are not supported; each
 142           version changes enough that supporting multiple versions is not
 143           likely to work.  Many older versions don't work with Perl
 144           5.6 as well.  This also screws up code fragments.  ;-(
 145           Releases are available at: <http://www.latex2html.org/>.
 146
 147
 148 What if Times fonts are not available?
 149 --------------------------------------
 150
 151 As distributed, the LaTeX documents use PostScript Times fonts.  This
 152 is done since they are much better looking and produce smaller
 153 PostScript files.  If, however, your TeX installation does not support
 154 them, they may be easily disabled.  Edit the file
 155 texiinputs/manual.cls and comment out the line that starts
 156 "\RequirePackage{times}" by inserting a "%" character at the beginning
 157 of the line.  An alternative is to install the right fonts and LaTeX
 158 style file.
 159
 160
 161 What if I want to use A4 paper?
 162 -------------------------------
 163
 164 Instead of building the PostScript by giving the command "make", give
 165 the command "make PAPER=a4 ps"; the output will be produced in the
 166 paper-a4/ subdirectory.  (You can use "make PAPER=a4 pdf" if you'd
 167 rather have PDF output.)
 168
 169
 170 Making HTML files
 171 -----------------
 172
 173 The LaTeX documents can be converted to HTML using Nikos Drakos'
 174 LaTeX2HTML converter.  See the Makefile; after some twiddling, "make
 175 html" should do the trick.
 176
 177
 178 What else is in here?
 179 ---------------------
 180
 181 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 Andrew Kuchling <akuchlin@mems-exchange.org>.  The file
 184 templates/howto.tex is a commented example which may be used as a
 185 template.  A Python script to "do the right thing" to format a howto
 186 document is included as tools/mkhowto.  These documents can be
 187 formatted as HTML, PDF, PostScript, or ASCII files.  Use "mkhowto
 188 --help" for information on using the formatting tool.
 189
 190 For authors of module documentation, there is a file
 191 templates/module.tex which may be used as a template for a module
 192 section.  This may be used in conjunction with either the howto or
 193 manual document class.  Create the documentation for a new module by
 194 copying the template to lib<mymodule>.tex and editing according to the
 195 instructions in the comments.
 196
 197
 198 Copyright notice
 199 ================
 200
 201 The Python source is copyrighted, but you can freely use and copy it
 202 as long as you don't change or remove the copyright notice:
 203
 204 ----------------------------------------------------------------------
 205 Copyright (c) 2000, 2001 Guido van Rossum.
 206 All rights reserved.
 207
 208 Copyright (c) 2000 BeOpen.com.
 209 All rights reserved.
 210
 211 Copyright (c) 1995-2000 Corporation for National Research Initiatives.
 212 All rights reserved.
 213
 214 Copyright (c) 1991-1995 Stichting Mathematisch Centrum.
 215 All rights reserved.
 216
 217 See the file "LICENSE" for information on usage and
 218 redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 219 ----------------------------------------------------------------------