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://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         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 What if Times fonts are not available?
 147 --------------------------------------
 148
 149 As distributed, the LaTeX documents use PostScript Times fonts.  This
 150 is done since they are much better looking and produce smaller
 151 PostScript files.  If, however, your TeX installation does not support
 152 them, they may be easily disabled.  Edit the file
 153 texinputs/pypaper.sty and comment out the line that starts
 154 "\RequirePackage{times}" by inserting a "%" character at the beginning
 155 of the line.  If you're formatting the docs for A4 paper instead of
 156 US-Letter paper, change paper-a4/pypaper.sty instead.  An alternative
 157 is to install the right fonts and LaTeX style file.
 158
 159
 160 What if I want to use A4 paper?
 161 -------------------------------
 162
 163 Instead of building the PostScript by giving the command "make ps",
 164 give the command "make PAPER=a4 ps"; the output will be produced in
 165 the paper-a4/ subdirectory.  (You can use "make PAPER=a4 pdf" if you'd
 166 rather have PDF output.)
 167
 168
 169 Making HTML files
 170 -----------------
 171
 172 The LaTeX documents can be converted to HTML using Nikos Drakos'
 173 LaTeX2HTML converter.  See the Makefile; after some twiddling, "make"
 174 should do the trick.
 175
 176
 177 What else is in here?
 178 ---------------------
 179
 180 There is a new LaTeX document class called "howto".  This is used for
 181 the new series of Python HOWTO documents which is being coordinated by
 182 Andrew Kuchling <akuchlin@mems-exchange.org>.  The file
 183 templates/howto.tex is a commented example which may be used as a
 184 template.  A Python script to "do the right thing" to format a howto
 185 document is included as tools/mkhowto.  These documents can be
 186 formatted as HTML, PDF, PostScript, or ASCII files.  Use "mkhowto
 187 --help" for information on using the formatting tool.
 188
 189 For authors of module documentation, there is a file
 190 templates/module.tex which may be used as a template for a module
 191 section.  This may be used in conjunction with either the howto or
 192 manual document class.  Create the documentation for a new module by
 193 copying the template to lib<mymodule>.tex and editing according to the
 194 instructions in the comments.
 195
 196 Documentation on the authoring Python documentation, including
 197 information about both style and markup, is available in the
 198 "Documenting Python" manual.
 199
 200
 201 Copyright notice
 202 ================
 203
 204 The Python source is copyrighted, but you can freely use and copy it
 205 as long as you don't change or remove the copyright notice:
 206
 207 ----------------------------------------------------------------------
 208 Copyright (c) 2000-2003 Python Software Foundation.
 209 All rights reserved.
 210
 211 Copyright (c) 2000 BeOpen.com.
 212 All rights reserved.
 213
 214 Copyright (c) 1995-2000 Corporation for National Research Initiatives.
 215 All rights reserved.
 216
 217 Copyright (c) 1991-1995 Stichting Mathematisch Centrum.
 218 All rights reserved.
 219
 220 See the file "commontex/license.tex" for information on usage and
 221 redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 222 ----------------------------------------------------------------------