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, 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>.

 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"; 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

 Copyright (c) 2000, BeOpen.com.
 Copyright (c) 1995-2000, Corporation for National Research Initiatives.
 Copyright (c) 1990-1995, Stichting Mathematisch Centrum.
 All rights reserved.

 See the file "Misc/COPYRIGHT" for information on usage and
 redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 ----------------------------------------------------------------------
	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, 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>.

	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"; 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

	Copyright (c) 2000, BeOpen.com.
	Copyright (c) 1995-2000, Corporation for National Research Initiatives.
	Copyright (c) 1990-1995, Stichting Mathematisch Centrum.
	All rights reserved.

	See the file "Misc/COPYRIGHT" for information on usage and
	redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES.
	----------------------------------------------------------------------