This is the README file for the py2tex package by Jeroen van Maanen.

CONTENTS
========

BLURB
INSTALLATION
USAGE OF PY2TEX
FORMAT THE DOCUMENTATION
DOCSTRIP
BUGS, COMMENTS

BLURB
=====

The py2tex package allows you to typeset Python programs with LaTeX.
It consists of some Python code to translate Python source to LaTeX
and a LaTeX style file that contains the necessary definitions.  The
style file also adds some degree of customizability.

Its primary function is to typeset Python code properly.
* Keywords bold.
* Functions slanted.
* Symbols instead of ASCII kludges for
  - assignment (=),
  - relations (==, <=, >=, !=, <>, in, not in, is, is not),
  - logical operators (not, and, or).
  [This is optional because some people (e.g., Guido) find the ASCII
  versions more recognizable.]
* Strings in typewriter type.  ASCII control characters in strings
  are handled properly, i.e., they are typeset as escape sequences
  ('TAB' is typeset as '\t' and 'ESC' is typeset as '\033').  Long
  strings (delimited by triple quotes) are handled properly too
  except in comments.
* Numeric literals are typeset sensibly.
  - floating point literals in scientific notation
    (like $1\cdot 10^6$).
  - octal literals in italic digits.
  - hexadecimal literals in typewriter type, lower case 'x', upper
    case digits.
* Proper indentation (also for continued lines).
* Proper line breaking (following TeX rules for formulas).
* Line numbers.
* Consecutive lines that start with a hash mark (#) right after the
  indentation are joined in a single `block comment' and typeset as
  a whole rather than line by line.

It also gives you the full power of TeX in the comments to your code
if you want.  This not only allows TeX constructs, like formulae, in
comments, it also allows for formatted scraps of Python code in
comments.  In (La)TeX mode the hash mark switches between TeX and
Python mode within comments, like the dollar sign switches between
TeX and math mode.

If you don't need these features, or if you want to typeset programs
that were not specifically written to be typeset with py2tex, you
can leave comments uninterpreted either by running the py2tex script
with the -v flag, or by inserting magic comments in the source file.

The Python source for this package is of course documented using the
package itself.  The accompanying LaTeX style file is documented
using the doc option by Frank Mittelbach.

INSTALLATION
============

The installation of the py2tex package is very simple:

--  gunzip and extract the file py2tex.tar.gz
    this creates a directory py2tex
--  put the file py2tex.py in a directory where Python will see it
    (i.e., a directory in $PYTHONPATH);
--  put the file py2tex in a directory that is in $PATH and make
    sure that it is executable (if not, use chmod(1));
--  put the file py2tex.sty in a directory where TeX will see it
    (i.e., a directory in $TEXINPUTS);

(Note that Python, the shell and TeX probably all look in the current
directory, so you can try it without moving anything.)

The preformatted documentation is included as the DVI file "doc.dvi".
(I assume that you know what to do with a .dvi file, otherwise you
would probably not be interested in this package.)

USAGE OF PY2TEX
===== == ======

To typeset a Python module called foo.py with py2tex, create a
LaTeX file along the following lines.

  %% frame.tex -- wrapper around foo
  \documentstyle[...,py2tex,...]{...}
  ...
  \begin{document}
  ...
  \PythonSource{foo.pt}
  ...
  \end{document}

Then give the command

$ py2tex -o foo.pt foo.py

Finally run LaTeX on the previously constructed wrapper, like this

$ latex frame

This will give you a .dvi file that you can print in the normal
way.

FORMAT THE DOCUMENTATION
====== === =============

This only applies if you want to format the documentation yourself.

If your LaTeX doesn't use the new font selection scheme (NFSS) then
the Python code will not come out in sans serif.  If you don't have
Frank Mittelbachs `doc' option (available on the CTAN ftp archives)
then you will get a verbatim copy of the documented style file, not a
nicely formatted one.

To generate the documentation for py2tex, first translate the python
sources with the package itself with the command

$ ./translate [ <pythondir> [ <bindir> ] ]

where <pythondir> is the directory where you installed py2tex.py and
<bindir> is the directory where you installed the py2tex script.
After that, run

$ latex doc

as often as is needed to get the table of contents right (probably two
times is sufficient).

DOCSTRIP
========

If you have the docstrip utility by Frank Mittelbach, you can produce
py2tex.sty from py2tex.doc using the command

$ latex py2tex.cmd

BUGS, COMMENTS
====  ========

If you encounter any problems with this package, please drop me an
email at <Jeroen.van.Maanen@inter.nl.net>.