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*.tex               The library reference
  11         ref.tex, ref[1-8].tex           The reference manual
  12         ext.tex                         How to extend Python
  13         qua.tex, quabib.bib             Article published in CWI Quarterly
  14
  15 All except qua.tex (which isn't built by the default target) use the
  16 style option file "myformat.sty".  This contains some macro
  17 definitions and sets some style parameters.
  18
  19 The style parameters are set up for European paper size (21 x 29.7 cm,
  20 a.k.a. A4, or roughly 8.27 x 11.7 inch) by default.  To use US paper,
  21 comment out the line saying \input{a4wide.sty} in myformat.sty (you
  22 may want to fiddle with lay-out parameters like \textwidth and
  23 \textheight, since the default format uses rather wide margins).
  24
  25 You need the makeindex utility to produce the index for ref.tex
  26 lib.tex; you need bibtex to produce the references list for qua.tex.
  27
  28 There's a Makefile to call latex and the other utilities in the right
  29 order and the right number of times.  This will produce dvi files for
  30 each document made; to preview them, use xdvi.  Printing depends on
  31 local conventions; at my site, I use dvips and lpr.  For example:
  32
  33         make ref                        # creates ref.dvi
  34         xdvi ref                        # preview it
  35         dvips -Ppsc ref | lpr -Ppsc     # print it on printer "psc".
  36
  37 If you don't have latex, you can ftp the pre-formatted PosytScript
  38 versions of the documents.  It should be in the same place where you
  39 fetched the main Python distribution, if you got it by ftp.  (See
  40 "../Misc/FAQ" for information about ftp-ing Python files.)
  41
  42
  43 Making the INFO version of the Library Reference
  44 ------------------------------------------------
  45
  46 The Library Reference can now also be read in hypertext form using the
  47 Emacs INFO system.  This uses Texinfo format as an intermediate step.
  48 It requires texinfo version 2 (we have used 2.14).
  49
  50 To build the info files (python-lib.info*), say "make libinfo".  This
  51 takes a while, even on machines with 33 MIPS and 16 Mbytes :-) You can
  52 ignore the output.
  53
  54 But first you'll have to change a site dependency in fix.el: if
  55 texinfo 2.xx isn't installed by default at your site, you'll have to
  56 install it (use archie to locate a version and ftp to fetch it).  If
  57 you can't install it in the standard Emacs load path, uncomment the
  58 line containing a "(setq load-path ...)" statement, and fill in the
  59 path where you put it.
  60
  61 The files used by the conversion process are:
  62
  63 partparse.py            Python script that converts LaTeX sources to
  64                         texi files.
  65
  66 texi{pre,post}.dat      Files placed before and after the result.
  67
  68 fix.el                  Elisp file executed by Emacs. Two calls to
  69                         'texinfo-all-menus-update are necessary in
  70                         some cases.
  71
  72 fix_hack                Shell script to fix the results of the
  73                         "underscore hack". {\ptt \char'137} is
  74                         back-translated to a simple underscore.  This
  75                         is needed for the texindex program.
  76
  77 whichlibs               Shell script to print a list of lib*.tex files
  78                         to be processed.
  79
  80 A Million thanks for Jan-Hein B\"uhrman for writing and debugging the
  81 convertor and related scripts, and for fixing the LaTeX sources and
  82 writing new macros for myformat.sty!