xdg-menu: Added examples to man pagetmp

xdg-menu: Provide useful hint when using --system as non-root user.

5 files changed, 424 insertions, 6 deletions

diff --git a/scripts/desc/xdg-menu.xml b/scripts/desc/xdg-menu.xml
index 79555f5..203278c 100755
--- a/scripts/desc/xdg-menu.xml
+++ b/scripts/desc/xdg-menu.xml
@@ -192,4 +192,141 @@
 
     </variablelist>
   </refsect1>
+  <refsect1 id="examples">
+    <title>Examples</title>
+    <para>
+      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 order to add the application to the menu there needs to be a
+      .desktop file with a suitable <emphasis>Categories</emphasis> entry:
+<programlisting>
+webmirror.desktop:
+
+  [Desktop Entry]
+  Encoding=UTF-8
+  Type=Application
+
+  Exec=webmirror
+  Icon=webmirror
+
+  Name=WebMirror
+  Name[nl]=WebSpiegel
+
+  Categories=Network;WebDevelopment;
+</programlisting>
+    </para>
+    <para>Now the xdg-menu tool can be used to add the webmirror.desktop file
+    to the desktop application menu:
+<programlisting>
+xdg-menu --system --vendor shinythings --install ./webmirror.desktop
+</programlisting>
+    </para>
+    <para>
+      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.
+    </para>
+    <para>
+      In the next example the company ShinyThings Inc. wants to add its own
+      submenu to the desktop application menu consisting of a
+      "WebMirror" menu item and a
+      "WebMirror Admin Tool" menu item.
+    </para>
+    <para>
+      First the company needs to create two .desktop files that describe
+      the two menu items, this time no Categories item is needed:
+<programlisting>
+webmirror.desktop:
+
+  [Desktop Entry]
+  Encoding=UTF-8
+  Type=Application
+
+  Exec=webmirror
+  Icon=webmirror
+
+  Name=WebMirror
+  Name[nl]=WebSpiegel
+
+
+webmirror-admin.desktop:
+
+  [Desktop Entry]
+  Encoding=UTF-8
+  Type=Application
+
+  Exec=webmirror-admintool
+  Icon=webmirror-admintool
+
+  Name=WebMirror Admin Tool
+  Name[nl]=WebSpiegel Administratie Tool
+</programlisting>
+    </para>
+    <para>
+      The files can be installed with:
+<programlisting>
+xdg-menu --system --noupdate --vendor shinythings --install ./webmirror.desktop
+xdg-menu --system --noupdate --vendor shinythings --install ./webmirror-admin.desktop
+</programlisting>
+    </para>
+    <para>
+      Because multiple items are added the <option>--noupdate</option>
+      option has been used.
+    </para>
+    <para>
+      In addition a .directory file needs to be created to provide a title and icon
+      for the sub-menu itself:
+<programlisting>
+webmirror.directory:
+
+  [Desktop Entry]
+  Encoding=UTF-8
+
+  Icon=webmirror
+
+  Name=WebMirror
+  Name[nl]=WebSpiegel
+</programlisting>
+    </para>
+    <para>
+      This webmirror.directorty file can be installed with:
+<programlisting>
+xdg-menu --system --noupdate --vendor shinythings --install ./webmirror.directory
+</programlisting>
+    </para>
+    <para>
+      The last step is to provide a .menu file that links it all
+      togther:
+<programlisting>
+webmirror.menu:
+
+  &lt;!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 0.8//EN"
+     "http://www.freedesktop.org/standards/menu-spec/menu-0.8.dtd"&gt;
+  &lt;Menu&gt;
+    &lt;Menu&gt;
+      &lt;Name&gt;WebMirror&lt;/Name&gt;
+      &lt;Directory&gt;shinythings-webmirror.directory&lt;/Directory&gt;
+      &lt;Include&gt;
+        &lt;Filename&gt;shinythings-webmirror.desktop&lt;/Filename&gt;
+        &lt;Filename&gt;shinythings-webmirror-admin.desktop&lt;/Filename&gt;
+      &lt;/Include&gt;
+    &lt;/Menu&gt;
+  &lt;/Menu&gt;
+</programlisting>
+    </para>
+    <para>
+      The webmirror.menu file can be installed with:
+<programlisting>
+xdg-menu --system --noupdate --vendor shinythings --install ./webmirror.menu
+</programlisting>
+    </para>
+    <para>
+      After installing multiple files with <option>--noupdate</option> make sure
+      to force an update:
+<programlisting>
+xdg-menu --system --forceupdate
+</programlisting>
+    </para>
+  </refsect1>
 </refentry>
diff --git a/scripts/html/xdg-menu.html b/scripts/html/xdg-menu.html
index cf772d8..87367ed 100644
--- a/scripts/html/xdg-menu.html
+++ b/scripts/html/xdg-menu.html
@@ -41,4 +41,126 @@
 	  </dd><dt><span class="term"><code class="option">--forceupdate</code></span></dt><dd>
 	    Force an update of the menu system. This is only useful if
 	    the last call to xdg-menu included the <code class="option">--noupdate</code> option.
