diff options
Diffstat (limited to 'Doc/README')
| -rw-r--r-- | Doc/README | 246 |
1 files changed, 0 insertions, 246 deletions
diff --git a/Doc/README b/Doc/README deleted file mode 100644 index a426ba2..0000000 --- a/Doc/README +++ /dev/null @@ -1,246 +0,0 @@ -Python standard documentation -- in LaTeX ------------------------------------------ - -This directory contains the LaTeX sources to the Python documentation -and tools required to support the formatting process. The documents -now require LaTeX2e; LaTeX 2.09 compatibility has been 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/pub/python/>). - -The following are the LaTeX source files: - - api/*.tex Python/C API Reference Manual - doc/*.tex Documenting Python - ext/*.tex Extending and Embedding the Python Interpreter - lib/*.tex Python Library Reference - mac/*.tex Macintosh Library Modules - ref/*.tex Python Reference Manual - tut/*.tex Python Tutorial - inst/*.tex Installing Python Modules - dist/*.tex Distributing Python Modules - -Most use the "manual" document class and "python" package, derived from -the old "myformat.sty" style file. The Macintosh Library Modules -document uses the "howto" document class instead. 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. By default, it will build the -HTML version of the documentation, but DVI, PDF, and PostScript can -also be made. To view the generated HTML, point your favorite browser -at the top-level index (html/index.html) after running "make". - -The Makefile can also 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 paper-letter/lib.ps # create lib.dvi and lib.ps - xdvi paper-letter/lib.dvi # preview lib.dvi - lpr paper-letter/lib.ps # print on default printer - - -What if I find a bug? ---------------------- - -First, check that the bug is present in the development version of the -documentation at <http://www.python.org/dev/doc/devel/>; 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! -Specific bugs and patches should be reported using our bug & patch -databases at: - - http://sourceforge.net/projects/python - -Other suggestions or questions should be sent to the Python -Documentation Team: - - docs@python.org - -Thanks! - - -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, versions 0.9 or newer. -More information is available on teTeX at <http://www.tug.org/tetex/>. -This is a Unix-only TeX distribution at this time. This documentation -release was tested with the 1.0.7 release, but there have been no -substantial changes since late in the 0.9 series, which we used -extensively for previous versions without any difficulty. - -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 distribution (pdfTeX - version 3.14159-13d (Web2C 7.3.1) 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 support is currently being revised using new - conversion tools by Michael Ernst <mernst@cs.washington.edu>. - - - 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. - - - Perl. Find the software at - <http://language.perl.com/info/software.html>. - - - HTML::Element. If you don't have this installed, you can get - this from CPAN. Use the command: - - perl -e 'use CPAN; CPAN::install("HTML::Element");' - - You may need to be root to do this. - -To create HTML files: - - - Perl 5.6.0 or newer. Find the software at - <http://language.perl.com/info/software.html>. - - - LaTeX2HTML 99.2b8 or newer. Older versions are not - supported; each version changes enough that supporting - multiple versions is not likely to work. Many older - versions don't work with Perl 5.6 as well. This also screws - up code fragments. ;-( Releases are available at: - <http://www.latex2html.org/>. - - -I got a make error: "make: don't know how to make commontex/patchlevel.tex." ----------------------------------------------------------------------------- - -Your version of make doesn't support the 'shell' function. You will need to -use a version which does, e.g. GNU make. - - -LaTeX (or pdfLaTeX) ran out of memory; how can I fix it? --------------------------------------------------------- - -This is known to be a problem at least on Mac OS X, but it has been -observed on other systems in the past. - -On some systems, the default sizes of some of the memory pools -allocated by TeX needs to be changed; this is a configuration setting -for installations based on web2c (most if not all installations). -This is usually set in a file named texmf/web2c/texmf.cnf (where the -top-level texmf/ directory is part of the TeX installation). If you -get a "buffer overflow" warning from LaTeX, open that configuration -file and look for the "main_memory.pdflatex" setting. If there is not -one, you can add a line with the setting. The value 1500000 seems to -be sufficient for formatting the Python documetantion. - - -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 -texinputs/pypaper.sty and comment out the line that starts -"\RequirePackage{times}" by inserting a "%" character at the beginning -of the line. If you're formatting the docs for A4 paper instead of -US-Letter paper, change paper-a4/pypaper.sty instead. 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 ps", -give the command "make PAPER=a4 ps"; the output will be produced in -the paper-a4/ subdirectory. (You can use "make PAPER=a4 pdf" if you'd -rather have PDF output.) - - -Making HTML files ------------------ - -The LaTeX documents can be converted to HTML using Nikos Drakos' -LaTeX2HTML converter. See the Makefile; after some twiddling, "make" -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 <akuchlin@mems-exchange.org>. The file -templates/howto.tex is a commented example which may be used as a -template. A Python script to "do the right thing" to format a howto -document is included as tools/mkhowto. These documents can be -formatted as HTML, PDF, PostScript, or ASCII files. Use "mkhowto ---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. - -Documentation on the authoring Python documentation, including -information about both style and markup, is available in the -"Documenting Python" manual. - - -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 (c) 2000-2007 Python Software Foundation. -All rights reserved. - -Copyright (c) 2000 BeOpen.com. -All rights reserved. - -Copyright (c) 1995-2000 Corporation for National Research Initiatives. -All rights reserved. - -Copyright (c) 1991-1995 Stichting Mathematisch Centrum. -All rights reserved. - -See the file "commontex/license.tex" for information on usage and -redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES. ----------------------------------------------------------------------- |