path: root/gnome2-system-admin-guide/C/menustructure.xml

<?xml version="1.0" encoding="UTF-8"?>
<chapter id="menustructure-0">
  <title>Customizing Menus</title>

  <anchor id="menustructure-22" />

  <anchor id="menustructure-TBL-12" />

  <anchor id="menustructure-TBL-17" />

  <highlights>
    <para>The information in this chapter describes how the GNOME Desktop
    implements menus and how you can customize menus.</para>
  </highlights>

  <sect1 id="menustructure-1">
    <title>Introduction to Menus</title>

    <indexterm>
      <primary>menus</primary>

      <secondary>introduction</secondary>
    </indexterm>

    <para>The GNOME Desktop implements menus according to the <ulink
    url="http://www.freedesktop.org/wiki/Standards/menu-spec">XDG menu
    specification</ulink>. By supporting this specification, GNOME allows you
    to:</para>

    <itemizedlist>
      <listitem>
        <para>Customize the menu hierarchy easily. You can edit a small number
        of files to customize the menu hierarchy. You do not need to modify
        your applications or move files.</para>
      </listitem>

      <listitem>
        <para>Install applications easily. You do not need to provide
        information about the menu hierarchy to applications when you install
        the applications.</para>
      </listitem>

      <listitem>
        <para>Configure menus so that users cannot modify the menus.</para>
      </listitem>
    </itemizedlist>

    <para>Menus in the GNOME Desktop use the following components:</para>

    <itemizedlist>
      <listitem>
        <para>Menu definition files</para>
      </listitem>

      <listitem>
        <para>Desktop entry files</para>
      </listitem>

      <listitem>
        <para>Directory entry files</para>
      </listitem>
    </itemizedlist>
  </sect1>

  <sect1 id="menustructure-13">
    <title>Menu Definition Files</title>

    <indexterm>
      <primary>menu definition files</primary>
    </indexterm>

    <indexterm>
      <primary>.menu files</primary>

      <see>menu definition files</see>
    </indexterm>

    <para>Menu files define the hierarchy of menus that are used in the GNOME
    menu bar. By modifying these files, you can customize menus for all users,
    or for a single user depending on the location of the
    <filename>applications.menu</filename> file that you modify.</para>

    <para>Menu files must reside at
    <filename>$XDG_CONFIG_DIRS/menus/applications.menu</filename>. If
    <envar>$XDG_CONFIG_DIRS</envar><footnote>
        <para>$XDG_CONFIG_DIRS is the environment variable defined in the
        <ulink url="http://www.freedesktop.org/Standards/basedir-spec">XDG
        base directory specification</ulink>.</para>
      </footnote> is not set, then the default path
    <filename>/etc/xdg</filename> is used. This also implies that a user
    specific version may be located at
    <filename>$XDG_CONFIG_HOME/menus/applications.menu</filename>
    which is searched first. If <envar>$XDG_CONFIG_HOME</envar> is not set,
    then the default path <filename>~/.config</filename> is used. Directories
    which appear first in <envar>$XDG_CONFIG_DIRS</envar> are given precedence
    when there are several <filename>applications.menu</filename> files. The
    first file found is used and subsequent files are ignored.</para>

    <para>If you are confused about the order in which paths are searched,
    here is a simple list for resolving the location of
    <filename>applications.menu</filename>:</para>

    <orderedlist>
      <listitem>
        <para>Search each directory in <envar>$XDG_CONFIG_HOME</envar> in
        order to find <filename>menus/applications.menu</filename>. If
        <envar>$XDG_CONFIG_HOME</envar> is not set, it defaults to the
        <filename>~/.config/</filename> directory.</para>
      </listitem>

      <listitem>
        <para>Search each directory in <envar>$XDG_CONFIG_DIRS</envar> in
        order to find <filename>menus/applications.menu</filename>. If
        <filename>$XDG_CONFIG_DIRS</filename> is not set, it defaults to the
        <filename>/etc/xdg/</filename> directory.</para>
      </listitem>

      <listitem>
        <para>Use the first <filename>applications.menu</filename> file
        found.</para>
      </listitem>
    </orderedlist>

    <para>You can see an example of a <filename>.menu</filename> file in <xref
    linkend="example-menu" />. In this example, the top level menu is named
    <literal>Applications</literal>, which is specified using the
    <literal>&lt;Name&gt;</literal> element. The
    <literal>Applications</literal> menu contains a single submenu, but
    several submenus are allowed. Each submenu may also have an
    <literal>&lt;Include&gt;</literal> element. The purpose of the
    <literal>&lt;Include&gt;</literal> element is to perform a filter on the
    set of available desktop entries using matching rules.</para>

    <para>For example, the <literal>&lt;Category&gt;</literal> element is a
    basic matching rule that selects a <link
    linkend="menustructure-desktopentry"><emphasis>desktop
    entry</emphasis></link> only if the <link
    linkend="category-key"><literal>Categories</literal> key</link> contains
    the content of the <literal>&lt;Category&gt;</literal> element. In the
    example, the <literal>Accessories</literal> menu will include a
    <emphasis>desktop entry</emphasis> only if it contains
    <quote>Utility</quote> but not <quote>System</quote> in the Categories
    key. For more information on the Categories key, see <xref
    linkend="menustructure-desktopentry" />.</para>

    <example id="example-menu">
      <title>Example of a <filename>.menu</filename> file</title>

      <para><programlisting>&lt;!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"
 "http://www.freedesktop.org/standards/menu-spec/1.0/menu.dtd"&gt;
