GNOME.org
 

[libgda] Initial help support for the GdaBrowser

commit 63916d98f71352cae05088afd36aaf4f5060f70e
Author: Vivien Malerba <malerba gnome-db org>
Date:   Thu Apr 15 21:32:01 2010 +0200

    Initial help support for the GdaBrowser

 .gitignore                                         |    3 +
 autogen.sh                                         |    2 +-
 configure.in                                       |    6 +
 tools/browser/Makefile.am                          |    2 +-
 tools/browser/browser-window.c                     |   10 ++
 tools/browser/data-manager/data-console.c          |   13 ++
 tools/browser/data-manager/data-source.c           |    2 +-
 tools/browser/data-manager/spec-editor.c           |   31 ----
 tools/browser/help/.gitignore                      |    1 +
 tools/browser/help/C/data-manager-perspective.page |   93 +++++++++++++
 tools/browser/help/C/data-manager-xml-syntax.page  |  146 ++++++++++++++++++++
 tools/browser/help/C/diagram.page                  |   32 +++++
 tools/browser/help/C/features.page                 |   20 +++
 tools/browser/help/C/figures/cnc_open.png          |  Bin 0 -> 52941 bytes
 tools/browser/help/C/figures/data-man-mode.png     |  Bin 0 -> 1103 bytes
 tools/browser/help/C/figures/data-man-persp.png    |  Bin 0 -> 42049 bytes
 .../browser/help/C/figures/data-man-xmlcompose.png |  Bin 0 -> 26347 bytes
 tools/browser/help/C/figures/diagram.png           |  Bin 0 -> 17249 bytes
 tools/browser/help/C/figures/mainwin.png           |  Bin 0 -> 47008 bytes
 tools/browser/help/C/figures/query-exec-persp.png  |  Bin 0 -> 41929 bytes
 tools/browser/help/C/figures/trans-begin.png       |  Bin 0 -> 1077 bytes
 tools/browser/help/C/figures/trans-commit.png      |  Bin 0 -> 1158 bytes
 tools/browser/help/C/figures/trans-rollback.png    |  Bin 0 -> 1019 bytes
 tools/browser/help/C/general-ui.page               |   36 +++++
 tools/browser/help/C/index.page                    |   38 +++++
 tools/browser/help/C/legal.xml                     |    9 ++
 .../help/C/query-execution-perspective.page        |  100 +++++++++++++
 .../browser/help/C/schema-browser-perspective.page |   43 ++++++
 tools/browser/help/C/transactions.page             |   30 ++++
 tools/browser/help/C/variables.page                |   41 ++++++
 tools/browser/help/Makefile.am                     |   33 +++++
 tools/browser/help/gda-browser.omf.in              |   10 ++
 tools/browser/support.c                            |   75 ++++++++++
 tools/browser/support.h                            |    1 +
 34 files changed, 743 insertions(+), 34 deletions(-)
---
diff --git a/.gitignore b/.gitignore
index ec81d24..2bd33a3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -51,3 +51,6 @@ stamp-it
 keywords_hash.c
 mkkeywordhash
 gtk-doc.make
+gnome-doc-utils.make
+xmldocs.make
+omf.make
diff --git a/autogen.sh b/autogen.sh
index 1018d28..596a39b 100755
--- a/autogen.sh
+++ b/autogen.sh
@@ -21,5 +21,5 @@ REQUIRED_AUTOMAKE_VERSION=1.9
 gnome_autogen=`which gnome-autogen.sh`
 test -z "$gnome_autogen"
 
-USE_GNOME2_MACROS=1 . $gnome_autogen
+USE_GNOME2_MACROS=1 USE_COMMON_DOC_BUILD=yes . $gnome_autogen
 
diff --git a/configure.in b/configure.in
index b3d3707..2ea67ea 100644
--- a/configure.in
+++ b/configure.in
@@ -108,6 +108,10 @@ AC_ARG_PROGRAM
 AM_PROG_LIBTOOL
 AC_PROG_MAKE_SET
 
+dnl -- Initialize docs
+GNOME_DOC_INIT([0.9.0],,
+  [AC_MSG_WARN([[gnome-doc-utils not found: documentation will not be built.]])])
+
 dnl ******************************
 dnl glib-genmarshal
 dnl ******************************
@@ -1795,6 +1799,8 @@ tools/browser/data-manager/Makefile
 tools/browser/dummy-perspective/Makefile
 tools/browser/canvas/Makefile
 tools/browser/doc/Makefile
+tools/browser/help/Makefile
+tools/browser/help/gda-browser.omf
 testing/Makefile
 tests/Makefile
 tests/parser/Makefile
diff --git a/tools/browser/Makefile.am b/tools/browser/Makefile.am
index ff0c5d8..5f61999 100644
--- a/tools/browser/Makefile.am
+++ b/tools/browser/Makefile.am
@@ -1,7 +1,7 @@
 bin_PROGRAMS=gda-browser-4.0
 noinst_LTLIBRARIES = libbrowser.la
 
-SUBDIRS = data common schema-browser query-exec data-manager dummy-perspective
+SUBDIRS = data common schema-browser query-exec data-manager dummy-perspective help
 if HAVE_GOOCANVAS
 SUBDIRS+=canvas
 noinst_PROGRAMS=canvas-example
diff --git a/tools/browser/browser-window.c b/tools/browser/browser-window.c
index edb3c23..3248c47 100644
--- a/tools/browser/browser-window.c
+++ b/tools/browser/browser-window.c
@@ -203,6 +203,7 @@ static void transaction_commit_cb (GtkAction *action, BrowserWindow *bwin);
 static void transaction_rollback_cb (GtkAction *action, BrowserWindow *bwin);
 static void quit_cb (GtkAction *action, BrowserWindow *bwin);
 static void about_cb (GtkAction *action, BrowserWindow *bwin);
+static void manual_cb (GtkAction *action, BrowserWindow *bwin);
 static void window_close_cb (GtkAction *action, BrowserWindow *bwin);
 static void window_fullscreen_cb (GtkToggleAction *action, BrowserWindow *bwin);
 static void window_new_cb (GtkAction *action, BrowserWindow *bwin);
