INSTALL

   1 Installation
   2 ============
   3
   4
   5 Prerequisites
   6 -------------
   7
   8 PyX needs Python 2.x and a TeX installation (including Type1 fonts). Try to
   9 start 'python', 'tex' and 'kpsewhich cmr10.pfb' (the later should issue a full
  10 path of the requested Type1 font).
  11
  12
  13 Local usage without C extension modules
  14 ---------------------------------------
  15
  16 PyX can be run without any installation. To test your environment copy the file
  17 hello.py from the examples directory to the main pyx directory (where the
  18 subdirectory pyx containing the modules is located) and type 'python hello.py'.
  19 When your TeX installation isn't configured to use Type1 fonts by default, you
  20 may have to insert the line 'text.set(fontmaps="psfonts.cmz")' after the import
  21 statement and try again. See the FAQ for further details about TeX and font
  22 configuration issues.
  23
  24
  25 Installation procedure
  26 ----------------------
  27
  28 The installation of PyX is pretty straightforward if you have installed the
  29 Python distutils package.
  30
  31 First, you have to decide which C extension modules you want to build. This can
  32 be done by setting the respective flags in the setup.cfg config file. By default
  33 no C extension modules are built and appropriate fallbacks will be used instead.
  34
  35 The build_t1strip option enables the t1strip extension module, which provides
  36 partial font downloading (i.e. only the glyphs of a font that are used are
  37 included in the eps file). The only requisites for building this module are the
  38 Python header files and a C compiler. Note that the C compiler has to suit
  39 the Python distribution you are using.
  40
  41 The second extension module pykpathsea provides Python binding for the kpathsea
  42 library, which enables fast searching for files in the TeX/LaTeX directory
  43 hierarchy. You will need the header files of this library, which are not
  44 included in many standard TeX distributions. Besides that, the fallback, which
  45 uses the kpsewhich program, works equally well, although it is not as efficient
  46 as using the library directly. If you want to build the C extension module, you
  47 may also have to specify the location of the kpathsea header files and of the
  48 library itself in the setup.cfg file.
  49
  50 After you have adapted the setup.cfg file to your needs, you can either build
  51 the extension modules locally by running
  52
  53     python setup.py build_ext -i
  54
  55 or install PyX system wide by using
  56
  57     python setup.py install
  58
  59 or an appropriate variant thereof.
  60
  61
  62 Path setup when installing to a non-standard directory layout
  63 -------------------------------------------------------------
  64
  65 PyX places shared data in the directory <install-dir>/share/pyx and the system
  66 wide configuration in the file <root>/etc/pyxrc. <install-dir> and <root> are
  67 options to the distutils install-data command (and thus the install command).
  68 See the distutils documentation for details. The final path information is
  69 stored in siteconfig.py. While the original siteconfig.py calculates the
  70 positions relative to its current position thus enabling local usage, during
  71 install a proper siteconfig.py will be created.
  72
  73
  74 Compiling the manual
  75 --------------------
  76
  77 For the layout of the manual we have made use of the standard Python
  78 documentation framework. For building the manual, you will need the script
  79 "mkhowto" of your Python distribution. Please make a soft-link of this script
  80 into the manual directory
  81
  82     cd manual/
  83     ln -s </usr/lib/>python/doc/tools/mkhowto mkhowto
  84     make
  85
  86 Note that this requires Python version 2.3 and above. In former versions you
  87 will need to get the Python documentation sources separately from
  88 http://www.python.org/ and try to find the script there. Alternatively you may
  89 download the manual from the PyX homepage at http://pyx.sourceforge.net/.