&lt;Menu&gt;
  &lt;Name&gt;Applications&lt;/Name&gt;
  &lt;Directory&gt;Applications.directory&lt;/Directory&gt;

  &lt;!-- Read standard .directory and .desktop file locations --&gt;
  &lt;DefaultAppDirs/&gt;
  &lt;DefaultDirectoryDirs/&gt;

  &lt;!-- Accessories submenu --&gt;
  &lt;Menu&gt;
    &lt;Name&gt;Accessories&lt;/Name&gt;
    &lt;Directory&gt;Accessories.directory&lt;/Directory&gt;
    &lt;Include&gt;
      &lt;And&gt;
        &lt;Category&gt;Utility&lt;/Category&gt;
        &lt;Not&gt;
          &lt;Category&gt;System&lt;/Category&gt;
        &lt;/Not&gt;
      &lt;/And&gt;
    &lt;/Include&gt;
  &lt;/Menu&gt; &lt;!-- End Accessories --&gt;

  &lt;!-- possibly more submenus --&gt;

&lt;/Menu&gt; &lt;!-- End Applications --&gt;
</programlisting></para>
    </example>

    <para><xref linkend="menustructure-xmlmenu" /> describes some of the
    elements in <filename>.menu</filename> files. For a more detailed
    description, please see the <ulink
    url="http://www.freedesktop.org/wiki/Standards/menu-spec">XDG menu
    specification</ulink>.</para>

    <table frame="topbot" id="menustructure-xmlmenu">
      <title>Menu Definition File Elements</title>

      <tgroup cols="2" colsep="0" rowsep="0">
        <colspec colname="colspec2" colwidth="33.83*" />

        <colspec colname="colspec3" colwidth="80.00*" />

        <thead>
          <row rowsep="1">
            <entry><para>Element</para></entry>

            <entry><para>Description</para></entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry colname="colspec2"
            valign="top"><para><literal>&lt;Menu&gt;</literal> </para></entry>

            <entry colname="colspec3" valign="top"><para>The root element
            which may contain nested <literal>&lt;Menu&gt;</literal> elements
            that define submenus. How these elements are nested determines the
            menu structure.</para></entry>
          </row>

          <row>
            <entry colname="colspec2"
            valign="top"><para><literal>&lt;Name&gt;</literal> </para></entry>

            <entry colname="colspec3" valign="top"><para>Specifies the name of
            the menu. Every <literal>&lt;Menu&gt;</literal> element must
            contain a <literal>&lt;Name&gt;</literal> element.</para></entry>
          </row>

          <row>
            <entry colname="colspec2"
            valign="top"><para><literal>&lt;Directory&gt;</literal>
            </para></entry>

            <entry colname="colspec3" valign="top"><para>Specifies the name of
            the directory entry file that specifies the name, comment, and
            icon for the menu. If this element is not specified, then the
            <literal>&lt;Name&gt;</literal> element is to be used to display
            the menu name.</para><para>By default,
            <filename>.directory</filename> files are searched for in the
            location
            <filename>$XDG_DATA_DIRS/desktop-directories/</filename>
            as set forth in the <citetitle>XDG menu
            specification.</citetitle></para></entry>
          </row>

          <row>
            <entry
            colname="colspec2"><literal>&lt;DefaultAppDirs&gt;</literal></entry>

            <entry colname="colspec3">This is an instruction which indicates
            that all the available desktop entries from
            <filename>$XDG_DATA_DIRS/applications/</filename>
            should be scanned. If this instruction is not included, then these
            locations are not scanned for desktop entries.</entry>
          </row>

          <row>
            <entry
            colname="colspec2"><literal>&lt;DefaultDirectoryDirs&gt;</literal></entry>

            <entry colname="colspec3">This is an instruction which indicates
            that all the available directory entries from
            <filename>$XDG_DATA_DIRS/desktop-directories/</filename>
            should be scanned. If the instruction is not included, then these
            locations are not scanned for directory entries.</entry>
          </row>

          <row>
            <entry colname="colspec2"
            valign="top"><para><literal>&lt;Include&gt;</literal></para></entry>

            <entry colname="colspec3">Contains a list of matching rules by
            which the contents of a menu are generated. May include the
            <literal>&lt;Filename&gt;</literal>,
            <literal>&lt;Category&gt;</literal>,
            <literal>&lt;And&gt;</literal>, <literal>&lt;Or&gt;</literal>,
            <literal>&lt;Not&gt;</literal>, or <literal>&lt;All&gt;</literal>
            matching rules. If more than one rule is present, the rules are
            logically ORed so that <emphasis>desktop entries</emphasis> that
            match any rule are included.</entry>
          </row>

          <row>
            <entry
            colname="colspec2"><literal>&lt;Exclude&gt;</literal></entry>

            <entry colname="colspec3">The opposite of
            <literal>&lt;Include&gt;</literal> since any <emphasis>desktop
            entries</emphasis> that are matched in this element are excluded
            from the previous set of included elements. For this reason, this
            element must appear after the <literal>&lt;Include&gt;</literal>
            element.</entry>
          </row>

          <row>
            <entry
            colsep="colspec2"><literal>&lt;Filename&gt;</literal></entry>

            <entry colname="colspec3">A matching rule that selects a
            <emphasis>desktop entry</emphasis> when the Desktop File-Id
            matches the contents of the <literal>&lt;Filename&gt;</literal>
            element.</entry>
          </row>

          <row>
            <entry colname="colspec2"><literal>&lt;Category&gt;</literal></entry>

            <entry colname="colspec3">A matching rule that selects a
            <emphasis>desktop entry</emphasis> when the Categories key matches
            the contents of the <literal>&lt;Category&gt;</literal>
            element.</entry>
          </row>

          <row>
            <entry colname="colspec2"><literal>&lt;And&gt;</literal></entry>

            <entry colname="colspec3">A matching rule that selects a
            <emphasis>desktop entry</emphasis> when it is selected by
            <emphasis>all</emphasis> the nested matching rules in the
            <literal>&lt;And&gt;</literal> element.</entry>
          </row>

          <row>
            <entry colname="colspec2"><literal>&lt;Or&gt;</literal></entry>

            <entry colname="colspec3">A matching rule that selects a
            <emphasis>desktop entry</emphasis> when it is selected by
            <emphasis>any</emphasis> of the nested matching rules in the
            <literal>&lt;Or&gt;</literal> element.</entry>
          </row>

          <row>
            <entry colname="colspec2"><literal>&lt;Not&gt;</literal></entry>

            <entry colname="colspec3">A matching rule that does not select a
            <emphasis>desktop entry</emphasis> when it is selected by
            <emphasis>any</emphasis> of the nested matching rules in the
            <literal>&lt;Not&gt;</literal> element.</entry>
          </row>

          <row>
            <entry colname="colspec2"><literal>&lt;All&gt;</literal></entry>

            <entry colname="colspec3">A matching rule which selects all
            <emphasis>desktop entries</emphasis>.</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
  </sect1>

  <sect1 id="menustructure-desktopentry">
    <title>Desktop Entry Files</title>

    <anchor id="menustructure-6" />

    <indexterm>
      <primary>desktop entry files</primary>
    </indexterm>

    <indexterm>
      <primary>.desktop files</primary>

      <see>desktop entry files</see>
    </indexterm>

    <para>A <firstterm>desktop entry file</firstterm> is a data file that
    provides information about an item in a menu. The desktop entry file
    specifies the details for the item such as a name, a command to run, an
    icon, and so on. It also contains keywords which determine the location of
    the item in the menu hierarchy.</para>

    <para>Desktop entry files must reside in the
    <filename>$XDG_DATA_DIRS/applications</filename> directory and must have a
    <filename>.desktop</filename> file extension. If
    <envar>$XDG_DATA_DIRS</envar><footnote>
        <para>$XDG_DATA_DIRS is the environment variable defined in the <ulink
        url="http://www.freedesktop.org/Standards/basedir-spec">XDG base
        directory specification</ulink>.</para>
      </footnote> is not set, then the default path is
    <filename>/usr/share</filename> is used. This also implies that user
    specific desktop entries may be located at
    <filename>$XDG_DATA_HOME/applications</filename> which is
    searched first. If <envar>$XDG_DATA_HOME</envar> is not set, then the
    default path <filename>~/.local/share</filename> is used. Desktop entries
    are collected from all directories in the <envar>$XDG_DATA_DIRS</envar>
    environment variable. Directories which appear first in
    <envar>$XDG_CONFIG_DIRS</envar> are given precedence when there are
    several <filename>.desktop</filename> files with the same name.</para>

    <para>The following is a sample desktop entry file:</para>

    <programlisting>[Desktop Entry]
