[libgda] GdaBrowser: improved inline help

[Vivien Malerba <vivien src gnome org>]

commit 91eac8acec03779e08486ac5e377a8cb94141d69
Author: Vivien Malerba <malerba gnome-db org>
Date:   Sat Mar 19 12:38:16 2011 +0100

    GdaBrowser: improved inline help

 tools/browser/help/C/actions.page              |    1 -
 tools/browser/help/C/features.page             |    5 +-
 tools/browser/help/C/figures/virtual-cnc-2.png |  Bin 0 -> 35651 bytes
 tools/browser/help/C/figures/virtual-cnc-3.png |  Bin 0 -> 48960 bytes
 tools/browser/help/C/figures/virtual-cnc-4.png |  Bin 0 -> 102207 bytes
 tools/browser/help/C/figures/virtual-cnc-5.png |  Bin 0 -> 34537 bytes
 tools/browser/help/C/figures/virtual-cnc.png   |  Bin 0 -> 27229 bytes
 tools/browser/help/C/virtual-connections.page  |  107 +++++++++++++++++++++++-
 tools/browser/help/Makefile.am                 |    7 ++-
 9 files changed, 113 insertions(+), 7 deletions(-)
---
diff --git a/tools/browser/help/C/actions.page b/tools/browser/help/C/actions.page
index 269d7cf..9d05ef8 100644
--- a/tools/browser/help/C/actions.page
+++ b/tools/browser/help/C/actions.page
@@ -5,7 +5,6 @@
     <title type="sort">1</title>
     <link type="topic" xref="query-execution-perspective"/>
     <link type="topic" xref="data-manager-perspective"/>
-    <link type="guide" xref="index#presentation"/>
   </info>
   <title>Actions</title>
   <p>
diff --git a/tools/browser/help/C/features.page b/tools/browser/help/C/features.page
index 82ef91a..8799fed 100644
--- a/tools/browser/help/C/features.page
+++ b/tools/browser/help/C/features.page
@@ -40,12 +40,15 @@
       <item><p>analyse the table's contents, see the
       <link xref="data-manager-perspective">Data manager perspective</link></p></item>
     </list>
+    <p>
+      See also the section about <link xref="actions">actions</link>
+    </p>
   </section>
   <section>
     <title>Openness</title>
     <list>
       <item><p>CSV and other text files can be imported and used in conjunction with <link type="topic" xref="virtual-connections">connection binding</link></p></item>
-      <item><p>the general framework is opened enough to add new integrated features; specifically anyone can develop new <link type="topic" xref="general-ui">perspectives</link></p></item>      
+x      <item><p>the general framework is opened enough to add new integrated features; specifically anyone can develop new <link type="topic" xref="general-ui">perspectives</link></p></item>      
     </list>
   </section>
 </page>
diff --git a/tools/browser/help/C/figures/virtual-cnc-2.png b/tools/browser/help/C/figures/virtual-cnc-2.png
new file mode 100644
index 0000000..5e37bd1
Binary files /dev/null and b/tools/browser/help/C/figures/virtual-cnc-2.png differ
diff --git a/tools/browser/help/C/figures/virtual-cnc-3.png b/tools/browser/help/C/figures/virtual-cnc-3.png
new file mode 100644
index 0000000..1e71795
Binary files /dev/null and b/tools/browser/help/C/figures/virtual-cnc-3.png differ
diff --git a/tools/browser/help/C/figures/virtual-cnc-4.png b/tools/browser/help/C/figures/virtual-cnc-4.png
new file mode 100644
index 0000000..7153288
Binary files /dev/null and b/tools/browser/help/C/figures/virtual-cnc-4.png differ
diff --git a/tools/browser/help/C/figures/virtual-cnc-5.png b/tools/browser/help/C/figures/virtual-cnc-5.png
new file mode 100644
index 0000000..9b78e09
Binary files /dev/null and b/tools/browser/help/C/figures/virtual-cnc-5.png differ
diff --git a/tools/browser/help/C/figures/virtual-cnc.png b/tools/browser/help/C/figures/virtual-cnc.png
new file mode 100644
index 0000000..9837aa2
Binary files /dev/null and b/tools/browser/help/C/figures/virtual-cnc.png differ
diff --git a/tools/browser/help/C/virtual-connections.page b/tools/browser/help/C/virtual-connections.page
index 678e342..383cc8f 100644
--- a/tools/browser/help/C/virtual-connections.page
+++ b/tools/browser/help/C/virtual-connections.page
@@ -4,8 +4,9 @@
   <info>
     <title type="sort">1</title>
     <link type="guide" xref="features"/>
+    <link type="guide" xref="index#connections"/>
   </info>
-  <title>Connections binding</title>
+  <title>Connections binding (ie. virtual connections)</title>
   <p>
     Connection binding is a feature which allows to "bind" several connections and/or imported
     data sets into a single connection, which can be used almost like a regular connection.
@@ -20,10 +21,108 @@
     To create a new "bound" connection (or "virtual" connection), use the
     <guiseq><gui>Connection</gui><gui>Bind connection</gui></guiseq> menu, or the
     <keyseq><key>Ctrl</key><key>i</key></keyseq> shortcut. This pops up a new dialog window