@@ -239,6 +240,7 @@ static const GtkActionEntry ui_actions[] = {
         { "WindowClose", GTK_STOCK_CLOSE, "_Close", "", "Close this window", G_CALLBACK (window_close_cb)},
         { "Help", NULL, "_Help", NULL, "Help", NULL },
         { "HelpAbout", GTK_STOCK_ABOUT, "_About", NULL, "About", G_CALLBACK (about_cb) },
+        { "HelpManual", GTK_STOCK_HELP, "_Manual", "F1", "Manual", G_CALLBACK (manual_cb) },
 	{ "TransactionBegin", BROWSER_STOCK_BEGIN, N_("Begin"), NULL, N_("Begin a new transaction"),
           G_CALLBACK (transaction_begin_cb)},
         { "TransactionCommit", BROWSER_STOCK_COMMIT, N_("Commit"), NULL, N_("Commit current transaction"),
@@ -283,6 +285,7 @@ static const gchar *ui_actions_info =
         "    </menu>"
 	"    <placeholder name='MenuExtension'/>"
         "    <menu name='Help' action='Help'>"
+        "      <menuitem name='HelpManual' action= 'HelpManual'/>"
         "      <menuitem name='HelpAbout' action= 'HelpAbout'/>"
         "    </menu>"
         "  </menubar>"
@@ -1019,6 +1022,13 @@ about_cb (GtkAction *action, BrowserWindow *bwin)
         gtk_widget_show (dialog);
 }
 
+void
+manual_cb (GtkAction *action, BrowserWindow *bwin)
+{
+	browser_show_help (GTK_WINDOW (bwin), NULL);
+}
+
+
 /**
  * browser_window_get_connection
  * @bwin: a #BrowserWindow
diff --git a/tools/browser/data-manager/data-console.c b/tools/browser/data-manager/data-console.c
index 501a323..bab0186 100644
--- a/tools/browser/data-manager/data-console.c
+++ b/tools/browser/data-manager/data-console.c
@@ -169,6 +169,7 @@ data_console_get_type (void)
 static void editor_clear_clicked_cb (GtkButton *button, DataConsole *dconsole);
 static void variables_clicked_cb (GtkToggleButton *button, DataConsole *dconsole);
 static void execute_clicked_cb (GtkButton *button, DataConsole *dconsole);
+static void help_clicked_cb (GtkButton *button, DataConsole *dconsole);
 static void spec_editor_toggled_cb (GtkToggleButton *button, DataConsole *dconsole);
 static void spec_editor_changed_cb (SpecEditor *sped, DataConsole *dconsole);
 
@@ -315,6 +316,12 @@ data_console_new (BrowserConnection *bcnc)
 	g_signal_connect (button, "toggled",
 			  G_CALLBACK (spec_editor_toggled_cb), dconsole);
 
+	button = browser_make_small_button (FALSE, _("Help"), GTK_STOCK_HELP, _("Help"));
+	gtk_box_pack_start (GTK_BOX (bbox), button, FALSE, FALSE, 0);
+	g_signal_connect (button, "clicked",
+			  G_CALLBACK (help_clicked_cb), dconsole);
+
+
 
 	/* data contents page */
 	GtkWidget *wid;
@@ -346,6 +353,12 @@ execute_clicked_cb (GtkButton *button, DataConsole *dconsole)
 }
 
 static void
+help_clicked_cb (GtkButton *button, DataConsole *dconsole)
+{
+	browser_show_help ((GtkWindow*) gtk_widget_get_toplevel (dconsole), "data-manager-perspective");
+}
+
+static void
 variables_clicked_cb (GtkToggleButton *button, DataConsole *dconsole)
 {
 	if (gtk_toggle_button_get_active (button))
diff --git a/tools/browser/data-manager/data-source.c b/tools/browser/data-manager/data-source.c
index af9205a..642389c 100644
--- a/tools/browser/data-manager/data-source.c
+++ b/tools/browser/data-manager/data-source.c
@@ -299,7 +299,7 @@ init_from_query (DataSource *source, xmlNodePtr node)
 							g_hash_table_new_full (g_str_hash, g_str_equal,
 									       g_free, NULL);
 
-					tmp = g_strdup_printf ("%s %d", source->priv->id, i);
+					tmp = g_strdup_printf ("%s %d", source->priv->id, i+1);
 					g_array_append_val (source->priv->export_names, tmp);
 					g_hash_table_insert (source->priv->export_columns, tmp,
 							     GINT_TO_POINTER (i + 1));
diff --git a/tools/browser/data-manager/spec-editor.c b/tools/browser/data-manager/spec-editor.c
index cbfdbeb..1532287 100644
--- a/tools/browser/data-manager/spec-editor.c
+++ b/tools/browser/data-manager/spec-editor.c
@@ -169,32 +169,6 @@ editor_changed_cb (GtkTextBuffer *buffer, SpecEditor *sped)
 	sped->priv->signal_editor_changed_id = g_timeout_add_seconds (1, (GSourceFunc) signal_editor_changed, sped);
 }
 