Encoding=UTF-8
Name=Calculator
Name[fr]=Calculatrice
...
Comment=Perform calculations
Comment[fr]=Effectue des calculs compliqués
...
Exec=gcalctool
Icon=accessories-calculator
Terminal=false
Type=Application
StartupNotify=true
Categories=GNOME;GTK;Utility;Calculator</programlisting>

    <para><xref linkend="menustructure-TBL-7" /> describes the most important
    keys in desktop entry files. To get more information about desktop entry
    files, see the <ulink
    url="http://www.freedesktop.org/Standards/desktop-entry-spec">XDG Desktop
    Entry Specification</ulink>.</para>

    <table frame="topbot" id="menustructure-TBL-7">
      <title>Desktop Entry Keys</title>

      <tgroup cols="2" colsep="0" rowsep="0">
        <colspec colname="colspec0" colwidth="25.25*" />

        <colspec colname="colspec1" colwidth="74.75*" />

        <thead>
          <row rowsep="1">
            <entry><para>Desktop Entry Key</para></entry>

            <entry><para>Description</para></entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry colname="colspec0" id="category-key" valign="top"><para>
            <literal>Categories</literal> </para></entry>

            <entry colname="colspec1" valign="top"><para>Specifies the
            keywords that describe the item. The keywords are separated with
            semicolons (;). To see a list of the standard category keywords,
            see the desktop menu specification at
                <ulink url="http://www.freedesktop.org/Standards/menu-spec">
            http://www.freedesktop.org/Standards/menu-spec</ulink>
            </para><para><link linkend="menustructure-13">Menu
            Definition Files</link> map desktop entries to menus by using
            matching rules against the Categories key.</para></entry>
          </row>

          <row>
            <entry valign="top"><para> <literal>Comment</literal>
            </para></entry>

            <entry valign="top"><para>Specifies a short description of the
            item. The comment is displayed as a tooltip when you point to the
            item in the menu. </para></entry>
          </row>

          <row>
            <entry valign="top"><para> <literal>Encoding</literal>
            </para></entry>

            <entry valign="top"><para>Specifies the encoding of the desktop
            entry file. </para></entry>
          </row>

          <row>
            <entry valign="top"><para> <literal>Exec</literal> </para></entry>

            <entry valign="top"><para>Specifies a command to execute when you
            choose the item from the menu. </para></entry>
          </row>

          <row>
            <entry colname="colspec0" valign="top"><para>
            <literal>Icon</literal> </para></entry>

            <entry colname="colspec1" valign="top"><para>Specifies the
            filename of an icon that represents the item. Does not specify the
            path to the filename, or the file extension. </para></entry>
          </row>

          <row>
            <entry><literal>MimeType</literal></entry>

            <entry>Specifies the MIME types that the application can handle.</entry>
          </row>
         
          <row>
            <entry valign="top"><para> <literal>Name</literal> </para></entry>

            <entry valign="top"><para>Specifies the name of the item. This
            name is displayed on the item in the menu. </para></entry>
          </row>

          <row>
            <entry valign="top"><para> <literal>NoDisplay</literal> </para></entry>

            <entry valign="top"><para>This options means <quote>This application 
            exists, but don't display it in the menus</quote>.</para></entry>
          </row>

          <row>
            <entry colname="colspec0" valign="top"><para>
            <literal>Terminal</literal> </para></entry>

            <entry colname="colspec1" valign="top"><para>Specifies whether the
            command in the <literal>Exec</literal> key runs in a terminal
            window. If the value is <literal>true</literal> the command runs
            in a terminal window. </para><para>If the command does not create
            a window in which to run, the value of this key must be
            <literal>true</literal>.</para></entry>
          </row>

          <row>
            <entry colname="colspec0" valign="top"><para>
            <literal>Type</literal> </para></entry>

            <entry colname="colspec1" valign="top"><para>Specifies the type of
            item. This value is one of the following: </para><itemizedlist>
                <listitem>
                  <para><literal>Application</literal>: An item that starts an
                  application.</para>
                </listitem>

                <listitem>
                  <para><literal>Link</literal>: An item that links to a file,
                  folder, or a remote resource (such as a FTP site, a web
		   page, a Windows share...).</para>
                </listitem>

                <listitem>
                  <para><literal>FSDevice</literal>: An item that is a file
                  system device.</para>
                </listitem>

                <listitem>
                  <para><literal>Directory</literal>: An item that is a
                  Directory.</para>
                </listitem>
              </itemizedlist></entry>
          </row>

        </tbody>
      </tgroup>
    </table>

    <para>For more information on the keys in desktop entry files, see the
    desktop entry specification at the following URL:</para>

    <literallayout>
    <ulink url="http://www.freedesktop.org/Standards/desktop-entry-spec">http://www.freedesktop.org/Standards/desktop-entry-spec</ulink>
    </literallayout>

    <note>
      <para>Panel launchers and desktop objects also use desktop entry files.
      The desktop entry files for launchers and desktop objects provide the
      same information as for items in a menu. For example, the desktop entry
      files provide the command to run when a user chooses the launcher or
      object.</para>
    </note>
  </sect1>

  <sect1 id="menustructure-14">
    <title>Directory Entry Files</title>

    <indexterm>
      <primary>directory entry files</primary>
    </indexterm>

    <indexterm>
      <primary>.directory files</primary>

      <see>directory entry files</see>
    </indexterm>

    <para>A <firstterm>directory entry file</firstterm> is a data file that
    provides information about a menu. The directory entry file specifies the
    details for the menu such as a name, a tooltip, and an icon. Directory
    entry files have a <filename>.directory</filename> file extension.</para>

    <para>Directory entry files must reside in the
    <filename>$XDG_DATA_DIRS/desktop-directories</filename> directory. If
    <envar>$XDG_DATA_DIRS</envar> is not set, then the default path is
    <filename>/usr/share</filename> is used. This also implies that user
    specific directory entries may be located at
    <filename>$XDG_DATA_HOME/desktop-directories</filename>
    which is searched first. If <envar>$XDG_DATA_HOME</envar> is not set, then
    the default path <filename>~/.local/share</filename> is used. Directory
    entries are collected from all directories in the
    <envar>$XDG_DATA_DIRS</envar> environment variable. Directories which
    appear first in <envar>$XDG_DATA_DIRS</envar> are given precedence when
    there are several <filename>.directory</filename> files with the same
    name.</para>

    <para>The following is a sample directory entry file:</para>

    <programlisting>[Desktop Entry]
