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
  24 Most use the "manual" document class and "python" package, derived from
  25 the old "myformat.sty" style file.  The Macintosh Library Modules
  26 document uses the "howto" document class instead.  These contains many
  27 macro definitions useful in documenting Python, and set some style
  28 parameters.
  29
  30 There's a Makefile to call LaTeX and the other utilities in the right
  31 order and the right number of times.  This will produce DVI files for
  32 each document made; to preview them, use xdvi.  PostScript is produced
  33 by the same Makefile target that produces the DVI files.  This uses
  34 the dvips tool.  Printing depends on local conventions; at our site,
  35 we use lpr.  For example:
  36
  37         make lib        # create lib.dvi and lib.ps
  38         xdvi lib        # preview lib.dvi
  39         lpr lib.ps      # print on default printer
  40
  41
  42 What if I find a bug?
  43 ---------------------
  44
  45 First, check that the bug is present in the online version of the
  46 documentation at <http://www.python.org/docs/>; we may have already
  47 fixed it.
  48
  49 If we haven't, tell us about it.  We'd like the documentation to be
  50 complete and accurate, but have limited time.  If you discover any
  51 inconsistencies between the documentation and implementation, or just
  52 have suggestions as to how to improve the documentation, let is know!
  53 Send comments and patches to the Python Documentation Team:
  54
  55                            python-docs@python.org
  56
  57 Thanks!
  58
  59
  60 What happened to the Macintosh chapter of the Python Library Reference?
  61 -----------------------------------------------------------------------
  62
  63 The directory mac/ contains the LaTeX sources for the "Macintosh
  64 Library Modules" manual; this is built using the standard build
  65 targets, so check the proper output directory for your chosen format
  66 and paper size.
  67
  68
  69 What tools do I need?
  70 ---------------------
  71
  72 You need to install Python; some of the scripts used to produce the
  73 documentation are written in Python.  You don't need this
  74 documentation to install Python; instructions are included in the
  75 README file in the Python distribution.
  76
  77 The simplest way to get the rest of the tools in the configuration we
  78 used is to install the teTeX TeX distribution, version 0.4 or 0.9.  More
  79 information is available on teTeX at <http://www.tug.org/tetex/>.
  80 This is a Unix-only TeX distribution at this time.  Note that the 0.9
  81 release is still in testing; this documentation release was tested
  82 with the 9 Feb 1999 release.  We'll be upgrading to the final version
  83 when it becomes available.  Except for the PDF generation, there are
  84 no known problems with using the ("stable") teTeX 0.4 release.
  85
  86 If you don't want to get teTeX, here is what you'll need:
  87
  88 To create DVI, PDF, or PostScript files:
  89
  90         - LaTeX2e, 1995/12/01 or newer.  Older versions are likely to
  91           choke.
  92
  93         - makeindex.  This is used to produce the indexes for the
  94           library reference and Python/C API reference.
  95
  96 To create PDF files:
  97
  98         - pdflatex.  We used the one in the teTeX 0.9 distribution
  99           (pdfTeX version 3.14159-13b (Web2C 7.3beta4) at the time of
 100           this writing).  Versions even a couple of patchlevels
 101           earlier are highly likely to fail due to syntax changes for
 102           some of the pdftex primitives.
 103
 104 To create PostScript files:
 105
 106         - dvips.  Most TeX installations include this.  If you don't
 107           have one, check CTAN (<ftp://ctan.tug.org/tex-archive/>).
 108
 109 To create info files:
 110
 111         Note that info support is currently being revised using new
 112         conversion tools by Michael Ernst <mernst@cs.washington.edu>.
 113
 114         - makeinfo.  This is available from any GNU mirror.
 115
 116         - emacs or xemacs.  Emacs is available from the same place as
 117           makeinfo, and xemacs is available from ftp.xemacs.org.
 118
 119         - Perl.  Find the software at
 120           <http://language.perl.com/info/software.html>.
 121
 122 To create HTML files:
 123
 124         - Perl 5.004_04 or newer.  Find the software at
 125           <http://language.perl.com/info/software.html>.
 126
 127         - LaTeX2HTML 98.2b6.  Older version will fail with the new
 128           directory layout.  Version 98.2b8 specifically does not
 129           work; it translates `` and '' to &ldquo; and &rdquo;, which
 130           are not supported by popular Web browsers.  This also screws
 131           up code fragments.  ;-(  Releases are available at:
 132           <http://cdc-server.cdc.informatik.tu-darmstadt.de/~latex2html/>.
 133
 134
 135 What if Times fonts are not available?
 136 --------------------------------------
 137
 138 As distributed, the LaTeX documents use PostScript Times fonts.  This
 139 is done since they are much better looking and produce smaller
 140 PostScript files.  If, however, your TeX installation does not support
 141 them, they may be easily disabled.  Edit the file
 142 texiinputs/manual.cls and comment out the line that starts
 143 "\RequirePackage{times}" by inserting a "%" character at the beginning
 144 of the line.  An alternative is to install the right fonts and LaTeX
 145 style file.
 146
 147
 148 What if I want to use A4 paper?
 149 -------------------------------
 150
 151 Instead of building the PostScript by giving the command "make", give
 152 the command "make PAPER=a4"; the output will be produced in the
 153 paper-a4/ subdirectory.
 154
 155
 156 Making HTML files
 157 -----------------
 158
 159 The LaTeX documents can be converted to HTML using Nikos Drakos'
 160 LaTeX2HTML converter.  See the Makefile; after some twiddling, "make
 161 html" should do the trick.
 162
 163
 164 What else is in here?
 165 ---------------------
 166
 167 There is a new LaTeX document class called "howto".  This is used for
 168 the new series of Python HOWTO documents which is being coordinated by
 169 Andrew Kuchling <amk@acm.org>.  The file templates/howto.tex is a
 170 commented example which may be used a template.  A script to "do the
 171 right thing" to format a howto document is included as
 172 tools/mkhowto.  These documents can be formatted as HTML, PDF,
 173 PostScript, or ASCII files.  Support for this document class is
 174 still new, but is expected to evolve rapidly.  Use "mkhowto --help"
 175 for information on using the formatting tool.
 176
 177 For authors of module documentation, there is a file
 178 templates/module.tex which may be used as a template for a module
 179 section.  This may be used in conjunction with either the howto or
 180 manual document class.  Create the documentation for a new module by
 181 copying the template to lib<mymodule>.tex and editing according to the
 182 instructions in the comments.
 183
 184
 185 Copyright notice
 186 ================
 187
 188 The Python source is copyrighted, but you can freely use and copy it
 189 as long as you don't change or remove the copyright notice:
 190
 191 ----------------------------------------------------------------------
 192 Copyright 1991-1995 by Stichting Mathematisch Centrum, Amsterdam,
 193 The Netherlands.
 194
 195                         All Rights Reserved
 196
 197 Permission to use, copy, modify, and distribute this software and its
 198 documentation for any purpose and without fee is hereby granted,
 199 provided that the above copyright notice appear in all copies and that
 200 both that copyright notice and this permission notice appear in
 201 supporting documentation, and that the names of Stichting Mathematisch
 202 Centrum or CWI or Corporation for National Research Initiatives or
 203 CNRI not be used in advertising or publicity pertaining to
 204 distribution of the software without specific, written prior
 205 permission.
 206
 207 While CWI is the initial source for this software, a modified version
 208 is made available by the Corporation for National Research Initiatives
 209 (CNRI) at the Internet address ftp://ftp.python.org.
 210
 211 STICHTING MATHEMATISCH CENTRUM AND CNRI DISCLAIM ALL WARRANTIES WITH
 212 REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF
 213 MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH
 214 CENTRUM OR CNRI BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
 215 DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
 216 PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
 217 TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 218 PERFORMANCE OF THIS SOFTWARE.
 219 ----------------------------------------------------------------------