
#############################
Requirements and installation
#############################


============
Requirements
============

To use XIST you need the following software packages:

 1. Python 2.4,
 2. The Python XML package (at least version 0.8.4),
 3. ll-core (0.3 or newer),
 4. ll-url (0.15 or newer),
 5. ll-ansistyle (1.1 or newer),
 6. if you want to use automatic image size calculation: the Python
    Imaging Library,
 7. if you want to parse broken HTML: libxml2 (including its Python
    wrapper),
 8. if you want want to use the method asText to convert HTML to plain
    text: w3m,
 9. if you want to run the test suite: py.test,
10. and a C compiler supported by distutils, if you want to install the
    source distribution.


============
Installation
============

distutils is used for installation, so it's rather simple. Execute the
following command:

    python setup.py install


This will copy *.py files, compile *.c files and install everything in
the site-packages directory as the ll.xist package. distutils might
complain about a missing __init__.py, but you can ignore this: The main
package init file (for the ll package) is provided by ll-core.

If you're updating from a version older than 1.5, remove the old
package xist from your installation directory and remove the build
directory (if you're building from source).

If you're updating from a version older than 1.4, remove the old module
xist.url as this is no longer needed and might collide with the new
global module ll.url.

For Windows a binary distribution is provided. To install it, double
click it, and follow the instructions.

If you have difficulties installing this software, send a problem
report to Walter Dörwald (walter@livinglogic.de).


==================
Character encoding
==================

When you pass an 8bit string in the constructor of an XIST element,
these strings have to be converted to Unicode. XIST assumes that these
8bit strings are in the system default encoding, which normally is
ASCII. If you want to change this you can put a script named
sitecustomize.py somewhere in the Python path, with the following
content:

    import sys
    sys.setdefaultencoding("iso-8859-1")


(or any other encoding name that you want to use instead of
"iso-8859-1").

Starting with Python 2.3 you should instead define your source code
encoding in the first or second line of your script (see PEP 263) and
use Unicode string constants only.


============
Display hook
============

XIST provides several different display formats for XML trees (this is
extensible by implementing new presentation classes). Those display
formats are used in two ?pretty printing? modes. One is used for the
result of __repr__ calls and the other is used for output of XIST trees
in the interactive shell. To activate the interactive display, put
something like the following in your Python startup script:

    import ll
    from ll.xist import presenters

    ll.asdisplayhook(presenters.displayhook)


This hook uses the presenter object ll.xist.presenters.hookpresenter,
which you can modify or replace to customize the output of XIST trees.


===================
Syntax highlighting
===================

If you want syntax highlighting in your XIST tree dumps and have an
ANSI color capable terminal, set the environment variable XSC_REPRANSI
to 1 or 2 depending on whether you have a light or dark background
color. Setting XSC_REPRANSI to 0 turns off syntax highlighting.