Name=Graphics
Name[fr]=Graphisme
...
Comment=Graphics applications
Comment[fr]=Applications graphiques
...
Icon=gnome-graphics
Type=Directory
Encoding=UTF-8</programlisting>

    <para><xref linkend="menustructure-TBL-15" /> describes the most important
    keys in directory entry files.</para>

    <table frame="topbot" id="menustructure-TBL-15">
      <title>Directory Entry Keys</title>

      <tgroup cols="2" colsep="0" rowsep="0">
        <colspec colname="colspec0" colwidth="27.07*" />

        <colspec colname="colspec1" colwidth="72.93*" />

        <thead>
          <row rowsep="1">
            <entry><para>Directory Entry Key</para></entry>

            <entry><para>Description</para></entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry colname="colspec0" valign="top"><para>
            <literal>Name</literal> </para></entry>

            <entry colname="colspec1" valign="top"><para>Specifies the name of
            the menu. This name is displayed on the menu. </para></entry>
          </row>

          <row>
            <entry colname="colspec0" valign="top"><para>
            <literal>Comment</literal> </para></entry>

            <entry colname="colspec1" valign="top"><para>Specifies a short
            description of the menu. The comment is displayed as a tooltip
            when you point to the menu. </para></entry>
          </row>

          <row>
            <entry colname="colspec0" valign="top"><para>
            <literal>Icon</literal> </para></entry>

            <entry colname="colspec1" valign="top"><para>Specifies the
            filename of an icon that represents the menu. Does not specify the
            path to the filename, or the file extension. </para></entry>
          </row>

          <row>
            <entry valign="top"><para> <literal>Type</literal> </para></entry>

            <entry valign="top"><para>Specifies the type of menu. The value of
            this key is always <literal>Directory</literal>.</para></entry>
          </row>
        </tbody>
      </tgroup>
    </table>
  </sect1>

  <sect1 id="menustructure-2">
    <title>Editing System Menus</title>

    <anchor id="menustructure-23" />

    <indexterm>
      <primary>menus</primary>

      <secondary>editing</secondary>
    </indexterm>

    <para>You can edit menu configuration files and menu data files manually
    to customize menus.</para>

    <sect2 id="menustructure-3">
      <title>Adding Menus</title>

      <anchor id="menustructure-19" />

      <anchor id="menustructure-20" />

      <indexterm>
        <primary>menus</primary>

        <secondary>adding</secondary>
      </indexterm>

      <para>To add a menu for all users, perform the following steps:</para>

      <orderedlist>
        <listitem>
          <para>Create a directory entry file for the item that you want to
          add. Place the directory entry file in the
          <filename>$XDG_DATA_DIRS/desktop-directories</filename>
          directory. For more information on directory entry files, see <xref
          linkend="menustructure-14" />.</para>
        </listitem>

        <listitem>
          <para>Locate the
          <filename>$XDG_CONFIG_DIRS/menus/applications.menu</filename>
          file.</para>
        </listitem>

        <listitem>
          <para>In the <filename>.menu</filename> file, add a
          <literal>&lt;Menu&gt;</literal> element for the new menu. For more
          information on <filename>.menu</filename> files, see <xref
          linkend="menustructure-13" />.</para>
        </listitem>

        <listitem>
          <para>Create a <literal>&lt;Name&gt;</literal> element below
          <literal>&lt;Menu&gt;</literal>. The content of the element should
          contain the name for the menu.</para>
        </listitem>

        <listitem>
          <para>Create a <literal>&lt;Directory&gt;</literal> element below
          <literal>&lt;Menu&gt;</literal>. The content of the element should
          contain the name of the directory entry file.</para>
        </listitem>

        <listitem>
          <para>See <xref linkend="menustructure-4" /> for how to add an item
          to the menu.</para>
        </listitem>
      </orderedlist>

      <para>The next time that users log in, the menu should appear in the
      menu bar.</para>

      <note>
        <title>Missing Menu?</title>

        <para>If you did not specify any matching rules in the
        <literal>&lt;Include&gt;</literal> element, or if the rule did not
        match any desktop entries, then you may not see the menu in the menu
        bar.</para>
      </note>
    </sect2>

    <sect2 id="menustructure-4">
      <title>Adding an Item to a Menu</title>

      <indexterm>
        <primary>menus</primary>

        <secondary>adding items to</secondary>
      </indexterm>

      <para>To add an item to a menu for all users, perform the following
      steps:</para>

      <orderedlist>
        <listitem>
          <para>Create a desktop entry file for the item that you want to add.
          For more information on desktop entry files, see <xref
          linkend="menustructure-desktopentry" />.</para>
        </listitem>

        <listitem>
          <para>Place the desktop entry file in the 
          <filename>$XDG_DATA_DIRS/applications</filename> folder.</para>
        </listitem>

        <listitem>
          <para>Locate the
          <filename>$XDG_CONFIG_DIRS/menus/applications.menu</filename>
          file.</para>
        </listitem>

        <listitem>
          <para>Verify that a <literal>&lt;Menu&gt;</literal> element contains
          an <literal>&lt;Include&gt;</literal> element with a matching rule
          that selects the desktop entry file made in step 1.</para>
        </listitem>
      </orderedlist>

      <para>The next time that users log in, the menu item is in the assigned
      location.</para>
    </sect2>

    <sect2 id="menustructure-9">
      <title>Editing the Properties of a Menu</title>

      <indexterm>
        <primary>menus</primary>

        <secondary>editing properties of</secondary>
      </indexterm>

      <para>To edit the properties of a menu for all users, perform the
      following steps:</para>

      <orderedlist>
        <listitem>
          <para>Locate the
          <filename>$XDG_CONFIG_DIRS/menus/applications.menu</filename>
          file.</para>
        </listitem>

        <listitem>
          <para>Find the <literal>&lt;Menu&gt;</literal> entry in this file
          that corresponds to the menu you want to modify. Note the filename
          of the directory entry in the <literal>&lt;Directory&gt;</literal>
          element.</para>
        </listitem>

        <listitem>
          <para>Locate the directory entry for this menu. Modify the contents
          to change the properties of the menu. For more information on
          <filename>.directory</filename> files, see <xref
          linkend="menustructure-14" />.</para>
        </listitem>
      </orderedlist>
    </sect2>

    <sect2 id="menustructure-10">
      <title>Editing a Menu Item</title>

      <indexterm>
        <primary>menus</primary>

        <secondary>editing menu items</secondary>
      </indexterm>

      <para>To edit a menu item, perform the following steps:</para>

      <orderedlist>
        <listitem>
          <para>Locate the desktop entry in the 
          <filename>$XDG_DATA_DIRS/applications</filename>
          directory that corresponds to the menu item.</para>
        </listitem>

        <listitem>
          <para>Edit the desktop entry to change the properties of the menu
          item. For more information on desktop entry files, see <xref
          linkend="menustructure-desktopentry" />.</para>
        </listitem>
      </orderedlist>
    </sect2>

    <sect2 id="menustructure-11">
      <title>Deleting an Item from a Menu</title>

      <indexterm>
        <primary>menus</primary>

        <secondary>deleting menu items</secondary>
      </indexterm>

      <para>To delete an item from a menu for all users:</para>

      <orderedlist>
        <listitem>
          <para>Locate the
          <filename>$XDG_CONFIG_DIRS/menus/applications.menu</filename>
          file.</para>
        </listitem>

        <listitem>
          <para>Find the <literal>&lt;Menu&gt;</literal> element in this file
          that contains the desktop entry you want to delete.</para>
        </listitem>

        <listitem>
          <para>Insert an <literal>&lt;Exclude&gt;</literal> element after the
          closing tag for the <literal>&lt;Include&gt;</literal> element. Make
          sure this is in the <literal>&lt;Menu&gt;</literal> element
          determined in step 2.</para>
        </listitem>

        <listitem>
          <para>Insert the <literal>&lt;Filename&gt;</literal> matching rule
          as a subelement of <literal>&lt;Exclude&gt;</literal> to
          specifically exclude a desktop entry.</para>
        </listitem>
      </orderedlist>

      <para>The next time that users log in, the menu item is not displayed in
      the menu. <xref linkend="menustructure-deleteitem" /> shows how this
      done in the <filename>applications.menu</filename> file. The desktop
      entry for <filename>dasher.desktop</filename> is explicitly excluded
      from showing up in the accessibility menu.</para>

      <example id="menustructure-deleteitem">
        <title>Deleting an Item from a Menu</title>

        <programlisting>&lt;!-- ... --&gt;

  &lt;Menu&gt;
    &lt;Name&gt;Accessibility&lt;/Name&gt;
    &lt;Directory&gt;Accessibility.directory&lt;/Directory&gt;
    &lt;Include&gt;
      &lt;And&gt;
        &lt;Category&gt;Accessibility&lt;/Category&gt;
        &lt;Not&gt;&lt;Category&gt;Settings&lt;/Category&gt;&lt;/Not&gt;
      &lt;/And&gt;
    &lt;/Include&gt;
    &lt;Exclude&gt;
      &lt;Filename&gt;dasher.desktop&lt;/Filename&gt;
    &lt;/Exclude&gt;
  &lt;/Menu&gt;

