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

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

 The Python Reference Manual is no longer maintained in LaTeX.  It is
 now a FrameMaker document.  The FrameMaker 5.0 files (ref.book,
 ref*.doc) as well as PostScript generated (ref.ps) from it are in the
 subdirectory ref/.  (See <ftp://ftp.adobe.com/pub/adobe/framereader>
 for a free reader for FrameMaker documents, for some platforms.)  Many
 thanks to Robin Friedrich for the conversion of the Reference Manual
 to FrameMaker and his work on its index.

 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:

 	tut.tex				The tutorial
 	lib.tex, lib*.tex		The library reference
 	ext.tex				How to extend Python
 	api.tex				Reference for the Python/C API

 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 tools do I need?
 ---------------------

 You need to install Python; some of the scripts used to produce the
 documentation are written in Python.

 The simplest way to get the rest of the tools in the configuration we
 used is to install the teTeX TeX distribution, version 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 18 Mar 1998 release.  We'll be upgrading to the final version
 when it becomes available.

 If you don't want to get teTeX, or if you're not using UNIX, 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.12f at the time of this writing).  Versions even
 	  a couple of patchlevels different 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.1p1, or newer.  Releases are available at
 	  <http://www-dsed.llnl.gov/files/programs/unix/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?
 -------------------------------

 Edit the file texinputs/manual.cls.  Change the line that reads:

     \LoadClass[twoside,openright]{report}

 to say:

     \LoadClass[a4paper,twoside,openright]{report}

 Now do a "make clean all" to generate PostScript files.


 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.

 For the reference manual, we use Harlequin's webmaker.  We're not very
 happy with it and hope that eventually FrameMaker will be able to
 produce HTML without third party help.


 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 howto.tex is a commented
 template which may be used an example.  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.


 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.
	They now require LaTeX2e (LaTeX 2.09 compatibility is dropped).

	The Python Reference Manual is no longer maintained in LaTeX. It is
	now a FrameMaker document. The FrameMaker 5.0 files (ref.book,
	ref*.doc) as well as PostScript generated (ref.ps) from it are in the
	subdirectory ref/. (See <ftp://ftp.adobe.com/pub/adobe/framereader>
	for a free reader for FrameMaker documents, for some platforms.) Many
	thanks to Robin Friedrich for the conversion of the Reference Manual
	to FrameMaker and his work on its index.

	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:

	tut.tex The tutorial
	lib.tex, lib*.tex The library reference
	ext.tex How to extend Python
	api.tex Reference for the Python/C API

	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 tools do I need?
	---------------------

	You need to install Python; some of the scripts used to produce the
	documentation are written in Python.

	The simplest way to get the rest of the tools in the configuration we
	used is to install the teTeX TeX distribution, version 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 18 Mar 1998 release. We'll be upgrading to the final version
	when it becomes available.

	If you don't want to get teTeX, or if you're not using UNIX, 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.12f at the time of this writing). Versions even
	a couple of patchlevels different 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.1p1, or newer. Releases are available at
	<http://www-dsed.llnl.gov/files/programs/unix/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?
	-------------------------------

	Edit the file texinputs/manual.cls. Change the line that reads:

	\LoadClass[twoside,openright]{report}

	to say:

	\LoadClass[a4paper,twoside,openright]{report}

	Now do a "make clean all" to generate PostScript files.


	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.

	For the reference manual, we use Harlequin's webmaker. We're not very
	happy with it and hope that eventually FrameMaker will be able to
	produce HTML without third party help.


	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 howto.tex is a commented
	template which may be used an example. 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.


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