README for Narval version 1.1

$Date: 2002/02/27 17:45:41 $ $Revision: 1.13 $

DOWNLOADING
-----------

To run Narval, you need the following packages on your machine:

 * python 2.1 or above available from http://www.python.org/2.1.1/ The good old
   Python interpreter. 

 * PyXML 0.7 or above available from 
   http://sourceforge.net/projects/pyxml

 * 4Suite 0.12a1 or above available from http://www.4suite.org.
   4Suite is a DOM/XSL/XPATH implementation from Fourthought, Inc. 

 * PyGTK version 0.6 or above available from 
   http://www.daa.com.au/~james/pygtk/ and http://www.gtk.org/. 
   Python bindings for the GTK gui toolkit.

 * pyro version 2.1 or above available from
   http://sourceforge.net/projects/pyro
 or
   xmlrpc version 0.9.9 or above available from 
   http://www.pythonware.com/products/xmlrpc/
 (having both won't hurt. Most documentation assumes you are using pyro.)

 * xmltools version 1.3 or above available from http://www.logilab.org/xmltools

And of course, Narval itself, availalble from http://www.logilab.org/narval.

INSTALLING
----------

1. site-wide installation
-------------------------

Of course, you'll need to be root for this.

Untar the packages you downloaded in a directory using:

# tar xzf Narval-1.2a1.tar.gz

then

# cd Narval-1.2a1

Now use the setup.py script that's in the tools directory. In order to match
your local settings, you may want to edit the PREFIX variable in the "defines"
section at the top of the script.

# python setup.py install


2. user installation
--------------------

To use Narval without installing it for every user of your system, just untar
the packages you downloaded in a directory using:

$ tar xzf narval-1.2a1.tar.gz

You'll get a Narval-1.2a1 directory that you'll add to your PYTHONPATH environment
variable:

$ export PYTHONPATH=$PYTHONPATH:~/Narval-1.2a1

You also need to set up a configuration environment variable:
$ export NARVAL_SHARE=~/Narval-1.2a1/share

LAUNCHING
---------

0. Upgrading from previous versions
-----------------------------------

If you already had Narval installed on your machine, you should either manually
upgrade your NARVAL_HOME directories, or erase them and let Narval upgrade it
for you. If you chose to erase the NARVAL_HOME directories, you should backup
any custom modules, recipes and transformations, as well as the memory.xml file
if you have edited it to include your data in it.

To manually upgrade, just copy the files from the NARVAL_SHARE directory to 
your NARVAL_HOME, and overwrite existing files. This will upgrade the Narval 
standard library files that are available locally in your NARVAL_HOME.

Note this version includes a namespace for Narval and others DTD
changes, so you'll have to check for the new syntax and update your
own modules, transforms or recipe.

1. after site-wide installation
-------------------------------

If Narval was set up using setup.py or a RPM package, you should have three
executables somewhere in your path (probably /usr/bin), called 'narval',
'horn' and 'npm' which you can use to launch the applications.


2. after user installation
--------------------------

You must set the NARVAL_SHARE environment variable to point to the share 
subdirectory of the place where you unpacked Narval. For instance assuming it 
was in your home directory, you would use:

$ export NARVAL_SHARE=~/Narval-1.2a1/share 
with an sh-compatible shell, or:
$ setenv NARVAL_SHARE ~/Narval-1.2a1/share 
with a csh-compatible shell.

Then you can use 

$ python Narval-1.2a1/narval/Engine.py
or
$ python Narval-1.2a1/narval/Horn.py


USING
-----

1. quick start
--------------

To launch Narval with http connection and remote monitoring enabled, use the
'--pyro-port 8787' command line options. 

You will then be able to use the "Narval -> Connect" menu from Horn to connect
to Narval (using your hostname and 8787 as the port and pyro as the method). 
Play with the menus if you want, but don't lose too much of your time and...

Read the tutorial at http://www.logilab.org/narval/doc.html that describes how
to download, set up and start an existing application available from
ftp://ftp.logilab.org/pub/narval/applications...  

But be aware that you most probably won't get away without reading the fine
manuals :-).

2. going further
----------------

Read the tutorial first (see http://www.logilab.org/narval/doc.html). Really.

It describes what you can do with Narval, and shows how to build a recipe and
lauch it from Horn, step by step. After that, reading the user manual will
provide useful information. Feel free to subscribe to our mailing lists
(http://www.logilab.org/narval/dev.html#ml) and questions there, we shall be
glad to answer them.


          Have Fun

          The Logilab Team
