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 [pʏks]. Please do
  17 not pronounce it as [pʏx] or [pʏç].
  18
  19 .. _where_do_I_get_PyX:
  20
  21 Where do I get the latest version of PyX?
  22 =========================================
  23
  24 The current release of PyX (as well as older ones) is freely available from
  25 `http://pyx.sourceforge.net <http://pyx.sourceforge.net>`_ where also a
  26 subversion repository with the latest patches can be found. In addition, PyX is
  27 registered on the Python Package Index at
  28 `https://pypi.python.org/pypi/PyX <https://pypi.python.org/pypi/PyX>`_ and can
  29 be installed by ``easy_install`` and ``pip``. As PyX is hosted on PyPI, it can
  30 be directly downloaded and installed by ``pip``. Please see the
  31 `pip documentation <http://www.pip-installer.org/>`_ for details.
  32
  33 Possibly older versions of PyX are also available as package for various Linux
  34 distributions: see, for instance,
  35 `http://packages.debian.org/testing/python-pyx <http://packages.debian.org/testing/python-pyx>`_
  36 for information on the PyX package in Debian GNU/Linux or
  37 `http://packages.ubuntu.com/raring/python-pyx <http://packages.ubuntu.com/raring/python-pyx>`_
  38 for Ubuntu.
  39
  40 PyX has no dependencies on other Python packages.
  41
  42 How can I determine the version of PyX running on my machine?
  43 =============================================================
  44
  45 Start a python session (usually by typing ``python`` at the system prompt) and
  46 then type the following two commands (``>>>`` is the python prompt)
  47
  48 >>> import pyx
  49 >>> pyx.__version__
  50
  51 Note that there are two underscores before and after ``version``.
  52
  53 How can I access older versions of PyX?
  54 =======================================
  55
  56 There are reasons which might make it necessary to use older versions of PyX.
  57 If you are using Python 2 you will need PyX version 0.12.1 or earlier (see
  58 :ref:`python_requirements`). Furthermore, as at present it is not guaranteed
  59 that PyX is backward compatible, it may be desirable to access an older version
  60 of PyX instead of adapting older code to a more recent version of PyX. In order
  61 to do that, one needs the corresponding PyX package (see
  62 :ref:`where_do_I_get_PyX` if you need to download it), which should be unpacked
  63 below a directory, e.g.  ``/home/xyz/Python``,  where you want to keep the
  64 various PyX versions.  This will result in a subdirectory with a name like
  65 ``PyX-0.14`` which contains the contents of the corresponding package. You
  66 can then ask Python to first look in the appropriate directory before looking
  67 for the current version of PyX by inserting the following code (appropriately
  68 modified according to your needs) at the beginning of your program before
  69 importing the PyX module::
  70
  71    import sys
  72    sys.path.insert(0, "/home/xyz/Python/PyX-0.14")
  73
  74 Including appropriate lines even if the current version of PyX is used, might
  75 turn out to be helpful when the current version has become an old version
  76 (unless you have no difficulties determining the PyX version by looking at your
  77 code).
  78
  79 If your operating system supports path expansion, you might use as an
  80 alternative::
  81
  82    import sys, os
  83    sys.path.insert(0, os.path.expanduser("~/Python/PyX-0.14"))
  84
  85 which will expand the tilde to your home directory.
  86
  87 Does PyX run under my favorite operating system?
  88 ================================================
  89
  90 Yes, if you have installed Python (:ref:`what_is_python`) and TeX
  91 (:ref:`what_is_tex`). Both are available for a large variety of operating
  92 systems so chances are pretty good that you will get PyX to work on your
  93 system.
  94
  95 .. _python_requirements:
  96
  97 Under which versions of Python will PyX run?
  98 ============================================
  99
 100 Starting with version 0.13, PyX requires Python 3.2 or higher. If you still
 101 need to run PyX with Python 2, you should use version 0.12.1 which is designed
 102 to run with Python 2.3 up to 2.7.
 103
 104 The version of your Python interpreter can be determined by calling it with the
 105 option ``-V``. Alternatively, you can simply start the interpreter and take a
 106 look at the startup message. Note that there may be different versions of
 107 Python installed on your system at the same time. The default Python version
 108 need not be the same for all users.
 109
 110 Does PyX provide a GUI to view the produced image?
 111 ==================================================
 112
 113 No, PyX itself does not provide a means to view the produced image. The result
 114 of a PyX run is an EPS (= Encapsulated PostScript) file, a PS (= PostScript)
 115 file, a PDF (= Portable Document Format) file or a SVG (= Scalable Vector
 116 Graphics) file, which can be viewed, printed or imported into other
 117 applications.
 118
 119 There are several means of viewing PS and EPS files. A common way would be to
 120 use ``ghostview`` which provides a user interface to the PostScript interpreter
 121 ``ghostscript``. More information about this software, which is available for a
 122 variety of platforms, can be found at `http://www.cs.wisc.edu/~ghost/
 123 <http://www.cs.wisc.edu/~ghost/>`_.  If you do not own a printer which is
 124 capable of printing PostScript files directly, ``ghostscript`` may also be
 125 useful to translate PS and EPS files produced by PyX into something your
 126 printer will understand.
 127
 128 PDF files can be viewed by means of the ``Adobe Reader ®`` available from
 129 `http://www.adobe.com/products/acrobat/readstep2.html
 130 <http://www.adobe.com/products/acrobat/readstep2.html>`_. On systems running
 131 X11, ``xpdf`` might be an alternative. It is available from
 132 `http://www.foolabs.com/xpdf/ <http://www.foolabs.com/xpdf/>`_.
 133
 134 SVG files can be viewed by webbrowsers like Firefox available at
 135 `https://www.mozilla.org/en-US/firefox
 136 <https://www.mozilla.org/en-US/firefox>`_ or Chrome available at
 137 `https://www.google.com/chrome/ <https://www.google.com/chrome/>`_.
 138
 139 If you want to do interactive development of a PyX graphics, you might consider
 140 to use an IPython notebook (see :ref:`pyx_ipython_notebook`).
 141
 142 .. _pyx_ipython_notebook:
 143
 144 Will I be able to embed PyX graphics output into an IPython notebook?
 145 =====================================================================
 146
 147 Yes, PyX canvas object and objects inheriting from the canvas class, in particular
 148 graphs and text, can be embedded into an IPython notebook. Suppose you have a
 149 canvas object called ``c`` on which you have done some drawing. Then entering ``c``
 150 in an IPython notebook cell and executing that cell will automatically produce
 151 a SVG representation and embed it into the notebook. (Alternatively, also PNG
 152 is available by means of ghostscript, but the default display_order of IPython
 153 prefers SVG over PNG.) For more information on IPython and working with its
 154 notebooks see `http://www.ipython.org/ <http://www.ipython.org/>`_.
 155
 156 I am a Gnuplot user and want to try PyX. Where can I get some help?
 157 ===================================================================
 158
 159 There exists a tutorial by Titus Winters which explains how to perform standard
 160 Gnuplot tasks with \PyX. The tutorial can be found at
 161 `http://www.cs.ucr.edu/~titus/pyxTutorial/
 162 <http://www.cs.ucr.edu/~titus/pyxTutorial/>`_.
 163
 164 Where can I get help if my question is not answered in this FAQ?
 165 ================================================================
 166
 167 The PyX sources contain a reference manual which is also available online at
 168 `http://pyx.sourceforge.net/manual/ <http://pyx.sourceforge.net/manual/>`_.
 169 Furthermore, there exists a set of examples demonstrating various features of
 170 PyX, which is available in the sources or can be browsed at
 171 `http://pyx.sourceforge.net/examples.html
 172 <http://pyx.sourceforge.net/examples.html>`_.  If the feature you are looking
 173 for is among them, using the appropriate part of the example code or adapting
 174 it for your purposes may help.
 175
 176 There is also a user discussion list about PyX which you can subscribe to at
 177 `http://lists.sourceforge.net/lists/listinfo/pyx-user
 178 <http://lists.sourceforge.net/lists/listinfo/pyx-user>`_.  The archive of the
 179 discussion list is available at
 180 `http://sourceforge.net/mailarchive/forum.php?forum_name=pyx-user
 181 <http://sourceforge.net/mailarchive/forum.php?forum_name=pyx-user>`_.
 182
 183 Finally, it might be worth checking `http://pyx.sourceforge.net/pyxfaq.pdf
 184 <http://pyx.sourceforge.net/pyxfaq.pdf>`_ for an updated version of this FAQ.
 185
 186 .. [#texbook] D.Knuth, *The TeX book* (Addison-Wesley, 1984)