Docu update

1 files changed, 109 insertions, 55 deletions

diff --git a/scripts/html/xdg-desktop-menu.html b/scripts/html/xdg-desktop-menu.html
index daa6e30..eee4c2e 100644
--- a/scripts/html/xdg-desktop-menu.html
+++ b/scripts/html/xdg-desktop-menu.html
@@ -8,6 +8,29 @@
     </p></div><div class="refsect1" lang="en"><a name="commands"></a><h2>Commands</h2><div class="variablelist"><dl><dt><span class="term">install</span></dt><dd><p>
 	    Install one or more applications in a submenu of
 	    the desktop menu system.
+	  </p><p><em class="replaceable"><code>desktop-file</code></em>:
+            A desktop file represents a single menu entry in the menu.
+            Desktop files are defined by the freedesktop.org Desktop Entry
+            Specification. The most important aspects of *.desktop
+            files are summarized below.
+	  </p><p>
+            Menu entries can be added to the menu system in two different
+            ways. They can either be added to a predefined submenu in the
+            menu system based on one or more category keywords, or they can
+            be added to a new submenu. 
+	  </p><p>
+	    To add a menu entry to a predefined submenu the desktop file
+	    that represents the menu entry must have a Categories= entry
+	    that lists one or more keywords. The menu item will be included
+	    in an appropriate submenu based on the included keywords.
+	  </p><p>
+            To add menu items to a new submenu the desktop-files must be
+            preceded by a directory-file that describes the submenu.
+            If multiple desktop-files are specified, all entries will
+            be added to the same menu. If entries are installed to a menu
+            that has been created with a previous call to
+            <span><strong class="command">xdg-desktop-menu</strong></span> the entries will be
+            installed in addition to any already existing entries.
 	  </p><p><em class="replaceable"><code>directory-file</code></em>:
 	    The *.directory file indicated by
 	    <em class="replaceable"><code>directory-file</code></em> represents a submenu.
@@ -21,17 +44,6 @@
 	  </p><p>
             Directory files follow the syntax defined by the freedesktop.org
             Desktop Entry Specification.
-	  </p><p><em class="replaceable"><code>desktop-file</code></em>:
-            A desktop file represents a single application in the menu.
-            Desktop files are defined by the freedesktop.org Desktop Entry
-            Specification. The most important aspects of *.desktop
-            files are summarized below.
-	  </p><p>
-            If multiple desktop-files are specified, multiple entries will
-            be added to the same menu. If entries are installed to a menu
-            that has been created with a previous call to
-            <span><strong class="command">xdg-desktop-menu</strong></span> the entries will be
-            installed in addition to any already existing entries.
 	  </p></dd><dt><span class="term">uninstall</span></dt><dd><p>
 	    Remove applications or submenus from the desktop menu system
             previously installed with <span><strong class="command">xdg-desktop-menu install</strong></span>.
@@ -74,44 +86,7 @@
 	    Show this manualpage.
 	  </dd><dt><span class="term"><code class="option">--version</code></span></dt><dd>
             Show the xdg-utils version information.
