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

 THIS IS A *TEST* RELEASE.  It includes a significantly revised
 directory organization for the documentation, and much of the
 formatting process has been adjusted.  The documentation itself is not
 necessarily consistent with any released version of Python.

 The only purpose for this release is to test the usability of the new
 directory structure.  Please attempt to *format* the documentation to
 determine if the new processes are suitable for your purposes; the
 basic targets have been extensively tested, but variations may require
 some work.  Please let us know if there are any problems with the new
 organization or processes; send email to:

 			   python-docs@python.org


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

 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
 	ref/*.tex	Python Reference Manual
 	tut/*.tex	Python Tutorial

 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 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 not currently included in the build
 system.  To build, do the following:

 	cd Doc/mac
 	../tools/mkhowto.sh --ps --pdf --html mac

 (Any combination of --ps, --pdf, and --html may be used depending on
 your needs; the default is --pdf.)


 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.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 21 Apr 1998 release.  We'll be upgrading to the final version
 when it becomes available.  Except for the PDF generation, it also works
 with 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
 	  (version 0.12h 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 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.1p5 or newer.  Older version will fail with
 	  the new directory layout.  Releases are available at
 	  <http://dc-server.cdc.informatik.tu-darmstadt.de/~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?
 -------------------------------

 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
 l2h" 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 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.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.
 ----------------------------------------------------------------------
	THIS IS A TEST RELEASE. It includes a significantly revised
	directory organization for the documentation, and much of the
	formatting process has been adjusted. The documentation itself is not
	necessarily consistent with any released version of Python.

	The only purpose for this release is to test the usability of the new
	directory structure. Please attempt to format the documentation to
	determine if the new processes are suitable for your purposes; the
	basic targets have been extensively tested, but variations may require
	some work. Please let us know if there are any problems with the new
	organization or processes; send email to:

	python-docs@python.org


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

	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
	ref/*.tex Python Reference Manual
	tut/*.tex Python Tutorial

	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 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 not currently included in the build
	system. To build, do the following:

	cd Doc/mac
	../tools/mkhowto.sh --ps --pdf --html mac

	(Any combination of --ps, --pdf, and --html may be used depending on
	your needs; the default is --pdf.)


	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.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 21 Apr 1998 release. We'll be upgrading to the final version
	when it becomes available. Except for the PDF generation, it also works
	with 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
	(version 0.12h 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 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.1p5 or newer. Older version will fail with
	the new directory layout. Releases are available at
	<http://dc-server.cdc.informatik.tu-darmstadt.de/~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?
	-------------------------------

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