-    from which "items" to be included in the "bound" connection can be defined:
+    from which elements to be included in the "bound" connection can be defined as shown below.
+  </p>
+  <figure>
+    <title>Dialog to create a new virtual connection</title>
+    <desc>Here the current connection (c1) will be bound in the "c1" schema</desc>
+    <media type="image" mime="image/png" src="figures/virtual-cnc.png"/>
+  </figure>
+  <p>
+    Use the <guiseq><gui>Add binding</gui></guiseq> button to either:
   </p>
   <list>	
-    <item><p>Bind a connection to include all the tables of that connection</p></item>
-    <item><p>Bind a data set to import data from a text file as a single table</p></item>
+    <item><p>bind a connection to include all the tables of that connection: use the <guiseq><gui>Bind a connection</gui></guiseq> option. This option simply adds a new element in the dialog, to specify a schema name and select an existing connection</p></item>
+    <item><p>bind a data set to import data from a text file as a single table: use the <guiseq><gui>Bind a data set</gui></guiseq> option. See section below for more information.</p></item>
   </list>
+
+  <section>
+    <title>Use case for virtual connections</title>
+    <p>
+      To illustrate virtual connection usage, let's define a simple use case and see how it's usefull. Suppose you have
+      a database which contains the list of servers which you are responsible for. For simplicity, let's assume that
+      the database contains a table named "server" with the following definition:
+    </p>
+    <code>CREATE TABLE servers (name string, location string);</code>
+    <p>
+      Let's suppose this table contains the following information:
+    </p>
+    <code>
+> select * from servers ;
+name     | location
+---------+---------
+moon     | room1   
+darkstar | room2   
+flag     | room3   
+alf      | room2   
+vador    | room3   
+(5 rows)
+>
+    </code>
+    <p>
+      Now let's assume you have a third party program which gives you a list of servers for which there might be a
+      problem, the output of this program is a CSV file with a column for the server name, a column for the error code,
+      and a column describing the problem. Let's assume the CSV file has the following contents:
+    </p>
+    <code>
+$ cat problems.csv 
+Server name,Error code,Error description
+darkstar,0,file system full
+vador,1,outdated AV signature
+darkstar,2,overloaded
+flag,0,file system full
+$
+    </code>
+    <p>
+      Let's suppose now you want to know all the servers, where they are located where there is a problem with
+      error code 0. The solution is to bind the connection to the database (for example in the "c1" schema), import
+      the problems CSV file (for example in the "tab" table), and execute the following SQL command:
+    </p>
+    <code>
+SELECT 
+  "server name", 
+  location
+FROM tab
+  INNER JOIN c1.servers AS s ON (tab."server name" = s.name)
+WHERE "Error code"=0
+    </code>
+    <p>
+      Which returns the expected results as shown in the following figure:
+    </p>
+    <figure>
+      <title>Expected results from virtual connection</title>
+      <media type="image" mime="image/png" src="figures/virtual-cnc-4.png"/>
+    </figure>
+  </section>
+
+
+  <section>
+    <title>Importing a data set into a virtual connection</title>
+    <p>
+      To import a data set into a table in the virtual connection (for example to import the "problems.csv" file
+      from the use case), use the <guiseq><gui>Bind a data set</gui></guiseq> option from the virtual connection
+      creation dialog:
+    </p>
+    <figure>
+      <title>Import a data set into a virtual connection - 1</title>
+      <media type="image" mime="image/png" src="figures/virtual-cnc-5.png"/>
+    </figure>
+    <p>
+      From there use the <guiseq><gui>Import</gui></guiseq> button which allows you to select a file
+      to import and also define some import options (file encoding, file type, ...) After this step,
+      the virtual connection is ready to be used:
+    </p>
+    <figure>
+      <title>Import a data set into a virtual connection - 2</title>
+      <media type="image" mime="image/png" src="figures/virtual-cnc-2.png"/>
+    </figure>
+    <p>
+      The resulting virtual connection, identified as "c2" here is opened in its own new window:
+    </p>
+    <figure>
+      <title>New opened virtual connection</title>
+      <media type="image" mime="image/png" src="figures/virtual-cnc-3.png"/>
+    </figure>
+
+  </section>
 </page>
diff --git a/tools/browser/help/Makefile.am b/tools/browser/help/Makefile.am
index b592462..b196d02 100644
--- a/tools/browser/help/Makefile.am
+++ b/tools/browser/help/Makefile.am
@@ -22,7 +22,12 @@ DOC_FIGURES = \
 	figures/table-insert-data.png \
 	figures/declaredfk.png \
 	figures/declaredfk-dialog.png \
-	figures/schema-browser-persp.png
+	figures/schema-browser-persp.png \
+	figures/virtual-cnc.png \
+	figures/virtual-cnc-2.png \
+	figures/virtual-cnc-3.png \
+	figures/virtual-cnc-4.png \
+	figures/virtual-cnc-5.png
 
 DOC_PAGES = \
 	actions.page \