-          </dd></dl></div></div><div class="refsect1" lang="en"><a name="directoryfiles"></a><h2>Directory Files</h2><p>
-      The appearance of submenu in the application menu is
-      provided by a *.directory file. In particular it provides the title
-      of the submenu and a possible icon. A *.directory file consists of a
-      <span class="emphasis"><em>[Desktop Entry]</em></span> header followed by several
-      <em class="replaceable"><code>Key</code></em>=<em class="replaceable"><code>Value</code></em> lines.
-    </p><p>
-      A *.directory file can provide a title (name) for the submenu
-      in several different languages. This is done by adding a language
-      code as used by LC_MESSAGES in square brackets behind the 
-      <em class="replaceable"><code>Key</code></em>. This way one can specify different
-      values for the same <em class="replaceable"><code>Key</code></em> depending on the
-      currently selected language.
-    </p><p>
-      The following keys are relevqnt for submenus:
-    </p><div class="variablelist"><dl><dt><span class="term">Value=1.0</span></dt><dd>
-	    This is a mandatory field to indicate that the *.directory file
-	    follows the 1.0 version of the Desktop Entry specification.
-	  </dd><dt><span class="term">Type=Directory</span></dt><dd>
-	    This is a mandatory field that indicates that the *.directory file
-	    describes a submenu.
-	  </dd><dt><span class="term">Name=<em class="replaceable"><code>Menu Name</code></em></span></dt><dd>
-	    The title of submenu.
-	    For example <span class="emphasis"><em>Mozilla</em></span>
-	  </dd><dt><span class="term">Comment=<em class="replaceable"><code>Comment</code></em></span></dt><dd>
-	    Optional field to specify a tooltip for the submenu. 
-	  </dd><dt><span class="term">Icon=<em class="replaceable"><code>Icon File</code></em></span></dt><dd>
-	    The icon to use for the submenu. This can either be
-	    an absolute path to an image file or an icon-name.
-	    If an icon-name is provided an image lookup by name is done
-	    in the user's current icon theme.
-	    The <span><strong class="command">xdg-icon-resource</strong></span>
-	    command can be used to install image files into icon themes.
-	    The advantage of using an icon-name instead of an absolute
-	    path is that with an icon-name the submenu icon can be
-	    provided in several different sizes as well as in several
-	    differently themed styles.
-	  </dd></dl></div></div><div class="refsect1" lang="en"><a name="desktopfiles"></a><h2>Desktop Files</h2><p>
+          </dd></dl></div></div><div class="refsect1" lang="en"><a name="desktopfiles"></a><h2>Desktop Files</h2><p>
       An application item in the application menu is represented by a
       *.desktop file. A *.desktop file consists of a
       <span class="emphasis"><em>[Desktop Entry]</em></span> header followed by several
@@ -159,14 +134,66 @@
 	    be used instead of %f. If the application is able to open URLs
 	    in addition to local files then  %u or %U can be used instead
 	    of %f or %F.
-	  </dd><dt><span class="term">MimeType=<em class="replaceable"><code>Mimetypes</code></em></span></dt><dd>
+	  </dd><dt><span class="term">Categories=<em class="replaceable"><code>Categories</code></em></span></dt><dd><p>
+	    A list of categories separated by semi-colons. A category is
+	    a keyword that describes and classifies the application.
+	    By default applications are organized in the application menu
+            based on category. When menu entries are explicitly assigned
+            to a new submenu it is not necassery to list any categories.
+          </p><p>
+            When using categories it is recommended to include
+            one of the following categories:
+            AudioVideo, Development, Education, Game, Graphics, Network, 
+            Office, Settings, System, Utility.
+          </p><p>
+            See Appendix A of the XDG Desktop Menu Specification
+            for information about additional categories. 
+            http://standards.freedesktop.org/menu-spec/menu-spec-1.0.html
+	  </p></dd><dt><span class="term">MimeType=<em class="replaceable"><code>Mimetypes</code></em></span></dt><dd>
 	    A list of mimetypes separated by semi-colons. This field is
 	    used to indicate which file types the application is able to
 	    open.
 	  </dd></dl></div><p>
       For a complete oveview of the *.desktop file format please
       visit http://www.freedesktop.org/wiki/Standards/desktop-entry-spec
