summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/ivy-perl-1.html116
-rw-r--r--doc/ivy-perl-2.html44
-rw-r--r--doc/ivy-perl-3.html111
-rw-r--r--doc/ivy-perl-4.html28
-rw-r--r--doc/ivy-perl-5.html23
-rw-r--r--doc/ivy-perl-6.html35
-rw-r--r--doc/ivy-perl-7.html25
-rw-r--r--doc/ivy-perl.html66
-rw-r--r--doc/ivy-perl.sgml377
9 files changed, 377 insertions, 448 deletions
diff --git a/doc/ivy-perl-1.html b/doc/ivy-perl-1.html
deleted file mode 100644
index b6b2c92..0000000
--- a/doc/ivy-perl-1.html
+++ /dev/null
@@ -1,116 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
- <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.7">
- <TITLE>The Ivy Perl library guide: General information</TITLE>
- <LINK HREF="ivy-perl-2.html" REL=next>
-
- <LINK HREF="ivy-perl.html#toc1" REL=contents>
-</HEAD>
-<BODY>
-<A HREF="ivy-perl-2.html">Next</A>
-Previous
-<A HREF="ivy-perl.html#toc1">Contents</A>
-<HR>
-<H2><A NAME="s1">1. General information</A></H2>
-
-<H2><A NAME="ss1.1">1.1 What is Ivy?</A>
-</H2>
-
-<P>
-<P>Ivy is a software bus designed at CENA (France). A software bus is a system
-that allows software applications to exchange information with the illusion of
-broadcasting that information, selection being performed by the receiving
-applications. Using a software bus is very similar to dealing with events in a
-graphical toolkit: on one side, messages are emitted without caring about who
-will handle them, and on the other side, one decide to handle the messages that
-have a certain type or follow a certain pattern. Software buses are mainly aimed
-at facilitating the rapid development of new agents, and at managing a dynamic
-collection of agents on the bus: agents show up, emit messages and receive some,
-then leave the bus without blocking the others.
-<P>
-<H3>Architecture and principles</H3>
-
-<P>As opposed to other software buses, Ivy does not depend on a centralised
-server. Actually, Ivy is mostly a communication convention between processes,
-implemented through a collection of libraries in several languages.
-<P>
-<P>
-<P>From the programmer's point of view, Ivy is an information broadcasting
-channel. The main functions are:
-<P>
-<UL>
-<LI> connecting to a bus.<EM> Example: Ivy::start (-loopMode =>
- 'local', -ivyBus => '2011', -appName => "toto" );</EM></LI>
-<LI> sending a message.<EM> Example: Ivy::sendMsgs ("HELLO WORLD")</EM></LI>
-<LI> bind a message pattern to a callback function.<EM> Example:
- Ivy::bindRegexp ("^HELLO (.*)", [\&cb])</EM></LI>
-<LI> the main loop.<EM> MainLoop</EM></LI>
-</UL>
-<P>Ivy's
-decentralised connection scheme probably incurs limitations in terms of how many
-applications can be connected to an Ivy bus, but this simplifies management a
-lot. Basically, an Ivy bus is just a set of applications that decide to
-communicate together. The only conventions between these applications are:
-<OL>
-<LI> the use of the Ivy protocol (for obvious reasons)</LI>
-<LI> a bus address, made of a broadcast port number (a bit like a citizen band
-channel) and a set of networks addresses</LI>
-</OL>
-
-When an application wants to connect to a bus, it sends a broadcast message on the
-networks specified in the bus address, so that all applications present on those
-networks and listening on the specified port number connect to it. It then
-becomes part of the bus, and listens like the other ones.
-<P>The messages are exchanged in text format, and bindings are based on regular
-expressions with captures. If an application subscribes to
-<CODE>HELLO (.*)</CODE> and if another application emits the message <CODE>HELLO WORLD</CODE>, a
-callback will be called in the first application with <CODE>WORLD</CODE> as an argument.
-<P>
-<P>
-<H3>Using Ivy</H3>
-
-<P>You can use Ivy through applications that have been provided to you. This is the
-case for <CODE>ivyprobe</CODE>, an Ivy agent that allows you to examine the messages
-exchanged on a given bus and to send messages on that bus. You can refer to the
-web site <CODE>http:</CODE> for a list of available agents. However, what you will
-usually want to do is to develop your own applications. In order to do that you
-can use an Ivy connection kit, that is a library that implements Ivy.
-<P>
-<P>
-<P>Libraries that implement Ivy are available in the following environments:
-<UL>
-<LI> in C on Unix and Windows platforms, with its own communication library</LI>
-<LI> in C++ on Windows platforms</LI>
-<LI> in C++ on Unix platforms, integrated with the Uch communication library</LI>
-<LI> in C++ on Unix platforms, integrated with OpenInventor</LI>
-<LI> in C++ on Macintosh</LI>
-<LI> in Perl and in Perl/Tk</LI>
-<LI> integrated with Object Caml on Unix platforms</LI>
-<LI> in Scheme on Unix platforms</LI>
-<LI> in Java</LI>
-</UL>
-<P>
-<P>Connecting your application to an Ivy bus just consists in choosing the
-appropriate library, add the appropriate message emission and reception calls to
-your code, use the main loop provided in the library or make the necessary
-integrations, and get your code running!
-<P>
-<H2><A NAME="ss1.2">1.2 The Ivy Perl library</A>
-</H2>
-
-<P>The Ivy Perl library (aka Ivy-Perl or ivy-perl) is a Perl library that allows you to connect
-applications to an Ivy bus. You can use it to write applications in Perl or any
-other language that supports Perl extensions (Perl/Tk for instance). This guide documents how you can do
-that.
-<P>The Ivy Perl library is known to compile and work in WindowsNT and Linux
-environments. It should be easy to use on most Posix environments.
-<P>The Ivy Perl library was originally developed by Alexandre Bustico at CENA. It
-is maintained by the CENA-Toulouse team.
-<P>
-<HR>
-<A HREF="ivy-perl-2.html">Next</A>
-Previous
-<A HREF="ivy-perl.html#toc1">Contents</A>
-</BODY>
-</HTML>
diff --git a/doc/ivy-perl-2.html b/doc/ivy-perl-2.html
deleted file mode 100644
index 50b58ff..0000000
--- a/doc/ivy-perl-2.html
+++ /dev/null
@@ -1,44 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
- <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.7">
- <TITLE>The Ivy C library guide: Getting and installing the Ivy Perl library</TITLE>
- <LINK HREF="ivy-perl-3.html" REL=next>
- <LINK HREF="ivy-perl-1.html" REL=previous>
- <LINK HREF="ivy-perl.html#toc2" REL=contents>
-</HEAD>
-<BODY>
-<A HREF="ivy-perl-3.html">Next</A>
-<A HREF="ivy-perl-1.html">Previous</A>
-<A HREF="ivy-perl.html#toc2">Contents</A>
-<HR>
-<H2><A NAME="s2">2. Getting and installing the Ivy Perl library</A></H2>
-
-<P>You can get the latest versions of the Ivy Perl library from CENA (http://XXX) or
-from one of the Fairway sites (for instance http://XXX). Depending whether you
-use a supported distribution of Linux or not, you have the following options:
-<P>
-<H2><A NAME="ss2.1">2.1 Installing RedHat or Debian packages</A>
-</H2>
-<p>If your system is Linux/Redhat, you have to use the command <em><strong> rpm -i package-name</strong></em>.
-<p>If your system is Linux/Debian, you have to use the command <em><strong> dpkg -i package-name</strong></em>.
-
-
-<P>
-<P>
-<H2><A NAME="ss2.2">2.2 Getting and installing the sources</A>
-</H2>
-<p>If your system is not a Linux one, you have to get and install the source of ivy-perl.
-In this case, you have to get the source from CENA at http://XXX or from one of the Fairway sites.
-
-
-<P>
-<P>
-<P>
-<P>
-<HR>
-<A HREF="ivy-perl-3.html">Next</A>
-<A HREF="ivy-perl-1.html">Previous</A>
-<A HREF="ivy-perl.html#toc2">Contents</A>
-</BODY>
-</HTML>
diff --git a/doc/ivy-perl-3.html b/doc/ivy-perl-3.html
deleted file mode 100644
index bee7734..0000000
--- a/doc/ivy-perl-3.html
+++ /dev/null
@@ -1,111 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
- <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.7">
- <TITLE>The Ivy C library guide: Basic functions</TITLE>
- <LINK HREF="ivy-perl-4.html" REL=next>
- <LINK HREF="ivy-perl-2.html" REL=previous>
- <LINK HREF="ivy-perl.html#toc3" REL=contents>
-</HEAD>
-<BODY>
-<A HREF="ivy-perl-4.html">Next</A>
-<A HREF="ivy-perl-2.html">Previous</A>
-<A HREF="ivy-perl.html#toc3">Contents</A>
-<HR>
-<H2><A NAME="s3">3. Basic functions</A></H2>
-
-<H2><A NAME="ss3.1">3.1 Initialization and main loop</A>
-</H2>
-
-<P>Initializing an Ivy agent with the Ivy-Perl library is done by calling function <CODE>Ivy::start</CODE>. In theory, initialization is then over. However in
-practice, as for any asynchronous communication or interaction library, nothing
-happens until your application has reached the main loop.
-<P>The Ivy Perl library provides two kind of main loop: a "local" loop
- for perl code, and a "Tk" loop for perl-tk code.
-<P>Here is more details on <CODE>Ivy::start</CODE> function:
-<P>
-<BLOCKQUOTE><CODE>
-<PRE>
- Ivy::start(-loopMode => 'TK',
- -ivyBus => '2011',
- -appName => "TOTO",
- -neededApp => "TITI",
- -statusFunc => \&statusScan);
-
-</PRE>
-</CODE></BLOCKQUOTE>
-
-initializes and connects your application to the bus specified in <CODE>ivyBus</CODE>. The string provided
-should follow the convention described in section XX. Example: <CODE>"127:2010"</CODE>..
-<P>
-
-<BLOCKQUOTE><CODE>
-<PRE>
-MainLoop;
-</PRE>
-</CODE></BLOCKQUOTE>
-
-makes your application enter the main loop in which it will handle asynchronous
-communications and signals.
-<P>
-<BLOCKQUOTE><CODE>
-<PRE>
-Ivy::stop ();
-</PRE>
-</CODE></BLOCKQUOTE>
-
-makes your application exit the main loop.
-<P>
-<P>
-<H2><A NAME="ss3.2">3.2 Emitting messages</A>
-</H2>
-
-<P>Emitting a message on an Ivy bus is much like printing a message on the standard
-output. However, do not forget that your message will not be emitted if Ivy has
-not been properly initialized and if you do not have a main loop of some sort
-running. To emit a message, use <CODE>IvySendMsg</CODE>, which works like <CODE>printf</CODE>:
-<P>
-<BLOCKQUOTE><CODE>
-<PRE>
-Ivy::sendMsg ("...");
-</PRE>
-</CODE></BLOCKQUOTE>
-
-sends a message on the bus.
-<P>
-<P>
-<H2><A NAME="ss3.3">3.3 Subscribing to messages</A>
-</H2>
-
-<P>Subscribing to messages consists in binding a callback function to a message
-pattern. Patterns are described by regular expressions with captures. When a
-message matching the regular expression is detected on the bus, the callback
-function is called. The captures (ie the bits of the message that match the
-parts of regular expression delimited by brackets) are passed to the callback
-function much like options are passed to <CODE>main</CODE>. Use function <CODE>Ivy::bindRegexp</CODE>
-to bind a callback to a pattern.
-<BLOCKQUOTE><CODE>
-<PRE>
-Ivy::bindRegexp ("^HELLO WORLD", [\&Start]);
-</PRE>
-</CODE></BLOCKQUOTE>
-
-binds callback function <CODE>Start</CODE> to the regular expression specified by
-<CODE>regex_format</CODE>.
-<P>
-<BLOCKQUOTE><CODE>
-<PRE>
-Ivy::bindRegexp ("^HELLO WORLD", NULL);
-</PRE>
-</CODE></BLOCKQUOTE>
-
-deletes the binding.
-<P>
-<P>
-<P>
-<HR>
-<A HREF="ivy-perl-4.html">Next</A>
-<A HREF="ivy-perl-2.html">Previous</A>
-<A HREF="ivy-perl.html#toc3">Contents</A>
-</BODY>
-</HTML>
diff --git a/doc/ivy-perl-4.html b/doc/ivy-perl-4.html
deleted file mode 100644
index 88719cc..0000000
--- a/doc/ivy-perl-4.html
+++ /dev/null
@@ -1,28 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
- <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.7">
- <TITLE>The Ivy C library guide: Advanced functions</TITLE>
- <LINK HREF="ivy-perl-5.html" REL=next>
- <LINK HREF="ivy-perl-3.html" REL=previous>
- <LINK HREF="ivy-perl.html#toc4" REL=contents>
-</HEAD>
-<BODY>
-<A HREF="ivy-perl-5.html">Next</A>
-<A HREF="ivy-perl-3.html">Previous</A>
-<A HREF="ivy-perl.html#toc4">Contents</A>
-<HR>
-<H2><A NAME="s4">4. Advanced functions</A></H2>
-
-<H2><A NAME="ss4.1">4.1 Utilities</A>
-</H2>
-
-<H2><A NAME="ss4.2">4.2 Direct messages</A>
-</H2>
-
-<HR>
-<A HREF="ivy-perl-5.html">Next</A>
-<A HREF="ivy-perl-3.html">Previous</A>
-<A HREF="ivy-perl.html#toc4">Contents</A>
-</BODY>
-</HTML>
diff --git a/doc/ivy-perl-5.html b/doc/ivy-perl-5.html
deleted file mode 100644
index 96276ea..0000000
--- a/doc/ivy-perl-5.html
+++ /dev/null
@@ -1,23 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
- <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.7">
- <TITLE>The Ivy C library guide: Managing timers and other channels</TITLE>
- <LINK HREF="ivy-perl-6.html" REL=next>
- <LINK HREF="ivy-perl-4.html" REL=previous>
- <LINK HREF="ivy-perl.html#toc5" REL=contents>
-</HEAD>
-<BODY>
-<A HREF="ivy-perl-6.html">Next</A>
-<A HREF="ivy-perl-4.html">Previous</A>
-<A HREF="ivy-perl.html#toc5">Contents</A>
-<HR>
-<H2><A NAME="s5">5. Managing timers and other channels</A></H2>
-
-<P>
-<HR>
-<A HREF="ivy-perl-6.html">Next</A>
-<A HREF="ivy-perl-4.html">Previous</A>
-<A HREF="ivy-perl.html#toc5">Contents</A>
-</BODY>
-</HTML>
diff --git a/doc/ivy-perl-6.html b/doc/ivy-perl-6.html
deleted file mode 100644
index 9d31b44..0000000
--- a/doc/ivy-perl-6.html
+++ /dev/null
@@ -1,35 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
- <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.7">
- <TITLE>The Ivy C library guide: Conventions for writing applications</TITLE>
- <LINK HREF="ivy-perl-7.html" REL=next>
- <LINK HREF="ivy-perl-5.html" REL=previous>
- <LINK HREF="ivy-perl.html#toc6" REL=contents>
-</HEAD>
-<BODY>
-<A HREF="ivy-perl-7.html">Next</A>
-<A HREF="ivy-perl-5.html">Previous</A>
-<A HREF="ivy-perl.html#toc6">Contents</A>
-<HR>
-<H2><A NAME="s6">6. Conventions for writing applications</A></H2>
-<H3>6.1 Default bus</H3>
-By default, the bus used is <em><strong>127.255.255.255:2010 </em></strong> ie the application will be connected on the port 2010 of the local machine it runs on.</p>
-<P>You can set the bus to be used by setting the environment variable <CODE>IVYBUS</CODE> or by implementing the option <CODE>-b</CODE> in the application.</P>
-<P>
-<H3>6.2 Syntax of messages</h3>
-The syntax of the messages exchanged is totally free. However, the following convention is recommended:
-<menu>
-<li>The message syntax is <CODE>Subject Attributes</CODE></li>
-<li>A Subject is an object, named in a hierarchical form: <CODE>ObjectClass1:object1.ObjectClass2:object2...</CODE></li>
-<li>Attributes are pairs <CODE>(attribute-name, value)</CODE></li>
-</menu>
-Example:
-<p><CODE>AIRCRAFT:LIB720 Moved lat=46.1697 lon=2.0844 vx=-36 vy=-463 afl=330 rate=0 heading=184 ground_speed=465
-mach_speed=0 tendance=0 time=24600 cfl=330</CODE>
-<HR>
-<A HREF="ivy-perl-7.html">Next</A>
-<A HREF="ivy-perl-5.html">Previous</A>
-<A HREF="ivy-perl.html#toc6">Contents</A>
-</BODY>
-</HTML>
diff --git a/doc/ivy-perl-7.html b/doc/ivy-perl-7.html
deleted file mode 100644
index c46da20..0000000
--- a/doc/ivy-perl-7.html
+++ /dev/null
@@ -1,25 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
- <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.7">
- <TITLE>The Ivy C library guide: Known bugs</TITLE>
- <LINK HREF="ivy-perl-6.html" REL=previous>
- <LINK HREF="ivy-perl.html#toc7" REL=contents>
-</HEAD>
-<BODY>
-Next
-<A HREF="ivy-perl-6.html">Previous</A>
-<A HREF="ivy-perl.html#toc7">Contents</A>
-<HR>
-<H2><A NAME="s7">7. Known bugs</A></H2>
-<p>This version is only compatible with perl-tk 402-004.
-<p>It does not work with perl-tk 400.202 (fileId event problem)
-<p>It does not work with perl-tk_800.011 (remove file descriptor problem)
-
-
-<HR>
-Next
-<A HREF="ivy-perl-6.html">Previous</A>
-<A HREF="ivy-perl.html#toc7">Contents</A>
-</BODY>
-</HTML>
diff --git a/doc/ivy-perl.html b/doc/ivy-perl.html
deleted file mode 100644
index 58b8ea1..0000000
--- a/doc/ivy-perl.html
+++ /dev/null
@@ -1,66 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
- <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.7">
- <TITLE>The Ivy Perl library guide</TITLE>
- <LINK HREF="ivy-perl-1.html" REL=next>
-
-
-</HEAD>
-<BODY>
-<A HREF="ivy-perl-1.html">Next</A>
-Previous
-Contents
-<HR>
-<H1>The Ivy Perl library guide</H1>
-
-<H2>Stéphane Chatty, <CODE>chatty@cena.dgac.fr</CODE></H2>13 April 1999
-<P><HR>
-<EM>This document is a programmer's guide that describes how to use the Ivy Perl
-library to connect applications to an Ivy bus. This guide describes version 3.0
-of the library.</EM>
-<HR>
-<P>
-<H2><A NAME="toc1">1.</A> <A HREF="ivy-perl-1.html">General information</A></H2>
-
-<UL>
-<LI><A HREF="ivy-perl-1.html#ss1.1">1.1 What is Ivy?</A>
-<LI><A HREF="ivy-perl-1.html#ss1.2">1.2 The Ivy Perl library</A>
-</UL>
-<P>
-<H2><A NAME="toc2">2.</A> <A HREF="ivy-perl-2.html">Getting and installing the Ivy Perl library</A></H2>
-
-<UL>
-<LI><A HREF="ivy-perl-2.html#ss2.1">2.1 Installing RedHat or Debian packages</A>
-</UL>
-<P>
-<H2><A NAME="toc3">3.</A> <A HREF="ivy-perl-3.html">Basic functions</A></H2>
-
-<UL>
-<LI><A HREF="ivy-perl-3.html#ss3.1">3.1 Initialization and main loop</A>
-<LI><A HREF="ivy-perl-3.html#ss3.2">3.2 Emitting messages</A>
-<LI><A HREF="ivy-perl-3.html#ss3.3">3.3 Subscribing to messages</A>
-<LI><A HREF="ivy-perl-3.html#ss3.4">3.4 Example</A>
-</UL>
-<P>
-<H2><A NAME="toc4">4.</A> <A HREF="ivy-perl-4.html">Advanced functions</A></H2>
-
-<UL>
-<LI><A HREF="ivy-perl-4.html#ss4.1">4.1 Utilities</A>
-<LI><A HREF="ivy-perl-4.html#ss4.2">4.2 Direct messages</A>
-</UL>
-<P>
-<H2><A NAME="toc5">5.</A> <A HREF="ivy-perl-5.html">Managing timers and other channels</A></H2>
-
-
-<P>
-<H2><A NAME="toc6">6.</A> <A HREF="ivy-perl-6.html">Conventions for writing applications</A></H2>
-
-<P>
-<H2><A NAME="toc7">7.</A> <A HREF="ivy-perl-7.html">Known bugs</A></H2>
-<HR>
-<A HREF="ivy-perl-1.html">Next</A>
-Previous
-Contents
-</BODY>
-</HTML>
diff --git a/doc/ivy-perl.sgml b/doc/ivy-perl.sgml
new file mode 100644
index 0000000..31b39f5
--- /dev/null
+++ b/doc/ivy-perl.sgml
@@ -0,0 +1,377 @@
+<!--
+ The Ivy Perl library guide
+
+ Copyright (c) 1999-2000
+ Centre d'Etudes de la Navigation Aerienne
+
+ SGML source file
+
+ Authors: Stéphane Chatty <chatty@cena.dgac.fr>
+
+ $Id$
+
+ Please refer to file Ivy.pm for the
+ copyright notice regarding this software
+-->
+
+<!-- -------------------------------------------------------------------------------
+ This file was rebuilt from html files after the disappearance of the
+ original sgml file. It is not yet syntactically valid, and documents an
+ old version of Ivy Perl.
+ ------------------------------------------------------------------------------- -->
+
+<?xml version='1.0' ?>
+<!doctype article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
+
+<article>
+<artheader>
+
+<title>The Ivy Perl library guide</title>
+
+<authorgroup>
+<author>
+<firstname>Stéphane</firstname><surname>Chatty</surname>
+<affiliation><address><email>chatty@cena.fr</email></address></affiliation>
+</author>
+</authorgroup>
+<date>April 13, 1999</date>
+
+<copyright>
+<year>1999</year>
+<holder>Centre d'Études de la Navigation Aérienne</holder>
+</copyright>
+
+<abstract>
+<para>
+This document is a programmer's guide that describes how to use the Ivy Perl
+library to connect applications to an Ivy bus. This guide describes version 3.0
+of the library. The Ivy Perl library was mainly written by Alexandre Bustico
+from CENA, but this documentation is maintained by users of the library.
+</para>
+</abstract>
+</artheader>
+
+<sect1>
+<title>Foreword</title>
+
+<para>
+This document was written in SGML according to the DocBook DTD, so as to be able to
+generate PDF and html output. However, the authors have not yet mastered the
+intricacies of SGML, the DocBook DTD, the DocBook Stylesheets and the related
+tools, which have achieved the glorious feat of being far more complex than
+LaTeX and Microsoft Word combined together. This explains why this document, in addition
+to being incomplete, is so ugly. We'll try and improve it.
+</para>
+</sect1>
+
+
+<sect1>
+<title>What is Ivy?</title>
+<para>
+Ivy is a software bus designed at CENA (France). A software bus is a system
+that allows software applications to exchange information with the illusion of
+broadcasting that information, selection being performed by the receiving
+applications. Using a software bus is very similar to dealing with events in a
+graphical toolkit: on one side, messages are emitted without caring about who
+will handle them, and on the other side, one decide to handle the messages that
+have a certain type or follow a certain pattern. Software buses are mainly aimed
+at facilitating the rapid development of new agents, and at managing a dynamic
+collection of agents on the bus: agents show up, emit messages and receive some,
+then leave the bus without blocking the others.
+</para>
+
+
+<sect2>
+<title>Architecture and principles</title>
+
+<para>
+As opposed to other software buses, Ivy does not depend on a centralised
+server. Actually, Ivy is mostly a communication convention between processes,
+implemented through a collection of libraries in several languages.
+</para>
+
+<para>
+From the programmer's point of view, Ivy is an information broadcasting
+channel. The main functions are:
+
+<UL>
+<LI> connecting to a bus.<EM> Example: Ivy::start (-loopMode =>
+ 'local', -ivyBus => '2011', -appName => "toto" );</EM></LI>
+<LI> sending a message.<EM> Example: Ivy::sendMsgs ("HELLO WORLD")</EM></LI>
+<LI> bind a message pattern to a callback function.<EM> Example:
+ Ivy::bindRegexp ("^HELLO (.*)", [\&cb])</EM></LI>
+<LI> the main loop.<EM> MainLoop</EM></LI>
+</UL>
+</para>
+
+<para>
+Ivy's decentralised connection scheme probably incurs limitations in terms of
+how many applications can be connected to an Ivy bus, but this simplifies
+management a lot. Basically, an Ivy bus is just a set of applications that
+decide to communicate together. The only conventions between these applications
+are:
+<OL>
+<LI> the use of the Ivy protocol (for obvious reasons)</LI>
+<LI> a bus address, made of a broadcast port number (a bit like a citizen band
+channel) and a set of networks addresses</LI>
+</OL>
+</para>
+
+<para>
+When an application wants to connect to a bus, it sends a broadcast message on the
+networks specified in the bus address, so that all applications present on those
+networks and listening on the specified port number connect to it. It then
+becomes part of the bus, and listens like the other ones.
+</para>
+
+<para>
+The messages are exchanged in text format, and bindings are based on regular
+expressions with captures. If an application subscribes to
+<CODE>HELLO (.*)</CODE> and if another application emits the message <CODE>HELLO WORLD</CODE>, a
+callback will be called in the first application with <CODE>WORLD</CODE> as an argument.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Using Ivy</title>
+<para>
+You can use Ivy through applications that have been provided to you. This is the
+case for <CODE>ivyprobe</CODE>, an Ivy agent that allows you to examine the
+messages exchanged on a given bus and to send messages on that bus. You can
+refer to the web site <CODE>http://www.tls.cena.fr/products/ivy/</CODE> for a
+list of available agents. However, what you will usually want to do is to
+develop your own applications. In order to do that you can use an Ivy connection
+kit, that is a library that implements Ivy.
+</para>
+
+<para>
+Libraries that implement Ivy are available in the following environments:
+<UL>
+<LI> in C on Unix and Windows platforms, with its own communication library</LI>
+<LI> in C++ on Windows platforms</LI>
+<LI> in C++ on Unix platforms, integrated with the Uch communication library</LI>
+<LI> in C++ on Unix platforms, integrated with OpenInventor</LI>
+<LI> in C++ on Macintosh</LI>
+<LI> in Perl and in Perl/Tk</LI>
+<LI> integrated with Object Caml on Unix platforms</LI>
+<LI> in Scheme on Unix platforms</LI>
+<LI> in Java</LI>
+</UL>
+</para>
+
+<para>
+Connecting your application to an Ivy bus just consists in choosing the
+appropriate library, add the appropriate message emission and reception calls to
+your code, use the main loop provided in the library or make the necessary
+integrations, and get your code running!
+</para>
+</sect1>
+
+<sect1>
+<title>The Ivy Perl library</title>
+
+<sect2>
+<title>What is it?</title>
+
+<para>
+The Ivy Perl library (aka Perl-Net-Ivy or ivy-perl) is a Perl library that
+allows you to connect applications to an Ivy bus. You can use it to write
+applications in Perl or any other language that supports Perl extensions
+(Perl/Tk for instance). This guide documents how you can do that.
+</para>
+
+<para>
+The Ivy Perl library is known to compile and work in WindowsNT and Linux
+environments. It should be easy to use on most Posix environments.
+</para>
+
+<para>
+The Ivy Perl library was originally developed by Alexandre Bustico at CENA. It
+is maintained by the CENA-Toulouse team.
+</para>
+
+
+
+<sect2>
+<title>Getting and installing the Ivy Perl library</title>
+
+<para>
+You can get the latest versions of the Ivy C library from CENA
+(<ulink URL="http://www.tls.cena.fr/products/ivy/">http://www.tls.cena.fr/products/ivy/</ulink>). Depending
+on whether you use a supported binary distribution, you can retrieve RPM
+or Debian packages for Linux (do not forget to get the development package as
+well as the run-time package), or retrieve the source files and install them by hand.
+If your packages are Linux/RPM, you have to use the command <em><strong> rpm -i package-name</strong></em>.
+If your system is Linux/Debian, you have to use the command <em><strong> dpkg -i package-name</strong></em>.
+</para>
+</sect2>
+</sect1>
+
+<sect1>
+<title>Basic functions</title>
+
+<sect2>
+<title>Initialization and main loop</title>
+
+<para>
+Initializing an Ivy agent with the Ivy-Perl library is done by calling function
+<CODE>Ivy::start</CODE>. In theory, initialization is then over. However in
+practice, as for any asynchronous communication or interaction library, nothing
+happens until your application has reached the main loop.
+</para>
+
+<para>
+The Ivy Perl library provides two kind of main loop: a "LOCAL" loop
+ for perl code, and a "TK" loop for perl-Tk code.
+</para>
+
+<para>
+Here is more details on <CODE>Ivy::start</CODE> function:
+
+<programlisting>
+ Ivy::start(-loopMode =&gt; 'TK',
+ -ivyBus =&gt; '2011',
+ -appName =&gt; "TOTO",
+ -neededApp =&gt; "TITI",
+ -statusFunc =&gt; \&amp;statusScan);
+</programlisting>
+
+initializes and connects your application to the bus specified in
+<CODE>ivyBus</CODE>. The string provided should follow the convention described
+in section XX. Example: <CODE>"127:2010"</CODE>..
+</para>
+
+<para>
+<programlisting>
+MainLoop;
+</programlisting>
+
+makes your application enter the main loop in which it will handle asynchronous
+communications and signals.
+</para>
+
+<para>
+<programlisting>
+Ivy::stop ();
+</programlisting>
+
+makes your application exit the main loop.
+</para>
+
+<sect2>
+<title>Emitting messages</title>
+
+<para>
+Emitting a message on an Ivy bus is much like printing a message on the standard
+output. However, do not forget that your message will not be emitted if Ivy has
+not been properly initialized and if you do not have a main loop of some sort
+running. To emit a message, use <CODE>IvySendMsg</CODE>, which works like
+<CODE>printf</CODE>:
+</para>
+
+<para>
+<programlisting>
+Ivy::sendMsg ("...");
+</programlisting>
+
+sends a message on the bus.
+</para>
+
+
+<sect2>
+<title>Subscribing to messages</title>
+
+<para>
+Subscribing to messages consists in binding a callback function to a message
+pattern. Patterns are described by regular expressions with captures. When a
+message matching the regular expression is detected on the bus, the callback
+function is called. The captures (ie the bits of the message that match the
+parts of regular expression delimited by brackets) are passed to the callback
+function much like options are passed to <CODE>main</CODE>. Use function
+<CODE>Ivy::bindRegexp</CODE> to bind a callback to a pattern.
+
+<programlisting>
+Ivy::bindRegexp ("^HELLO WORLD", [\&amp;Start]);
+</programlisting>
+
+binds callback function <CODE>Start</CODE> to the regular expression specified by
+<CODE>regex_format</CODE>.
+</para>
+
+<para>
+<programlisting>
+Ivy::bindRegexp ("^HELLO WORLD", NULL);
+<programlisting>
+
+deletes the binding.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Advanced functions</title>
+
+<sect2>
+<title>Utilities</title>
+</sect2>
+
+<sect2>
+<title>Direct messages</title>
+</sect2>
+
+</sect1>
+
+<sect1>
+<title>Managing timers and other channels</title>
+</sect1>
+
+<sect1>
+<title>Conventions for writing applications</title>
+
+<sect2>
+<title>Default bus</title>
+<para>
+By default, the bus used is <em><strong>127.255.255.255:2010 </em></strong> ie
+the application will be connected on the port 2010 of the local machine it runs
+on.
+</para>
+
+<para>
+You can set the bus to be used by setting the environment variable
+<CODE>IVYBUS</CODE> or by implementing the option <CODE>-b</CODE> in the
+application.
+</para>
+
+<sect2>
+<title>Syntax of messages</title>
+<para>
+The syntax of the messages exchanged is totally free. However, the following
+convention is recommended:
+<menu>
+<li>The message syntax is <CODE>Subject Attributes</CODE></li>
+<li>A Subject is an object, named in a hierarchical form: <CODE>ObjectClass1:object1.ObjectClass2:object2...</CODE></li>
+<li>Attributes are pairs <CODE>(attribute-name, value)</CODE></li>
+</menu>
+</para>
+
+<para>
+Example:
+
+<programlisting>
+AIRCRAFT:LIB720 Moved lat=46.1697 lon=2.0844 vx=-36 vy=-463 afl=330 rate=0 heading=184 ground_speed=465 mach_speed=0 tendance=0 time=24600
+</programlisting>
+</para>
+
+</sect1>
+
+<sect1>
+<title>Known bugs</title>
+<para>
+Version 3 is only compatible with perl-tk 402-004.
+It does not work with perl-tk 400.202 (fileId event problem)
+It does not work with perl-tk_800.011 (remove file descriptor problem)
+</para>
+</sect1>
+</article>
+