INSTALL

Pre-installation Requirements
-----------------------------

In order to do an installation according to the instructions below, you
need to have Python installed.  You can get it from https://www.python.org/download/
if your system doesn't have it pre-installed.

The 'setup.py' python program which performs the installation also requires
one of the python packages 'Distribute'
(https://pypi.python.org/pypi/distribute/) or 'Setuptools'
(https://pypi.python.org/pypi/setuptools#installation-instructions).  In many
cases one of these are also pre-installed on your system, though.

Finally, on systems without a C compiler installed by default, you may also
need to install a pre-compiled binary for the 'lxml' library, if it's not
installed by default.  (You'll need to do this for Windows, for instance, while
for many versions of OS X it should already be included).  To find a
pre-compiled binary for your operating system, go to http://xmlsoft.org/ and
look for the appropriate link in the left-side menu-bar under 'Related links'.

Windows Pre-installation Requirements
------- ---------------- ------------

If you install python onto a windows system, there is a requirement that two additional
packages be installed at the same time.

'setup.py' requires the distribution package.  This is current accessible as 'ez_setup'
(https://pypi.python.org/pypi/ez_setup).

The 'lxml' library is required to be installed as a binary build.  This is currently 
accessible at https://pypi.python.org/pypi/lxml.  As of this time, the latest tested
package for Windows is 3.1.0.  Later versions are believed to work on other systems.

Although xml2rfc works with Python 3.3, it does not work with Python 3.2 and this is
the latest version of lxml that is available for install.  This means that for Windows,
Python 2.7 must be used. 

System Install
--------------

To install a system-wide version of xml2rfc, once you have the
pre-installation requirements in place, simply run::

   $ python setup.py install

User Install
------------

If you want to perform a local installation for a specific user, you have a
couple of options. You may use python's default location of user site-packages
by specifying the flag --user. These locations are::

   UNIX: $HOME/.local/lib/python<ver>/site-packages
   OSX: $HOME/Library/Python/<ver>/lib/python/site-packages
   Windows: %APPDATA%/Python/Python<ver>/site-packages

You can additionally combine the flag --install-scripts with --user to specify
a directory on your PATH to install the xml2rfc executable to. For example,
the following command::

   $ python setup.py install --user --install-scripts=$HOME/bin

will install the xml2rfc library and data to your local site-packages
directory, and an executable python script xml2rfc to $HOME/bin.

Note that if you do not specify --install-scripts, and the default location
(/usr/local/bin) has unsuitable privileges, the script will be placed in another
location chosen by the installation script.

Custom Install
--------------

The option --prefix allows you to specify the base path for all installation
files. The setup.py script will exit with an error if your PYTHONPATH is not
correctly configured to contain the library path the script tries to install
to.

The command is used as follows::

   $ python setup.py install --prefix=<path>

For further fine-tuning of the installation behavior, you can get a list of
all available options by running::

   $ python setup.py install --help