Doc/README - platform/external/python/cpython2 - Gitiles

 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 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 9 Feb 1999 release.  We'll be upgrading to the final version
 when it becomes available.  Except for the PDF generation, there are
 no known problems with using 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
 	  (pdfTeX version 3.14159-13b (Web2C 7.3beta4) 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>.

 To create HTML files:

 	- Perl 5.004_04 or newer.  Find the software at
 	  <http://language.perl.com/info/software.html>.

 	- LaTeX2HTML 98.2b6.  Older version will fail with the new
 	  directory layout.  Version 98.2b8 specifically does not
 	  work; it translates `` and '' to &ldquo; and &rdquo;, which
 	  are not supported by popular Web browsers.  This also screws
 	  up code fragments.  ;-(  Releases are available at:
 	  <http://cdc-server.cdc.informatik.tu-darmstadt.de/~latex2html/>.
 	  Really new versions also don't work, but I'm not sure when
 	  things broke.


 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"; 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
 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 <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.  These documents can be formatted as HTML, PDF,
 PostScript, or ASCII files.  Support for this document class is
 still new, but is expected to evolve rapidly.  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 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.
 ----------------------------------------------------------------------
	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 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 9 Feb 1999 release. We'll be upgrading to the final version
	when it becomes available. Except for the PDF generation, there are
	no known problems with using 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
	(pdfTeX version 3.14159-13b (Web2C 7.3beta4) 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>.

	To create HTML files:

	- Perl 5.004_04 or newer. Find the software at
	<http://language.perl.com/info/software.html>.

	- LaTeX2HTML 98.2b6. Older version will fail with the new
	directory layout. Version 98.2b8 specifically does not
	work; it translates `` and '' to “ and ”, which
	are not supported by popular Web browsers. This also screws
	up code fragments. ;-( Releases are available at:
	<http://cdc-server.cdc.informatik.tu-darmstadt.de/~latex2html/>.
	Really new versions also don't work, but I'm not sure when
	things broke.


	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"; 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
	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 <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. These documents can be formatted as HTML, PDF,
	PostScript, or ASCII files. Support for this document class is
	still new, but is expected to evolve rapidly. 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 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.
	----------------------------------------------------------------------