GNOME.org
 

[gnome-devel-docs] Review help guide in new platform overview

commit 0d1a41bb9a5da0983211aebd3bb893a61ea3d115
Author: Ekaterina Gerasimova <kittykat3756 gmail com>
Date:   Wed Jun 19 11:07:55 2013 -0400

    Review help guide in new platform overview

 new-platform-overview/dev-help-appmenu.page |   96 ++++++++++++--------------
 new-platform-overview/dev-help-build.page   |   47 ++++++-------
 new-platform-overview/dev-help-context.page |   62 -----------------
 new-platform-overview/dev-help-write.page   |   97 +++++++++++++++++++++++++++
 new-platform-overview/dev-help.page         |   48 +++++--------
 5 files changed, 180 insertions(+), 170 deletions(-)
---
diff --git a/new-platform-overview/dev-help-appmenu.page b/new-platform-overview/dev-help-appmenu.page
index 712f912..f274c5d 100644
--- a/new-platform-overview/dev-help-appmenu.page
+++ b/new-platform-overview/dev-help-appmenu.page
@@ -4,93 +4,85 @@
       id="dev-help-appmenu">
 
   <info>
-    <link type="next" xref="dev-help-context"/>
-    <revision version="0.1" date="2013-06-18" status="stub"/>
+    <link type="seealso" xref="dev-help"/>
+    <revision version="0.1" date="2013-06-19" 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 type="editor">
+      <name>Ekaterina Gerasimova</name>
+      <email its:translate="no">kittykat3756 gmail com</email>
+      <years>2013</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>
+  <title>Add <gui>Help</gui> to the application menu</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>
-
+  <p>Most GNOME applications should have an application menu. The
+  <gui style="menuitem">Help</gui> menu item should go above the
+  <gui style="menuitem">About</gui> menu item.</p>
 
-<list>
+  <example>
+  <note>
+    <p>The example, based on
+    <app href="https://git.gnome.org/browse/cheese/tree/src/cheese-main.vala";>Cheese</app>,
+    assumes that your application is written in Vala. It will be slightly
+    different for other languages.</p>
+  </note>
 
-  <item><p>Define the action by adding the <em style="strong"><file>{ "help", on_help }</file></em> line.</p>
-
-<code>
+  <p>Add the <gui style="menuitem">Help</gui> item to the list of actions:</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 },
+        <input>{ "help", on_help },</input>
         { "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>
+  <p>Add the <gui style="menuitem">Help</gui> menu item to the application
+  menu:</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);
-           
+  var menu = new GLib.Menu ();
+  var section = new GLib.Menu ();
+
+  <input>var item = new GLib.MenuItem (_("_Help"), "app.help");
+  item.set_attribute ("accel", "s", "F1");
+  section.append_item (item);</input>
 </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>
+  <p>Open <app>Yelp</app> when the <gui style="menuitem">Help</gui> button is
+  clicked:</p>
 
 <code>
-   /**
-     * Show the Cheese help contents.
-     */
-    private void on_help ()
+  private void on_help ()
+  {
+    var screen = main_window.get_screen ();
+    try
     {
-        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);
-        }
+      Gtk.show_uri (screen, <input>"help:cheese"</input>, Gtk.get_current_event_time ());
     }
-
+    catch (Error err)
+    {
+      message ("Error opening help: %s", err.message);
+    }
+  }
 </code>
-</item>
-</list>
 
+  <p>To link to a section on the <file>index.page</file>, use
+  <code>"help:<input>applicationname</input>/index#<input>sectionid</input>"</code>.</p>
+
+  </example>
 </page>
diff --git a/new-platform-overview/dev-help-build.page b/new-platform-overview/dev-help-build.page
index 3906b52..2050111 100644
--- a/new-platform-overview/dev-help-build.page
+++ b/new-platform-overview/dev-help-build.page
@@ -12,9 +12,9 @@
       <email its:translate="no">radina matic gmail com</email>
       <years>2013</years>
     </credit>
-    <credit type="copyright editor">
-      <name></name>
-      <email its:translate="no"></email>
+    <credit type="editor">
+      <name>Ekaterina Gerasimova</name>
+      <email its:translate="no">kittykat3756 gmail com</email>
       <years></years>
     </credit>
 
@@ -22,49 +22,44 @@
 
   </info>
 
-  <title>Set up your buildsystem</title>
+  <title>Set up your build system</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>Help is normally installed into the
+  <file its:translate="no">usr/share/help/$lang/HELP_ID</file> directory.</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>
+  <p>Add the following lines in the file <file>configure.ac</file>:</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>AC_CONFIG_FILES([
+help/Makefile
+])</code>
 
+  <p>Add the following line to the <file>Makefile.am</file>:</p>
+  <code>SUBDIRS = help</code>
+               
+  <p>Add a <file>help/Makefile.am</file>, it should look like:</p>
 <code>
 @YELP_HELP_RULES@
 
-HELP_ID = name_of_application
+HELP_ID = <input>applicationname</input>
 
+# Media files
 HELP_MEDIA = \
        figures/icon.png