-    </p></div><div class="refsect1" lang="en"><a name="env_vars"></a><h2>Environment Variables</h2><p>
+    </p></div><div class="refsect1" lang="en"><a name="directoryfiles"></a><h2>Directory Files</h2><p>
+      The appearance of submenu in the application menu is
+      provided by a *.directory file. In particular it provides the title
+      of the submenu and a possible icon. A *.directory file consists of a
+      <span class="emphasis"><em>[Desktop Entry]</em></span> header followed by several
+      <em class="replaceable"><code>Key</code></em>=<em class="replaceable"><code>Value</code></em> lines.
+    </p><p>
+      A *.directory file can provide a title (name) for the submenu
+      in several different languages. This is done by adding a language
+      code as used by LC_MESSAGES in square brackets behind the 
+      <em class="replaceable"><code>Key</code></em>. This way one can specify different
+      values for the same <em class="replaceable"><code>Key</code></em> depending on the
+      currently selected language.
+    </p><p>
+      The following keys are relevqnt for submenus:
+    </p><div class="variablelist"><dl><dt><span class="term">Value=1.0</span></dt><dd>
+	    This is a mandatory field to indicate that the *.directory file
+	    follows the 1.0 version of the Desktop Entry specification.
+	  </dd><dt><span class="term">Type=Directory</span></dt><dd>
+	    This is a mandatory field that indicates that the *.directory file
+	    describes a submenu.
+	  </dd><dt><span class="term">Name=<em class="replaceable"><code>Menu Name</code></em></span></dt><dd>
+	    The title of submenu.
+	    For example <span class="emphasis"><em>Mozilla</em></span>
+	  </dd><dt><span class="term">Comment=<em class="replaceable"><code>Comment</code></em></span></dt><dd>
+	    Optional field to specify a tooltip for the submenu. 
+	  </dd><dt><span class="term">Icon=<em class="replaceable"><code>Icon File</code></em></span></dt><dd>
+	    The icon to use for the submenu. This can either be
+	    an absolute path to an image file or an icon-name.
+	    If an icon-name is provided an image lookup by name is done
+	    in the user's current icon theme.
+	    The <span><strong class="command">xdg-icon-resource</strong></span>
+	    command can be used to install image files into icon themes.
+	    The advantage of using an icon-name instead of an absolute
+	    path is that with an icon-name the submenu icon can be
+	    provided in several different sizes as well as in several
+	    differently themed styles.
+	  </dd></dl></div></div><div class="refsect1" lang="en"><a name="env_vars"></a><h2>Environment Variables</h2><p>
       xdg-desktop-menu honours the following environment variables:
     </p><div class="variablelist"><dl><dt><span class="term">XDG_UTILS_DEBUG_LEVEL</span></dt><dd>
 	    Setting this environment variable to a non-zero numerical value
@@ -193,13 +220,40 @@
       The company ShinyThings Inc. has developed an application named
       "WebMirror" and would like to add it to the application menu.
       The company will use "shinythings" as its vendor id.
-      In this example the company ShinyThings Inc. will add its own
+      In order to add the application to the menu there needs to be a
+      .desktop file with a suitable <span class="emphasis"><em>Categories</em></span> entry:
+</p><pre class="programlisting">
+shinythings-webmirror.desktop:
+
+  [Desktop Entry]
+  Encoding=UTF-8
+  Type=Application
+
+  Exec=webmirror
+  Icon=webmirror
+
+  Name=WebMirror
+  Name[nl]=WebSpiegel
+
+  Categories=Network;WebDevelopment;
+</pre><p>
+    </p><p>Now the xdg-desktop-menu tool can be used to add the
+    shinythings-webmirror.desktop file to the desktop application menu:
+</p><pre class="programlisting">
+xdg-desktop-menu install ./shinythings-webmirror.desktop
+</pre><p>
+    </p><p>
+      Note that for the purpose of this example the menu items are available
+      in two languages, English and Dutch.
+      The language code for Dutch is nl.
+    </p><p>
+      In the next example the company ShinyThings Inc. will add its own
       submenu to the desktop application menu consisting of a
-      "WebMirror" menu item and a
-      "WebMirror Admin Tool" menu item.
+      "WebMirror" menu item and a "WebMirror Admin Tool" menu item.
     </p><p>
       First the company needs to create two .desktop files that describe
-      the two menu items:
+      the two menu items. Since the items are to be added to a new submenu
+      it is not necassery to include a Categories= line:
 </p><pre class="programlisting">
 shinythings-webmirror.desktop: