[libgda] Documentation: detailled how to create a new provider form template

[Vivien Malerba <vivien src gnome org>]

commit 492dc8da612fa36a24f2befddca64fce521e9021
Author: Vivien Malerba <malerba gnome-db org>
Date:   Tue Apr 21 10:28:44 2009 +0200

    Documentation: detailled how to create a new provider form template
---
 ChangeLog                  |    5 +++++
 doc/C/libgda-4.0-docs.sgml |   34 ++++++++++++++++++++++++++++++++++
 doc/C/prov-writing.xml     |    6 ------
 3 files changed, 39 insertions(+), 6 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index cbb3804..0d9599c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2009-04-21  Vivien Malerba <malerba gnome-db org>
+
+	* doc/C/libgda-4.0-docs.sgml:
+	* doc/C/prov-writing.xml: detailled how to create a new provider from template
+
 2009-04-20  Vivien Malerba <malerba gnome-db org>
 
 	* configure.in:
diff --git a/doc/C/libgda-4.0-docs.sgml b/doc/C/libgda-4.0-docs.sgml
index 2b067cd..36c2777 100644
--- a/doc/C/libgda-4.0-docs.sgml
+++ b/doc/C/libgda-4.0-docs.sgml
@@ -1551,6 +1551,40 @@ g_object_unref (eng);
       &provider-support-sql;
       &provider-support;
     </chapter>
+<sect1>
+    <title>Getting started</title>
+    <para>
+      &LIBGDA;'s sources contain templates to get started in creating a new database provider. The following templates
+      are available:
+      <itemizedlist>
+	<listitem><para>the template in the <filename class="directory">providers/skel-implementation/capi</filename>
+	    directory which can be used when writing a provider using the database's C or C++ API (for example
+	    the PostgreSQL or MySQL providers)</para></listitem>
+	<listitem><para>the template in the <filename class="directory">providers/skel-implementation/models</filename>
+	    directory which can be used when writing a provider for a system which is not a relational database (or
+	    does offer a very limited API, such as for the MS Access or Berkeley DB systems).</para></listitem>
+      </itemizedlist>
+    </para>
+    <para>
+      In any case, for example to create a DummyDb provider, follow these steps:
+      <itemizedlist>
+	<listitem><para>copy one of the template's directory into a new directory named
+	    <filename class="directory">dummydb</filename></para></listitem>
+	<listitem><para>From inside that new directory, run the
+	    <filename class="directory">providers/prepare_provider_sources.sh</filename> script with the name
+	    of the provider as sole argument ("dummydb" here), which replaces
+	    all the class and object names with the name of the provider and renames the files correctly. These
+	    new sources should be compilable without any modification.</para></listitem>
+	<listitem><para>Edit the <filename>Makefile.am</filename> to add provider specific compilation and link
+	    flags</para></listitem>
+	<listitem><para>Integrate the provider's new code into a compilation unit: either &LIBGDA;'s sources in
+	    the <filename class="directory">providers</filename>directory or in your own application (this step usually involves
+	    modifying the <filename>configure.ac</filename> or <filename>configure.in</filename> files).</para></listitem>
+	<listitem><para>Implement the missing parts (it is usually a good idea to look how other provider's
+	    implementations are done to get ideas).</para></listitem>
+      </itemizedlist>
+    </para>
+  </sect1>
     &provider-writing;
   </part>
 
diff --git a/doc/C/prov-writing.xml b/doc/C/prov-writing.xml
index e21c868..1f0fc49 100644
--- a/doc/C/prov-writing.xml
+++ b/doc/C/prov-writing.xml
@@ -23,12 +23,6 @@
     should be implemented, optionnally the <link linkend="prov-close-connection">close_connection()</link> can
     also be implemented.
   </para>
-  <para>
-    To implement a virtual provider, one can copy the contents of the 
-    <filename class="directory">providers/skel-implementation/models</filename> directory, change all references
-    to "models" with the correct provider name, and implement the missing parts, using if necessary the
-    BDB an MDB providers' implementations as examples.
-  </para>
 
   <sect1>
     <title>Synchronous / asynchronous mode</title>