-       # list of media files used in user help
-       # in case of no media files leave empty
 
+# Help pages
 HELP_FILES = \
        index.page \
-       introduction.page
-       # list of Mallard .page files
+       introduction.page \
+       anotherpage.page
 
-HELP_LINGUAS = ca cs de el en_GB es fi fr gl hu id 
-       # in case of no translations leave empty
+# Translated languages
+HELP_LINGUAS = en_GB 
 </code>
 
 </page>
diff --git a/new-platform-overview/dev-help-write.page b/new-platform-overview/dev-help-write.page
new file mode 100644
index 0000000..bafcecd
--- /dev/null
+++ b/new-platform-overview/dev-help-write.page
@@ -0,0 +1,97 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      xmlns:its="http://www.w3.org/2005/11/its";
+      type="topic" style="task"
+      id="dev-help-write">
+
+  <info>
+    <link type="next" xref="dev-help-build"/>
+    <revision version="0.1" date="2013-06-19" status="stub"/>
+
+    <credit type="author">
+      <name>Ekaterina Gerasimova</name>
+      <email its:translate="no">kittykat3756 gmail com</email>
+      <years>2013</years>
+    </credit>
+
+    <include href="cc-by-sa-3-0.xml" xmlns="http://www.w3.org/2001/XInclude"/>
+
+  </info>
+
+  <title>Write some help</title>
+
+  <links type="series" style="floatend">
+    <title>Set up help</title>
+  </links>
+
+  <p>Write some <link href="http://www.projectmallard.org/";>Mallard</link>
+  pages and add them to <file>help/C</file>.</p>
+  
+  <p>Most projects should have an index.page and some content pages, although
+  you may not need an <file>index.page</file> if you are dropping plugin help
+  into another project.</p>
+  
+  <example>
+    <listing>
+      <title><file>help/C/index.page</file></title>
+<code><![CDATA[
+<page xmlns="http://projectmallard.org/1.0/";
+      xmlns:its="http://www.w3.org/2005/11/its";
+      type="guide"
+      id="index">
+
+  <info>
+    <revision pkgversion="3.9" date="2013-06-19" status="stub"/>
+
+    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>
+  </info>
+
+  <title>
+    <media type="image" mime="image/png" its:translate="no" src="figures/icon.png" />
+    Application name
+  </title>
+
+  <section id="features" style="2column">
+    <title>Features</title>
+  </section>
+
+</page>
+]]></code>
+    </listing>
+  
+    <listing>
+      <title><file>help/C/introduction.page</file></title>
+<code><![CDATA[
+<page xmlns="http://projectmallard.org/1.0/";
+      xmlns:its="http://www.w3.org/2005/11/its";
+      type="topic"
+      id="introduction">
+
+  <info>
+<!--
+    <link type="guide" xref="index#features"/>
+    <link type="seealso" xref="anotherpageid"/>
+-->
+    <revision pkgversion="3.9" date="2013-06-19" status="stub"/>
+ 
+    <credit type="author">
+      <name>Your Name</name>
+      <email its:translate="no">mail example com</email>
+      <years>2013</years>
+    </credit>
+ 
+    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>
+
+    <desc>Welcome to _Application name_</desc>
+  </info>
+
+  <title>Introduction</title>
+
+  <p>This application is awesome!</p>
+
+</page>
+]]></code>
+    </listing>
+  </example>
+
+ 
+</page>
diff --git a/new-platform-overview/dev-help.page b/new-platform-overview/dev-help.page
index 25cff20..5c1458e 100644
--- a/new-platform-overview/dev-help.page
+++ b/new-platform-overview/dev-help.page
@@ -4,54 +4,42 @@
       id="dev-help">
 
   <info>
-     <link type="guide" xref="index#dev"/>
-     <link type="next" xref="dev-help-build"/>
-     <link type="seealso" xref="dev-translate"/>
+    <link type="guide" xref="index" group="help"/>
+    <link type="next" xref="dev-help-write"/>
+    <link type="seealso" xref="dev-translate"/>
 
-     <revision version="0.1" date="2013-06-18" status="stub"/>
+    <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 type="editor">
+      <name>Ekaterina Gerasimova</name>
+      <email its:translate="no">kittykat3756 gmail com</email>
+      <years>2013</years>
     </credit>
 
     <include href="cc-by-sa-3-0.xml" xmlns="http://www.w3.org/2001/XInclude"/>
 
-    <desc>Introduction</desc>
+    <desc>Application and context sensitive user help and documentation.</desc>
 
   </info>
 
-  <title>Include user help in your application</title>
+  <title>User help</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>
-
-  <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>yelp-tools</em> package installed to bundle Mallard
-    documentation into your application.</p>
-  </note>
+  <p>You may want to add help, such as an introduction to your application or a
+  list of keyboard shortcuts, to your application.</p>
+
+  <p>Use <app>yelp-tools</app> to build
+  <link href="http://www.projectmallard.org/";>Mallard</link> help which can be
+  discrete or integrated with other application help.</p>
+
+  <p>Mallard is a markup language which is designed for topic-oriented help.</p>
 
 </page>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]