Doc/README

   1 Python main documentation -- in LaTeX
   2 -------------------------------------
   3
   4 This directory contains the LaTeX sources to the Python documentation
   5 and a published article about Python.
   6
   7 The following are the LaTeX source files:
   8
   9         tut.tex                         The tutorial
  10         lib.tex, lib[1-5].tex           The library reference
  11         ref.tex, ref[1-8].tex           The reference manual
  12         qua.tex, quabib.bib             Article published in CWI Quarterly
  13
  14 All except qua.tex use the style option file "myformat.sty".  This
  15 contains some macro definitions and sets some style parameters.
  16
  17 The style parameters are set up for European paper size (21 x 29.7 cm,
  18 a.k.a. A4, or roughly 8.27 x 11.7 inch) by default.  To use US paper,
  19 comment out the line saying \input{a4wide.sty} in myformat.sty (you
  20 may want to fiddle with lay-out parameters like \textwidth and
  21 \textheight, since the default format uses rather wide margins).
  22
  23 You need the makeindex utility to produce the index for ref.tex
  24 lib.tex; you need bibtex to produce the references list for qua.tex.
  25
  26 There's a Makefile to call latex and the other utilities in the right
  27 order and the right number of times.  This will produce dvi files for
  28 each document made; to preview them, use xdvi.  Printing depends on
  29 local conventions; at my site, I use dvips and lpr.  For example:
  30
  31         make ref                        # creates ref.dvi
  32         xdvi ref                        # preview it
  33         dvips -Ppsc ref | lpr -Ppsc     # print it on printer "psc".
  34
  35 If you don't have latex, you can ftp the pre-formatted PosytScript
  36 versions of the documents; see "../misc/FTP" for information about
  37 ftp-ing Python files.
  38
  39 Making the INFO version of the Library Reference
  40 ------------------------------------------------
  41
  42 The Library Reference can now also be read in hypertext form using the
  43 Emacs INFO system.  This uses Texinfo format as an intermediate step.
  44 It requires texinfo version 2 (we have used 2.14).
  45
  46 To build the info files (python-lib.info*), say "make libinfo".  This
  47 takes a while, even on machines with 33 MIPS and 16 Mbytes :-) You can
  48 ignore the output.
  49
  50 But first you'll have to change a site dependency in fix.el: if
  51 texinfo 2.xx is installed by default at your site, comment out the two
  52 lines starting with "(setq load-path"; if it isn't, change the path!
  53 (I'm afraid that if you don't have texinfo 2.xx this won't work -- use
  54 archie to locate a version and ftp to fetch it.)
  55
  56 The files used by the conversion process are:
  57
  58 partparse.py            the dirty-written Python script that converts
  59                         LaTeX sources to texi files. Output is left in
  60                         `@out.texi'
  61
  62 texi{pre,post}.dat      these files will be put before and after the
  63                         result
  64
  65 fix.sh                  calls emacs in order to update all the nodes and
  66                         menus. After this, makeinfo will convert the
  67                         texinfo-source to the info-file(s). Assumption:
  68                         the texi-source is called `@out.texi'
  69
  70 fix.el                  the elisp-file executed by emacs. Two calls to
  71                         'texinfo-all-menus-update are necessary in
  72                         some cases
  73
  74 fix_hack                executable shell script that fixes the results
  75                         of the underscore hack. {\ptt \char'137} is
  76                         back-translated to a simple underscore. This is
  77                         needed for the texindex program
  78
  79 handy.el                some handy Emacs-macro's that helped converting
  80                         ``old'' documentation to a format that could be
  81                         understood by the converter scipt (partparse.py).
  82                         (You don't really need this, but, as the name
  83                         says, these macros are "handy")
  84
  85 A Million thanks for Jan-Hein B\"uhrman for writing and debugging the
  86 convertor and related scripts, and for fixing the LaTeX sources and
  87 writing new macros for myformat.sty!