home *** CD-ROM | disk | FTP | other *** search
/ PC Welt 2006 November (DVD) / PCWELT_11_2006.ISO / casper / filesystem.squashfs / usr / share / gnome / help / system-admin-guide / C / menustructure.xml < prev    next >
Encoding:
Extensible Markup Language  |  2006-08-09  |  37.9 KB  |  1,051 lines

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <chapter id="menustructure-0">
  3.   <title>Customizing Menus</title>
  4.  
  5.   <anchor id="menustructure-22" />
  6.  
  7.   <anchor id="menustructure-TBL-12" />
  8.  
  9.   <anchor id="menustructure-TBL-17" />
  10.  
  11.   <highlights>
  12.     <para>The information in this chapter describes how the GNOME Desktop
  13.     implements menus and how you can customize menus.</para>
  14.   </highlights>
  15.  
  16.   <sect1 id="menustructure-1">
  17.     <title>Introduction to Menus</title>
  18.  
  19.     <indexterm>
  20.       <primary>menus</primary>
  21.  
  22.       <secondary>introduction</secondary>
  23.     </indexterm>
  24.  
  25.     <para>The GNOME Desktop implements menus according to the <ulink
  26.     url="http://www.freedesktop.org/wiki/Standards/menu-spec">XDG menu
  27.     specification</ulink>. By supporting this specification, GNOME allows you
  28.     to:</para>
  29.  
  30.     <itemizedlist>
  31.       <listitem>
  32.         <para>Customize the menu hierarchy easily. You can edit a small number
  33.         of files to customize the menu hierarchy. You do not need to modify
  34.         your applications or move files.</para>
  35.       </listitem>
  36.  
  37.       <listitem>
  38.         <para>Install applications easily. You do not need to provide
  39.         information about the menu hierarchy to applications when you install
  40.         the applications.</para>
  41.       </listitem>
  42.  
  43.       <listitem>
  44.         <para>Configure menus so that users cannot modify the menus.</para>
  45.       </listitem>
  46.     </itemizedlist>
  47.  
  48.     <para>Menus in the GNOME Desktop use the following components:</para>
  49.  
  50.     <itemizedlist>
  51.       <listitem>
  52.         <para>Menu definition files</para>
  53.       </listitem>
  54.  
  55.       <listitem>
  56.         <para>Desktop entry files</para>
  57.       </listitem>
  58.  
  59.       <listitem>
  60.         <para>Directory entry files</para>
  61.       </listitem>
  62.     </itemizedlist>
  63.   </sect1>
  64.  
  65.   <sect1 id="menustructure-13">
  66.     <title>Menu Definition Files</title>
  67.  
  68.     <indexterm>
  69.       <primary>menu definition files</primary>
  70.     </indexterm>
  71.  
  72.     <indexterm>
  73.       <primary>.menu files</primary>
  74.  
  75.       <see>menu definition files</see>
  76.     </indexterm>
  77.  
  78.     <para>Menu files define the hierarchy of menus that are used in the GNOME
  79.     menu bar. By modifying these files, you can customize menus for all users,
  80.     or for a single user depending on the location of the
  81.     <filename>applications.menu</filename> file that you modify.</para>
  82.  
  83.     <para>Menu files must reside at
  84.     <filename>$XDG_CONFIG_DIRS/menus/applications.menu</filename>. If
  85.     <envar>$XDG_CONFIG_DIRS</envar><footnote>
  86.         <para>$XDG_CONFIG_DIRS is the environment variable defined in the
  87.         <ulink url="http://www.freedesktop.org/Standards/basedir-spec">XDG
  88.         base directory specification</ulink>.</para>
  89.       </footnote> is not set, then the default path
  90.     <filename>/etc/xdg</filename> is used. This also implies that a user
  91.     specific version may be located at
  92.     <filename>$XDG_CONFIG_HOME/menus/applications.menu</filename>
  93.     which is searched first. If <envar>$XDG_CONFIG_HOME</envar> is not set,
  94.     then the default path <filename>~/.config</filename> is used. Directories
  95.     which appear first in <envar>$XDG_CONFIG_DIRS</envar> are given precedence
  96.     when there are several <filename>applications.menu</filename> files. The
  97.     first file found is used and subsequent files are ignored.</para>
  98.  
  99.     <para>If you are confused about the order in which paths are searched,
  100.     here is a simple list for resolving the location of
  101.     <filename>applications.menu</filename>:</para>
  102.  
  103.     <orderedlist>
  104.       <listitem>
  105.         <para>Search each directory in <envar>$XDG_CONFIG_HOME</envar> in
  106.         order to find <filename>menus/applications.menu</filename>. If
  107.         <envar>$XDG_CONFIG_HOME</envar> is not set, it defaults to the
  108.         <filename>~/.config/</filename> directory.</para>
  109.       </listitem>
  110.  
  111.       <listitem>
  112.         <para>Search each directory in <envar>$XDG_CONFIG_DIRS</envar> in
  113.         order to find <filename>menus/applications.menu</filename>. If
  114.         <filename>$XDG_CONFIG_DIRS</filename> is not set, it defaults to the
  115.         <filename>/etc/xdg/</filename> directory.</para>
  116.       </listitem>
  117.  
  118.       <listitem>
  119.         <para>Use the first <filename>applications.menu</filename> file
  120.         found.</para>
  121.       </listitem>
  122.     </orderedlist>
  123.  
  124.     <para>You can see an example of a <filename>.menu</filename> file in <xref
  125.     linkend="example-menu" />. In this example, the top level menu is named
  126.     <literal>Applications</literal>, which is specified using the
  127.     <literal><Name></literal> element. The
  128.     <literal>Applications</literal> menu contains a single submenu, but
  129.     several submenus are allowed. Each submenu may also have an
  130.     <literal><Include></literal> element. The purpose of the
  131.     <literal><Include></literal> element is to perform a filter on the
  132.     set of available desktop entries using matching rules.</para>
  133.  
  134.     <para>For example, the <literal><Category></literal> element is a
  135.     basic matching rule that selects a <link
  136.     linkend="menustructure-desktopentry"><emphasis>desktop
  137.     entry</emphasis></link> only if the <link
  138.     linkend="category-key"><literal>Categories</literal> key</link> contains
  139.     the content of the <literal><Category></literal> element. In the
  140.     example, the <literal>Accessories</literal> menu will include a
  141.     <emphasis>desktop entry</emphasis> only if it contains
  142.     <quote>Utility</quote> but not <quote>System</quote> in the Categories
  143.     key. For more information on the Categories key, see <xref
  144.     linkend="menustructure-desktopentry" />.</para>
  145.  
  146.     <example id="example-menu">
  147.       <title>Example of a <filename>.menu</filename> file</title>
  148.  
  149.       <para><programlisting><!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"
  150.  "http://www.freedesktop.org/standards/menu-spec/1.0/menu.dtd">
  151. <Menu>
  152.   <Name>Applications</Name>
  153.   <Directory>Applications.directory</Directory>
  154.  
  155.   <!-- Read standard .directory and .desktop file locations -->
  156.   <DefaultAppDirs/>
  157.   <DefaultDirectoryDirs/>
  158.  
  159.   <!-- Accessories submenu -->
  160.   <Menu>
  161.     <Name>Accessories</Name>
  162.     <Directory>Accessories.directory</Directory>
  163.     <Include>
  164.       <And>
  165.         <Category>Utility</Category>
  166.         <Not>
  167.           <Category>System</Category>
  168.         </Not>
  169.       </And>
  170.     </Include>
  171.   </Menu> <!-- End Accessories -->
  172.  
  173.   <!-- possibly more submenus -->
  174.  
  175. </Menu> <!-- End Applications -->
  176. </programlisting></para>
  177.     </example>
  178.  
  179.     <para><xref linkend="menustructure-xmlmenu" /> describes some of the
  180.     elements in <filename>.menu</filename> files. For a more detailed
  181.     description, please see the <ulink
  182.     url="http://www.freedesktop.org/wiki/Standards/menu-spec">XDG menu
  183.     specification</ulink>.</para>
  184.  
  185.     <table frame="topbot" id="menustructure-xmlmenu">
  186.       <title>Menu Definition File Elements</title>
  187.  
  188.       <tgroup cols="2" colsep="0" rowsep="0">
  189.         <colspec colname="colspec2" colwidth="33.83*" />
  190.  
  191.         <colspec colname="colspec3" colwidth="80.00*" />
  192.  
  193.         <thead>
  194.           <row rowsep="1">
  195.             <entry><para>Element</para></entry>
  196.  
  197.             <entry><para>Description</para></entry>
  198.           </row>
  199.         </thead>
  200.  
  201.         <tbody>
  202.           <row>
  203.             <entry colname="colspec2"
  204.             valign="top"><para><literal><Menu></literal> </para></entry>
  205.  
  206.             <entry colname="colspec3" valign="top"><para>The root element
  207.             which may contain nested <literal><Menu></literal> elements
  208.             that define submenus. How these elements are nested determines the
  209.             menu structure.</para></entry>
  210.           </row>
  211.  
  212.           <row>
  213.             <entry colname="colspec2"
  214.             valign="top"><para><literal><Name></literal> </para></entry>
  215.  
  216.             <entry colname="colspec3" valign="top"><para>Specifies the name of
  217.             the menu. Every <literal><Menu></literal> element must
  218.             contain a <literal><Name></literal> element.</para></entry>
  219.           </row>
  220.  
  221.           <row>
  222.             <entry colname="colspec2"
  223.             valign="top"><para><literal><Directory></literal>
  224.             </para></entry>
  225.  
  226.             <entry colname="colspec3" valign="top"><para>Specifies the name of
  227.             the directory entry file that specifies the name, comment, and
  228.             icon for the menu. If this element is not specified, then the
  229.             <literal><Name></literal> element is to be used to display
  230.             the menu name.</para><para>By default,
  231.             <filename>.directory</filename> files are searched for in the
  232.             location
  233.             <filename>$XDG_DATA_DIRS/desktop-directories/</filename>
  234.             as set forth in the <citetitle>XDG menu
  235.             specification.</citetitle></para></entry>
  236.           </row>
  237.  
  238.           <row>
  239.             <entry
  240.             colname="colspec2"><literal><DefaultAppDirs></literal></entry>
  241.  
  242.             <entry colname="colspec3">This is an instruction which indicates
  243.             that all the available desktop entries from
  244.             <filename>$XDG_DATA_DIRS/applications/</filename>
  245.             should be scanned. If this instruction is not included, then these
  246.             locations are not scanned for desktop entries.</entry>
  247.           </row>
  248.  
  249.           <row>
  250.             <entry
  251.             colname="colspec2"><literal><DefaultDirectoryDirs></literal></entry>
  252.  
  253.             <entry colname="colspec3">This is an instruction which indicates
  254.             that all the available directory entries from
  255.             <filename>$XDG_DATA_DIRS/desktop-directories/</filename>
  256.             should be scanned. If the instruction is not included, then these
  257.             locations are not scanned for directory entries.</entry>
  258.           </row>
  259.  
  260.           <row>
  261.             <entry colname="colspec2"
  262.             valign="top"><para><literal><Include></literal></para></entry>
  263.  
  264.             <entry colname="colspec3">Contains a list of matching rules by
  265.             which the contents of a menu are generated. May include the
  266.             <literal><Filename></literal>,
  267.             <literal><Category></literal>,
  268.             <literal><And></literal>, <literal><Or></literal>,
  269.             <literal><Not></literal>, or <literal><All></literal>
  270.             matching rules. If more than one rule is present, the rules are
  271.             logically ORed so that <emphasis>desktop entries</emphasis> that
  272.             match any rule are included.</entry>
  273.           </row>
  274.  
  275.           <row>
  276.             <entry
  277.             colname="colspec2"><literal><Exclude></literal></entry>
  278.  
  279.             <entry colname="colspec3">The opposite of
  280.             <literal><Include></literal> since any <emphasis>desktop
  281.             entries</emphasis> that are matched in this element are excluded
  282.             from the previous set of included elements. For this reason, this
  283.             element must appear after the <literal><Include></literal>
  284.             element.</entry>
  285.           </row>
  286.  
  287.           <row>
  288.             <entry
  289.             colsep="colspec2"><literal><Filename></literal></entry>
  290.  
  291.             <entry colname="colspec3">A matching rule that selects a
  292.             <emphasis>desktop entry</emphasis> when the Desktop File-Id
  293.             matches the contents of the <literal><Filename></literal>
  294.             element.</entry>
  295.           </row>
  296.  
  297.           <row>
  298.             <entry colname="colspec2"><literal><Category></literal></entry>
  299.  
  300.             <entry colname="colspec3">A matching rule that selects a
  301.             <emphasis>desktop entry</emphasis> when the Categories key matches
  302.             the contents of the <literal><Category></literal>
  303.             element.</entry>
  304.           </row>
  305.  
  306.           <row>
  307.             <entry colname="colspec2"><literal><And></literal></entry>
  308.  
  309.             <entry colname="colspec3">A matching rule that selects a
  310.             <emphasis>desktop entry</emphasis> when it is selected by
  311.             <emphasis>all</emphasis> the nested matching rules in the
  312.             <literal><And></literal> element.</entry>
  313.           </row>
  314.  
  315.           <row>
  316.             <entry colname="colspec2"><literal><Or></literal></entry>
  317.  
  318.             <entry colname="colspec3">A matching rule that selects a
  319.             <emphasis>desktop entry</emphasis> when it is selected by
  320.             <emphasis>any</emphasis> of the nested matching rules in the
  321.             <literal><Or></literal> element.</entry>
  322.           </row>
  323.  
  324.           <row>
  325.             <entry colname="colspec2"><literal><Not></literal></entry>
  326.  
  327.             <entry colname="colspec3">A matching rule that does not select a
  328.             <emphasis>desktop entry</emphasis> when it is selected by
  329.             <emphasis>any</emphasis> of the nested matching rules in the
  330.             <literal><Not></literal> element.</entry>
  331.           </row>
  332.  
  333.           <row>
  334.             <entry colname="colspec2"><literal><All></literal></entry>
  335.  
  336.             <entry colname="colspec3">A matching rule which selects all
  337.             <emphasis>desktop entries</emphasis>.</entry>
  338.           </row>
  339.         </tbody>
  340.       </tgroup>
  341.     </table>
  342.   </sect1>
  343.  
  344.   <sect1 id="menustructure-desktopentry">
  345.     <title>Desktop Entry Files</title>
  346.  
  347.     <anchor id="menustructure-6" />
  348.  
  349.     <indexterm>
  350.       <primary>desktop entry files</primary>
  351.     </indexterm>
  352.  
  353.     <indexterm>
  354.       <primary>.desktop files</primary>
  355.  
  356.       <see>desktop entry files</see>
  357.     </indexterm>
  358.  
  359.     <para>A <firstterm>desktop entry file</firstterm> is a data file that
  360.     provides information about an item in a menu. The desktop entry file
  361.     specifies the details for the item such as a name, a command to run, an
  362.     icon, and so on. It also contains keywords which determine the location of
  363.     the item in the menu hierarchy.</para>
  364.  
  365.     <para>Desktop entry files must reside in the
  366.     <filename>$XDG_DATA_DIRS/applications</filename> directory and must have a
  367.     <filename>.desktop</filename> file extension. If
  368.     <envar>$XDG_DATA_DIRS</envar><footnote>
  369.         <para>$XDG_DATA_DIRS is the environment variable defined in the <ulink
  370.         url="http://www.freedesktop.org/Standards/basedir-spec">XDG base
  371.         directory specification</ulink>.</para>
  372.       </footnote> is not set, then the default path is
  373.     <filename>/usr/share</filename> is used. This also implies that user
  374.     specific desktop entries may be located at
  375.     <filename>$XDG_DATA_HOME/applications</filename> which is
  376.     searched first. If <envar>$XDG_DATA_HOME</envar> is not set, then the
  377.     default path <filename>~/.local/share</filename> is used. Desktop entries
  378.     are collected from all directories in the <envar>$XDG_DATA_DIRS</envar>
  379.     environment variable. Directories which appear first in
  380.     <envar>$XDG_CONFIG_DIRS</envar> are given precedence when there are
  381.     several <filename>.desktop</filename> files with the same name.</para>
  382.  
  383.     <para>The following is a sample desktop entry file:</para>
  384.  
  385.     <programlisting>[Desktop Entry]
  386. Encoding=UTF-8
  387. Name=Calculator
  388. Name[fr]=Calculatrice
  389. ...
  390. Comment=Perform calculations
  391. Comment[fr]=Effectue des calculs compliqu├⌐s
  392. ...
  393. Exec=gcalctool
  394. Icon=gnome-calculator
  395. Terminal=false
  396. Type=Application
  397. StartupNotify=true
  398. Categories=GTK;GNOME;Application;Utility;</programlisting>
  399.  
  400.     <para><xref linkend="menustructure-TBL-7" /> describes the most important
  401.     keys in desktop entry files. To get more information about desktop entry
  402.     files, see the <ulink
  403.     url="http://www.freedesktop.org/Standards/desktop-entry-spec">XDG Desktop
  404.     Entry Specification</ulink>.</para>
  405.  
  406.     <table frame="topbot" id="menustructure-TBL-7">
  407.       <title>Desktop Entry Keys</title>
  408.  
  409.       <tgroup cols="2" colsep="0" rowsep="0">
  410.         <colspec colname="colspec0" colwidth="25.25*" />
  411.  
  412.         <colspec colname="colspec1" colwidth="74.75*" />
  413.  
  414.         <thead>
  415.           <row rowsep="1">
  416.             <entry><para>Desktop Entry Key</para></entry>
  417.  
  418.             <entry><para>Description</para></entry>
  419.           </row>
  420.         </thead>
  421.  
  422.         <tbody>
  423.           <row>
  424.             <entry colname="colspec0" id="category-key" valign="top"><para>
  425.             <literal>Categories</literal> </para></entry>
  426.  
  427.             <entry colname="colspec1" valign="top"><para>Specifies the
  428.             keywords that describe the item. The keywords are separated with
  429.             semicolons (;). To see a list of the standard category keywords,
  430.             see the desktop menu specification at
  431.                 <ulink url="http://www.freedesktop.org/Standards/menu-spec">
  432.             http://www.freedesktop.org/Standards/menu-spec</ulink>
  433.             </para><para><link linkend="menustructure-13">Menu
  434.             Definition Files</link> map desktop entries to menus by using
  435.             matching rules against the Categories key.</para></entry>
  436.           </row>
  437.  
  438.           <row>
  439.             <entry valign="top"><para> <literal>Comment</literal>
  440.             </para></entry>
  441.  
  442.             <entry valign="top"><para>Specifies a short description of the
  443.             item. The comment is displayed as a tooltip when you point to the
  444.             item in the menu. </para></entry>
  445.           </row>
  446.  
  447.           <row>
  448.             <entry valign="top"><para> <literal>Encoding</literal>
  449.             </para></entry>
  450.  
  451.             <entry valign="top"><para>Specifies the encoding of the desktop
  452.             entry file. </para></entry>
  453.           </row>
  454.  
  455.           <row>
  456.             <entry valign="top"><para> <literal>Exec</literal> </para></entry>
  457.  
  458.             <entry valign="top"><para>Specifies a command to execute when you
  459.             choose the item from the menu. </para></entry>
  460.           </row>
  461.  
  462.           <row>
  463.             <entry colname="colspec0" valign="top"><para>
  464.             <literal>Icon</literal> </para></entry>
  465.  
  466.             <entry colname="colspec1" valign="top"><para>Specifies the
  467.             filename of an icon that represents the item. Does not specify the
  468.             path to the filename, or the file extension. </para></entry>
  469.           </row>
  470.  
  471.           <row>
  472.             <entry><literal>MimeType</literal></entry>
  473.  
  474.             <entry>Specifies the MIME types that the application can handle.</entry>
  475.           </row>
  476.          
  477.           <row>
  478.             <entry valign="top"><para> <literal>Name</literal> </para></entry>
  479.  
  480.             <entry valign="top"><para>Specifies the name of the item. This
  481.             name is displayed on the item in the menu. </para></entry>
  482.           </row>
  483.  
  484.           <row>
  485.             <entry valign="top"><para> <literal>NoDisplay</literal> </para></entry>
  486.  
  487.             <entry valign="top"><para>This options means <quote>This application 
  488.             exists, but don't display it in the menus</quote>.</para></entry>
  489.           </row>
  490.  
  491.           <row>
  492.             <entry colname="colspec0" valign="top"><para>
  493.             <literal>Terminal</literal> </para></entry>
  494.  
  495.             <entry colname="colspec1" valign="top"><para>Specifies whether the
  496.             command in the <literal>Exec</literal> key runs in a terminal
  497.             window. If the value is <literal>true</literal> the command runs
  498.             in a terminal window. </para><para>If the command does not create
  499.             a window in which to run, the value of this key must be
  500.             <literal>true</literal>.</para></entry>
  501.           </row>
  502.  
  503.           <row>
  504.             <entry colname="colspec0" valign="top"><para>
  505.             <literal>Type</literal> </para></entry>
  506.  
  507.             <entry colname="colspec1" valign="top"><para>Specifies the type of
  508.             item. This value is one of the following: </para><itemizedlist>
  509.                 <listitem>
  510.                   <para><literal>Application</literal>: An item that starts an
  511.                   application.</para>
  512.                 </listitem>
  513.  
  514.                 <listitem>
  515.                   <para><literal>Link</literal>: An item that links to a file,
  516.                   folder, or a remote resource (such as a FTP site, a web
  517.            page, a Windows share...).</para>
  518.                 </listitem>
  519.  
  520.                 <listitem>
  521.                   <para><literal>FSDevice</literal>: An item that is a file
  522.                   system device.</para>
  523.                 </listitem>
  524.  
  525.                 <listitem>
  526.                   <para><literal>Directory</literal>: An item that is a
  527.                   Directory.</para>
  528.                 </listitem>
  529.               </itemizedlist></entry>
  530.           </row>
  531.  
  532.         </tbody>
  533.       </tgroup>
  534.     </table>
  535.  
  536.     <para>For more information on the keys in desktop entry files, see the
  537.     desktop entry specification at the following URL:</para>
  538.  
  539.     <literallayout>
  540.     <ulink url="http://www.freedesktop.org/Standards/desktop-entry-spec">http://www.freedesktop.org/Standards/desktop-entry-spec</ulink>
  541.     </literallayout>
  542.  
  543.     <note>
  544.       <para>Panel launchers and desktop objects also use desktop entry files.
  545.       The desktop entry files for launchers and desktop objects provide the
  546.       same information as for items in a menu. For example, the desktop entry
  547.       files provide the command to run when a user chooses the launcher or
  548.       object.</para>
  549.     </note>
  550.   </sect1>
  551.  
  552.   <sect1 id="menustructure-14">
  553.     <title>Directory Entry Files</title>
  554.  
  555.     <indexterm>
  556.       <primary>directory entry files</primary>
  557.     </indexterm>
  558.  
  559.     <indexterm>
  560.       <primary>.directory files</primary>
  561.  
  562.       <see>directory entry files</see>
  563.     </indexterm>
  564.  
  565.     <para>A <firstterm>directory entry file</firstterm> is a data file that
  566.     provides information about a menu. The directory entry file specifies the
  567.     details for the menu such as a name, a tooltip, and an icon. Directory
  568.     entry files have a <filename>.directory</filename> file extension.</para>
  569.  
  570.     <para>Directory entry files must reside in the
  571.     <filename>$XDG_DATA_DIRS/desktop-directories</filename> directory. If
  572.     <envar>$XDG_DATA_DIRS</envar> is not set, then the default path is
  573.     <filename>/usr/share</filename> is used. This also implies that user
  574.     specific directory entries may be located at
  575.     <filename>$XDG_DATA_HOME/desktop-directories</filename>
  576.     which is searched first. If <envar>$XDG_DATA_HOME</envar> is not set, then
  577.     the default path <filename>~/.local/share</filename> is used. Directory
  578.     entries are collected from all directories in the
  579.     <envar>$XDG_DATA_DIRS</envar> environment variable. Directories which
  580.     appear first in <envar>$XDG_DATA_DIRS</envar> are given precedence when
  581.     there are several <filename>.directory</filename> files with the same
  582.     name.</para>
  583.  
  584.     <para>The following is a sample directory entry file:</para>
  585.  
  586.     <programlisting>[Desktop Entry]
  587. Name=Graphics
  588. Name[fr]=Graphisme
  589. ...
  590. Comment=Graphics applications
  591. Comment[fr]=Applications graphiques
  592. ...
  593. Icon=gnome-graphics
  594. Type=Directory
  595. Encoding=UTF-8</programlisting>
  596.  
  597.     <para><xref linkend="menustructure-TBL-15" /> describes the most important
  598.     keys in directory entry files.</para>
  599.  
  600.     <table frame="topbot" id="menustructure-TBL-15">
  601.       <title>Directory Entry Keys</title>
  602.  
  603.       <tgroup cols="2" colsep="0" rowsep="0">
  604.         <colspec colname="colspec0" colwidth="27.07*" />
  605.  
  606.         <colspec colname="colspec1" colwidth="72.93*" />
  607.  
  608.         <thead>
  609.           <row rowsep="1">
  610.             <entry><para>Directory Entry Key</para></entry>
  611.  
  612.             <entry><para>Description</para></entry>
  613.           </row>
  614.         </thead>
  615.  
  616.         <tbody>
  617.           <row>
  618.             <entry colname="colspec0" valign="top"><para>
  619.             <literal>Name</literal> </para></entry>
  620.  
  621.             <entry colname="colspec1" valign="top"><para>Specifies the name of
  622.             the menu. This name is displayed on the menu. </para></entry>
  623.           </row>
  624.  
  625.           <row>
  626.             <entry colname="colspec0" valign="top"><para>
  627.             <literal>Comment</literal> </para></entry>
  628.  
  629.             <entry colname="colspec1" valign="top"><para>Specifies a short
  630.             description of the menu. The comment is displayed as a tooltip
  631.             when you point to the menu. </para></entry>
  632.           </row>
  633.  
  634.           <row>
  635.             <entry colname="colspec0" valign="top"><para>
  636.             <literal>Icon</literal> </para></entry>
  637.  
  638.             <entry colname="colspec1" valign="top"><para>Specifies the
  639.             filename of an icon that represents the menu. Does not specify the
  640.             path to the filename, or the file extension. </para></entry>
  641.           </row>
  642.  
  643.           <row>
  644.             <entry valign="top"><para> <literal>Type</literal> </para></entry>
  645.  
  646.             <entry valign="top"><para>Specifies the type of menu. The value of
  647.             this key is always <literal>Directory</literal>.</para></entry>
  648.           </row>
  649.         </tbody>
  650.       </tgroup>
  651.     </table>
  652.   </sect1>
  653.  
  654.   <sect1 id="menustructure-2">
  655.     <title>Editing System Menus</title>
  656.  
  657.     <anchor id="menustructure-23" />
  658.  
  659.     <indexterm>
  660.       <primary>menus</primary>
  661.  
  662.       <secondary>editing</secondary>
  663.     </indexterm>
  664.  
  665.     <para>You can edit menu configuration files and menu data files manually
  666.     to customize menus.</para>
  667.  
  668.     <sect2 id="menustructure-3">
  669.       <title>Adding Menus</title>
  670.  
  671.       <anchor id="menustructure-19" />
  672.  
  673.       <anchor id="menustructure-20" />
  674.  
  675.       <indexterm>
  676.         <primary>menus</primary>
  677.  
  678.         <secondary>adding</secondary>
  679.       </indexterm>
  680.  
  681.       <para>To add a menu for all users, perform the following steps:</para>
  682.  
  683.       <orderedlist>
  684.         <listitem>
  685.           <para>Create a directory entry file for the item that you want to
  686.           add. Place the directory entry file in the
  687.           <filename>$XDG_DATA_DIRS/desktop-directories</filename>
  688.           directory. For more information on directory entry files, see <xref
  689.           linkend="menustructure-14" />.</para>
  690.         </listitem>
  691.  
  692.         <listitem>
  693.           <para>Locate the
  694.           <filename>$XDG_CONFIG_DIRS/menus/applications.menu</filename>
  695.           file.</para>
  696.         </listitem>
  697.  
  698.         <listitem>
  699.           <para>In the <filename>.menu</filename> file, add a
  700.           <literal><Menu></literal> element for the new menu. For more
  701.           information on <filename>.menu</filename> files, see <xref
  702.           linkend="menustructure-13" />.</para>
  703.         </listitem>
  704.  
  705.         <listitem>
  706.           <para>Create a <literal><Name></literal> element below
  707.           <literal><Menu></literal>. The content of the element should
  708.           contain the name for the menu.</para>
  709.         </listitem>
  710.  
  711.         <listitem>
  712.           <para>Create a <literal><Directory></literal> element below
  713.           <literal><Menu></literal>. The content of the element should
  714.           contain the name of the directory entry file.</para>
  715.         </listitem>
  716.  
  717.         <listitem>
  718.           <para>See <xref linkend="menustructure-4" /> for how to add an item
  719.           to the menu.</para>
  720.         </listitem>
  721.       </orderedlist>
  722.  
  723.       <para>The next time that users log in, the menu should appear in the
  724.       menu bar.</para>
  725.  
  726.       <note>
  727.         <title>Missing Menu?</title>
  728.  
  729.         <para>If you did not specify any matching rules in the
  730.         <literal><Include></literal> element, or if the rule did not
  731.         match any desktop entries, then you may not see the menu in the menu
  732.         bar.</para>
  733.       </note>
  734.     </sect2>
  735.  
  736.     <sect2 id="menustructure-4">
  737.       <title>Adding an Item to a Menu</title>
  738.  
  739.       <indexterm>
  740.         <primary>menus</primary>
  741.  
  742.         <secondary>adding items to</secondary>
  743.       </indexterm>
  744.  
  745.       <para>To add an item to a menu for all users, perform the following
  746.       steps:</para>
  747.  
  748.       <orderedlist>
  749.         <listitem>
  750.           <para>Create a desktop entry file for the item that you want to add.
  751.           For more information on desktop entry files, see <xref
  752.           linkend="menustructure-desktopentry" />.</para>
  753.         </listitem>
  754.  
  755.         <listitem>
  756.           <para>Place the desktop entry file in the 
  757.           <filename>$XDG_DATA_DIRS/applications</filename> folder.</para>
  758.         </listitem>
  759.  
  760.         <listitem>
  761.           <para>Locate the
  762.           <filename>$XDG_CONFIG_DIRS/menus/applications.menu</filename>
  763.           file.</para>
  764.         </listitem>
  765.  
  766.         <listitem>
  767.           <para>Verify that a <literal><Menu></literal> element contains
  768.           an <literal><Include></literal> element with a matching rule
  769.           that selects the desktop entry file made in step 1.</para>
  770.         </listitem>
  771.       </orderedlist>
  772.  
  773.       <para>The next time that users log in, the menu item is in the assigned
  774.       location.</para>
  775.     </sect2>
  776.  
  777.     <sect2 id="menustructure-9">
  778.       <title>Editing the Properties of a Menu</title>
  779.  
  780.       <indexterm>
  781.         <primary>menus</primary>
  782.  
  783.         <secondary>editing properties of</secondary>
  784.       </indexterm>
  785.  
  786.       <para>To edit the properties of a menu for all users, perform the
  787.       following steps:</para>
  788.  
  789.       <orderedlist>
  790.         <listitem>
  791.           <para>Locate the
  792.           <filename>$XDG_CONFIG_DIRS/menus/applications.menu</filename>
  793.           file.</para>
  794.         </listitem>
  795.  
  796.         <listitem>
  797.           <para>Find the <literal><Menu></literal> entry in this file
  798.           that corresponds to the menu you want to modify. Note the filename
  799.           of the directory entry in the <literal><Directory></literal>
  800.           element.</para>
  801.         </listitem>
  802.  
  803.         <listitem>
  804.           <para>Locate the directory entry for this menu. Modify the contents
  805.           to change the properties of the menu. For more information on
  806.           <filename>.directory</filename> files, see <xref
  807.           linkend="menustructure-14" />.</para>
  808.         </listitem>
  809.       </orderedlist>
  810.     </sect2>
  811.  
  812.     <sect2 id="menustructure-10">
  813.       <title>Editing a Menu Item</title>
  814.  
  815.       <indexterm>
  816.         <primary>menus</primary>
  817.  
  818.         <secondary>editing menu items</secondary>
  819.       </indexterm>
  820.  
  821.       <para>To edit a menu item, perform the following steps:</para>
  822.  
  823.       <orderedlist>
  824.         <listitem>
  825.           <para>Locate the desktop entry in the 
  826.           <filename>$XDG_DATA_DIRS/applications</filename>
  827.           directory that corresponds to the menu item.</para>
  828.         </listitem>
  829.  
  830.         <listitem>
  831.           <para>Edit the desktop entry to change the properties of the menu
  832.           item. For more information on desktop entry files, see <xref
  833.           linkend="menustructure-desktopentry" />.</para>
  834.         </listitem>
  835.       </orderedlist>
  836.     </sect2>
  837.  
  838.     <sect2 id="menustructure-11">
  839.       <title>Deleting an Item from a Menu</title>
  840.  
  841.       <indexterm>
  842.         <primary>menus</primary>
  843.  
  844.         <secondary>deleting menu items</secondary>
  845.       </indexterm>
  846.  
  847.       <para>To delete an item from a menu for all users:</para>
  848.  
  849.       <orderedlist>
  850.         <listitem>
  851.           <para>Locate the
  852.           <filename>$XDG_CONFIG_DIRS/menus/applications.menu</filename>
  853.           file.</para>
  854.         </listitem>
  855.  
  856.         <listitem>
  857.           <para>Find the <literal><Menu></literal> element in this file
  858.           that contains the desktop entry you want to delete.</para>
  859.         </listitem>
  860.  
  861.         <listitem>
  862.           <para>Insert an <literal><Exclude></literal> element after the
  863.           closing tag for the <literal><Include></literal> element. Make
  864.           sure this is in the <literal><Menu></literal> element
  865.           determined in step 2.</para>
  866.         </listitem>
  867.  
  868.         <listitem>
  869.           <para>Insert the <literal><Filename></literal> matching rule
  870.           as a subelement of <literal><Exclude></literal> to
  871.           specifically exclude a desktop entry.</para>
  872.         </listitem>
  873.       </orderedlist>
  874.  
  875.       <para>The next time that users log in, the menu item is not displayed in
  876.       the menu. <xref linkend="menustructure-deleteitem" /> shows how this
  877.       done in the <filename>applications.menu</filename> file. The desktop
  878.       entry for <filename>dasher.desktop</filename> is explicitly excluded
  879.       from showing up in the accessibility menu.</para>
  880.  
  881.       <example id="menustructure-deleteitem">
  882.         <title>Deleting an Item from a Menu</title>
  883.  
  884.         <programlisting><!-- ... -->
  885.  
  886.   <Menu>
  887.     <Name>Accessibility</Name>
  888.     <Directory>Accessibility.directory</Directory>
  889.     <Include>
  890.       <And>
  891.         <Category>Accessibility</Category>
  892.         <Not><Category>Settings</Category></Not>
  893.       </And>
  894.     </Include>
  895.     <Exclude>
  896.       <Filename>dasher.desktop</Filename>
  897.     </Exclude>
  898.   </Menu>
  899.  
  900. <!-- ... -->
  901. </programlisting>
  902.       </example>
  903.     </sect2>
  904.   </sect1>
  905.  
  906.   <sect1 id="menustructure-usermenus">
  907.     <title>Editing User Menus and Menu Merging</title>
  908.  
  909.     <indexterm>
  910.       <primary>menus</primary>
  911.  
  912.       <secondary>editing user menus</secondary>
  913.     </indexterm>
  914.  
  915.     <para>You can use the following GNOME Desktop applications to edit menus
  916.     for users:</para>
  917.  
  918.     <itemizedlist>
  919.       <listitem>
  920.         <para>GNOME Menu Editor</para>
  921.       </listitem>
  922.     </itemizedlist>
  923.  
  924.     <para>A simple menu editor is available for users to edit their menus. For
  925.     more information, see <ulink
  926.     url="ghelp:user-guide?goseditmainmenu-1">Working With Menus</ulink> in the
  927.     <ulink url="ghelp:user-guide">GNOME User Guide</ulink>. Alternatively, you
  928.     can manually create and edit a user menu file.</para>
  929.  
  930.     <para>To manually create a custom menu for a user, the
  931.     <filename>$XDG_CONFIG_HOME/menus/applications.menu</filename>
  932.     must exist. In the case that <envar>$XDG_CONFIG_HOME</envar> is not set,
  933.     the default <filename>~/.config</filename> directory is used. Since this is the
  934.     first location that is searched for the
  935.     <filename>applications.menu</filename> file, it takes precedence over all
  936.     other menu files.</para>
  937.  
  938.     <para>User menus can contain all the elements described in <xref
  939.     linkend="menustructure-13" />. For a complete list of the elements
  940.     allowed, see the <ulink
  941.     url="http://www.freedesktop.org/wiki/Standards/menu-spec">XDG menu
  942.     specification</ulink>.</para>
  943.  
  944.     <para>Since user menu files take precedence over the system menu file, it
  945.     will completely replace the system menu unless it explicitly
  946.     <emphasis>merges</emphasis> the system menu. Information on menu merging
  947.     is available in the following subsections.</para>
  948.  
  949.     <sect2>
  950.       <title>Merging the System Menu</title>
  951.  
  952.       <indexterm>
  953.         <primary>menus</primary>
  954.  
  955.         <secondary>merging the system menu</secondary>
  956.       </indexterm>
  957.  
  958.       <para>Often, a user only wants to add or delete menu items in addition
  959.       to the standard system menu. To support single changes like these, it is
  960.       recommended that you use the <literal><MergeFile></literal>
  961.       element with the attribute <literal>type="parent"</literal> within the
  962.       user's <filename>applications.menu</filename> file.</para>
  963.  
  964.       <para>The <literal><MergeFile></literal> element allows a menu to
  965.       be merged with the contents of the user's menu file. When you specify
  966.       the attribute <literal>type="parent"</literal>, then the contents of the
  967.       <literal><MergeFile></literal> element are ignored and the next
  968.       <filename>applications.menu</filename> file in the
  969.       <filename>$XDG_CONFIG_DIRS/menus</filename> directory is used for
  970.       merging.</para>
  971.  
  972.       <note>
  973.         <title>Older Specifications</title>
  974.  
  975.         <para>Older specifications did not include the <literal>type</literal>
  976.         attribute and simply required the location of the menu file to be
  977.         merged as the content of the <literal><MergeFile></literal>
  978.         element. As a result, you may still see a location specified in the
  979.         contents of <literal><MergeFile></literal>, even when
  980.         <literal>type="parent"</literal>.</para>
  981.       </note>
  982.  
  983.       <para>The merging is performed as follows:</para>
  984.  
  985.       <itemizedlist>
  986.         <listitem>
  987.           <para>The children of the root <literal><Menu></literal>
  988.           element in the merged menu file<footnote>
  989.               <para>Merged menu file refers to the next
  990.               <filename>applications.menu</filename> in the
  991.               <filename>$XDG_CONFIG_DIRS/menus</filename> directory.</para>
  992.             </footnote> are substituted for the
  993.           <literal><MergeFile></literal> element in the base menu
  994.           file.</para>
  995.         </listitem>
  996.  
  997.         <listitem>
  998.           <para>All child <literal><Menu></literal> elements with the
  999.           same name are consolidated into a single
  1000.           <literal><Menu></literal> element. This is by done appending
  1001.           all child elements of each <literal><Menu></literal> element
  1002.           with the same name into the <emphasis>last</emphasis> occurrence of
  1003.           the menu element.</para>
  1004.         </listitem>
  1005.       </itemizedlist>
  1006.  
  1007.       <para><xref linkend="menustructure-systemmerge" /> shows an example of a
  1008.       user menu file explicitly merging the system menu file.</para>
  1009.  
  1010.       <example id="menustructure-systemmerge">
  1011.         <title>Merging the System Menu</title>
  1012.  
  1013.         <programlisting><!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN"
  1014.  "http://www.freedesktop.org/standards/menu-spec/menu-1.0.dtd">
  1015.  
  1016. <Menu>
  1017.   <Name>Applications</Name>
  1018.   <MergeFile type="parent">/etc/xdg/menus/applications.menu</MergeFile>
  1019.   <Menu>
  1020.     <Name>Accessibility</Name>
  1021.     <Exclude>
  1022.       <Filename>dasher.desktop</Filename>
  1023.     </Exclude>
  1024.   </Menu>
  1025. </Menu>
  1026. </programlisting>
  1027.       </example>
  1028.     </sect2>
  1029.  
  1030.     <sect2>
  1031.       <title>Merging Arbitrary Menus</title>
  1032.  
  1033.       <indexterm>
  1034.         <primary>menus</primary>
  1035.  
  1036.         <secondary>merging arbitrary menus</secondary>
  1037.       </indexterm>
  1038.  
  1039.       <para>Arbitrary menu files can be merged in much the same way as system
  1040.       menus. The difference is that the <literal>type</literal> attribute must
  1041.       be set to <literal>path</literal> or must be excluded from the
  1042.       <literal><MergeFile></literal> element in order to do this type of
  1043.       merge.</para>
  1044.  
  1045.       <para>The merge is performed in the same way except that the location of
  1046.       the <emphasis>merged menu file</emphasis> is specified in the contents
  1047.       of the <literal><MergeFile></literal> element.</para>
  1048.     </sect2>
  1049.   </sect1>
  1050. </chapter>
  1051.