GNOME.org
 

[gnome-devel-docs] Add user help tutorials for new developer overview

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

    Add user help tutorials for new developer overview

 new-platform-overview/dev-help-appmenu.page |   96 +++++++++++++++++++++++++++
 new-platform-overview/dev-help-build.page   |   70 +++++++++++++++++++
 new-platform-overview/dev-help-context.page |   62 +++++++++++++++++
 new-platform-overview/dev-help.page         |   61 ++++++++++++-----
 4 files changed, 270 insertions(+), 19 deletions(-)
---
diff --git a/new-platform-overview/dev-help-appmenu.page b/new-platform-overview/dev-help-appmenu.page
new file mode 100644
index 0000000..712f912
--- /dev/null
+++ b/new-platform-overview/dev-help-appmenu.page
@@ -0,0 +1,96 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      xmlns:its="http://www.w3.org/2005/11/its";
+      type="topic" style="task"
+      id="dev-help-appmenu">
+
+  <info>
+    <link type="next" xref="dev-help-context"/>
+    <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="cc-by-sa-3-0.xml" xmlns="http://www.w3.org/2001/XInclude"/>
+
+  </info>
+
+  <title>Add Help item to the app menu in the top bar</title>
+
+  <links type="series" style="floatend">
+    <title>Set up help</title>
+  </links>
+
+  <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 <code>var item = new GLib.MenuItem (_("_Help"), "app.help");</code> 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>
+
+</page>
diff --git a/new-platform-overview/dev-help-build.page b/new-platform-overview/dev-help-build.page
new file mode 100644
index 0000000..3906b52
--- /dev/null
+++ b/new-platform-overview/dev-help-build.page
@@ -0,0 +1,70 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      xmlns:its="http://www.w3.org/2005/11/its";
+      type="topic" style="task"
+      id="dev-help-build">
+
+  <info>
+     <link type="next" xref="dev-help-appmenu"/>
+     <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="cc-by-sa-3-0.xml" xmlns="http://www.w3.org/2001/XInclude"/>
+
+  </info>
+
+  <title>Set up your buildsystem</title>
+
+  <links type="series" style="floatend">
+    <title>Set up help</title>
+  </links>
+
+  <p>Once you have some Mallard <file>.page</file> files, place them into the
+  <file>help/C/</file> folder among the rest of your code files.</p>
+
+  <p>You will also need <app>yelp-tools</app> installed to bundle
+  Mallard documentation into your application.</p>
+
+  <p>Modify these 3 files to include instructions how to install user help
+  files into the <file>usr/share/help/$lang/HELP_ID</file> folder:</p>
+
+  <p>Add the following lines in the file <em style="strong"><file>configure.ac</file></em>.</p>
+  
+  <code>YELP_HELP_INIT</code>
+  
+  <code>help/Makefile</code>
+  <p>This line should go under <file>AC_CONFIG_FILES</file>.</p>
+  <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>
+               
+  <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>
+
+</page>
diff --git a/new-platform-overview/dev-help-context.page b/new-platform-overview/dev-help-context.page
new file mode 100644
index 0000000..bb6348e
--- /dev/null
+++ b/new-platform-overview/dev-help-context.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="dev-help-context">
+
+  <info>
+    <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="cc-by-sa-3-0.xml" xmlns="http://www.w3.org/2001/XInclude"/>
+
+  </info>
+
+  <title>Add context help</title>
+
+  <links type="series" style="floatend">
+    <title>Set up help</title>
+  </links>
+
+  <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:
+  <code>help:cheese/index#preferences</code>.</p>
+
+  <p>The following code lines are from an application
+  <app href="https://git.gnome.org/browse/cheese/tree/src/cheese-main.vala";>Cheese</app>
+  written in Vala, but should be fairly similar in other languages.</p>
+
+<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>
+
+</page>
diff --git a/new-platform-overview/dev-help.page b/new-platform-overview/dev-help.page
index 2c912b5..25cff20 100644
--- a/new-platform-overview/dev-help.page
+++ b/new-platform-overview/dev-help.page
@@ -1,34 +1,57 @@
 <page xmlns="http://projectmallard.org/1.0/";
+      xmlns:its="http://www.w3.org/2005/11/its";
       type="topic" style="task"
       id="dev-help">
+
   <info>
-    <link type="guide" xref="index" group="help"/>
-  
-    <revision version="0.1" date="2012-02-19" status="stub"/>
+     <link type="guide" xref="index#dev"/>
+     <link type="next" xref="dev-help-build"/>
+     <link type="seealso" xref="dev-translate"/>
+
+     <revision version="0.1" date="2013-06-18" status="stub"/>
 
     <credit type="author copyright">
-      <name>Phil Bull</name>
-      <email>philbull gmail com</email>
-      <years>2012</years>
+      <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="cc-by-sa-3-0.xml" xmlns="http://www.w3.org/2001/XInclude"/>
+
+    <desc>Introduction</desc>
 
-    <desc>Integrate user assistance features and accessibility support.</desc>
   </info>
 
-  <title>Help and accessibility tools</title>
+  <title>Include user help in your application</title>
+
+  <links type="series" style="floatend">
+    <title>Set up help</title>
+  </links>
+
+  <p>Your application will be more valued, look more professional and be better
+  appreciated by the users if it is properly documented. </p>
 
-  <comment>
-    <cite date="2012-02-19" href="mailto:philbull gmail com">Phil Bull</cite>
-    <p>This assumes the reader knows how to.... By the end of this page,
-    the reader will be able to....</p>
-  </comment>
+  <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>Short introductory text...</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>
 
-  <steps>
-    <item><p>First step...</p></item>
-    <item><p>Second step...</p></item>
-    <item><p>Third step...</p></item>
-  </steps>
+  <note style="warning">
+    <p>You will need <em>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]