&lt;!-- ... --&gt;
</programlisting>
      </example>
    </sect2>
  </sect1>

  <sect1 id="menustructure-usermenus">
    <title>Editing User Menus and Menu Merging</title>

    <indexterm>
      <primary>menus</primary>

      <secondary>editing user menus</secondary>
    </indexterm>

    <para>You can use the following GNOME Desktop applications to edit menus
    for users:</para>

    <itemizedlist>
      <listitem>
        <para>GNOME Menu Editor</para>
      </listitem>
    </itemizedlist>

    <para>A simple menu editor is available for users to edit their menus. For
    more information, see <ulink
    url="ghelp:user-guide?goseditmainmenu-1">Working With Menus</ulink> in the
    <ulink url="ghelp:user-guide">GNOME User Guide</ulink>. Alternatively, you
    can manually create and edit a user menu file.</para>

    <para>To manually create a custom menu for a user, the
    <filename>$XDG_CONFIG_HOME/menus/applications.menu</filename>
    must exist. In the case that <envar>$XDG_CONFIG_HOME</envar> is not set,
    the default <filename>~/.config</filename> directory is used. Since this is the
    first location that is searched for the
    <filename>applications.menu</filename> file, it takes precedence over all
    other menu files.</para>

    <para>User menus can contain all the elements described in <xref
    linkend="menustructure-13" />. For a complete list of the elements
    allowed, see the <ulink
    url="http://www.freedesktop.org/wiki/Standards/menu-spec">XDG menu
    specification</ulink>.</para>

    <para>Since user menu files take precedence over the system menu file, it
    will completely replace the system menu unless it explicitly
    <emphasis>merges</emphasis> the system menu. Information on menu merging
    is available in the following subsections.</para>

    <sect2>
      <title>Merging the System Menu</title>

      <indexterm>
        <primary>menus</primary>

        <secondary>merging the system menu</secondary>
      </indexterm>

      <para>Often, a user only wants to add or delete menu items in addition
      to the standard system menu. To support single changes like these, it is
      recommended that you use the <literal>&lt;MergeFile&gt;</literal>
      element with the attribute <literal>type="parent"</literal> within the
      user's <filename>applications.menu</filename> file.</para>

      <para>The <literal>&lt;MergeFile&gt;</literal> element allows a menu to
      be merged with the contents of the user's menu file. When you specify
      the attribute <literal>type="parent"</literal>, then the contents of the
      <literal>&lt;MergeFile&gt;</literal> element are ignored and the next
      <filename>applications.menu</filename> file in the
      <filename>$XDG_CONFIG_DIRS/menus</filename> directory is used for
      merging.</para>

      <note>
        <title>Older Specifications</title>

        <para>Older specifications did not include the <literal>type</literal>
        attribute and simply required the location of the menu file to be
        merged as the content of the <literal>&lt;MergeFile&gt;</literal>
        element. As a result, you may still see a location specified in the
        contents of <literal>&lt;MergeFile&gt;</literal>, even when
        <literal>type="parent"</literal>.</para>
      </note>

      <para>The merging is performed as follows:</para>

      <itemizedlist>
        <listitem>
          <para>The children of the root <literal>&lt;Menu&gt;</literal>
          element in the merged menu file<footnote>
              <para>Merged menu file refers to the next
              <filename>applications.menu</filename> in the
              <filename>$XDG_CONFIG_DIRS/menus</filename> directory.</para>
            </footnote> are substituted for the
          <literal>&lt;MergeFile&gt;</literal> element in the base menu
          file.</para>
        </listitem>

        <listitem>
          <para>All child <literal>&lt;Menu&gt;</literal> elements with the
          same name are consolidated into a single
          <literal>&lt;Menu&gt;</literal> element. This is by done appending
          all child elements of each <literal>&lt;Menu&gt;</literal> element
          with the same name into the <emphasis>last</emphasis> occurrence of
          the menu element.</para>
        </listitem>
      </itemizedlist>

      <para><xref linkend="menustructure-systemmerge" /> shows an example of a
      user menu file explicitly merging the system menu file.</para>

      <example id="menustructure-systemmerge">
        <title>Merging the System Menu</title>

        <programlisting>&lt;!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"
 "http://www.freedesktop.org/standards/menu-spec/menu-1.0.dtd"&gt;