-static void help_expand_cb (GtkWidget *exp, SpecEditor *sped)
-{
-#define XML_SYNTAX_HELP _("<small>The XML tree's root node must be a <span foreground=\"#4e9a06\"><tt>&lt;data&gt;</tt></span>, which " \
-			  "is allowed to contain one or more data source definitions.\n" \
-			  "Each data source is defined by <span foreground=\"#4e9a06\"><tt>&lt;query&gt;</tt></span> or <span foreground=\"#4e9a06\"><tt>&lt;table&gt;</tt></span> nodes, both accepting the following optional attributes:\n" \
-			  " - <span foreground=\"#4e9a06\">\"id\"</span> to specify a data source string ID, used when linking data sources one to another;\n" \
-			  " - <span foreground=\"#4e9a06\">\"title\"</span> to specify a title.\n\n" \
-			  "Use the <span foreground=\"#4e9a06\"><tt>&lt;query&gt;</tt></span> tag to specify an SQL SELECT statement, as the contents of the tag. Linkage to other\n" \
-			  "data sources can be achieved using variables in the SELECT's SQL.\n\n" \
-			  "Use the <span foreground=\"#4e9a06\"><tt>&lt;table&gt;</tt></span> node to define a data source which will display the contents of a table. This tag:\n" \
-			  " - requires the <span foreground=\"#4e9a06\">\"name\"</span> attribute which represents the table name.\n" \
-			  " - can contain a <span foreground=\"#4e9a06\"><tt>&lt;depend&gt;</tt></span> node which defines a dependency on another data source with the \n" \
-			  "   <span foreground=\"#4e9a06\">\"foreign_key_table\"</span> attribute defining the name of the table to which there are foreign keys\n" \
-			  "   used to determine the dependency, and the <span foreground=\"#4e9a06\">\"id\"</span> attribute can specify a data source ID if different than\n" \
-			  "   the aforementioned table.\n"			\
-			  "</small>")
-	if (! sped->priv->help) {
-		sped->priv->help = gtk_label_new ("");
-		gtk_label_set_markup (GTK_LABEL (sped->priv->help), XML_SYNTAX_HELP);
-		gtk_label_set_ellipsize (GTK_LABEL (sped->priv->help), PANGO_ELLIPSIZE_END);
-		gtk_misc_set_alignment (GTK_MISC (sped->priv->help), 0., 0.);
-		gtk_container_add (GTK_CONTAINER (exp), sped->priv->help);
-		gtk_widget_show (sped->priv->help);
-	}
-}
-
 /**
  * spec_editor_new
  *
@@ -228,11 +202,6 @@ spec_editor_new (BrowserConnection *bcnc)
 	
 	gtk_box_pack_start (GTK_BOX (vbox), sw, TRUE, TRUE, 0);
 
-	exp = gtk_expander_new (_("XML syntax help"));
-	gtk_box_pack_start (GTK_BOX (vbox), exp, FALSE, FALSE, 0);
-	g_signal_connect (exp, "activate",
-			  G_CALLBACK (help_expand_cb), sped);
-
 #ifdef HAVE_GTKSOURCEVIEW
         sped->priv->text = gtk_source_view_new ();
         gtk_source_buffer_set_highlight_syntax (GTK_SOURCE_BUFFER (gtk_text_view_get_buffer (GTK_TEXT_VIEW (sped->priv->text))),
diff --git a/tools/browser/help/.gitignore b/tools/browser/help/.gitignore
new file mode 100644
index 0000000..ce040fc
--- /dev/null
+++ b/tools/browser/help/.gitignore
@@ -0,0 +1 @@
+gda-browser.omf
diff --git a/tools/browser/help/C/data-manager-perspective.page b/tools/browser/help/C/data-manager-perspective.page
new file mode 100644
index 0000000..80eb7ed
--- /dev/null
+++ b/tools/browser/help/C/data-manager-perspective.page
@@ -0,0 +1,93 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="data-manager-perspective">
+<info>
+  <title type="sort">1</title>
+  <link type="guide" xref="index#perspectives"/>
+</info>
+<title>The data manager perspective</title>
+<p>
+  Use the data manager perspective to navigate through the database's data. To switch
+  to this perspective, use the <guiseq><gui>Perspective</gui><gui>Data Manager</gui></guiseq>
+  menu, or the <keyseq><key>Ctrl</key><key>D</key></keyseq> shortcut.
+</p>
+<p>
+  The workflow in this perspective is organized around the definition of one or more <em>data sources</em>
+  (which selects data in the database) which, when executed, result in a data set displayed in
+  a tabular view. The perspective's work area
+</p>
+<p>
+  The perspective is devided in two horizontal panes: the left pane to keep favorite data sources set's
+  definitions, and the right pane being the action area, where each data source is executed and the
+  results presented in a tabular view.
+</p>
+<figure>
+  <title>Data manager perspective</title>
+  <desc>The data manager perspective, with two data sources</desc>
+  <media type="image" mime="image/png" src="figures/data-man-persp.png"/>
+</figure>
+<p>
+  In the figure above, there are two data sources: one for the 'customers' table and one for the
+  'orders' table (which here lists the orders from a customer), the later data source
+  depending on the former one as there is a foreign key from
+  the 'orders' table which references the 'customers' table. The two data sources have been
+  executed and the result is composed of two tabular views side by side.
+</p>
+<p>
+  Because the 'orders' data source
+  depends on the 'customers' data source, its corresponding view is on the right of the one
+  corresponding to the 'customers' data source.
+  Also when the row selection of the 'customers' view changes, the whole contents of the 'orders' view
+  is refreshed.
+</p>
+<section>
+  <title>Defining data sources</title>
+  <p>
+    The simplest data source
+    is a data source which represents all the data from a table, displayed when executed as a single
+    tabular view, as if one executed the <code>SELECT * FROM mytable</code> statement in
+    the <link xref="query-execution-perspective"/>.
+  </p>
+  <p>
+    The following figure shows the data sources editing mode (switch to editing mode using the
+    <media type="image" mime="image/png" src="figures/data-man-mode.png"/> toolbar button)
+    at the moment data sources can only be
+    defined using an <link xref="data-manager-xml-syntax">XML syntax</link>.
+  </p>
+  <figure>
+    <title>Data sources edition</title>
+    <desc>Editing data sources in the data manager perspetive</desc>
+    <media type="image" mime="image/png" src="figures/data-man-xmlcompose.png"/>
+  </figure>
+
+  <p>
+    The commands available through the command buttons are:
+  </p>
+  <list>
+    <item><p><gui>Clear</gui>: clears the XML editor</p></item>
+    <item><p><gui>Variables</gui>: shows/hide the <link xref="variables-syntax">variables</link> panel where you can give values to the variables
+	present in the SQL code of any data source's definition. The panel is automatically shown when a variable is detected in 
+	the SQL code</p></item>
+    <item><p><gui>Execute</gui>: executes the defined data sources</p></item>
+    <item><p><gui>View XML</gui>: toggles between the XML editor and the UI editor</p></item>
+    <item><p><gui>Help</gui>: shows some help</p></item>
+  </list>
+</section>
+<section>
+  <title>Executing defined data sources</title>
+  <p>
+    To execute a defined set of data sources, simply switch to execute mode using
+    the <media type="image" mime="image/png" src="figures/data-man-mode.png"/> toolbar button
+    or the <gui>Execute</gui> button.
+  </p>
+  <p>
+    The layout of tabular views for each data source is automatically generated in columns using the following
+    rule: if a data source B depends on a data source A, then its tabular view is displayed on
+    the right of the one for A.
+  </p>
+  <p>
+    Also if you change the selected row of tabular view of a data source A , then the tabular views of
+    all the data sources depending on A will also have their tabular view refreshed.
+  </p>
+</section>
+</page>
diff --git a/tools/browser/help/C/data-manager-xml-syntax.page b/tools/browser/help/C/data-manager-xml-syntax.page
new file mode 100644
index 0000000..ea160c7
--- /dev/null
+++ b/tools/browser/help/C/data-manager-xml-syntax.page
@@ -0,0 +1,146 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="data-manager-xml-syntax">
+<info>
+  <title type="sort">1</title>
+</info>
+<title>The data manager's XML syntax</title>
+<p>
+  The XML tree's root node must be a <code>&lt;data&gt;</code>, which
+  is allowed to contain one or more data source definitions.
+  Each data source is defined by <code>&lt;query&gt;</code> or <code>&lt;table&gt;</code> nodes,
+  both accepting the following optional attributes:
+</p>
+<list>
+  <item><p>"id" to specify a data source string ID, used when linking data sources one to another;</p></item>
+  <item><p>"title" to specify a title.</p></item>
+</list>
+<p>
+  It is of course possible to use both the <code>&lt;query&gt;</code> or <code>&lt;table&gt;</code> tags
+  in the same data sources specifications.
+</p>
+
+<section>
+  <title>Exported variables</title>
+  <p>
+    Each data source exports some variables which can be reused by other data sources to introduce
+    a dependency. When the data sources are executed, the contents of these exported variables are
+    reset depending on the row actually selected in the resulting tabular view. If no row is selected
+    then the variable is unset.
+  </p>
+  <p>
+    Any data source depending on a variable is executed again when the variable changes, and
+    in case the variable is unset, the data source's execution result is an empty data set.
+  </p>
+</section>
+<section>
+  <title>The <code>&lt;query&gt;</code> tag</title>
+  <p>
+    Use the <code>&lt;query&gt;</code> tag to specify an SQL SELECT statement, as the contents of the tag.
+    Linkage to other data sources can be achieved using <link xref="variables-syntax">variables</link> in the
+    SELECT's SQL.
+  </p>
+
+  <code><![CDATA[
+<data>
+  <query title="Customers" id="customers">
+    SELECT id, name FROM customers where name like ##name::string
+  </query>
+  <query title="Customer's details" id="cust_details">
+    SELECT * FROM customers WHERE id=##customers id::int
+  </query>
+</data>]]>
+  </code>
+  <p>
+    For example the previous XML specification defines two data sources:
+  </p>
+  <list>
+    <item><p>the <code>customers</code> data source which selects some fields from the
+	<em>customers</em> table, and which depends on a string variable named <code>name</code>.
+	This variable has to be set when the data sources are executed because it won't be exported
+	by any data source in this specification.</p></item>
+    <item><p>the <code>cust_details</code> data source which selects all the details of a customer
+	specified using its ID. This second data source depends on the previous one because the
+	<code>customers id</code> variable is exported from the <code>customers</code> data source.
+    </p></item>
+  </list>
+  <p>
+    Executing this data sources specification will create two tabular views: one where you can select
+    a customer, and one which displays all the attributes for the selected customer.
+  </p>
+
+  <section>
+    <title>Exported variables</title>
+    <p>
+      Each data source defined by a <code>&lt;query&gt;</code> tag exports the following variable for
+      each column of the resulting data set (the variable's type is the same as the column's type):
+    </p>
+    <list>
+      <item><p><code>&lt;data source ID&gt;@&lt;column position&gt;</code> where the column's position
+	  starts at 1</p></item>
+      <item><p><code>&lt;data source ID&gt;@&lt;column name&gt; if the data set's column is a table column</code></p></item>
+    </list>
+  </section>
+
+</section>
+
+<section>
+  <title>The <code>&lt;table&gt;</code> tag</title>
+  <p>
+    Use the <code>&lt;table&gt;</code> tag to define a data source which will display the contents of a table.
+    This tag:
+  </p>
+  <list>
+    <item><p>requires the "name" attribute which represents the table name.</p></item>
+    <item><p>can contain a <code>&lt;depend&gt;</code> node which defines a dependency on another
+	data source with
+	the "foreign_key_table" attribute defining the name of the table to which there are foreign keys
+	used to determine the dependency, and the "id" attribute can specify a data source ID if different than
+	the aforementioned table</p></item>
+  </list>
+
+  <code><![CDATA[
+<data>
+  <table name="customers"/>
+  <table name="orders">
+    <depend foreign_key_table="customers"/>
+  </table>
+</data>]]>
+  </code>
+  <p>
+    For example the previous XML specification defines two data sources:
+  </p>
+  <list>
+    <item><p>the <code>customers</code> data source which selects all the contents of the
+	<em>customers</em> table.</p></item>
+    <item><p>the <code>orders</code> data source which selects among contents of the <code>orders</code>
+	table, the rows which correspond to a row in the <code>customers</code> table (assuming here
+	that the <code>orders</code> references the <code>customers</code> table in some way).
+    </p></item>
+  </list>
+  <p>
+    Note in this example that:
+  </p>
+  <list>
+    <item><p>you don't have to specify the fields involved in the foreign key linking the
+	<code>orders</code> and <code>customers</code> tables</p></item>
+    <item><p>the data sources IDs have been assigned the names of the selected tables as no "id" attribute
+	has been specified for the <code>&lt;table&gt;</code> tags.</p></item>
+  </list>
+
+  <section>
+    <title>Exported variables</title>
+    <p>
+      Each data source defined by a <code>&lt;query&gt;</code> tag exports the following variable for
+      each table's column (the variable's type is the same as the column's type):
+    </p>
+    <list>
+      <item><p><code>&lt;data source ID&gt;@&lt;column name&gt;</code></p></item>
+      <item><p><code>&lt;data source ID&gt;@&lt;column position&gt;</code> where the column's position
+	  starts at 1</p></item>
+    </list>
+  </section>
+
+
+</section>
+</page>
diff --git a/tools/browser/help/C/diagram.page b/tools/browser/help/C/diagram.page
new file mode 100644
index 0000000..02c9b59
--- /dev/null
+++ b/tools/browser/help/C/diagram.page
@@ -0,0 +1,32 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="diagram">
+  <info>
+    <title type="sort">1</title>
+  </info>
+  <title>Diagrams</title>
+  <p>
+    Diagrams are present throughout the <app>gda-browser</app>, and are made of a canvas on which
+    graphical items are displayed (like tables for example).
+  </p>
+  <figure>
+    <title>Diagram</title>
+    <desc>Diagram showing some tables and their relations</desc>
+    <media type="image" mime="image/png" src="figures/diagram.png"/>
+  </figure>
+  <p>
+    The items can be moved around on the canvas (note that as long as the whole diagram fits in the
+    canvas, it remains centered on it). Other manipulations are possible:
+  </p>
+  <list>
+    <item><p>zooming in and out using the mouse's wheel, or through the contextual menu (right
+	click on the canvas); a zoom to fit the canvas is also available in the contextual menu</p></item>
+    <item><p>bring closer or moving away items from one another using the mouse's wheel while holding the
+    <key>Shift</key> key</p></item>
+    <item><p>arranging items linearly or radially, through the contextual menu</p></item>
+    <item><p>printing, through the contextual menu</p></item>
+    <item><p>exporting as PNG or SVG images, through the contextual menu</p></item>
+    <item><p>adding items, through the contextual menu</p></item>
+    <item><p>removing items, through the items's contextual menu</p></item>
+  </list>
+</page>
diff --git a/tools/browser/help/C/features.page b/tools/browser/help/C/features.page
new file mode 100644
index 0000000..951432a
--- /dev/null
+++ b/tools/browser/help/C/features.page
@@ -0,0 +1,20 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="features">
+  <info>
+    <title type="sort">1</title>
+    <link type="guide" xref="index#presentation"/>	
+  </info>
+  <title>Features</title>
+  <p>
+    <app>gda-browser</app>'s current features are:
+  </p>
+  <list>
+    <item><p>multiple simultaneous connections can be opened at once</p></item>
+    <item><p>multi threaded: each connection is handled in it own thread, meaning that no single
+	connection can lock the application</p></item>
+    <item><p>several windows can be opened for a single connection</p></item>
+    <item><p>full screen mode accessible to maximize the screen space usage</p></item>
+    <item><p>extensibility: the general framework is opened enough to add new integrated features</p></item>
+  </list>
+</page>
diff --git a/tools/browser/help/C/figures/cnc_open.png b/tools/browser/help/C/figures/cnc_open.png
new file mode 100644
index 0000000..4e93e85
Binary files /dev/null and b/tools/browser/help/C/figures/cnc_open.png differ
diff --git a/tools/browser/help/C/figures/data-man-mode.png b/tools/browser/help/C/figures/data-man-mode.png
new file mode 100644
index 0000000..80873f4
Binary files /dev/null and b/tools/browser/help/C/figures/data-man-mode.png differ
diff --git a/tools/browser/help/C/figures/data-man-persp.png b/tools/browser/help/C/figures/data-man-persp.png
new file mode 100644
index 0000000..4e0eccd
Binary files /dev/null and b/tools/browser/help/C/figures/data-man-persp.png differ
diff --git a/tools/browser/help/C/figures/data-man-xmlcompose.png b/tools/browser/help/C/figures/data-man-xmlcompose.png
new file mode 100644
index 0000000..3ebdca2
Binary files /dev/null and b/tools/browser/help/C/figures/data-man-xmlcompose.png differ
diff --git a/tools/browser/help/C/figures/diagram.png b/tools/browser/help/C/figures/diagram.png
new file mode 100644
index 0000000..22d611c
Binary files /dev/null and b/tools/browser/help/C/figures/diagram.png differ
diff --git a/tools/browser/help/C/figures/mainwin.png b/tools/browser/help/C/figures/mainwin.png
new file mode 100644
index 0000000..9328e64
Binary files /dev/null and b/tools/browser/help/C/figures/mainwin.png differ
diff --git a/tools/browser/help/C/figures/query-exec-persp.png b/tools/browser/help/C/figures/query-exec-persp.png
new file mode 100644
index 0000000..1212f3b
Binary files /dev/null and b/tools/browser/help/C/figures/query-exec-persp.png differ
diff --git a/tools/browser/help/C/figures/trans-begin.png b/tools/browser/help/C/figures/trans-begin.png
new file mode 100644
index 0000000..fd31602
Binary files /dev/null and b/tools/browser/help/C/figures/trans-begin.png differ
diff --git a/tools/browser/help/C/figures/trans-commit.png b/tools/browser/help/C/figures/trans-commit.png
new file mode 100644
index 0000000..383e8a1
Binary files /dev/null and b/tools/browser/help/C/figures/trans-commit.png differ
diff --git a/tools/browser/help/C/figures/trans-rollback.png b/tools/browser/help/C/figures/trans-rollback.png
new file mode 100644
index 0000000..9034cbf
Binary files /dev/null and b/tools/browser/help/C/figures/trans-rollback.png differ
diff --git a/tools/browser/help/C/general-ui.page b/tools/browser/help/C/general-ui.page
new file mode 100644
index 0000000..5d2bbe7
--- /dev/null
+++ b/tools/browser/help/C/general-ui.page
@@ -0,0 +1,36 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="general-ui">
+  <info>
+    <title type="sort">1</title>
+    <link type="guide" xref="index#presentation"/>
+  </info>
+  <title>General interface organization</title>
+  <p>
+    The <app>gda-browser</app> is composed of one or more top level windows, each window relating to a
+    single connection (which name is in its title). For any given connection, several windows can be opened
+    (use the <guiseq><gui>Window</gui><gui>New window</gui></guiseq> menu or
+    the <keyseq><key>Ctrl</key><key>N</key></keyseq> shortcut).
+  </p>
+  <figure>
+    <title>A connection window</title>
+    <desc>Window opened for the 'c1' connection (and the Schema browser prespective)</desc>
+    <media type="image" mime="image/png" src="figures/mainwin.png"/>
+  </figure>
+
+  <p>
+    Within each window, several <em>perspectives</em> are available which are adapted to
+    different activities:
+  </p>
+  <list>
+    <item><p>the <link xref="schema-browser-perspective">Schema browser perspective</link> to help understand the database's layout</p></item>
+    <item><p>the <link xref="query-execution-perspective">Query execution perspective</link> to execute any SQL command</p></item>
+    <item><p>the <link xref="data-manager-perspective">Data manager perspective</link> to navigate through the database's contents</p></item>
+  </list>
+  <p>
+    The currently displayed perspective can be changed individually for each window, and, as all perspectives 
+    have an action area composed of tabs, tabs can be moved from one window to the other if the source
+    and distination window are for the same connection, and display the same perspective (simply drag
+    and drop a tab from one window to the other using the tab's label as a handle).
+  </p>
+</page>
diff --git a/tools/browser/help/C/index.page b/tools/browser/help/C/index.page
new file mode 100644
index 0000000..2b301a2
--- /dev/null
+++ b/tools/browser/help/C/index.page
@@ -0,0 +1,38 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="guide"
+      id="index">
+  <info>
+    <credit type="author">
+      <name>Vivien Malerba</name>
+      <email>malerba gnome-db org</email>
+    </credit>
+  </info>
+
+  <title>Gda Browser Help</title>
+  <p><app>gda-browser</app> is a tool for database administrators: they can analyse database's schemas
+    to understand how data is organized, run SQL commands interractively, and in a broader way manage
+    the data contained in the databases.</p>
+
+  <p>Several connections to databases can be opened at once, allowing the user to work on multiple
+    databases at once (it is also possible to execute commands on several connections at the same time).</p>
+
+  <p>As <app>gda-browser</app> uses the <app>libgda</app> library, it can open connections to databases
+    for which a database driver (provider) exists in <app>libgda</app>
+    (<link href="http://www.oracle.com";>Oracle</link>, <link href="http://www.mysql.org";>MySQL</link>,
+    <link href="http://www.postgresql.org/";>PostgreSQL</link>, <link href="http://www.sqlite.org";>SQLite</link>,
+    MS Access (through the <link href="http://sourceforge.net/projects/mdbtools/";>MDBTools</link> library) and
+    <link href="http://java.sun.com/docs/books/tutorial/jdbc/index.html";>JDBC</link> are supported at
+    the moment). </p>
+
+  <section id="presentation" style="1column">
+    <title>Presentation</title>
+  </section>
+  <section id="perspectives" style="1column">
+    <title>Perspectives</title>
+  </section>
+
+  <section id="connections" style="1column">
+    <title>Connections management</title>
+  </section>
+
+</page>
diff --git a/tools/browser/help/C/legal.xml b/tools/browser/help/C/legal.xml
new file mode 100644
index 0000000..86d6173
--- /dev/null
+++ b/tools/browser/help/C/legal.xml
@@ -0,0 +1,9 @@
+<license xmlns="http://projectmallard.org/1.0/";
+         href="http://creativecommons.org/licenses/by-sa/3.0/";>
+<p>This work is licensed under a
+<link href="http://creativecommons.org/licenses/by-sa/3.0/";>Creative Commons
+Attribution-Share Alike 3.0 Unported License</link>.</p>
+<p>As a special exception, the copyright holders give you permission to copy,
+modify, and distribute the example code contained in this document under the
+terms of your choosing, without restriction.</p>
+</license>
diff --git a/tools/browser/help/C/query-execution-perspective.page b/tools/browser/help/C/query-execution-perspective.page
new file mode 100644
index 0000000..4334dea
--- /dev/null
+++ b/tools/browser/help/C/query-execution-perspective.page
@@ -0,0 +1,100 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="query-execution-perspective">
+<info>
+  <title type="sort">1</title>
+  <link type="guide" xref="index#perspectives"/>
+</info>
+<title>The query execution perspective</title>
+<p>
+  Use the query perspective to execute SQL statements. To switch
+  to this perspective, use the <guiseq><gui>Perspective</gui><gui>Query execution (SQL)</gui></guiseq>
+  menu, or the <keyseq><key>Ctrl</key><key>S</key></keyseq> shortcut.
+</p>
+<p>
+  The perspective is devided in two horizontal panes: the left pane for the user defined favorite statements,
+  and the right pane being the action area.
+</p>
+<figure>
+  <title>Query exec perspective</title>
+  <desc>The query exec prespective with one SELECT statement executed</desc>
+  <media type="image" mime="image/png" src="figures/query-exec-persp.png"/>
+</figure>
+
+<p>
+  The left
+  part of the perspective lists the favorite statements which have been user defined. Activating a
+  favorite (double clicking) resets the SQL text area's contents to the selected statement's SQL.
+</p>
+<p>
+  The right pane is composed of zero or more tabs where the SQL is entered and executed. In each tab
+  there is:
+</p>
+<list>
+  <item><p>an SQL area in the top left part</p></item>
+  <item><p>command buttons in the top right part</p></item>
+  <item><p>execution history in the lower left part</p></item>
+  <item><p>execution results in the lower right part</p></item>
+</list>
+
+<section>
+  <title>SQL area</title>
+  <p>
+    The SQL area is an SQL editor. The SQL can be any SQL understood by the database, with the exception
+    of <link xref="variables-syntax">variables</link> (which must have a specific syntax).
+  </p>
+  <p>
+    The keyboard shortcuts in the SQL editor are:
+  </p>
+  <list>
+    <item><p><keyseq><key>Ctrl</key><key>SPACE</key></keyseq> to obtain a completion list</p></item>
+    <item><p><keyseq><key>Ctrl</key><key>ENTER</key></keyseq> to execute the SQL code</p></item>
+    <item><p><keyseq><key>Ctrl</key><key>l</key></keyseq> to clear the editor</p></item>
+    <item><p><keyseq><key>Ctrl</key><key>Up</key></keyseq> and
+	<keyseq><key>Ctrl</key><key>Down</key></keyseq> to navigate through the editor's history</p></item>
+  </list>
+</section>
+
+<section>
+  <title>Command buttons</title>
+  <p>
+    The commands available through the command buttons are:
+  </p>
+  <list>
+    <item><p><gui>Clear</gui>: clears the editor (similar to the <keyseq><key>Ctrl</key><key>l</key></keyseq> shortcut)</p></item>
+    <item><p><gui>Variables</gui>: shows or hides the <link xref="variables-syntax">variables</link> panel where you can give values to the variables
+	present in the SQL code. The panel is automatically shown when a variable is detected in 
+	the SQL code</p></item>
+    <item><p><gui>Execute</gui>: executes the SQL code. If the SQL code contains some variables which have not been
+	set, then a popup first appears requesting the variables to be given values. This is similar
+	to the <keyseq><key>Ctrl</key><key>ENTER</key></keyseq> shortcut</p></item>
+    <item><p><gui>Indent</gui>: re-indents the SQL code (warning: this removes any comments)</p></item>
+    <item><p><gui>Favorites</gui>: adds the current SQL code to the favorites</p></item>
+  </list>
+</section>
+
+<section>
+  <title>Execution history</title>
+  <p>
+    The execution history part contains a list of the past executed statements, ordered by executaion date
+    along with an indication when the statement was executed (11 minutes in the figure above). Selecting
+    an history item displays the corresponding result in the execution results part.
+  </p>
+  <p>
+    The <gui>Copy</gui> button copies the currently selected history item's SQL code to the SQL editor, and the
+    <gui>Clear</gui> button removes all the history items.
+  </p>
+  <p>
+    Note that any given history item can also be removed individually using the <key>Suppr</key> key.
+  </p>
+</section>
+
+<section>
+  <title>Execution results</title>
+  <p>
+    The Execution results part displays the execution result of the currently selected execution
+    history item, as a table for SELECT statement, giving information for other types of
+    statement, or giving the execution error notice if the execution failed.
+  </p>
+</section>
+</page>
diff --git a/tools/browser/help/C/schema-browser-perspective.page b/tools/browser/help/C/schema-browser-perspective.page
new file mode 100644
index 0000000..596de7e
--- /dev/null
+++ b/tools/browser/help/C/schema-browser-perspective.page
@@ -0,0 +1,43 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="schema-browser-perspective">
+<info>
+  <title type="sort">1</title>
+  <link type="guide" xref="index#perspectives"/>
+</info>
+<title>The schema browser perspective</title>
+<p>
+  Use the schema browser perspective to understand the database's organisation (schema). To switch
+  to this perspective, use the <guiseq><gui>Perspective</gui><gui>Schema browser</gui></guiseq> menu, or
+  the <keyseq><key>Ctrl</key><key>B</key></keyseq> shortcut.
+</p>
+<p>
+  The perspective is devided in two horizontal panes: the left pane for the user defined favorites, and
+  the right pane being the action area.
+</p>
+<figure>
+  <title>Schema browser perspective's default view</title>
+  <desc>The default Schema browser prespective</desc>
+  <media type="image" mime="image/png" src="figures/mainwin.png"/>
+</figure>
+
+<p>
+  The left
+  part of the perspective lists the favorite database objects or diagrams. Double clicking on a favorite
+  opens its properties in the right pane.
+</p>
+<p>
+  The right pane is composed of several types of tabs:
+</p>
+<list>
+  <item><p>a tab listing all the database's tables and views, in a <em>cloud</em> view where
+      the tables with the more relations to other tables being displayed in a larger font;
+      this tab is always present</p></item>
+  <item><p>zero or more tabs representing a table or views' properties: the list of columns,
+      the list of constraints (primary or foreign keys, and unique constraints), a <link xref="diagram">diagram</link> showing the
+      related tables, and an area to define display preferences for each column's data</p></item>
+  <item><p>zero or more <link xref="diagram">diagrams</link> in which any number of tables can be represented, where they are
+      linked using their relations (as foreign key constraints)</p></item>
+</list>
+
+</page>
diff --git a/tools/browser/help/C/transactions.page b/tools/browser/help/C/transactions.page
new file mode 100644
index 0000000..9fbdee5
--- /dev/null
+++ b/tools/browser/help/C/transactions.page
@@ -0,0 +1,30 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="transactions">
+  <info>
+    <title type="sort">1</title>
+    <link type="topic" xref="query-execution-perspective"/>
+    <link type="guide" xref="index#connections"/>
+  </info>
+  <title>Transactions</title>
+  <p>
+    Transactions can be started, committed or rolled back on a per connection basis:
+  </p>
+  <list>
+    <item><p>use the <media type="image" mime="image/png" src="figures/trans-begin.png"/> toolbar 
+    button to start a transaction</p></item>
+    <item><p>use the <media type="image" mime="image/png" src="figures/trans-commit.png"/> toolbar 
+    button to commit the current transaction (apply all the changes)</p></item>
+    <item><p>use the <media type="image" mime="image/png" src="figures/trans-rollback.png"/> toolbar 
+    button to abort the current transaction (forget all the changes)</p></item>
+  </list>
+  <note>
+    <p>
+      A transaction may be started automatically when executin a SELECT statement which involves
+      binary objects (BLOBs), and the transaction may be locked while the resulting data set is
+      kept in memory (to get rid of a data set in a
+      <link xref="query-execution-perspective">query execution perspective</link>, clear the
+      history item relating to the data set).
+    </p>
+  </note>
+</page>
diff --git a/tools/browser/help/C/variables.page b/tools/browser/help/C/variables.page
new file mode 100644
index 0000000..a9c1c4b
--- /dev/null
+++ b/tools/browser/help/C/variables.page
@@ -0,0 +1,41 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="variables-syntax">
+  <info>
+    <title type="sort">1</title>
+    <link type="topic" xref="query-execution-perspective"/>
+    <link type="topic" xref="data-manager-perspective"/>
+  </info>
+  <title>Variables in SQL code</title>
+  <p>
+    Variables (sometimes refered to as <em>placeholders</em>) are places in SQL code
+    which are replaced by actual values when the SQL code is executed. The benefits are
+    faster execution times (as the SQL code is parsed only once) and a protection against
+    SQL injection vulnerabilities.
+  </p>
+  <p>
+    Variables can be used in any SQL code, and are defined using the following syntax:
+  </p>
+  <code>
+<![CDATA[##<variable name>[::<variable type>[::NULL]]]]></code>
+  <p>
+    Notes:
+  </p>
+  <list>
+    <item><p>the <em>variable name</em> can contain any SQL identifier character or among the
+	<code>+-.|@?</code>characters (no space allowed)</p></item>
+    <item><p>the <em>variable type</em> can be among: <code>string</code>, <code>boolean</code>, 
+	<code>int</code>, <code>date</code>, <code>time</code>, <code>timestamp</code>, 
+	<code>guint</code>, <code>blob</code> and <code>binary</code></p></item>
+    <item><p>the <code>::NULL</code> can be appended to specify that the variable may take the
+	special <code>NULL</code> value.</p></item>
+  </list>
+  <p>
+    Examples:
+  </p>
+  <code>
+##name::string
+##id::int::NULL
+##sales 3::date::NULL
+##customers id::int</code>
+</page>
diff --git a/tools/browser/help/Makefile.am b/tools/browser/help/Makefile.am
new file mode 100644
index 0000000..9e69c83
--- /dev/null
+++ b/tools/browser/help/Makefile.am
@@ -0,0 +1,33 @@
+include $(top_srcdir)/gnome-doc-utils.make
+
+DOC_ID = gda-browser
+
+DOC_INCLUDES = legal.xml
+DOC_FIGURES = \
+	figures/cnc_open.png \
+	figures/data-man-mode.png \
+	figures/data-man-persp.png \
+	figures/data-man-xmlcompose.png \
+	figures/diagram.png \
+	figures/mainwin.png \
+	figures/query-exec-persp.png \
+	figures/trans-begin.png \
+	figures/trans-commit.png \
+	figures/trans-rollback.png
+
+DOC_PAGES = \
+	data-manager-perspective.page \
+	data-manager-xml-syntax.page \
+	diagram.page \
+	features.page \
+	general-ui.page \
+	index.page \
+	legal.xml \
+	query-execution-perspective.page \
+	schema-browser-perspective.page \
+	transactions.page \
+	variables.page
+
+DOC_LINGUAS = 
+
+dist-hook: doc-dist-hook
diff --git a/tools/browser/help/gda-browser.omf.in b/tools/browser/help/gda-browser.omf.in
new file mode 100644
index 0000000..1c7bd0d
--- /dev/null
+++ b/tools/browser/help/gda-browser.omf.in
@@ -0,0 +1,10 @@
+<?xml version="1.0" standalone="no"?>
+<omf>
+  <resource>
+    <subject category="GNOME|Utilities"/>
+    <type>manual</type>
+    <relation seriesid="06406397-f65a-2194-090b-8d8e95958b5f00"/>
+    <rights type="GNU FDL" license.version="1.1" holder="Vivien Malerba"/>
+  </resource>
+</omf>
+
diff --git a/tools/browser/support.c b/tools/browser/support.c
index c3363c6..1bf6fdc 100644
--- a/tools/browser/support.c
+++ b/tools/browser/support.c
@@ -220,6 +220,81 @@ browser_show_notice (GtkWindow *parent, const gchar *context, const gchar *forma
 	}
 }
 
+/**
+ * browser_show_help
+ * @topic: the help topic, or %NULL for the global index
+ */
+void
+browser_show_help (GtkWindow *parent, const gchar *topic)
+{
+	GdkScreen *screen;
+	GError *error = NULL;
+
+	const gchar *const *langs;
+	gchar *uri = NULL;
+	gint i;
+	
+	langs = g_get_language_names ();
+	for (i = 0; langs[i]; i++) {
+		const gchar *lang;
+		lang = langs[i];
+		if (strchr (lang, '.'))
+			continue;
+
+		uri = gda_gbr_get_file_path (GDA_DATA_DIR, "gnome", "help", "gda-browser", lang, NULL);
+
+		if (g_file_test (uri, G_FILE_TEST_EXISTS)) {
+			if (topic) {
+				gchar *tmp;
+				tmp = g_strdup_printf ("%s?%s", uri, topic);
+				g_free (uri);
+				uri = tmp;
+			}
+			break;
+		}
+		g_free (uri);
+		uri = NULL;
+	}
+	/*g_print ("URI [%s]\n", uri);*/
+	if (uri == NULL) {
+		browser_show_error (NULL,  _("Unable to display help. Please make sure the  "
+					     "documentation package is installed."));
+		return;
+	}
+
+#if GTK_CHECK_VERSION(2,14,0)
+	gchar *ruri;
+
+	screen = gtk_widget_get_screen ((GtkWidget*) parent);
+	ruri = g_strdup_printf ("ghelp:%s", uri);
+	gtk_show_uri (screen, ruri,  gtk_get_current_event_time (), &error);
+	g_free (ruri);
+
+#else
+	gchar *command;
+	
+	command = g_strconcat ("gnome-help ghelp://", uri,  NULL);
+	screen = gtk_widget_get_screen (GTK_WIDGET (parent));
+	gdk_spawn_command_line_on_screen (screen, command, &error);
+	g_free (command);
+#endif
+	if (error) {
+		GtkWidget *d;
+		d = gtk_message_dialog_new (parent, 
+					    GTK_DIALOG_MODAL | GTK_DIALOG_DESTROY_WITH_PARENT,
+					    GTK_MESSAGE_ERROR, GTK_BUTTONS_CLOSE, 
+					    "%s", _("Unable to open help file"));
+		gtk_message_dialog_format_secondary_text (GTK_MESSAGE_DIALOG (d),
+							  "%s", error->message);
+		g_signal_connect (d, "response", G_CALLBACK (gtk_widget_destroy), NULL);
+		gtk_window_present (GTK_WINDOW (d));
+		
+		g_error_free (error);
+	}
+
+	g_free (uri);
+}
+
 static GtkWidget *
 _browser_make_tab_label (const gchar *label,
 			 GtkWidget *img, gboolean with_close,
diff --git a/tools/browser/support.h b/tools/browser/support.h
index 8f15e1f..accae8d 100644
--- a/tools/browser/support.h
+++ b/tools/browser/support.h
@@ -32,6 +32,7 @@ BrowserConnection *browser_connection_open (GError **error);
 gboolean           browser_connection_close (GtkWindow *parent, BrowserConnection *bcnc);
 void               browser_show_error (GtkWindow *parent, const gchar *format, ...);
 void               browser_show_notice (GtkWindow *parent, const gchar *context, const gchar *format, ...);
+void               browser_show_help (GtkWindow *parent, const gchar *topic);
 
 GtkWidget*         browser_make_tab_label_with_stock (const gchar *label,
 						      const gchar *stock_id, gboolean with_close,
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]