| Python main documentation -- in LaTeX |
| ------------------------------------- |
| |
| This directory contains the LaTeX sources to the Python documentation. |
| They now require LaTeX2e (LaTeX 2.09 compatibility is dropped). |
| |
| If you don't have LaTeX, or if you'd rather not format the |
| documentation yourself, you can ftp a tar file containing HTML, PDF, |
| or PostScript versions of all documents. Additional formats may be |
| available. These should be in the same place where you fetched the |
| main Python distribution (try <http://www.python.org> or |
| <ftp://ftp.python.org>). |
| |
| The following are the LaTeX source files: |
| |
| api/*.tex Python/C API Reference Manual |
| ext/*.tex Extending and Embedding the Python Interpreter |
| lib/*.tex Python Library Reference |
| ref/*.tex Python Reference Manual |
| tut/*.tex Python Tutorial |
| |
| All use the "manual" document class and "python" package, derived from |
| the old "myformat.sty" style file. These contains many macro |
| definitions useful in documenting Python, and set some style parameters. |
| |
| There's a Makefile to call LaTeX and the other utilities in the right |
| order and the right number of times. This will produce DVI files for |
| each document made; to preview them, use xdvi. PostScript is produced |
| by the same Makefile target that produces the DVI files. This uses |
| the dvips tool. Printing depends on local conventions; at our site, |
| we use lpr. For example: |
| |
| make lib # create lib.dvi and lib.ps |
| xdvi lib # preview lib.dvi |
| lpr lib.ps # print on default printer |
| |
| |
| What if I find a bug? |
| --------------------- |
| |
| First, check that the bug is present in the online version of the |
| documentation at <http://www.python.org/docs/>; we may have already |
| fixed it. |
| |
| If we haven't, tell us about it. We'd like the documentation to be |
| complete and accurate, but have limited time. If you discover any |
| inconsistencies between the documentation and implementation, or just |
| have suggestions as to how to improve the documentation, let is know! |
| Send comments and patches to the Python Documentation Team: |
| |
| python-docs@python.org |
| |
| Thanks! |
| |
| |
| What happened to the Macintosh chapter of the Python Library Reference? |
| ----------------------------------------------------------------------- |
| |
| The directory mac/ contains the LaTeX sources for the "Macintosh |
| Library Modules" manual; this is built using the standard build |
| targets, so check the proper output directory for your chosen format |
| and paper size. |
| |
| |
| What tools do I need? |
| --------------------- |
| |
| You need to install Python; some of the scripts used to produce the |
| documentation are written in Python. You don't need this |
| documentation to install Python; instructions are included in the |
| README file in the Python distribution. |
| |
| The simplest way to get the rest of the tools in the configuration we |
| used is to install the teTeX TeX distribution, version 0.4 or 0.9. More |
| information is available on teTeX at <http://www.tug.org/tetex/>. |
| This is a UNIX-only TeX distribution at this time. Note that the 0.9 |
| release is still in testing; this documentation release was tested |
| with the 21 Apr 1998 release. We'll be upgrading to the final version |
| when it becomes available. Except for the PDF generation, it also works |
| with the (stable) teTeX 0.4 release. |
| |
| If you don't want to get teTeX, here is what you'll need: |
| |
| To create DVI, PDF, or PostScript files: |
| |
| - LaTeX2e, 1995/12/01 or newer. Older versions are likely to |
| choke. |
| |
| - makeindex. This is used to produce the indexes for the |
| library reference and Python/C API reference. |
| |
| To create PDF files: |
| |
| - pdflatex. We used the one in the teTeX 0.9 distribution |
| (version 0.12h at the time of this writing). Versions even |
| a couple of patchlevels earlier are highly likely to fail |
| due to syntax changes for some of the pdftex primitives. |
| |
| To create PostScript files: |
| |
| - dvips. Most TeX installations include this. If you don't |
| have one, check CTAN (<ftp://ctan.tug.org/tex-archive/>). |
| |
| To create info files: |
| |
| (Note that info is not currently supported. If you need it, |
| please fix or replace tools/partparse.py and send the new |
| version to python-docs@python.org. We'll be glad to provide |
| free copies of the info files to anyone who can support the |
| process. ;-) |
| |
| - makeinfo. This is available from any GNU mirror. |
| |
| - emacs or xemacs. Emacs is available from the same place as |
| makeinfo, and xemacs is available from ftp.xemacs.org. |
| |
| To create HTML files: |
| |
| - Perl 5.004_04 or newer. Find the software at |
| <http://language.perl.com/info/software.html>. |
| |
| - LaTeX2HTML 98.2b2 or newer. Older version will fail with |
| the new directory layout. Releases are available at |
| <http://dc-server.cdc.informatik.tu-darmstadt.de/~latex2html/>. |
| |
| |
| What if Times fonts are not available? |
| -------------------------------------- |
| |
| As distributed, the LaTeX documents use PostScript Times fonts. This |
| is done since they are much better looking and produce smaller |
| PostScript files. If, however, your TeX installation does not support |
| them, they may be easily disabled. Edit the file |
| texiinputs/manual.cls and comment out the line that starts |
| "\RequirePackage{times}" using a "%" character at the beginning of the |
| line. An alternative is to install the right fonts and LaTeX style |
| file. |
| |
| |
| What if I want to use A4 paper? |
| ------------------------------- |
| |
| Instead of building the PostScript by giving the command "make", give |
| the command "make PAPER=a4"; the output will be produced in the |
| paper-a4/ subdirectory. |
| |
| |
| Making HTML files |
| ----------------- |
| |
| The LaTeX documents can be converted to HTML using Nikos Drakos' |
| LaTeX2HTML converter. See the Makefile; after some twiddling, "make |
| l2h" should do the trick. |
| |
| |
| What else is in here? |
| --------------------- |
| |
| There is a new LaTeX document class called "howto". This is used for |
| the new series of Python HOWTO documents which is being coordinated by |
| Andrew Kuchling <amk@acm.org>. The file templates/howto.tex is a |
| commented example which may be used a template. A script to "do the |
| right thing" to format a howto document is included as |
| tools/mkhowto.sh. Support for this document class is still new, but |
| is expected to evolve rapidly. Use "mkhowto.sh --help" for |
| information on using the formatting tool. |
| |
| For authors of module documentation, there is a file |
| templates/module.tex which may be used as a template for a module |
| section. This may be used in conjunction with either the howto or |
| manual document class. Create the documentation for a new module by |
| copying the template to lib<mymodule>.tex and editing according to the |
| instructions in the comments. |
| |
| |
| Copyright notice |
| ================ |
| |
| The Python source is copyrighted, but you can freely use and copy it |
| as long as you don't change or remove the copyright notice: |
| |
| ---------------------------------------------------------------------- |
| Copyright 1991-1995 by Stichting Mathematisch Centrum, Amsterdam, |
| The Netherlands. |
| |
| All Rights Reserved |
| |
| Permission to use, copy, modify, and distribute this software and its |
| documentation for any purpose and without fee is hereby granted, |
| provided that the above copyright notice appear in all copies and that |
| both that copyright notice and this permission notice appear in |
| supporting documentation, and that the names of Stichting Mathematisch |
| Centrum or CWI or Corporation for National Research Initiatives or |
| CNRI not be used in advertising or publicity pertaining to |
| distribution of the software without specific, written prior |
| permission. |
| |
| While CWI is the initial source for this software, a modified version |
| is made available by the Corporation for National Research Initiatives |
| (CNRI) at the Internet address ftp://ftp.python.org. |
| |
| STICHTING MATHEMATISCH CENTRUM AND CNRI DISCLAIM ALL WARRANTIES WITH |
| REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF |
| MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH |
| CENTRUM OR CNRI BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL |
| DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR |
| PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER |
| TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR |
| PERFORMANCE OF THIS SOFTWARE. |
| ---------------------------------------------------------------------- |