-	  </dd></dl></div></div></div></body></html>
+	  </dd></dl></div></div><div class="refsect1" lang="en"><a name="examples"></a><h2>Examples</h2><p>
+      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 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">
+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-menu tool can be used to add the webmirror.desktop file
+    to the desktop application menu:
+</p><pre class="programlisting">
+xdg-menu --system --vendor shinythings --install ./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. wants to add its own
+      submenu to the desktop application menu consisting of a
+      "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, this time no Categories item is needed:
+</p><pre class="programlisting">
+webmirror.desktop:
+
+  [Desktop Entry]
+  Encoding=UTF-8
+  Type=Application
+
+  Exec=webmirror
+  Icon=webmirror
+
+  Name=WebMirror
+  Name[nl]=WebSpiegel
+
+
+webmirror-admin.desktop:
+
+  [Desktop Entry]
+  Encoding=UTF-8
+  Type=Application
+
+  Exec=webmirror-admintool
+  Icon=webmirror-admintool
+
+  Name=WebMirror Admin Tool
+  Name[nl]=WebSpiegel Administratie Tool
+</pre><p>
+    </p><p>
+      The files can be installed with:
+</p><pre class="programlisting">
+xdg-menu --system --noupdate --vendor shinythings --install ./webmirror.desktop
+xdg-menu --system --noupdate --vendor shinythings --install ./webmirror-admin.desktop
+</pre><p>
+    </p><p>
+      Because multiple items are added the <code class="option">--noupdate</code>
+      option has been used.
+    </p><p>
+      In addition a .directory file needs to be created to provide a title and icon
+      for the sub-menu itself:
+</p><pre class="programlisting">
+webmirror.directory:
+
+  [Desktop Entry]
+  Encoding=UTF-8
+
+  Icon=webmirror
+
+  Name=WebMirror
+  Name[nl]=WebSpiegel
+</pre><p>
+    </p><p>
+      This webmirror.directorty file can be installed with:
+</p><pre class="programlisting">
+xdg-menu --system --noupdate --vendor shinythings --install ./webmirror.directory
+</pre><p>
+    </p><p>
+      The last step is to provide a .menu file that links it all
+      togther:
+</p><pre class="programlisting">
+webmirror.menu:
+
+  &lt;!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 0.8//EN"
+     "http://www.freedesktop.org/standards/menu-spec/menu-0.8.dtd"&gt;
+  &lt;Menu&gt;
+    &lt;Menu&gt;
+      &lt;Name&gt;WebMirror&lt;/Name&gt;
+      &lt;Directory&gt;shinythings-webmirror.directory&lt;/Directory&gt;
+      &lt;Include&gt;
+        &lt;Filename&gt;shinythings-webmirror.desktop&lt;/Filename&gt;
+        &lt;Filename&gt;shinythings-webmirror-admin.desktop&lt;/Filename&gt;
+      &lt;/Include&gt;
+    &lt;/Menu&gt;
+  &lt;/Menu&gt;
+</pre><p>
+    </p><p>
+      The webmirror.menu file can be installed with:
+</p><pre class="programlisting">
+xdg-menu --system --noupdate --vendor shinythings --install ./webmirror.menu
+</pre><p>
+    </p><p>
+      After installing multiple files with <code class="option">--noupdate</code> make sure
+      to force an update:
+</p><pre class="programlisting">
+xdg-menu --system --forceupdate
+</pre><p>
+    </p></div></div></body></html>
diff --git a/scripts/man/xdg-menu.1 b/scripts/man/xdg-menu.1
index 1b97ee7..e8daed0 100644
--- a/scripts/man/xdg-menu.1
+++ b/scripts/man/xdg-menu.1
@@ -86,5 +86,163 @@ Removes the *\&.menu file indicated by \fImenu\-file\fR from the menu system\&.
 \fB\-\-forceupdate\fR
 Force an update of the menu system\&. This is only useful if the last call to xdg\-menu included the \fB\-\-noupdate\fR option\&.
 