&lt;Menu&gt;
  &lt;Name&gt;Applications&lt;/Name&gt;
  &lt;MergeFile type="parent"&gt;/etc/xdg/menus/applications.menu&lt;/MergeFile&gt;
  &lt;Menu&gt;
    &lt;Name&gt;Accessibility&lt;/Name&gt;
    &lt;Exclude&gt;
      &lt;Filename&gt;dasher.desktop&lt;/Filename&gt;
    &lt;/Exclude&gt;
  &lt;/Menu&gt;
&lt;/Menu&gt;
</programlisting>
      </example>
    </sect2>

    <sect2>
      <title>Merging Arbitrary Menus</title>

      <indexterm>
        <primary>menus</primary>

        <secondary>merging arbitrary menus</secondary>
      </indexterm>

      <para>Arbitrary menu files can be merged in much the same way as system
      menus. The difference is that the <literal>type</literal> attribute must
      be set to <literal>path</literal> or must be excluded from the
      <literal>&lt;MergeFile&gt;</literal> element in order to do this type of
      merge.</para>

      <para>The merge is performed in the same way except that the location of
      the <emphasis>merged menu file</emphasis> is specified in the contents
      of the <literal>&lt;MergeFile&gt;</literal> element.</para>
    </sect2>
  </sect1>
</chapter>