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