diff options
| author | Brent Smith <gnome@nextreality.net> | 2006-02-27 04:13:49 +0000 |
|---|---|---|
| committer | Brent Smith <bmsmith@src.gnome.org> | 2006-02-27 04:13:49 +0000 |
| commit | f4122ca589d59cfb47678fa3f1f78085b0131609 (patch) | |
| tree | 6373f4f090950dcb6007c5a6b16e850a51b7a7b0 /gnome2-system-admin-guide | |
| parent | 31077c52d4c27c3444d98afa13933cb8b9d88102 (diff) | |
| download | gnome-user-docs-f4122ca589d59cfb47678fa3f1f78085b0131609.tar.gz gnome-user-docs-f4122ca589d59cfb47678fa3f1f78085b0131609.tar.xz gnome-user-docs-f4122ca589d59cfb47678fa3f1f78085b0131609.zip | |
Rewrite of mimetypes.xml and menustructure.xml to bring them up to date in
2006-02-26 Brent Smith <gnome@nextreality.net>
* gnome2-system-admin-guide/C/ChangeLog:
* gnome2-system-admin-guide/C/menustructure.xml:
* gnome2-system-admin-guide/C/mimetypes.xml:
Rewrite of mimetypes.xml and menustructure.xml to bring them up to
date in the system administration guide. Fixes #158037, #147388
Diffstat (limited to 'gnome2-system-admin-guide')
| -rw-r--r-- | gnome2-system-admin-guide/C/ChangeLog | 15 | ||||
| -rw-r--r-- | gnome2-system-admin-guide/C/menustructure.xml | 1310 | ||||
| -rw-r--r-- | gnome2-system-admin-guide/C/mimetypes.xml | 1420 |
3 files changed, 1622 insertions, 1123 deletions
diff --git a/gnome2-system-admin-guide/C/ChangeLog b/gnome2-system-admin-guide/C/ChangeLog index cfef1b6..eca163f 100644 --- a/gnome2-system-admin-guide/C/ChangeLog +++ b/gnome2-system-admin-guide/C/ChangeLog @@ -1,9 +1,16 @@ +2006-02-26 Brent Smith <gnome@nextreality.net> + + * menustructure.xml: + * mimetypes.xml: + Complete rewrite of menustructure.xml and mimetypes.xml. Old section + ids have been preserved with anchors. + 2006-02-19 Brent Smith <gnome@nextreality.net> - * gconf.xml: - convert the Command Line Options table to a variable list, and changed - examples to use <literallayout> instead of <para> so that the commands - are not justified (which makes them hard to read) + * gconf.xml: + convert the Command Line Options table to a variable list, and changed + examples to use <literallayout> instead of <para> so that the commands + are not justified (which makes them hard to read) 2006-02-15 Brent Smith <gnome@nextreality.net> diff --git a/gnome2-system-admin-guide/C/menustructure.xml b/gnome2-system-admin-guide/C/menustructure.xml index 7e761e8..75f088b 100644 --- a/gnome2-system-admin-guide/C/menustructure.xml +++ b/gnome2-system-admin-guide/C/menustructure.xml @@ -1,251 +1,388 @@ +<?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> + <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 way in which the GNOME Desktop implements menus enables you to do -the following:</para> + + <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. The menu hierarchy is -not based on the file system hierarchy. 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> + <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> + <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>File abstraction layer</para> - </listitem> - <listitem> - <para>Vfolders</para> + <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-22"> - <title>File Abstraction Layer</title> + + <sect1 id="menustructure-13"> + <title>Menu Definition Files</title> + <indexterm> - <primary>menus</primary> - <secondary>file abstraction layer</secondary> + <primary>menu definition files</primary> </indexterm> + <indexterm> - <primary>file abstraction layer, and menus</primary> + <primary>.menu files</primary> + + <see>menu definition files</see> </indexterm> - <para>The <literal>gnome-vfs</literal> file abstraction layer -provides a simplified and generalized way for applications to interact with -files. The file abstraction layer also provides <firstterm>Uniform Resource -Identifier</firstterm> (URI) locations that map to particular menu configuration -files. To add a menu or a menu item for all users, you must add the menu or -menu item to one of the URI locations. <xref linkend="menustructure-TBL-12"/> -lists the menus to which you can add items, and the URI locations that correspond -to the menus.</para> - <table frame="topbot" id="menustructure-TBL-12"> - <title>Menus and URI Locations</title> + + <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, default to + <filename>~/.config/</filename></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, default to + <filename>/etc/xdg/</filename></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><Name></literal> element. The + <literal>Applications</literal> menu contains a single submenu, but + several submenus are allowed. Each submenu may also have an + <literal><Include></literal> element. The purpose of the + <literal><Include></literal> element is to perform a filter on the + set of available desktop entries using matching rules.</para> + + <para>For example, the <literal><Category></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><Category></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><!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN" + "http://www.freedesktop.org/standards/menu-spec/1.0/menu.dtd"> +<Menu> + <Name>Applications</Name> + <Directory>Applications.directory</Directory> + + <!-- Read standard .directory and .desktop file locations --> + <DefaultAppDirs/> + <DefaultDirectoryDirs/> + + <!-- Accessories submenu --> + <Menu> + <Name>Accessories</Name> + <Directory>Accessories.directory</Directory> + <Include> + <And> + <Category>Utility</Category> + <Not> + <Category>System</Category> + </Not> + </And> + </Include> + </Menu> <!-- End Accessories --> + + <!-- possibly more submenus --> + +</Menu> <!-- End Applications --> +</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 colwidth="50*"/> - <colspec colwidth="50*"/> + <colspec colname="colspec2" colwidth="33.83*" /> + + <colspec colname="colspec3" colwidth="80.00*" /> + <thead> <row rowsep="1"> - <entry> - <para>Menu</para> - </entry> - <entry> - <para>URI Locations</para> - </entry> + <entry><para>Element</para></entry> + + <entry><para>Description</para></entry> </row> </thead> + <tbody> <row> - <entry valign="top"> - <para><guimenu>Applications</guimenu> menu for all -users</para> - </entry> - <entry valign="top"> - <para> - <literal>applications-all-users:///</literal> - </para> - </entry> + <entry colname="colspec2" + valign="top"><para><literal><Menu></literal> </para></entry> + + <entry colname="colspec3" valign="top"><para>The root element + which may contain nested <literal><Menu></literal> elements + that define submenus. How these elements are nested determines the + menu structure.</para></entry> </row> + <row> - <entry valign="top"> - <para><guimenu>Desktop Preferences</guimenu> menu for all users</para> - </entry> - <entry valign="top"> - <para> - <literal>preferences-all-users:///</literal> - </para> - </entry> + <entry colname="colspec2" + valign="top"><para><literal><Name></literal> </para></entry> + + <entry colname="colspec3" valign="top"><para>Specifies the name of + the menu. Every <literal><Menu></literal> element must + contain a <literal><Name></literal> element.</para></entry> </row> - </tbody> - </tgroup> - </table> - </sect1> - <sect1 id="menustructure-13"> - <title>Vfolders and Menus</title> - <indexterm> - <primary>menus</primary> - <secondary>vfolders</secondary> - </indexterm> - <indexterm> - <primary>vfolders</primary> - </indexterm> - <para>In general terms, -a <firstterm>vfolder</firstterm> is a virtual representation of items that -reside in a physical location or physical locations on your system. For example, -a vfolder might represent the contents of several directories. A vfolder is -an abstraction from one or more physical locations. In terms of menus in the -GNOME Desktop, a vfolder is a representation in a menu of items that might -be physically located in several directories. </para> - <para><indexterm><primary>menus</primary><secondary>vfolder information files</secondary></indexterm><indexterm><primary>vfolder information files</primary></indexterm>A <firstterm>vfolder information file</firstterm> is an XML file -that describes a vfolder. Vfolder information files specify the structure -of your menus. Vfolder information files specify the names of your menus, -and the order in which applications appear in your menus. Vfolder information -files have a <filename>.vfolder-info</filename> file extension. </para> - <para>The following is an excerpt from a vfolder information file:</para> - <literallayout><?xml version="1.0"?> -<VFolderInfo> -. -. -. - <Folder> - <Name>Applications</Name> - <Desktop>Applications.directory</Desktop> - <Folder> - <Name>Accessories</Name> - <DontShowIfEmpty/> - <Desktop>Accessories.directory</Desktop> - <Query> - <And> - <Keyword>Application</Keyword> - <Keyword>Utility</Keyword> - </And> - </Query> - </Folder> -. -. -. - </Folder> -</VFolderInfo></literallayout> - <para><xref linkend="menustructure-TBL-17"/> describes some of the elements -in vfolder information files.</para> - <table frame="topbot" id="menustructure-TBL-17"> - <title>Vfolder Information File Elements</title> - <tgroup cols="2" colsep="0" rowsep="0"> - <colspec colname="colspec2" colwidth="33.83*"/> - <colspec colname="colspec3" colwidth="66.17*"/> - <thead> - <row rowsep="1"> - <entry> - <para>Element</para> - </entry> - <entry> - <para>Description</para> - </entry> + + <row> + <entry colname="colspec2" + valign="top"><para><literal><Directory></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><Name></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> - </thead> - <tbody> + + <row> + <entry + colname="colspec2"><literal><DefaultAppDirs></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><DefaultDirectoryDirs></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><Include></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><Filename></literal>, + <literal><Category></literal>, + <literal><And></literal>, <literal><Or></literal>, + <literal><Not></literal>, or <literal><All></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" valign="top"> - <para> - <literal><Folder></literal> - </para> - </entry> - <entry colname="colspec3" valign="top"> - <para>Contains the elements that define -the name, content, and structure of the menu.</para> - </entry> + <entry + colname="colspec2"><literal><Exclude></literal></entry> + + <entry colname="colspec3">The opposite of + <literal><Include></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><Include></literal> + element.</entry> </row> + <row> - <entry colname="colspec2" valign="top"> - <para> - <literal><Name></literal> - </para> - </entry> - <entry colname="colspec3" valign="top"> - <para>Specifies the name of the menu.</para> - </entry> + <entry + colsep="colspec2"><literal><Filename></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><Filename></literal> + element.</entry> </row> + <row> - <entry colname="colspec2" valign="top"> - <para> - <literal><Desktop></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.</para> - </entry> + <entry colname="colspec2"><Category></entry> + + <entry colname="colspec3">A matching rule that selects a + <emphasis>desktop entry</emphasis> when the Categories key matches + the contents of the <literal><Category></literal> + element.</entry> </row> + <row> - <entry colname="colspec2" valign="top"> - <para> - <literal><Query></literal> - </para> - </entry> - <entry colname="colspec3" valign="top"> - <para>Specifies a query to run on desktop -entry files. If a desktop entry file matches the requirements in the query, -the menu item is displayed in the menu. </para> - <para>The query in the excerpt -searches for desktop entry files that contain the keywords <literal>Application</literal> and <literal>Utility</literal> in the <literal>Categories</literal> -key. Desktop entry files that match are displayed in the <guimenu>Applications</guimenu> menu.</para> - <para>This element is optional.</para> - </entry> + <entry colname="colspec2"><literal><And></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><And></literal> element.</entry> </row> + <row> - <entry colname="colspec2" valign="top"> - <para> - <literal><DontShowIfEmpty/></literal> - </para> - </entry> - <entry colname="colspec3" valign="top"> - <para>If this -element is present, the menu is not displayed if the menu does not contain -any items.</para> - <para>This element is optional.</para> - </entry> + <entry colname="colspec2"><literal><Or></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><Or></literal> element.</entry> + </row> + + <row> + <entry colname="colspec2"><literal><Not></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><Not></literal> element.</entry> + </row> + + <row> + <entry colname="colspec2"><literal><All></literal></entry> + + <entry colname="colspec3">A matching rule which selects all + <emphasis>desktop entries</emphasis>.</entry> </row> </tbody> </tgroup> </table> </sect1> - <sect1 id="menustructure-6"> + + <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. The desktop entry file -also contains keywords which determine the location of the item in the menu -hierarchy. Desktop entry files have a <filename>.desktop</filename> file extension.</para> + + <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> - <literallayout>[Desktop Entry] + + <programlisting>[Desktop Entry] Encoding=UTF-8 Name=Calculator Comment=Perform calculations @@ -253,467 +390,642 @@ Exec=gcalctool Icon=gcalctool.png Terminal=false Type=Application -Categories=GNOME;Application;Utility; -X-GNOME-DocPath=gcalctool/gcalctool.xml</literallayout> - <para><xref linkend="menustructure-TBL-7"/> describes the most important keys -in desktop entry files.</para> +Categories=GTK;GNOME;Application;Utility;</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*"/> + <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> + <entry><para>Desktop Entry Key</para></entry> + + <entry><para>Description</para></entry> </row> </thead> + <tbody> <row> - <entry valign="top"> - <para> - <literal>Encoding</literal> - </para> - </entry> - <entry valign="top"> - <para>Specifies the encoding of the desktop entry file. </para> - </entry> + <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>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> + <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>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> + <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>Exec</literal> - </para> - </entry> - <entry valign="top"> - <para>Specifies a command to execute when you choose the item -from the menu. </para> - </entry> + <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> + <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 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> + <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> + <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>Application</literal>: Enter this option for an -item that starts an application.</para> + <para><literal>Link</literal>: An item that links to a file, + folder, or FTP site.</para> </listitem> + <listitem> - <para><literal>Link</literal>: Enter this option for an item that -links to a file, folder, or FTP site.</para> + <para><literal>FSDevice</literal>: An item that is a file + system device.</para> </listitem> - </itemizedlist> - </entry> + + <listitem> + <para><literal>Directory</literal>: An item that is a + Directory.</para> + </listitem> + </itemizedlist></entry> </row> + <row> - <entry colname="colspec0" 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 the -following URL: </para> - <literallayout> - <ulink url="http://www.freedesktop.org">http://www.freedesktop.org</ulink> - </literallayout> - <para>The vfolder information -files map the keywords to menus.</para> - </entry> + <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 the following URL: + </para><literallayout> + <ulink url="http://www.freedesktop.org/Standards/menu-spec">http://www.freedesktop.org/Standards/menu-spec</ulink> + </literallayout><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 colname="colspec0" valign="top"> - <para> - <literal>X-GNOME-DocPath</literal> - </para> - </entry> - <entry colname="colspec1" valign="top"> - <para>Specifies -the help file to display when you choose <guimenuitem>Help on <replaceable>application-name</replaceable></guimenuitem> from the menu item popup menu.</para> - </entry> + <entry><literal>MimeType</literal></entry> + + <entry>Specifies the MIME types </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> + + <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">http://www.freedesktop.org</ulink> + <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> + 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>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 at + <filename>$XDG_DATA_DIRS/desktop-directories/</filename>. 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> - <literallayout>[Desktop Entry] + + <programlisting>[Desktop Entry] Name=Accessories Comment=Accessories menu Icon=gnome-util.png -Type=Directory</literallayout> - <para><xref linkend="menustructure-TBL-15"/> describes the most important keys -in directory entry files.</para> +Type=Directory</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*"/> + <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> + <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> + <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> + <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> + <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> + <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 Menus</title> + <title>Editing System Menus</title> + + <anchor id="menustructure-23" /> + <indexterm> <primary>menus</primary> + <secondary>editing</secondary> </indexterm> - <para>You use the following GNOME Desktop components to edit menus:</para> - <itemizedlist> - <listitem> - <para><application>Nautilus</application> file manager</para> - </listitem> - <listitem> - <para>Menus on panels</para> - </listitem> - </itemizedlist> - <para>When you use the file manager to add menus or menu items for all users, -you must add the menu or menu item to a URI location. <xref linkend="menustructure-TBL-12"/> -lists the menus to which you can add items, and the URI locations that correspond -to the menus.</para> - <para>When you use panels to customize menus for all users, you use the menu -item popup menu. For more information, see <citetitle>Working With Menus</citetitle> -in the <citetitle>GNOME 2.6 Desktop User Guide</citetitle>.</para> - <para>You can also use menu configuration files and menu data files to customize -menus.</para> + + <para>You can edit menu configuration files and menu data files manually + to customize menus.</para> + <sect2 id="menustructure-3"> <title>Adding Menus</title> - <para>You can add menus for all users in the following ways: </para> - <itemizedlist> + + <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>Use the file manager.</para> + <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>Modify the menu configuration files and menu data files.</para> + <para>Locate the + <filename>$XDG_CONFIG_DIRS/menus/applications.menu</filename> + file.</para> </listitem> - </itemizedlist> - <sect3 id="menustructure-19"> - <title>To Add a Menu Using the File Manager</title> - <indexterm> - <primary>menus</primary> - <secondary>adding using file manager</secondary> - </indexterm> - <indexterm> - <primary>file manager</primary> - <secondary>adding menus -with</secondary> - </indexterm> - <para>To add a menu for all users, perform the -following steps:</para> - <orderedlist> - <listitem> - <para>In a file manager window, access the location where you want -to add the menu. For example, to add a menu to the <guimenu>Applications</guimenu> -menu, type <literal>applications-all-users:///</literal> in the <guilabel>Location</guilabel> field, then press <keycap>Return</keycap>.</para> - </listitem> - <listitem> - <para>Choose <menuchoice><guimenu>File</guimenu><guimenuitem>New Folder</guimenuitem></menuchoice>. An untitled folder is added to the -view pane. The name of the folder is selected.</para> - </listitem> - <listitem> - <para>Type a name for the folder, then press <keycap>Return</keycap>. -The vfolder information file for the location that you accessed in step 1 -is automatically updated with the details of the new menu. The name of the -folder is displayed as the name of the menu.</para> - </listitem> - </orderedlist> - <para>The next time that users log in, the menu is in the assigned location.</para> - </sect3> - <sect3 id="menustructure-20"> - <title>To Add a Menu Using Menu Files</title> - <indexterm> - <primary>menus</primary> - <secondary>adding using menu files</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. Create the directory entry file in the <filename>/usr/share/gnome/vfolders</filename> directory. For more information on directory entry files, see <xref linkend="menustructure-14"/>. </para> - </listitem> - <listitem> - <para>Locate the vfolder information file for the location where -you want to add the menu. For example, to add a menu to the <guimenu>Applications</guimenu> menu, locate the file <filename>/etc/gnome-vfs-2.0/vfolders/applications-all-users.vfolder-info</filename>. </para> - </listitem> - <listitem> - <para>In the vfolder information file, add a <literal><Folder></literal> element for the new menu. For more information on vfolder information -files, see <xref linkend="menustructure-13"/>.</para> - </listitem> - </orderedlist> - <para>The next time that users log in, the menu is in the assigned location.</para> - </sect3> + + <listitem> + <para>In the <filename>.menu</filename> file, add a + <literal><Menu></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><Name></literal> element below + <literal><Menu></literal>. The content of the element should + contain the name for the menu.</para> + </listitem> + + <listitem> + <para>Create a <literal><Directory></literal> element below + <literal><Menu></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><Include></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>To Add an Item to a Menu</title> + <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> + 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-6"/>. </para> + <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>Open a file manager window. Choose <menuchoice><guimenu>File</guimenu><guimenuitem>New Window</guimenuitem></menuchoice> to open a second -file manager window.</para> + <para>Place the desktop entry file in the folder + <filename>$XDG_DATA_DIRS/applications/</filename></para> </listitem> + <listitem> - <para>In one window, access the location where you want to add the -menu item. For example, to add a menu item to the <guimenu>Preferences</guimenu> -menu, type <literal>preferences-all-users:///</literal> in the <guilabel>Location</guilabel> field, then press <keycap>Return</keycap>.</para> + <para>Locate the + <filename>$XDG_CONFIG_DIRS/menus/applications.menu</filename> + file.</para> </listitem> + <listitem> - <para>In the other window, select the desktop entry file that you -created for the menu item. Drag the desktop entry file to the location where -you want to add the menu item.</para> - <para>Alternatively, you can copy the desktop entry file, then paste the file -into the location where you want to add the menu item.</para> + <para>Verify that a <literal><Menu></literal> element contains + an <literal><Include></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> + + <para>The next time that users log in, the menu item is in the assigned + location.</para> </sect2> + <sect2 id="menustructure-9"> - <title>To Edit the Properties of a Menu</title> + <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> + + <para>To edit the properties of a menu for all users, perform the + following steps:</para> + <orderedlist> <listitem> - <para>From a panel, open the menu that you want to edit. Right-click -on any item in the menu.</para> + <para>Locate the + <filename>$XDG_CONFIG_DIRS/menus/applications.menu</filename> + file.</para> </listitem> + <listitem> - <para>Choose <menuchoice><guimenu>Entire menu</guimenu><guimenuitem>Properties</guimenuitem></menuchoice>. A <guilabel>Launcher Properties</guilabel> dialog is displayed.</para> + <para>Find the <literal><Menu></literal> entry in this file + that corresponds to the menu you want to modify. Note the filename + of the directory entry in the <literal><Directory></literal> + element.</para> </listitem> + <listitem> - <para>Modify the properties of the menu in the <guilabel>Launcher Properties</guilabel> dialog. For more information on the elements in the <guilabel>Launcher Properties</guilabel> dialog, see <citetitle>Working With Panels</citetitle> in the <citetitle>GNOME 2.6 Desktop User Guide</citetitle>.</para> - </listitem> - <listitem> - <para>Click <guibutton>OK</guibutton>.</para> + <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>To Edit a Menu Item</title> + <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>From a panel, open the menu that contains the item that you -want to edit. Right-click on the item that you want to edit.</para> - </listitem> - <listitem> - <para>Choose <guimenuitem>Properties</guimenuitem>. A <guilabel>Launcher Properties</guilabel> dialog is displayed.</para> - </listitem> - <listitem> - <para>Modify the properties of the menu item in the <guilabel>Launcher Properties</guilabel> dialog. For more information on the elements in the <guilabel>Launcher Properties</guilabel> dialog, see <citetitle>Working With Panels</citetitle> in the <citetitle>GNOME 2.6 Desktop User Guide</citetitle>.</para> + <para>Locate the desktop entry in + <filename>$XDG_DATA_DIRS/applications/</filename> + corresponding to the menu item.</para> </listitem> + <listitem> - <para>Click <guibutton>OK</guibutton>.</para> + <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>To Delete an Item from a Menu</title> + <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, from a panel, open the menu -that contains the item that you want to delete. Right-click on the item that -you want to delete. Choose <guimenuitem>Remove this item</guimenuitem>. </para> - <para>The next time that users log in, the menu item is not displayed in the -menu.</para> + + <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><Menu></literal> element in this file + that contains the desktop entry you want to delete.</para> + </listitem> + + <listitem> + <para>Insert an <literal><Exclude></literal> element after the + closing tag for the <literal><Include></literal> element. Make + sure this is in the <literal><Menu></literal> element + determined in step 2.</para> + </listitem> + + <listitem> + <para>Insert the <literal><Filename></literal> matching rule + as a subelement of <literal><Exclude></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><!-- ... --> + + <Menu> + <Name>Accessibility</Name> + <Directory>Accessibility.directory</Directory> + <Include> + <And> + <Category>Accessibility</Category> + <Not><Category>Settings</Category></Not> + </And> + </Include> + <Exclude> + <Filename>dasher.desktop</Filename> + </Exclude> + </Menu> + +<!-- ... --> +</programlisting> + </example> </sect2> </sect1> - <sect1 id="menustructure-23"> - <title>To Configure Menus That Users Cannot Modify</title> + + <sect1 id="menustructure-usermenus"> + <title>Editing User Menus and Menu Merging</title> + <indexterm> <primary>menus</primary> - <secondary>configuring menus that users -cannot modify</secondary> + + <secondary>editing user menus</secondary> </indexterm> - <para>Users cannot modify a menu if the -following conditions are true:</para> + + <para>You can use the following GNOME Desktop applications to edit menus + for users:</para> + <itemizedlist> <listitem> - <para>A vfolder information file that corresponds to the menu is -present in the <filename>/etc/gnome-vfs-2.0/vfolders</filename> directory.</para> - </listitem> - <listitem> - <para>The vfolder information file has the same name as the URI -location that corresponds to the menu.</para> - </listitem> - <listitem> - <para>The user permissions for the vfolder information file are -set to read only. </para> + <para>GNOME Menu Editor</para> </listitem> </itemizedlist> - <para>To configure a menu so that users cannot modify the menu, perform the -following steps:</para> - <orderedlist> - <listitem> - <para>Create a vfolder information file for the menu that you want -to configure in the <filename>/etc/gnome-vfs-2.0/vfolders</filename> directory.</para> - </listitem> - <listitem> - <para>Give the vfolder information file the name of the URI location -that corresponds to the menu that you want to configure. For example, to configure -the <guimenu>Applications</guimenu> menu, create a vfolder information called <filename>applications.vfolder-info</filename> in the <filename>/etc/gnome-vfs-2.0/vfolders</filename> directory.</para> - </listitem> - <listitem> - <para>Set the permissions on the vfolder information file to read -only.</para> - </listitem> - </orderedlist> + + <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> 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><MergeFile></literal> + element with the attribute <literal>type="parent"</literal> within the + user's <filename>applications.menu</filename> file.</para> + + <para>The <literal><MergeFile></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><MergeFile></literal> element are ignored and the next + <filename>applications.menu</filename> file in + <filename>$XDG_CONFIG_DIRS/menus/</filename> 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><MergeFile></literal> + element. As a result, you may still see a location specified in the + contents of <literal><MergeFile></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><Menu></literal> + element in the merged menu file<footnote> + <para>Merged menu file refers to the next + <filename>applications.menu</filename> in + <filename>$XDG_CONFIG_DIRS/menus/</filename></para> + </footnote> are substituted for the + <literal><MergeFile></literal> element in the base menu + file.</para> + </listitem> + + <listitem> + <para>All child <literal><Menu></literal> elements with the + same name are consolidated into a single + <literal><Menu></literal> element. This is by done appending + all child elements of each <literal><Menu></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><!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN" + "http://www.freedesktop.org/standards/menu-spec/menu-1.0.dtd"> + +<Menu> + <Name>Applications</Name> + <MergeFile type="parent">/etc/xdg/menus/applications.menu</MergeFile> + <Menu> + <Name>Accessibility</Name> + <Exclude> + <Filename>dasher.desktop</Filename> + </Exclude> + </Menu> +</Menu> +</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><MergeFile></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><MergeFile></literal> element.</para> + </sect2> </sect1> </chapter> diff --git a/gnome2-system-admin-guide/C/mimetypes.xml b/gnome2-system-admin-guide/C/mimetypes.xml index e9a07f4..6c56071 100644 --- a/gnome2-system-admin-guide/C/mimetypes.xml +++ b/gnome2-system-admin-guide/C/mimetypes.xml @@ -1,719 +1,899 @@ +<?xml version="1.0" encoding="UTF-8"?> <chapter id="mimetypes-0"> <title>MIME Types</title> + <anchor id="mimetypes-TBL-3"/> + <anchor id="mimetypes-TBL-6"/> + <anchor id="mimetypes-TBL-8"/> + <highlights> - <para>This chapter describes how applications detect MIME types, -how to register MIME types, and how to add applications to the GNOME Desktop.</para> + <para>This chapter describes how applications detect MIME types, how to + register MIME types, and how to add applications to the GNOME + Desktop.</para> </highlights> - <sect1 id="mimetypes-1"> + + <para>The purpose of this chapter is to make it easy for an administrator to + understand how to configure different parts of the MIME database and give an + general overview of the MIME system. Therefore we will + <emphasis>not</emphasis> attempt to go into details where it is not + necessary. For the gory details, it is recommended that you refer to the + <ulink url="http://www.freedesktop.org/Standards/shared-mime-info-spec">XDG + shared mime info specification</ulink>.</para> + + <sect1 id="mimetypes-intro"> <title>Introduction to MIME Types</title> + <anchor id="mimetypes-1"/> + <indexterm> <primary>MIME types</primary> + <secondary>introduction</secondary> </indexterm> + <para>A <firstterm>Multipurpose Internet Mail Extension</firstterm> -(MIME) type identifies the format of a file. The MIME type enables applications -to read the file. Applications such as Internet browsers and email applications -use the MIME type to handle files of different types. For example, an email -application can use the MIME type to detect what type of file is in a file -attached to an email.</para> - <para>The <application>Nautilus</application> file manager uses MIME types -to identify the type of a file. The file manager needs to know the MIME type -of a file to perform the following tasks:</para> + [<acronym>MIME</acronym>] type identifies the format of a file. + Applications such as Internet browsers and email applications use the MIME + type of a file to decide which actions to perform on it. For example, an + email application can use the MIME type to detect the format of an + attachment and choose an appropriate viewer for the file, such as opening + a text document with <application>gedit</application>.</para> + + <para>As another example, the <application>Nautilus</application> file + manager needs to know the MIME type of a file to perform the following + tasks:</para> + <itemizedlist> <listitem> <para>Open the file in an appropriate application.</para> </listitem> + <listitem> <para>Display a string that describes the type of file.</para> </listitem> + <listitem> <para>Display an appropriate icon to represent the file.</para> </listitem> + <listitem> - <para>Display a list of other applications that can open the file.</para> + <para>Display a list of other applications that can open the + file.</para> </listitem> </itemizedlist> - <para>If you add a new application, you must ensure that other applications -can recognize the files associated with the application. You must perform -several tasks to enable other applications to detect the MIME type of the -application files.</para> - <para>This section describes how applications detect the MIME types of files, -and how applications are associated with MIME types. This chapter also describes -the procedure that you must follow to add a new application.</para> + + <para>MIME types were originally proposed as a standard for identifying + the message body of an e-mail message. Now, many systems use MIME types to + identify the format of arbitrary files on the file system. MIME types are + composed of a top-level <emphasis>media type</emphasis> followed by a + <emphasis>subtype identifier</emphasis>, separated by a forward slash + character, <quote><literal>/</literal></quote>. One example of a MIME type + is <literal>image/jpeg</literal>. The media type in this example is + <quote><literal>image</literal></quote> and the subtype identifier is + <quote><literal>jpeg</literal></quote>. The top-level media type is meant + to be a general categorization about the content of the file, while the + subtype identifer is meant to specifically identify the format of the + file.</para> + + <para>There are eight media types currently blessed by the + <acronym>IANA</acronym> [Internet Assigned Naming Authority]. These eight + media types are <simplelist type="inline"> + <member>application</member> + + <member>audio</member> + + <member>image</member> + + <member>message</member> + + <member>model</member> + + <member>multipart</member> + + <member>text</member> + + <member>video</member> + </simplelist>. Many subtypes exist for each media type; for more + information, see <ulink + url="http://www.iana.org/assignments/media-types/">MIME Media + Types</ulink> at the <ulink url="http://www.iana.org/">IANA</ulink> web + site.</para> + + <para>Implementation of MIME types in GNOME follows the <ulink + url="http://www.freedesktop.org/Standards/shared-mime-info-spec">XDG + shared mime info specification</ulink>. This specification provides the + following advantages:</para> + + <itemizedlist> + <listitem> + <para>Standard locations for all MIME related files.</para> + </listitem> + + <listitem> + <para>A standard way for applications to register information about a + new MIME type.</para> + </listitem> + + <listitem> + <para>A standard way to retrieve the MIME type for a file.</para> + </listitem> + + <listitem> + <para>A standard way to retrieve information about a MIME type.</para> + </listitem> + </itemizedlist> + + <para>The rest of the chapter describes the files and directories that + make up the MIME database, details about source XML files, how to create + or modify MIME types, how to register applications as handlers for certain + MIME types and finally, how to add an application to the GNOME + desktop.</para> </sect1> - <sect1 id="mimetypes-10"> - <title>Detecting the MIME Type for a File</title> + + <sect1 id="mimetypes-database"> + <title>The MIME Database</title> + <anchor id="mimetypes-4"/> + <anchor id="mimetypes-5"/> + <indexterm> <primary>MIME types</primary> - <secondary>detecting</secondary> - </indexterm> - <indexterm> - <primary>detecting MIME types</primary> + + <secondary>database</secondary> </indexterm> - <para>Applications -can detect the MIME type of a file as follows:</para> - <orderedlist> + + <para>The MIME database is a collection of files that make up:</para> + + <itemizedlist> <listitem> - <para>The application uses <firstterm>file content sniffers</firstterm> -to search for a particular pattern in the file. A file content sniffer associates -a specific pattern in a file with a MIME type. If the application finds a -match for the pattern, the MIME type associated with the pattern is the MIME -type of the file.</para> + <para>The set of known MIME types</para> </listitem> + <listitem> - <para>If file content sniffers do not identify the MIME type, then -the application can check the filename. The application checks the filename -against the <firstterm>MIME type registry</firstterm>. The MIME type registry -associates particular file extensions and filename patterns, with particular -MIME types. If a match for the filename is found, the MIME type associated -with the extension or pattern is the MIME type of the file.</para> + <para>The method for determing the MIME type of a file</para> </listitem> - </orderedlist> - <para>The following sections provide further information on file content sniffers -and the MIME type registry.</para> - <sect2 id="mimetypes-2"> - <title>File Content Sniffers</title> - <indexterm> - <primary>MIME types</primary> - <secondary>file content sniffers</secondary> - </indexterm> - <indexterm> - <primary>file content sniffers</primary> - </indexterm> - <para>File content sniffers are specified in the file <filename>/etc/gnome-vfs-mime-magic</filename>. The following is an example of a file content sniffer:</para> - <literallayout>0 string \x89PNG image/png</literallayout> - <para>The syntax for file content sniffers is as follows:</para> - <literallayout>offset_start[:offset_end] pattern_type pattern [&pattern_mask] type</literallayout> - <para><xref linkend="mimetypes-TBL-3"/> describes the fields in a file content -sniffer.</para> - <table frame="topbot" id="mimetypes-TBL-3"> - <title>Fields in a File Content Sniffer</title> - <tgroup cols="2" colsep="0" rowsep="0"> - <colspec colwidth="29.90*"/> - <colspec colwidth="70.10*"/> - <thead> - <row rowsep="1"> - <entry> - <para>Field</para> - </entry> - <entry> - <para>Description</para> - </entry> - </row> - </thead> - <tbody> - <row> - <entry valign="top"> - <para> - <literal>offset_start</literal> - </para> - </entry> - <entry valign="top"> - <para>Specifies the number of characters to ignore in -the file before searching for a text pattern.</para> - </entry> - </row> - <row> - <entry valign="top"> - <para> - <literal>pattern_type</literal> - </para> - </entry> - <entry valign="top"> - <para>Specifies the type of pattern to search for. The <literal>string</literal> pattern type is the only pattern type that is supported at -the time of publication of this guide.</para> - </entry> - </row> - <row> - <entry valign="top"> - <para> - <literal>pattern</literal> - </para> - </entry> - <entry valign="top"> - <para>Specifies the pattern to search for. </para> - </entry> - </row> - <row> - <entry valign="top"> - <para> - <literal>pattern_mask</literal> - </para> - </entry> - <entry valign="top"> - <para>Specifies a <firstterm>pattern mask</firstterm>, -in hexadecimal format. For more information on pattern masks, see the next -section.</para> - <para>This field is optional. This field is not present in -the example.</para> - </entry> - </row> - <row> - <entry valign="top"> - <para> - <literal>type</literal> - </para> - </entry> - <entry valign="top"> - <para>Specifies the MIME type to associate with files that match -this entry.</para> - </entry> - </row> - </tbody> - </tgroup> - </table> - </sect2> - <sect2 id="mimetypes-12"> - <title>Pattern Masks</title> - <indexterm> - <primary>MIME types</primary> - <secondary>pattern mask</secondary> - </indexterm> - <indexterm> - <primary>pattern mask</primary> - </indexterm> - <para>A -pattern mask identifies bits in the pattern to ignore when searching for a -pattern in a file. The following is an example of a file content sniffer with -a pattern mask:</para> - <literallayout>0 string BMxxxx\000\000 &0xffff00000000ffff image/bmp</literallayout> - <para>The pattern and mask in the example are as follows:</para> - <informaltable frame="none"> - <tgroup cols="9" colsep="0" rowsep="0"> - <colspec colwidth="16.54*"/> - <colspec colwidth="10.21*"/> - <colspec colwidth="10.41*"/> - <colspec colwidth="10.21*"/> - <colspec colwidth="10.41*"/> - <colspec colwidth="10.21*"/> - <colspec colwidth="10.41*"/> - <colspec colwidth="10.21*"/> - <colspec colwidth="10.41*"/> - <tbody> - <row> - <entry valign="top"> - <para>Pattern</para> - </entry> - <entry valign="top"> - <para> - <literal>B</literal> - </para> - </entry> - <entry valign="top"> - <para> - <literal>M</literal> - </para> - </entry> - <entry valign="top"> - <para> - <literal>x</literal> - </para> - </entry> - <entry valign="top"> - <para> - <literal>x</literal> - </para> - </entry> - <entry valign="top"> - <para> - <literal>x</literal> - </para> - </entry> - <entry valign="top"> - <para> - <literal>x</literal> - </para> - </entry> - <entry valign="top"> - <para> - <literal>\000</literal> - </para> - </entry> - <entry valign="top"> - <para> - <literal>\000</literal> - </para> - </entry> - </row> - <row> - <entry valign="top"> - <para>Mask</para> - </entry> - <entry valign="top"> - <para> - <literal>ff</literal> - </para> - </entry> - <entry valign="top"> - <para> - <literal>ff</literal> - </para> - </entry> - <entry valign="top"> - <para> - <literal>00</literal> - </para> - </entry> - <entry valign="top"> - <para> - <literal>00</literal> - </para> - </entry> - <entry valign="top"> - <para> - <literal>00</literal> - </para> - </entry> - <entry valign="top"> - <para> - <literal>00</literal> - </para> - </entry> - <entry valign="top"> - <para> - <literal>ff</literal> - </para> - </entry> - <entry valign="top"> - <para> - <literal>ff</literal> - </para> - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - <para>The pattern and mask specify a file with the following characteristics:</para> - <orderedlist> + + <listitem> + <para>Meta information regarding a MIME type, such as a human readable + description to use when displaying files of this type.</para> + </listitem> + </itemizedlist> + + <sect2 id="mimetypes-location"> + <title>Location</title> + + <para>As an administrator, the most important and basic step to + understanding the MIME system is learning the locations where these + files are stored. Since the <ulink + url="http://www.freedesktop.org/Standards/shared-mime-info-spec">XDG + shared mime info specification</ulink> was drafted by the X Desktop + Group, it also makes use of the <ulink + url="http://www.freedesktop.org/wiki/Standards/basedir-spec">XDG base + directory specification</ulink>. It is highly recommended that you + familiarize yourself with this specification, as it is also important + for other system administration tasks such as editing menus. A brief + summary of the directory locations as pertaining to the MIME + specification is given below.</para> + + <para>The MIME database is created from the set of files located in the + <filename>$XDG_DATA_HOME/mime</filename> and + <filename>$XDG_DATA_DIRS/mime</filename> directories. If + these environment variables are unset, then they default to the values + <filename>~/.local/share</filename> and + <filename>/usr/local/share:/usr/share</filename> respectively. As can be + seen from the default value for <envar>$XDG_DATA_DIRS</envar> , each + environment variable is actually a colon separated list of directories. + The user's database at + <filename>$XDG_DATA_HOME/mime</filename> has precedence + over the system database at + <filename>$XDG_DATA_DIRS/mime</filename> when conflicting + definitions are encountered. Similar to the <citetitle>XDG shared mime + specification</citetitle>, we will refer to this set of directories as + <literal><MIME></literal> in the rest of this document.</para> + + <para>For example, assuming default paths for the environment variables, + <quote>Load + <filename><MIME>/text/plain.xml</filename></quote> + means to load the following files:</para> + + <itemizedlist> <listitem> - <para>The file begins with <literal>BM</literal>.</para> + <para><filename>~/.local/share/mime/text/plain.xml</filename></para> </listitem> + <listitem> - <para><literal>BM</literal> is followed by four bytes with any values.</para> + <para><filename>/usr/local/share/mime/text/plain.xml</filename></para> </listitem> + <listitem> - <para>The four bytes are followed by <literal>\000\000</literal>.</para> + <para><filename>/usr/share/mime/text/plain.xml</filename></para> </listitem> - </orderedlist> - <para>The file content sniffer specifies that the MIME type of files that -match the pattern and mask is <literal>image/bmp</literal>.</para> + </itemizedlist> </sect2> - <sect2 id="mimetypes-4"> - <title>MIME Type Registry</title> - <indexterm> - <primary>MIME types</primary> - <secondary>MIME type registry</secondary> - </indexterm> - <para>The MIME type registry is located in <filename>/usr/share/mime-info</filename>. The MIME type registry contains the following files:</para> - <informaltable frame="topbot"> - <tgroup cols="2" colsep="0" rowsep="0"> - <colspec colwidth="50*"/> - <colspec colwidth="50*"/> - <thead> - <row rowsep="1"> - <entry> - <para>File</para> - </entry> - <entry> - <para>File Extension</para> - </entry> - </row> - </thead> - <tbody> - <row> - <entry valign="top"> - <para>MIME information file</para> - </entry> - <entry valign="top"> - <para> - <filename>.mime</filename> - </para> - </entry> - </row> - <row> - <entry valign="top"> - <para>MIME keys file</para> - </entry> - <entry valign="top"> - <para> - <filename>.keys</filename> - </para> - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - <para>The following sections describe MIME information files and MIME keys -files.</para> - <sect3 id="mimetypes-5"> - <title>MIME Information Files</title> - <indexterm> - <primary>MIME types</primary> - <secondary>MIME information files</secondary> - </indexterm> - <para><firstterm>MIME information files</firstterm> -associate MIME types with one or both of the following:</para> - <itemizedlist> + + <sect2 id="mimetypes-contents"> + <title>Contents</title> + + <para>The following is a list of directories and files that are found + inside the MIME database along with brief descriptions:</para> + + <variablelist> + <varlistentry> + <term><filename><MIME>/packages/</filename></term> + <listitem> - <para>File extensions</para> + <para>This directory contains any number of XML files, each of + which describe a collection of MIME types. By default, the + <filename>freedesktop.org.xml</filename> file is installed in the + <filename>/usr/share/mime/packages</filename> directory. This file + contains all the default MIME types that are widely used and + recognized.</para> + + <para>Applications which provide information about new MIME types + are to install a <emphasis>single</emphasis> new XML file here. + Depending on the prefix where the application is installed, it + will create the file in the <filename>/mime/package</filename> + subdirectory of one of the directories in + <envar>$XDG_DATA_HOME:$XDG_DATA_DIRS</envar>. For example, an + application installed to <filename>/usr/bin</filename> should + install a new source XML file to the + <filename>/usr/share/mime/packages</filename> directory. For more + information about the XML files in the + <filename>packages</filename> directory, please see <xref linkend="mimetypes-source-xml"/>.</para> </listitem> + </varlistentry> + + <varlistentry> + <term><filename><MIME>/<replaceable>MEDIA</replaceable>/<replaceable>SUBTYPE</replaceable>.xml</filename></term> + <listitem> - <para>Filename patterns</para> + <para>These directories and files are automatically generated from + the collection of source XML files in the + <filename><MIME>/packages/</filename> subdirectory by the + <application>update-mime-database</application> application. For + example, for each <literal>mime-type</literal> element in the + <filename>/usr/share/mime/packages/freedesktop.org.xml</filename> + file, a directory is created at + <filename>/usr/share/mime/</filename> with the <emphasis>media + type</emphasis> of the MIME type. An XML file is created in that + directory with the <emphasis>subtype identifier</emphasis> of that + MIME type as well. The contents of the created XML file include + comments (and translations for them), subclasses designations and + aliases.</para> + + <example> + <title>Example: + <filename>/usr/share/mime/text/plain.xml</filename> file</title> + + <para><programlisting><?xml version='1.0' encoding='utf-8'?> +<mime-type xmlns="http://www.freedesktop.org/standards/shared-mime-info" type="text/plain"> +<!--Created automatically by update-mime-database. DO NOT EDIT!--> + <comment>plain text document</comment> + <!-- possibly more translations --> + <comment xml:lang="es">documento de texto sencillo</comment> + <comment xml:lang="eu">testu soileko dokumentua</comment> + <comment xml:lang="fi">perustekstiasiakirja</comment> + <comment xml:lang="fr">document plein texte</comment> + <!-- possibly more translations --> +</mime-type> +</programlisting>This file is generated by the + <application>update-mime-database</application> application, + using the default source XML file + <filename>freedesktop.org.xml</filename>.</para> + </example> </listitem> - </itemizedlist> - <para>When an application searches for the MIME type of a file, the application -checks the filename against the MIME information files. If a match for the -filename is found, the MIME type associated with the extension or pattern -is the MIME type of the file.</para> - <para>In MIME information files, the filename pattern to search for is written -as a regular expression.</para> - <para>The format of MIME type entries in MIME information files is as follows:</para> - <literallayout><replaceable>MIME-type</replaceable> - ext[,priority]: <replaceable>list-of-extensions</replaceable> - regex[,priority]: <replaceable>list-of-regular-expressions</replaceable></literallayout> - <para>You can specify a priority value for the file extension and the regular -expression. You can use the priority value to differentiate composite filenames. -For example, you can assign a priority of <literal>1</literal> to the <filename>.gz</filename> extension, and assign a higher priority of <literal>2</literal> -to the <filename>.tar.gz</filename> extension. In this case, the file <filename>abc.tar.gz</filename> takes the MIME type for <filename>.tar.gz</filename>.</para> - <note> - <para>You must indent the <literal>ext</literal> field and the <literal>regex</literal> field with a tab character (<literal>\t</literal>).</para> - </note> - <para>The following MIME type entries are samples from the <filename>gnome-vfs.mime</filename> MIME information file:</para> - <literallayout>application/x-compressed-tar - regex,2: tar\.gz$ - ext: tgz -audio/x-real-audio - ext: rm ra ram -image/jpeg - ext: jpe jpeg jpg -image/png - ext: png -text/html - ext: html htm HTML -text/plain - ext: asc txt TXT -text/x-readme - regex: README.*</literallayout> - <note> - <para>The file manager reads the MIME information files alphabetically. -The alphabetical order determines the order in which MIME types are assigned -to file extensions or regular expressions. For example, if the same file extension -is assigned to different MIME types in the files <filename>abc.mime</filename> -and <filename>def.mime</filename>, the MIME type in <filename>abc.mime</filename> -is used.</para> - </note> - </sect3> - <sect3 id="mimetypes-11"> - <title>MIME Keys Files</title> - <indexterm> - <primary>MIME types</primary> - <secondary>MIME keys files</secondary> - </indexterm> - <para><firstterm>MIME keys file</firstterm> provide information -about a MIME type that is used in the user interface. For example, the MIME -keys file provides a description of a MIME type, and specifies an icon to -represent files of that MIME type.</para> - <para>The following is a sample from a MIME keys file:</para> - <literallayout>text/html - description=HTML page - icon_filename=gnome-text-html - default_action_type=application - short_list_application_ids_for_novice_user_level=mozilla,netscape,galeon - category=Documents/World Wide Web</literallayout> - <note> - <para>You must indent the keys in a MIME keys file with a tab character -(<literal>\t</literal>).</para> - </note> - <para><xref linkend="mimetypes-TBL-6"/> describes the most important keys in -MIME keys files. Typically, the <literal>description</literal> key and the <literal>category</literal> key are localized.</para> - <table frame="topbot" id="mimetypes-TBL-6"> - <title>Keys in MIME Keys Files</title> - <tgroup cols="2" colsep="0" rowsep="0"> - <colspec colname="colspec0" colwidth="50*"/> - <colspec colname="colspec1" colwidth="50*"/> - <thead> - <row rowsep="1"> - <entry> - <para>Key</para> - </entry> - <entry> - <para>Description</para> - </entry> - </row> - </thead> - <tbody> - <row> - <entry colname="colspec0" valign="top"> - <para> - <literal>can_be_executable</literal> - </para> - </entry> - <entry colname="colspec1" valign="top"> - <para>Specifies -whether files of this MIME type can be executed.</para> - </entry> - </row> - <row> - <entry valign="top"> - <para> - <literal>description</literal> - </para> - </entry> - <entry valign="top"> - <para>Describes the MIME type. This description can be -displayed in the file manager and other applications.</para> - </entry> - </row> - <row> - <entry valign="top"> - <para> - <literal>icon_filename</literal> - </para> - </entry> - <entry valign="top"> - <para>Specifies the filename of an icon to represent the -MIME type. Does not specify the path to the filename, or the file extension. </para> - <para>This icon can be displayed in the file manager and other applications.</para> - </entry> - </row> - <row> - <entry valign="top"> - <para> - <literal>default_action_type</literal> - </para> - </entry> - <entry valign="top"> - <para>Specifies the category of action to take when a -file of this MIME type is opened by the user. Enter <literal>application</literal> -for this MIME type for most applications.</para> - </entry> - </row> - <row> - <entry valign="top"> - <para> - <literallayout>short_list_application_ids -_for_novice_user_level</literallayout> - </para> - </entry> - <entry valign="top"> - <para>Specifies the application to use when a file of this MIME type is opened by -a user. Specify one or more applications, in order of priority. The applications -must also be registered in the application registry.</para> - </entry> - </row> - <row> - <entry valign="top"> - <para> - <literal>category</literal> - </para> - </entry> - <entry valign="top"> - <para>Specifies a category for the MIME type. The value -of this key determines the location of the MIME type in the <application>File Types and Programs</application> preference tool.</para> - </entry> - </row> - </tbody> - </tgroup> - </table> - </sect3> + </varlistentry> + + <varlistentry> + <term><filename><MIME>/globs</filename></term> + + <listitem> + <para>Contains one line with a MIME type and a glob pattern, + separated by a colon. Files which match the glob pattern are + resolved to the MIME type specified before the colon. There are + special rules about how filenames are matched by the glob pattern; + for more details see the <citetitle>XDG shared mime + specification</citetitle>.</para> + + <para>This file is also generated by the + <application>update-mime-database</application> application, using + the default source XML file + <filename>freedesktop.org.xml</filename>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename><MIME>/magic</filename></term> + + <listitem> + <para>A binary file which contains information on how to resolve + MIME types by <quote>sniffing</quote> the content of the file. + This is generally a set of one or more rules such as <quote>check + for the string <literal>%PDF- </literal>at byte offset 0 in the + file; if found, assign it the MIME type + <literal>application/pdf</literal></quote>.</para> + + <para>This file is also generated by the + <application>update-mime-database</application> + application.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename><MIME>/XMLnamespaces</filename></term> + + <listitem> + <para>Contains a mapping of XML namespaces to MIME types. Each + line contains three fields, the namespace, the localName and the + MIME type. Each field is separated by a space. If the localName is + empty, then there are two spaces between the namespace and the + MIME type.</para> + + <para>This file is also generated by the + <application>update-mime-database</application> + application.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename><MIME>/aliases</filename></term> + + <listitem> + <para>Contains a list of aliases for each MIME type. An alias is + simply a MIME type that is sometimes known as another type. For + each line in this file there are two fields: the first field is + the alias name, and the second field is the MIME type. The fields + are separated by a space.</para> + + <para>This file is also generated by the + <application>update-mime-database</application> + application.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename><MIME>/subclasses</filename></term> + + <listitem> + <para>Contains a list of subclassed MIME types and their + <quote>parent</quote> MIME type. From the <citetitle>XDG shared + mime specification:</citetitle><blockquote> + <para>A type is a subclass of another type if any instance of + the first type is also an instance of the second. For example, + all image/svg files are also text/xml, text/plain and + application/octet-stream files. Subclassing is about the + format, rather than the catagory of the data (for example, + there is no 'generic spreadsheet' class that all spreadsheets + inherit from).</para> + </blockquote>The format of this file is similar to the + <filename>aliases</filename> file. Each line contains two fields, + where the first field is the subclassed MIME type and the second + field is the parent MIME type. Each field is separated by a + space.</para> + + <para>This file is also generated by the + <application>update-mime-database</application> + application.</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2 id="mimetypes-refresh"> + <title>Refreshing the MIME Database</title> + + <para>Understanding how to refresh the MIME database is important for + administrators who wish to add new MIME types to the system, or + otherwise modify information about a MIME type. The application + <application>update-mime-database</application> is intended for this + purpose.</para> + + <para>For example, if an application installs information about a new + MIME type to <filename>/usr/share/mime/packages/diff.xml</filename>, + then <application>update-mime-database</application> must be called with + the parameter <filename>/usr/share/mime</filename>.</para> + + <screen><prompt>#</prompt> <userinput>update-mime-database /usr/share/mime</userinput> +<computeroutput>*** +* Updating MIME database in /usr/share/mime... +*** +</computeroutput></screen> + + <para>The MIME database is refreshed by scanning all the source XML + files in the directory + <filename><MIME>/packages</filename>.</para> </sect2> </sect1> - <sect1 id="mimetypes-7"> - <title>Registering Applications for MIME Types</title> + + <sect1 id="mimetypes-source-xml"> + <title>The source XML files</title> + <anchor id="mimetypes-11" /> + <anchor id="mimetypes-12" /> + <anchor id="mimetypes-2" /> + <indexterm> <primary>MIME types</primary> - <secondary>registering applications -for</secondary> + + <secondary>source XML files</secondary> </indexterm> - <indexterm> - <primary>applications</primary> - <secondary>registry</secondary> - </indexterm> - <para>The <firstterm>application registry</firstterm> contains text files that register applications. The application -registration files contain a series of key-value pairs that specify details -for applications. For example, the application registration files contain -the following information:</para> + + <para>Located in the <filename><MIME>/packages</filename> directory, + these XML files provide all the information regarding MIME types that is + installed into the database by the + <application>update-mime-database</application> application. There are a + few rules about the XML file itself:</para> + <itemizedlist> <listitem> - <para>The command to use to start the application.</para> + <para>It must specify the namespace as + <quote><literal>http://www.freedesktop.org/standards/shared-mime-info</literal></quote></para> + </listitem> + + <listitem> + <para>The root element must be <literal>mime-info</literal></para> </listitem> + <listitem> - <para>MIME types to associate with the application.</para> + <para>Zero or more <literal>mime-type</literal> elements can be + specified as children of the <literal>mime-info</literal> element. The + <literal>type</literal> attribute is used to specify the MIME type + that is being defined.</para> </listitem> </itemizedlist> - <para>An application registration file can contain one or more application -registrations. Application registration files have a <filename>.applications</filename> extension.</para> - <para>The location of the application registry is <filename>/usr/share/application-registry</filename>. This directory contains a default application registration file -that is called <filename>gnome-vfs.applications</filename>.</para> - <para>To register an application, add a registration file for the application -to the application registry. </para> - <para>The following is an example of an application registration:</para> - <literallayout>eog - command=eog - name=Eye of Gnome - can_open_multiple_files=true - expects_uris=false - requires_terminal=false - mime_types=image/bmp,image/gif,image/jpeg,image/png,image/tiff, -image/x-xpixmap,image/x-bmp,image/x-png,image/x-portable-anymap, -image/x-portable-bitmap,image/x-portable-graymap, -image/x-portable-pixmap</literallayout> - <para><xref linkend="mimetypes-TBL-8"/> describes the keys in application registration -files.</para> - <table frame="topbot" id="mimetypes-TBL-8"> - <title>Keys for an Application Registration</title> + + <para>By default, the <filename>freedesktop.org.xml</filename> file is + installed to the <filename>packages</filename> directory in one of the + <filename><MIME></filename> paths (usually + <filename>/usr/share/mime/packages</filename>).</para> + + <para><xref linkend="mimetypes-mimeinfo-elements" /> gives a brief + description for each of the elements that can occur as children to the + <literal>mime-type</literal> element.</para> + + <table frame="topbot" id="mimetypes-mimeinfo-elements"> + <title>Child elements of <literal><mime-info></literal></title> + <tgroup cols="2" colsep="0" rowsep="0"> - <colspec colname="colspec0" colwidth="50*"/> - <colspec colname="colspec1" colwidth="50*"/> + <colspec colwidth="44.90*" /> + + <colspec colwidth="59.10*" /> + <thead> <row rowsep="1"> - <entry> - <para>Key</para> - </entry> - <entry> - <para>Description</para> - </entry> + <entry>Element (and attributes)</entry> + + <entry>Description</entry> </row> </thead> + <tbody> <row> - <entry valign="top"> - <para>Application identifier</para> - </entry> - <entry valign="top"> - <para>Specifies a unique identifier for the application. This -identifier must be the same as the identifier in the short_list_application_ids_for_novice_user_level -key in the MIME keys file for the application.</para> - </entry> - </row> - <row> - <entry valign="top"> - <para> - <literal>command</literal> - </para> - </entry> - <entry valign="top"> - <para>Specifies the command to use to start the application, -and any options to use with the command.</para> - </entry> - </row> - <row> - <entry valign="top"> - <para> - <literal>name</literal> - </para> - </entry> - <entry valign="top"> - <para>Specifies a name for the application. The name is used -in the user interface. For example, the name is used in the <guimenu>Open -With</guimenu> submenu in the file manager.</para> - </entry> + <entry><literal><glob + pattern="<replaceable>*.xyz</replaceable>"></literal></entry> + + <entry>This element specifies a glob pattern against filenames. If + the filename matches, then it is assigned the MIME type of the + parent <literal>mime-type</literal> element. The + <literal>pattern</literal> attribute is mandatory.</entry> </row> + <row> - <entry valign="top"> - <para> - <literal>can_open_multiple_files</literal> - </para> - </entry> - <entry valign="top"> - <para>Specifies whether the application can open several -files at the same time.</para> - </entry> + <entry><literal><magic + priority="<replaceable>50</replaceable>"></literal></entry> + + <entry>This element contains a list of <literal>match</literal> + elements as its children. The <literal>priority</literal> + attribute is optional, and specifies a priority between 0 and 100, + with 100 being the highest matching priority. Each child + <literal>match</literal> element has three required attributes: + <simplelist type="inline"> + <member><literal>type</literal></member> + + <member><literal>offset</literal></member> + + <member><literal>value</literal></member> + </simplelist> and a fourth optional attribute, + <literal>mask</literal>. For details on these attributes, see the + <ulink + url="http://www.freedesktop.org/Standards/shared-mime-info-spec">XDG + shared mime info specification</ulink>.</entry> </row> + <row> - <entry valign="top"> - <para> - <literal>expects_uris</literal> - </para> - </entry> - <entry valign="top"> - <para>Specifies whether the application can process URIs. -If the value of this key is <literal>true</literal>, the application registration -entry must also contain a <literal>supported_uri_schemes</literal> key.</para> - </entry> + <entry><literal><alias + type="<replaceable>media</replaceable>/<replaceable>subtype</replaceable>"></literal></entry> + + <entry>This element defines an alias for the parent + <literal>mime-type</literal> element. An alias is simply a MIME + type that is sometimes known as another type. For example, + <literal>application/x-pdf</literal> is an alias for the MIME type + <literal>application/pdf</literal>.</entry> </row> + <row> - <entry colname="colspec0" valign="top"> - <para> - <literal>supported_uri_schemes</literal> - </para> - </entry> - <entry colname="colspec1" valign="top"> - <para>Specifies -the URI schemes that the application can process.</para> - </entry> + <entry><literal><sub-class-of + type="<replaceable>media</replaceable>/<replaceable>subtype</replaceable>"></literal></entry> + + <entry>This element defines the parent + <literal>mime-type</literal> element as a subclass of the MIME + type specified in the <literal>type</literal> attribute. For + example, <literal>image/svg</literal> is a sub class of the MIME + type <literal>text/xml</literal>, <literal>text/plain</literal>, + and <literal>application/octet-stream</literal>.</entry> </row> + <row> - <entry valign="top"> - <para> - <literal>requires_terminal</literal> - </para> - </entry> - <entry valign="top"> - <para>Specifies whether to run the application in a terminal -window. Enter <literal>true</literal> for this field for an application that -does not create a window in which to run.</para> - </entry> + <entry><literal><comment + xml:lang="<replaceable>locale</replaceable>"></literal></entry> + + <entry>This element provides a human readable description for the + MIME type. There can be zero or more occurrences of this element + as long as each one contains a unique value for the + <literal>xml:lang</literal> attribute.</entry> </row> + <row> - <entry valign="top"> - <para> - <literal>mime_types</literal> - </para> - </entry> - <entry valign="top"> - <para>Specifies the MIME types that the application can -use.</para> - </entry> + <entry><literal><root-XML + namespaceURI="<replaceable>namespace</replaceable>" + localName=""></literal></entry> + + <entry>If a file is determined to an XML file, then this element + helps to further classify it through the use of the + <literal>namespaceURI</literal> and <literal>localName</literal> + attributes, both of which are required. The attribute + <literal>namespaceURI</literal> is the namespace of the document, + and <literal>localName</literal> is the name of the root element + for the document. If <literal>localName</literal> is present but + its value is empty, then the root element may have any name, but + the namespace must still match.</entry> </row> </tbody> </tgroup> </table> + + <para>The easiest way to understand these files is to take a look at an + example. Borrowing from the <citetitle>XDG shared mime + specification</citetitle>, <xref linkend="mimetypes-source-xml-example" /> + displays the contents of a source XML file called + <filename>diff.xml</filename>. This example defines the MIME type + <literal>text/x-diff</literal>. There are multiple + <literal>comment</literal> elements which give a human readable name to + the MIME type in a number of different languages. This MIME type has both + rules for matching through glob patterns <emphasis>and</emphasis> through + the use of content <quote>sniffing</quote> (better known as + <filename>magic</filename> rules). Any file with the extension + <literal>.diff</literal> or <filename>.patch</filename> will resolve to + this MIME type. Additionally any file whose contents start with the + strings specified in the <literal>value</literal> attributes of the + <literal>match</literal> element, will resolve to the + <literal>text/x-diff</literal> MIME type.</para> + + <para>The order in which glob patterns and magic rules apply is beyond the + scope of this document. For details on this, see the <ulink + url="http://www.freedesktop.org/Standards/shared-mime-info-spec">XDG + shared mime info specification</ulink>.</para> + + <example id="mimetypes-source-xml-example"> + <title>Example of a source XML file: + <filename>diff.xml</filename></title> + + <programlisting><?xml version='1.0'?> +<mime-info xmlns='http://www.freedesktop.org/standards/shared-mime-info'> + <mime-type type="text/x-diff"> + <comment>Differences between files</comment> + <comment xml:lang="af">verskille tussen lêers</comment> + <!-- more translated comment elements --> + <magic priority="50"> + <match type="string" offset="0" value="diff\t"/> + <match type="string" offset="0" value="***\t"/> + <match type="string" offset="0" value="Common subdirectories: "/> + </magic> + <glob pattern="*.diff"/> + <glob pattern="*.patch"/> + </mime-type> +</mime-info></programlisting> + </example> </sect1> + + <sect1 id="mimetypes-modifying"> + <title>Modifying MIME types</title> + + <indexterm> + <primary>MIME types</primary> + + <secondary>verifying changes</secondary> + </indexterm> + + <indexterm> + <primary>MIME types</primary> + + <secondary>modifying</secondary> + </indexterm> + + <para>You should never directly modify the source XML files that are + installed to the <filename><MIME>/packages</filename> directory by + applications. Instead, modify the <filename>Overrides.xml</filename> file. + This file has precedence over all other source XML files installed into + the same <filename>packages</filename> directory. If you are an + application author, then this rule does not apply. You should create a new + source XML file and place it in the proper + <filename><MIME>/packages</filename> directory (your + <filename>Makefile</filename> will take care of this, of course).</para> + + <para>You can modify the MIME database for all users on the system or for + a particular user depending on the location of the file you change. To + modify the database for all users, make changes to the file + <filename>Overrides.xml</filename> in the + <filename>$XDG_DATA_DIRS/mime/packages</filename> + directory. To modify the database for a single user, make changes to the + file <filename>Overrides.xml</filename> in the + <filename>$XDG_DATA_HOME/mime/packages</filename> + directory.</para> + + <para>After changes are made, you must always run the + <application>update-mime-database</application> application, with the + directory location of the MIME database as the first parameter.</para> + + <sect2 id="mimetypes-addmodify"> + <title>Adding or Modifying MIME types</title> + + <para>To add one or more MIME types for all users:</para> + + <orderedlist> + <listitem> + <para>Create or modify an existing + <filename>Overrides.xml</filename> source XML file, containing the + definitions for the MIME types. For more information, see <xref + linkend="mimetypes-source-xml" />.</para> + </listitem> + + <listitem> + <para>Place the <filename>Overrides.xml</filename> file in the + <filename>/usr/share/mime/packages</filename> directory.</para> + </listitem> + + <listitem> + <para>Update the MIME database by running + <application>update-mime-database</application> using the system + account.<screen><prompt>#</prompt> <userinput>update-mime-database /usr/share/mime</userinput></screen></para> + </listitem> + </orderedlist> + + <para>To add one or more MIME types for a single user, follow the same + steps, except place your <filename>Overrides.xml</filename> file in the + <filename>~/.local/share/mime/packages</filename> directory. + Additionally, call <application>update-mime-database</application> with + <filename>~/.local/share/mime/packages</filename> as the first + parameter.</para> + </sect2> + + <sect2 id="mimetypes-verifying"> + <title>Verifying Changes</title> + <anchor id="mimetypes-10"/> + + <para>After you have made a change to the MIME database and refreshed + its contents, you can verify that the change has taken effect using the + <application>gnomevfs-info</application> application. This application + prints the MIME type and other useful information about a file.</para> + + <para>Running <application>gnomevfs-info</application> on a SVG file + gives you the output shown below. You'll notice the default application + for this MIME type is <filename>eog.desktop</filename>; We will discuss + default applications in <xref linkend="mimetypes-registering" />.</para> + + <screen><prompt>$</prompt> <userinput>gnomevfs-info mime-diagram.svg</userinput> +<computeroutput>Name : mime-diagram.svg +Type : Regular +MIME type : image/svg+xml +Default app : eog.desktop +Size : 14869 +Blocks : 32 +I/O block size : 4096 +Local : YES +SUID : NO +SGID : NO +Sticky : NO +Permissions : 600644 +Link count : 1 +UID : 1000 +GID : 100 +Access time : Wed Feb 22 18:24:47 2006 +Modification time : Wed Feb 22 18:24:42 2006 +Change time : Wed Feb 22 18:24:42 2006 +Device # : 775 +Inode # : 297252 +Readable : YES +Writable : YES +Executable : NO</computeroutput> +<prompt>$</prompt> +</screen> + + <para><xref linkend="mimetypes-newtype-example" /> walks through the steps of + creating a new MIME type and then verifying the changes using + <application>gnomevfs-info</application>.</para> + </sect2> + + <sect2 id="mimetypes-newtype-example"> + <title><literal>application/x-newtype</literal> Example</title> + + <para>To create (or override) a MIME type and verify the changes:</para> + + <orderedlist> + <listitem> + <para>Make a new, empty file in your home directory called + <filename>testing.xyz</filename>.</para> + </listitem> + + <listitem> + <para>Use <application>gnomevfs-info</application> on the file to + find out the MIME type.The MIME type for this file should be + detected as <literal>text/plain</literal> because there are not any + glob patterns or magic rules that match it<footnote> + <para>When no glob patterns or magic rules match a file, then it + is resolved to the MIME type <literal>text/plain</literal> if it + contains textual data or + <literal>application/octet-stream</literal> for binary data. If + the file is empty, then it defaults to + <literal>text/plain</literal>.</para> + </footnote>.</para> + </listitem> + + <listitem> + <para>Create (or modify) the <filename>Overrides.xml</filename> file + as described in <xref linkend="mimetypes-addmodify" /> with the + contents given in <xref linkend="mimetypes-overrides-xml" />.</para> + </listitem> + + <listitem> + <para>Refresh the database using + <application>update-mime-database</application>.</para> + </listitem> + + <listitem> + <para>Use <application>gnomevfs-info</application> to verify that + your change has taken effect. You should see the MIME type for the + <filename>testing.xyz</filename> file resolved as + <literal>application/x-newtype</literal>.</para> + + <screen><prompt>$</prompt> <userinput>gnomevfs-info testing.xyz | grep MIME +</userinput><computeroutput>MIME type : application/x-newtype +</computeroutput><prompt>$</prompt></screen> + </listitem> + </orderedlist> + + <example id="mimetypes-overrides-xml"> + <title><filename>Overrides.xml</filename> file</title> + + <programlisting><?xml version='1.0' encoding='utf-8'?> +<mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info"> + <mime-type type="application/x-newtype"><comment>new mime type</comment><glob pattern="*.xyz"/></mime-type> +</mime-info></programlisting> + </example> + </sect2> + </sect1> + + <sect1 id="mimetypes-registering"> + <title>Registering Applications for MIME Types</title> + + <anchor id="mimetypes-7" /> + + <indexterm> + <primary>MIME types</primary> + + <secondary>registering applications for</secondary> + </indexterm> + + <indexterm> + <primary>applications</primary> + + <secondary>registry</secondary> + </indexterm> + + <para>Registering applications to handle MIME types is fairly + straightforward. Applications are registered by creating a + <literal>MimeType</literal> key in their <filename>.desktop</filename> + entry file and listing each MIME type separated by a semicolon. The + <literal>MimeType</literal> key should only be used in + <filename>.desktop</filename> files whose <literal>Type</literal> key has + the value <quote><literal>Application</literal></quote>. For more + information on <filename>.desktop</filename> files, see <xref + linkend="menustructure-desktopentry" />.</para> + + <para>After creating or modifying a <filename>.desktop</filename> entry + file, you must update the application database using the + <application>update-desktop-database</application> application (very + similar to <application>update-mime-database, except it does not take a + parameter)</application>. This will create a + <filename>mimeinfo.cache</filename> file in the + <filename>applications</filename> subdirectory for each directory in + <filename>$XDG_DATA_HOME:$XDG_DATA_DIRS</filename>. + The cache file is necessary so that all the <filename>.desktop</filename> + files do not need to be scanned for just the <literal>MimeType</literal> + key, as this causes unnecessary disk I/O.</para> + + <para>Default applications to use for specific MIME types should be + specified in a file called <filename>defaults.list</filename>. This file + is located in the <filename>applications</filename> subdirectory for each + directory in <envar>$XDG_DATA_HOME</envar> and + <envar>$XDG_DATA_DIRS</envar>. The format for this file consists of the + MIME type, the <literal>=</literal> symbol and the Desktop File ID (which + is the filename for the desktop entry file). <xref + linkend="mimetypes-registering-example" /> is a short example of a + <filename>defaults.list</filename> file in a user's + <filename>~/.local/share/applications</filename> directory.</para> + + <example id="mimetypes-registering-example"> + <title>A User's <filename>defaults.list</filename> file</title> + + <programlisting>[Default Applications] +application/pdf=evince.desktop +text/html=epiphany.desktop +text/plain=gedit.desktop +image/jpeg=eog.desktop +image/png=eog.desktop +text/xml=gedit.desktop +</programlisting> + </example> + + <note> + <title>XDG Desktop Entry Specification</title> + + <para>How to register MIME types for applications is part of the <ulink + url="http://www.freedesktop.org/wiki/Standards/desktop-entry-spec">XDG desktop entry specification</ulink>, rather than the + <ulink + url="http://www.freedesktop.org/Standards/shared-mime-info-spec">XDG + shared mime info specification</ulink>.</para> + </note> + </sect1> + <sect1 id="mimetypes-9"> <title>Adding an Application to the GNOME Desktop</title> + <indexterm> <primary>MIME types</primary> + <secondary>adding applications</secondary> </indexterm> + <indexterm> <primary>applications</primary> + <secondary>adding</secondary> </indexterm> - <para>To add an application to the GNOME Desktop, perform the -following steps:</para> + + <para>To add an application to the GNOME Desktop, perform the following + steps:</para> + <orderedlist> <listitem> - <para>Add a menu item for the application. For more information -on how to add an item to a menu, see <xref linkend="menustructure-0"/>.</para> - </listitem> - <listitem> - <para>Add an icon for the application to <filename>/usr/share/icons/<replaceable>theme-name</replaceable>/<replaceable>icon-size</replaceable>/apps</filename>. -For more information on icons and themes, see <xref linkend="themes-0"/>. </para> - </listitem> - <listitem> - <para>If the application uses a new MIME type, add a file content -sniffer for the new MIME type. For more information on file content sniffers, -see <xref linkend="mimetypes-2"/>.</para> + <para>Add a menu item for the application. For more information on how + to add an item to a menu, see <xref + linkend="menustructure-2" />.</para> </listitem> + <listitem> - <para>If the application uses a new MIME type, add a MIME information -file for the application to the MIME type registry. For more information on -MIME information files, see <xref linkend="mimetypes-5"/>.</para> + <para>Add an icon for the application to + <filename>/usr/share/icons/<replaceable>theme-name</replaceable>/<replaceable>icon-size</replaceable>/apps</filename>. + For more information on icons and themes, see <xref + linkend="themes-11" />.</para> </listitem> + <listitem> - <para>Add a MIME keys file for the application to the MIME type -registry. For more information on MIME keys files, see <xref linkend="mimetypes-11"/>.</para> + <para>If the application uses a new MIME type, add a source XML file + to the MIME database. For more information, see <xref + linkend="mimetypes-modifying" />.</para> </listitem> + <listitem> <para>If the application uses a new MIME type, add an icon for the -MIME type to <filename>/usr/share/icons/<replaceable>theme-name</replaceable>/<replaceable>icon-size</replaceable>/mimetypes</filename>. For more information on icons -and themes, see <xref linkend="themes-0"/>. </para> + MIME type to + <filename>/usr/share/icons/<replaceable>theme-name</replaceable>/<replaceable>icon-size</replaceable>/mimetypes</filename>. + For more information on icons and themes, see <xref + linkend="themes-0" />.</para> </listitem> + <listitem> - <para>To associate the application with a MIME type, add an application -registration file to the application registry. For more information on the -application registry, see <xref linkend="mimetypes-7"/>.</para> + <para>To associate the application with a MIME type, include a + <literal>MimeType</literal> key in your <filename>.desktop</filename> + file. For more information, see <xref + linkend="mimetypes-registering" />.</para> </listitem> </orderedlist> </sect1> |