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

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


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


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