+.SH "EXAMPLES"
+
+.PP
+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 order to add the application to the menu there needs to be a \&.desktop file with a suitable \fICategories\fR entry: 
+
+.nf
+
+webmirror\&.desktop:
+
+  [Desktop Entry]
+  Encoding=UTF\-8
+  Type=Application
+
+  Exec=webmirror
+  Icon=webmirror
+
+  Name=WebMirror
+  Name[nl]=WebSpiegel
+
+  Categories=Network;WebDevelopment;
+
+.fi
+ 
+
+.PP
+Now the xdg\-menu tool can be used to add the webmirror\&.desktop file to the desktop application menu: 
+
+.nf
+
+xdg\-menu \-\-system \-\-vendor shinythings \-\-install \&./webmirror\&.desktop
+
+.fi
+ 
+
+.PP
+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\&.
+
+.PP
+In the next example the company ShinyThings Inc\&. wants to add its own submenu to the desktop application menu consisting of a "WebMirror" menu item and a "WebMirror Admin Tool" menu item\&.
+
+.PP
+First the company needs to create two \&.desktop files that describe the two menu items, this time no Categories item is needed: 
+
+.nf
+
+webmirror\&.desktop:
+
+  [Desktop Entry]
+  Encoding=UTF\-8
+  Type=Application
+
+  Exec=webmirror
+  Icon=webmirror
+
+  Name=WebMirror
+  Name[nl]=WebSpiegel
+
+
+webmirror\-admin\&.desktop:
+
+  [Desktop Entry]
+  Encoding=UTF\-8
+  Type=Application
+
+  Exec=webmirror\-admintool
+  Icon=webmirror\-admintool
+
+  Name=WebMirror Admin Tool
+  Name[nl]=WebSpiegel Administratie Tool
+
+.fi
+ 
+
+.PP
+The files can be installed with: 
+
+.nf
+
+xdg\-menu \-\-system \-\-noupdate \-\-vendor shinythings \-\-install \&./webmirror\&.desktop
+xdg\-menu \-\-system \-\-noupdate \-\-vendor shinythings \-\-install \&./webmirror\-admin\&.desktop
+
+.fi
+ 
+
+.PP
+Because multiple items are added the \fB\-\-noupdate\fR option has been used\&.
+
+.PP
+In addition a \&.directory file needs to be created to provide a title and icon for the sub\-menu itself: 
+
+.nf
+
+webmirror\&.directory:
+
+  [Desktop Entry]
+  Encoding=UTF\-8
+
+  Icon=webmirror
+
+  Name=WebMirror
+  Name[nl]=WebSpiegel
+
+.fi
+ 
+
+.PP
+This webmirror\&.directorty file can be installed with: 
+
+.nf
+
+xdg\-menu \-\-system \-\-noupdate \-\-vendor shinythings \-\-install \&./webmirror\&.directory
+
+.fi
+ 
+
+.PP
+The last step is to provide a \&.menu file that links it all togther: 
+
+.nf
+
+webmirror\&.menu:
+
+  <!DOCTYPE Menu PUBLIC "\-//freedesktop//DTD Menu 0\&.8//EN"
+     "http://www\&.freedesktop\&.org/standards/menu\-spec/menu\-0\&.8\&.dtd">
+  <Menu>
+    <Menu>
+      <Name>WebMirror</Name>
+      <Directory>shinythings\-webmirror\&.directory</Directory>
+      <Include>
+        <Filename>shinythings\-webmirror\&.desktop</Filename>
+        <Filename>shinythings\-webmirror\-admin\&.desktop</Filename>
+      </Include>
+    </Menu>
+  </Menu>
+
+.fi
+ 
+
+.PP
+The webmirror\&.menu file can be installed with: 
+
+.nf
+
+xdg\-menu \-\-system \-\-noupdate \-\-vendor shinythings \-\-install \&./webmirror\&.menu
+
+.fi
+ 
+
+.PP
+After installing multiple files with \fB\-\-noupdate\fR make sure to force an update: 
+
+.nf
+
+xdg\-menu \-\-system \-\-forceupdate
+
+.fi
+ 
+
 .SH AUTHORS
 Kevin Krammer, Jeremy White.
diff --git a/scripts/xdg-menu b/scripts/xdg-menu
index b89ece7..2382a7a 100755
--- a/scripts/xdg-menu
+++ b/scripts/xdg-menu
@@ -31,7 +31,6 @@
 #   ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 #   OTHER DEALINGS IN THE SOFTWARE.
 #
-#
 #---------------------------------------------
 
 usage()
@@ -52,7 +51,7 @@ _USAGE
 
 update_desktop_database()
 {
-    echo Update desktop database: $mode
+#    echo Update desktop database: $mode
     if [ "$mode" = "system" ] ; then
         for x in `echo $PATH | sed 's/:/ /g'` /opt/gnome/bin; do
            if [ -x $x/update-desktop-database ] ; then
@@ -229,7 +228,8 @@ else
     gnome_dir=$gnome_global_dir
     my_umask=022
     if [ -n "$xdg_dir $kde_dir $gnome_dir" ] ; then
-        echo Error:  No writable system menu directory found.
+        [ `whoami` = "root" ] || rootmsg="Try as root or use --user."
+        echo Error:  No writable system menu directory found. $rootmsg
         exit 3 
     fi
 fi
diff --git a/scripts/xdg-menu.in b/scripts/xdg-menu.in
index 39a88c3..8c602e3 100755
--- a/scripts/xdg-menu.in
+++ b/scripts/xdg-menu.in
@@ -24,7 +24,7 @@ _USAGE
 
 update_desktop_database()
 {
-    echo Update desktop database: $mode
+#    echo Update desktop database: $mode
     if [ "$mode" = "system" ] ; then
         for x in `echo $PATH | sed 's/:/ /g'` /opt/gnome/bin; do
            if [ -x $x/update-desktop-database ] ; then
@@ -201,7 +201,8 @@ else
     gnome_dir=$gnome_global_dir
     my_umask=022
     if [ -n "$xdg_dir $kde_dir $gnome_dir" ] ; then
-        echo Error:  No writable system menu directory found.
+        [ `whoami` = "root" ] || rootmsg="Try as root or use --user."
+        echo Error:  No writable system menu directory found. $rootmsg
         exit 3 
     fi
 fi