Pointless standard documentation -- in LaTeX
--------------------------------------------

This directory contains the LaTeX sources to the Pointless documentation and
tools required to support the formatting process.  It is a tailored version of
the coresponding Python documentation directory.  The documents require
LaTeX2e.

The following are the LaTeX source files:

	ref/*.tex	The Pointless Manual

Most use the "manual" document class as well as and "python" and "pointless"
package.

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/ref.ps	# create ref.dvi and ref.ps
	xdvi paper-letter/ref.dvi	# preview ref.dvi
	lpr paper-letter/ref.ps		# print on default printer


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


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



Copyright notice
================

The Pointless 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) 2001-2003 
All rights reserved.


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