cpython/Doc
Andrew M. Kuchling f33c118869 Add introductory note about this article's draft status
Grammatical and typographic fixes from David Goodger
Expanded notes about PEP 229
Removed user-visible XXXes; they're in comments now
2001-01-23 02:48:26 +00:00
..
api Fixed a bunch of typos caught by Gilles Civario. 2001-01-19 22:48:33 +00:00
dist Updates to reflect pending changes to the XML conversion process. 2000-11-22 16:42:37 +00:00
doc Minor typo: \subsubsections --> \subsubsection 2000-11-27 20:10:18 +00:00
ext Worked around bug SF #125880: changed the text of three sections that 2001-01-22 18:38:00 +00:00
html Remove bogus "echo" command. 2001-01-09 22:50:13 +00:00
info Update the dependency information to allow the other Makefiles to handle 2000-10-26 19:26:47 +00:00
inst Do not require packages that are not needed. 2000-10-26 21:13:22 +00:00
lib Added link to the "Python Codecs" project at SourceForge. 2001-01-22 20:17:54 +00:00
longhtml Describe the purpose of the "long HTML" package. 2000-04-07 14:47:27 +00:00
mac Updates to reflect pending changes to the XML conversion process. 2000-11-22 16:42:37 +00:00
paper-a4 Ignore the generated api.tex. 2000-06-30 19:25:41 +00:00
paper-letter Adjust the Macintosh manual to have the formatting dependencies for 2000-10-14 05:47:17 +00:00
perl Fix \seepep handling -- correct URL to the online PEP repository on SF is 2001-01-22 17:33:24 +00:00
ref Updated note about collection of cyclic garbage, based on comments from 2001-01-22 17:46:18 +00:00
templates Minor changes. Explain that for class exceptions, use excdesc but do not 2000-07-06 16:12:47 +00:00
texinputs Remove the dollar sign from the formatting of environment variables -- 2001-01-22 17:50:42 +00:00
tools When generating the source package, copy in the LICENSE file from the main 2001-01-22 21:34:20 +00:00
tut Clarify comments about returning None using a return without an expression; 2001-01-19 22:34:59 +00:00
whatsnew Add introductory note about this article's draft status 2001-01-23 02:48:26 +00:00
.cvsignore Never mind ignoring a copied LICENSE file; let's do this another way. 2001-01-22 21:31:38 +00:00
ACKS Fix a typo, remove one copy of a duplicated name. 2001-01-10 05:33:38 +00:00
Makefile Change the main targets to generate HTML instead of PostScript. 2001-01-22 20:47:26 +00:00
Makefile.deps Added documentation for the xreadlines module & related changes. The 2001-01-09 22:47:46 +00:00
README A variety of updates of out-of-date information. 2001-01-22 21:38:09 +00:00
TODO Remove an item that no longer needs to be done for 2.0. 2000-09-07 21:11:45 +00:00
libmods.tex Lots of small corrections by Andrew Kuchling (plus all new rotor docs) 1994-08-08 12:30:22 +00:00
libstd.tex Restructured library documentation 1994-01-02 01:22:07 +00:00

README

Python main 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>).

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
	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.  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 development version of the
documentation at <http://python.sourceforge.net/devel-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!
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:

	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, 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.004_04 or newer.  Find the software at
	  <http://language.perl.com/info/software.html>.

	- LaTeX2HTML 99.2b8.  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://saftsack.fs.uni-bayreuth.de/~latex2ht/current/>.


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}" by inserting 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 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
html" 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.


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, 2001 Guido van Rossum.
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 "LICENSE" for information on usage and
redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES.
----------------------------------------------------------------------