Documentation update 3.2 -> 3.8, mentionning:

  - include is now in Ivy/ivy.h
  - we now use PCRE
  - IvyMainLoop() now has two arguments
  - it's glib, and not gtk

1 files changed, 29 insertions, 33 deletions

diff --git a/doc/ivy-c.sgml b/doc/ivy-c.sgml
index 7365746..bd0be09 100644
--- a/doc/ivy-c.sgml
+++ b/doc/ivy-c.sgml
@@ -40,14 +40,14 @@
 <date>December 11, 2002</date>
 
 <copyright>
-<year>1998-2002</year>
+<year>1998-2006</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 C
-library to connect applications to an Ivy bus. This guide describes version 3.2
+library to connect applications to an Ivy bus. This guide describes version 3.8
 of the library.
 </para>
 </abstract>
@@ -90,7 +90,7 @@ library, please refer to <citetitle>The Ivy sofware bus: a white
 paper</citetitle>. If you want more details about the internals of Ivy, have a
 look at <citetitle>The Ivy architecture and protocol</citetitle>. And finally,
 if you are more interested in other languages, refer to other guides such as
-<citetitle>The Ivy Perl library guide</citetitle>. All those documents should be 
+<citetitle>The Ivy Java library guide</citetitle>. All those documents should be 
 available from the Ivy Web site at <ulink URL="http://www.tls.cena.fr/products/ivy/">http://www.tls.cena.fr/products/ivy/</ulink>.
 </para>
 </sect1>
@@ -108,7 +108,7 @@ Ivy bus. This guide is here to help you do that.
 </para>
 
 <para>
-The Ivy C library is known to compile and work in WindowsNT and Linux
+The Ivy C library is known to compile and work in Win32, Linux, and MacOSX
 environments. It should be easy to use on most Posix environments. 
 </para>
 
@@ -125,8 +125,8 @@ is maintained by a group at CENA (Toulouse, France)
 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 binary 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 compile them.
+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 compile them.
 </para>
 </sect2>
 
@@ -151,8 +151,8 @@ Here is the code of "hellotranslater.c":
 #include &lt;stdlib.h&gt;
 #include &lt;stdio.h&gt;
 #include &lt;getopt.h&gt;
-#include &lt;ivy.h&gt;
-#include &lt;ivyloop.h&gt;
+#include &lt;Ivy/ivy.h&gt;
+#include &lt;Ivy/ivyloop.h&gt;
 
 /* callback associated to "Hello" messages */
 void HelloCallback (IvyClientPtr app, void *data, int argc, char **argv)
@@ -195,7 +195,7 @@ main (int argc, char**argv)
 	IvyBindMsg (ByeCallback, 0, "^Bye$");
 
 	/* main loop */
-	IvyMainLoop (0);
+	IvyMainLoop (0,0);
 }
 
 </programlisting>
@@ -308,14 +308,15 @@ environment variable is not defined, the default value
 <parameter>"127:2010"</parameter> is used.
 
 <programlisting>
-void IvyMainLoop (void (*hook) (void));
+void IvyMainLoop (void (*beforehook) (void),void (*afterhook) (void));
 </programlisting>
 makes your application enter the main loop in which it will handle asynchronous
 communications and signals. This is the default Ivy main loop, based on the
 <function>select</function> POSIX system call.
-If non-null, <parameter>hook</parameter> is called every time the main loop is
+If non-null, <parameter>beforehook</parameter> is called every time the main loop is
 about to enter <function>select</function>, and can be used (with care!) to
-extend the main loop.
+extend the main loop. <parameter>afterhook</parameter> is called each time the
+main loop exits <function>select</function>.
 
 <programlisting>
 void IvyStop ();
@@ -346,7 +347,9 @@ sends a message on the bus. This function has exactly the same behaviour as
 <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
+pattern. Patterns are described by regular expressions with captures. Since
+the 3.6 library, we use <ulink url="http://www.pcre.org/">Perl Compatible Regular
+Expression</ulink>. 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
@@ -397,7 +400,10 @@ typedef void (*MsgCallback)(IvyClientPtr app, void *data, int argc, char **argv)
 <sect2>
 <title>Direct messages</title>
 <para>
-[to be written]
+There are cases when we don't want to send messages to every other subscribee
+on the bus. Direct messages allow peer to peer communication, and thus kind of
+break the software bus metaphor. We strongly discourage you to use them, and
+thus won't provide handy documentation.
 </para>
 </sect2>
 
@@ -587,21 +593,11 @@ int main(int argc,char *argv[]){
 
 <sect2>
 <title>Using Ivy with Tcl/Tk</title>
-<para>Just load the libtclivy.so package, and use the following commands
-<programlisting>
-#!/usr/bin/tclsh
-Ivy::init $name $hellomessge connectproc dieproc
-Ivy::start $domain
-Ivy::bind $regexp ballback
-Ivy::applist
-Ivy::send $message
-Ivy::applist
-mainloop
-</programlisting>
+<para>
 A full example in Tcl/Tk is provided here:
 <programlisting>
 #!/usr/bin/wish
-load libtclivy.so.3.4
+load libtclivy.so.3
 proc connect {args} { }
 proc send { } {
   global tosend
@@ -622,12 +618,12 @@ pack .send
 </sect2>
 
 <sect2>
-<title>Using Ivy with Gtk</title>
+<title>Using Ivy with Gtk/Gdk</title>
 <para>There is little to do to make your gtk applications Ivy aware: just add
 the following lines into your code:
 <programlisting>
-#include &lt;ivy.h&gt;
-#include &lt;ivygtkloop.h&gt;
+#include &lt;Ivy/ivy.h&gt;
+#include &lt;Ivy/ivyglibloop.h&gt;
 ...
 IvyInit ("IvyGtkButton", "IvyGtkButton READY",NULL,NULL,NULL,NULL);
 IvyBindMsg(textCallback,&amp;tosend,"^Ivy Button text=(.*)");
@@ -636,12 +632,12 @@ IvyStart (bus);
 </para>
 
 <para>A full example: gtkIvyButton.c  is provided below, compile it with the
--lgtkivy flag. The other flags depend on your system installation ( replace
-pkg-config with gtk-config for older gnome1 libs)
+appropriate flags for your gtk distribution ( `pkg-config --cflags --libs
+gtk+-x11-2.0 `) and -lglibivy . 
 <programlisting>
 #include &lt;gtk/gtk.h&gt;
-#include &lt;ivy.h&gt;
-#include &lt;ivygtkloop.h&gt;
+#include &lt;Ivy/ivy.h&gt;
+#include &lt;Ivy/ivyglibloop.h&gt;
 #include &lt;stdio.h&gt;
 #include &lt;stdlib.h&gt;