faq/general_aspects_pyx.rst

   1 ======================
   2 General aspects of PyX
   3 ======================
   4
   5 The name of the game
   6 ====================
   7
   8 Originally, the name PyX was constructed as a combination of **P**\ ostscript,
   9 i.e. the first output format supported by PyX, P\ **y**\ thon, i.e. the language
  10 in which PyX is written, and Te\ **X**, i.e. the program which PyX uses for
  11 typesetting purposes.  Actually, the title of this question is a tribute to TeX
  12 because it is taken from the first chapter of the TeX book [#texbook]_ where
  13 the origin of the name TeX and its pronunciation are explained.
  14
  15 Despite the ties between TeX and PyX, their pronunciation is quite different.
  16 According to the developers of PyX, it should be pronounced as pyks. Please do
  17 not pronounce it as pyx or pyç.
  18
  19 .. todo::
  20
  21    Replace y in IPA by the correct sign (U+028F).
  22
  23 .. _where_do_I_get_PyX:
  24
  25 Where do I get the latest version of PyX?
  26 =========================================
  27
  28 The current release of PyX (as well as older ones) is freely available from
  29 `pyx.sourceforge.net <http://pyx.sourceforge.net>`_ where also a
  30 subversion repository with the latest patches can be found. Possibly older
  31 versions of PyX are also available as package for various Linux distributions:
  32 see, for instance,  `http://packages.debian.org/testing/python/python-pyx.html
  33 <http://packages.debian.org/testing/python/python-pyx.html>`_ for information
  34 on the \PyX package in Debian GNU/Linux,
  35 `http://packages.gentoo.org/ebuilds/?pyx-0.7.1
  36 <http://packages.gentoo.org/ebuilds/?pyx-0.7.1>`_ for a Gentoo Linux ebuild,
  37 and `http://www.novell.com/products/linuxpackages/professional/python-pyx.html
  38 <http://www.novell.com/products/linuxpackages/professional/python-pyx.html>`_
  39 for the PyX package in the SUSE LINUX professional distribution.
  40
  41 How can I determine the version of PyX running on my machine?
  42 =============================================================
  43
  44 Start a python session (usually by typing ``python`` at the system prompt) and
  45 then type the following two commands (``>>>`` is the python prompt)
  46
  47 >>> import pyx
  48 >>> pyx.__version__
  49
  50 Note that there are two underscores before and after ``version``.
  51
  52 How can I access older versions of PyX?
  53 =======================================
  54
  55 As at present it is not guaranteed that PyX is backward compatible, it may be
  56 desirable to access an older version of PyX instead of adapting older code to
  57 the current version of PyX. In order to do that, one needs the corresponding
  58 PyX package (see :ref:`where_do_I_get_PyX` if you need to download it), which
  59 should be unpacked below a directory, e.g.  ``/home/xyz/Python``,  where you
  60 want to keep the various PyX versions.  This will result in a subdirectory with
  61 a name like ``PyX-0.11.1`` which contains the contents of the corresponding
  62 package. You can then ask Python to first look in the appropriate directory
  63 before looking for the current version of PyX by inserting the following code
  64 (appropriately modified according to your needs) at the beginning of your
  65 program before importing the PyX module::
  66
  67    import sys
  68    sys.path.insert(0, "/home/xyz/Python/PyX-0.11.1")
  69
  70 Including appropriate lines even if the current version of PyX is used, might
  71 turn out to be helpful when the current version has become an old version
  72 (unless you have no difficulties determining the PyX version by looking at your
  73 code).
  74
  75 If your operating system supports path expansion, you might use as an
  76 alternative::
  77
  78    import sys, os
  79    sys.path.insert(0, os.path.expanduser("~/Python/PyX-0.11.1"))
  80
  81 which will expand the tilde to your home directory.
  82
  83 Does PyX run under my favorite operating system?
  84 ================================================
  85
  86 Yes, if you have installed Python :ref:`what_is_python`) and TeX
  87 (:ref:`what_is_tex`). Both are available for a large variety of operating
  88 systems so chances are pretty good that you will get PyX to work on your
  89 system.
  90
  91 Under which versions of Python will PyX run?
  92 ============================================
  93
  94 PyX is supposed to work with Python 2.1 and above. However, most of the
  95 development takes place under the current production version of Python (2.4.1
  96 by the time of this writing) and thus PyX is better tested with this version.
  97 On the other hand, the examples and tests are verified to run with Python 2.1
  98 and above using the latest bugfix releases. PyX will not work with earlier
  99 Python versions due to missing language features.
 100
 101 The version of your Python interpreter can be determined by calling it with the
 102 option ``-V``. Alternatively, you can simply start the interpreter and take a
 103 look at the startup message. Note that there may be different versions of
 104 Python installed on your system at the same time. The default Python version
 105 need not be the same for all users.
 106
 107 Does PyX provide a GUI to view the produced image?
 108 ==================================================
 109
 110 No, PyX itself does not provide a means to view the produced image. The result
 111 of a PyX run is an EPS (= Encapsulated PostScript) file, a PS (= PostScript)
 112 file or a PDF (= Portable Document Format) file, which can be viewed, printed
 113 or imported into other applications.
 114
 115 There are several means of viewing PS and EPS files. A common way would be to
 116 use ``ghostview`` which provides a user interface to the PostScript interpreter
 117 ``ghostscript``. More information about this software, which is available for a
 118 variety of platforms, can be found at `http://www.cs.wisc.edu/~ghost/
 119 <http://www.cs.wisc.edu/~ghost/>`_.  If you do not own a printer which is
 120 capable of printing PostScript files directly, ``ghostscript`` may also be
 121 useful to translate PS and EPS files produced by PyX into something your
 122 printer will understand.
 123
 124 PDF files can be viewed by means of the ``Adobe Reader ®`` available from
 125 `http://www.adobe.com/products/acrobat/readstep2.html
 126 <http://www.adobe.com/products/acrobat/readstep2.html>`_. On systems running
 127 X11, ``xpdf`` might be an alternative. It is available from
 128 `http://www.foolabs.com/xpdf/ <http://www.foolabs.com/xpdf/>`_.
 129
 130 I am a Gnuplot user and want to try PyX. Where can I get some help?
 131 ===================================================================
 132
 133 There exists a tutorial by Titus Winters which explains how to perform standard
 134 Gnuplot tasks with \PyX. The tutorial can be found at
 135 `http://www.cs.ucr.edu/~titus/pyxTutorial/
 136 <http://www.cs.ucr.edu/~titus/pyxTutorial/>`_.
 137
 138 Where can I get help if my question is not answered in this FAQ?
 139 ================================================================
 140
 141 The PyX sources contain a reference manual which is also available online at
 142 `http://pyx.sourceforge.net/manual/ <http://pyx.sourceforge.net/manual/>`_.
 143 Furthermore, there exists a set of examples demonstrating various features of
 144 PyX, which is available in the sources or can be browsed at
 145 `http://pyx.sourceforge.net/examples.html
 146 <http://pyx.sourceforge.net/examples.html>`_.  If the feature you are looking
 147 for is among them, using the appropriate part of the example code or adapting
 148 it for your purposes may help.
 149
 150 There is also a user discussion list about PyX which you can subscribe to at
 151 `http://lists.sourceforge.net/lists/listinfo/pyx-user
 152 <http://lists.sourceforge.net/lists/listinfo/pyx-user>`_.  The archive of the
 153 discussion list is available at
 154 `http://sourceforge.net/mailarchive/forum.php?forum_name=pyx-user
 155 <http://sourceforge.net/mailarchive/forum.php?forum_name=pyx-user>`_.
 156
 157 Finally, it might be worth checking `http://pyx.sourceforge.net/pyxfaq.pdf
 158 <http://pyx.sourceforge.net/pyxfaq.pdf>`_ for an updated version of this FAQ.
 159
 160 .. [#texbook] D.Knuth, *The TeX book* (Addison-Wesley, 1984)