GNOME.org
 

[gnome-devel-docs/wip/reorganization] docs: <Adding user help tutorials for dev docs.>

commit a08361fc8efa36f57906720fa64fd91e2abdb5e2
Author: Radina Matic <radina matic gmail com>
Date:   Tue Jun 18 14:34:13 2013 -0400

    docs: <Adding user help tutorials for dev docs.>

 tutorials/C/user-help-integration-app-menu.page    |  101 ++++++++++++++++++++
 .../C/user-help-integration-context-help.page      |   62 ++++++++++++
 tutorials/C/user-help-integration-install.page     |   88 +++++++++++++++++
 tutorials/C/user-help-intro.page                   |   42 ++++++++
 4 files changed, 293 insertions(+), 0 deletions(-)
---
diff --git a/tutorials/C/user-help-integration-app-menu.page b/tutorials/C/user-help-integration-app-menu.page
new file mode 100644
index 0000000..452bb36
--- /dev/null
+++ b/tutorials/C/user-help-integration-app-menu.page
@@ -0,0 +1,101 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      xmlns:its="http://www.w3.org/2005/11/its";
+      type="topic" style="task"
+      id="user-help-int-app-menu">
+  <info>
+     <link type="seealso" xref="user-help-int-install"/>
+     <link type="seealso" xref="user-help-int-context-help"/>
+     <revision version="0.1" date="2013-06-18" status="stub"/>
+
+    <credit type="author copyright">
+      <name>Radina Matic</name>
+      <email its:translate="no">radina matic gmail com</email>
+      <years>2013</years>
+    </credit>
+    <credit type="copyright editor">
+      <name></name>
+      <email its:translate="no"></email>
+      <years></years>
+    </credit>
+
+    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>
+
+  </info>
+
+  <title>Integrate documentation in your application - App Menu</title>
+
+
+
+<section id="app-menu">
+   <title>Add Help item to the app menu in the top bar</title>
+
+  <p>If your application has an app menu, follow these 3 steps to add the Help item:</p>
+
+<note style="warning">
+  <p>The following code lines are from an application <link 
href="https://git.gnome.org/browse/cheese/tree/src/cheese-main.vala";><app>Cheese</app></link> written in 
Vala, but should be fairly similar in other languages.</p>
+</note>
+
+
+<list>
+
+  <item><p>Define the action by adding the <em style="strong"><file>{ "help", on_help }</file></em> line.</p>
+
+<code>
+   private const GLib.ActionEntry action_entries[] = {
+        { "shoot", on_shoot },
+        { "mode", on_action_radio, "s", "'photo'", on_mode_change },
+        { "fullscreen", on_action_toggle, null, "false", on_fullscreen_change },
+        { "effects", on_action_toggle, null, "false", on_effects_change },
+        { "preferences", on_preferences },
+        { "about", on_about },
+        <em style="strong">{ "help", on_help },</em>
+        { "quit", on_quit }
+    };
+
+   add_action_entries (action_entries, my_Gtk_Application);
+
+</code>
+</item>
+
+<item><p>Create the menu item with <em style="strong"><file>var item = new GLib.MenuItem (_("_Help"), 
"app.help");</file></em> line, and define the F1 shortcut attribute.</p>
+
+<code>
+// Create the menus.
+            var menu = new GLib.Menu ();
+            var section = new GLib.Menu ();
+            
+            <em style="strong">var item = new GLib.MenuItem (_("_Help"), "app.help");
+            item.set_attribute ("accel", "s", "F1");</em>
+            section.append_item (item);
+           
+</code>
+</item>
+
+<item><p>Define the function that will open the Yelp window and load the help file of your application. In 
the example below, the code <em style="strong"><file>"help:cheese"</file></em> will open Yelp and tell it to 
load the Mallard files for the Cheese app.</p>
+
+<code>
+   /**
+     * Show the Cheese help contents.
+     */
+    private void on_help ()
+    {
+        var screen = main_window.get_screen ();
+        try
+        {
+            Gtk.show_uri (screen, <em style="strong">"help:cheese"</em>, Gtk.get_current_event_time ());
+        }
+        catch (Error err)
+        {
+            message ("Error opening help: %s", err.message);
+        }
+    }
+
+</code>
+</item>
+
+</list>
+
+</section>
+
+
+</page>
diff --git a/tutorials/C/user-help-integration-context-help.page 
b/tutorials/C/user-help-integration-context-help.page
new file mode 100644
index 0000000..a679d23
--- /dev/null
+++ b/tutorials/C/user-help-integration-context-help.page
@@ -0,0 +1,62 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      xmlns:its="http://www.w3.org/2005/11/its";
+      type="topic" style="task"
+      id="user-help-int-context-help">
+  <info>
+     <link type="seealso" xref="user-help-int-install"/>
+     <link type="seealso" xref="user-help-int-app-menu"/>
+     <revision version="0.1" date="2013-06-17" status="stub"/>
+
+    <credit type="author copyright">
+      <name>Radina Matic</name>
+      <email its:translate="no">radina matic gmail com</email>
+      <years>2013</years>
+    </credit>
+    <credit type="copyright editor">
+      <name></name>
+      <email its:translate="no"></email>
+      <years></years>
+    </credit>
+
+    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>
+
+  </info>
+
+  <title>Integrate documentation in your application - Context Help</title>
+
+
+ <section id="context-help">
+   <title>Add context help</title>
+
+  <p>Sometimes you will want to open a specific Mallard page (or just a section of it) that refers to a 
specific window or feature of your application. In the example below, there is button in the Preferences 
dialog of Cheese app that opens the "preferences" section of the index.page Mallard file of Cheese help. The 
code looks like this: <em style="strong"><file>"help:cheese/index#preferences"</file></em>.</p>
+
+<note style="warning">
+  <p>The following code lines are from an application <link 
href="https://git.gnome.org/browse/cheese/tree/src/cheese-main.vala";><app>Cheese</app></link> written in 
Vala, but should be fairly similar in other languages.</p>
+</note>
+
+<code>
+/**
+   * Show the help for the preferences dialog.
+   *
+   * @param button the help button
+   */
+  public void on_dialog_help (Gtk.Button button)
+  {
+    try
+    {
+      Gtk.show_uri (this.dialog.get_screen (), <em style="strong">"help:cheese/index#preferences"</em>,
+        Gdk.CURRENT_TIME);
+    }
+    catch
+    {
+      warning ("%s", "Error showing help");
+    }
+  }
+
+</code>
+
+
+
+ </section>
+
+</page>
diff --git a/tutorials/C/user-help-integration-install.page b/tutorials/C/user-help-integration-install.page
new file mode 100644
index 0000000..d982dfd
--- /dev/null
+++ b/tutorials/C/user-help-integration-install.page
@@ -0,0 +1,88 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      xmlns:its="http://www.w3.org/2005/11/its";
+      type="topic" style="task"
+      id="user-help-int-install">
+  <info>
+     <link type="seealso" xref="user-help-int-app-menu"/>
+     <link type="seealso" xref="user-help-int-context-help"/>
+     <revision version="0.1" date="2013-06-18" status="stub"/>
+
+    <credit type="author copyright">
+      <name>Radina Matic</name>
+      <email its:translate="no">radina matic gmail com</email>
+      <years>2013</years>
+    </credit>
+    <credit type="copyright editor">
+      <name></name>
+      <email its:translate="no"></email>
+      <years></years>
+    </credit>
+
+    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>
+
+  </info>
+
+  <title>Integrate documentation in your application - Installation</title>
+
+<section id="install">
+   <title>Installation of user docs files</title>
+
+  <p>Once you have some Mallard .page files, place them into the <em style="strong">help/C/</em> folder 
among the rest of your code files.</p>
+
+<note style="warning">
+<p>GNOME applications use <em style="strong">autotools</em> to build installers. </p>
+</note>
+
+<note style="warning">
+<p>You will also need <em style="strong">yelp-tools</em> installed to bundle Mallard documentation into your 
application.</p>
+</note>
+
+
+ <p>Modify these 3 files to include instructions how to install user help files into the <em 
style="strong"><code>usr/share/help/$lang/HELP_ID</code></em> folder:</p>
+
+<list>
+  <item><p>Add the following lines in the file <em style="strong"><file>configure.ac</file></em>.</p>
+    <steps>
+       <item>
+          <code>YELP_HELP_INIT</code>
+       </item>
+
+       <item>
+          <code>help/Makefile</code>
+               <p>This line should go under <file>AC_CONFIG_FILES</file>.</p>
+       </item>
+
+     </steps>
+
+  </item>
+
+  <item><p>Add the following line at the begining of the <em style="strong"><file>Makefile.am 
</file></em>file.</p>
+       <code>SUBDIRS = po help</code>
+
+  </item>
+               
+  <item><p>Write the <em style="strong"><file>help/Makefile.am</file></em> file. The most important line 
defines the ID of your app: <em style="strong"><code>HELP_ID = name_of_application</code></em>.</p>
+
+<code>
+ YELP_HELP_RULES@
+
+HELP_ID = name_of_application
+
+HELP_MEDIA = \
+       figures/icon.png
+       # list of media files used in user help
+       # in case of no media files leave empty
+
+HELP_FILES = \
+       index.page \
+       introduction.page
+       # list of Mallard .page files
+
+HELP_LINGUAS = ca cs de el en_GB es fi fr gl hu id 
+       # in case of no translations leave empty
+</code>
+</item>
+</list>
+</section> 
+
+</page>
diff --git a/tutorials/C/user-help-intro.page b/tutorials/C/user-help-intro.page
new file mode 100644
index 0000000..a489a96
--- /dev/null
+++ b/tutorials/C/user-help-intro.page
@@ -0,0 +1,42 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      xmlns:its="http://www.w3.org/2005/11/its";
+      type="topic" style="task"
+      id="user-help-intro">
+  <info>
+     <link type="seealso" xref="user-help-int-install"/>
+     <link type="seealso" xref="user-help-int-app-menu"/>
+     <link type="seealso" xref="user-help-int-context-help"/>
+     <link type="seealso" xref="translation"/>
+
+     <revision version="0.1" date="2013-06-18" status="stub"/>
+
+    <credit type="author copyright">
+      <name>Radina Matic</name>
+      <email its:translate="no">radina matic gmail com</email>
+      <years>2013</years>
+    </credit>
+    <credit type="copyright editor">
+      <name></name>
+      <email its:translate="no"></email>
+      <years></years>
+    </credit>
+
+    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>
+
+       <desc>Introduction</desc>
+
+  </info>
+
+  <title>Include user help in your application</title>
+
+  <p>Your application will be more valued, look more professional and be better appreciated by the users if 
it is properly documented. </p>
+
+  <p>In the following tutorials you can read about all the important issues to keep in mind while writing 
the user documentation, and the procedure to properly include it into your code so it can be easily accessed 
by the users.</p>
+
+  <p>You can write user help in various formats, but we recommend <link 
href="http://www.projectmallard.org/";>Mallard</link>. GNOME applications use Mallard markup language which 
makes easier to provide better help to users. Mallard documents are topic-oriented: users can easily find a 
specific topic they are interested in, and not read the whole user manual. You can learn more at <link 
href="http://www.projectmallard.org/";>Mallard website</link>.</p>
+
+<note style="warning">
+<p>You will need <em style="strong">yelp-tools</em> package installed to bundle Mallard documentation into 
your application.</p>
+</note>
+
+</page>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]