From f4122ca589d59cfb47678fa3f1f78085b0131609 Mon Sep 17 00:00:00 2001 From: Brent Smith Date: Mon, 27 Feb 2006 04:13:49 +0000 Subject: Rewrite of mimetypes.xml and menustructure.xml to bring them up to date in 2006-02-26 Brent Smith * 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 --- gnome2-system-admin-guide/C/ChangeLog | 15 +- gnome2-system-admin-guide/C/menustructure.xml | 1310 ++++++++++++++--------- gnome2-system-admin-guide/C/mimetypes.xml | 1420 ++++++++++++++----------- 3 files changed, 1622 insertions(+), 1123 deletions(-) (limited to 'gnome2-system-admin-guide') 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 + + * 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 - * gconf.xml: - convert the Command Line Options table to a variable list, and changed - examples to use instead of 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 instead of so that the commands + are not justified (which makes them hard to read) 2006-02-15 Brent Smith 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 @@ + Customizing Menus + + + + + + + - The information in this chapter describes how the GNOME -Desktop implements menus and how you can customize menus. + The information in this chapter describes how the GNOME Desktop + implements menus and how you can customize menus. + Introduction to Menus + menus + introduction - The way in which the GNOME Desktop implements menus enables you to do -the following: + + The GNOME Desktop implements menus according to the XDG menu + specification. By supporting this specification, GNOME allows you + to: + - 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. + 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. + - Install applications easily. You do not need to provide information -about the menu hierarchy to applications when you install the applications. + Install applications easily. You do not need to provide + information about the menu hierarchy to applications when you install + the applications. + Configure menus so that users cannot modify the menus. + Menus in the GNOME Desktop use the following components: + - File abstraction layer - - - Vfolders + Menu definition files + Desktop entry files + Directory entry files - - File Abstraction Layer + + + Menu Definition Files + - menus - file abstraction layer + menu definition files + - file abstraction layer, and menus + .menu files + + menu definition files - The gnome-vfs file abstraction layer -provides a simplified and generalized way for applications to interact with -files. The file abstraction layer also provides Uniform Resource -Identifier (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. -lists the menus to which you can add items, and the URI locations that correspond -to the menus. - - Menus and URI Locations + + 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 + applications.menu file that you modify. + + Menu files must reside at + $XDG_CONFIG_DIRS/menus/applications.menu. If + $XDG_CONFIG_DIRS + $XDG_CONFIG_DIRS is the environment variable defined in the + XDG + base directory specification. + is not set, then the default path + /etc/xdg/ is used. This also implies that a user + specific version may be located at + $XDG_CONFIG_HOME/menus/applications.menu + which is searched first. If $XDG_CONFIG_HOME is not set, + then the default path ~/.config/ is used. Directories + which appear first in $XDG_CONFIG_DIRS are given precedence + when there are several applications.menu files. The + first file found is used and subsequent files are ignored. + + If you are confused about the order in which paths are searched, + here is a simple list for resolving the location of + applications.menu: + + + + Search each directory in $XDG_CONFIG_HOME in + order to find /menus/applications.menu. If + $XDG_CONFIG_HOME is not set, default to + ~/.config/ + + + + Search each directory in $XDG_CONFIG_DIRS in + order to find /menus/applications.menu. If + $XDG_CONFIG_DIRS is not set, default to + /etc/xdg/ + + + + Use the first applications.menu file + found. + + + + You can see an example of a .menu file in . In this example, the top level menu is named + Applications, which is specified using the + <Name> element. The + Applications menu contains a single submenu, but + several submenus are allowed. Each submenu may also have an + <Include> element. The purpose of the + <Include> element is to perform a filter on the + set of available desktop entries using matching rules. + + For example, the <Category> element is a + basic matching rule that selects a desktop + entry only if the Categories key contains + the content of the <Category> element. In the + example, the Accessories menu will include a + desktop entry only if it contains + Utility but not System in the Categories + key. For more information on the Categories key, see . + + + Example of a <filename>.menu</filename> file + + <!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 --> + + + + describes some of the + elements in .menu files. For a more detailed + description, please see the XDG menu + specification. + + + Menu Definition File Elements + - - + + + + - - Menu - - - URI Locations - + Element + + Description + - - Applications menu for all -users - - - - applications-all-users:/// - - + <Menu> + + The root element + which may contain nested <Menu> elements + that define submenus. How these elements are nested determines the + menu structure. + - - Desktop Preferences menu for all users - - - - preferences-all-users:/// - - + <Name> + + Specifies the name of + the menu. Every <Menu> element must + contain a <Name> element. - - - - - - Vfolders and Menus - - menus - vfolders - - - vfolders - - In general terms, -a vfolder 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. - menusvfolder information filesvfolder information filesA vfolder information file 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 .vfolder-info file extension. - The following is an excerpt from a vfolder information file: - <?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> - describes some of the elements -in vfolder information files. - - Vfolder Information File Elements - - - - - - - Element - - - Description - + + + <Directory> + + + 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 + <Name> element is to be used to display + the menu name.By default, + .directory files are searched for in the + location + $XDG_DATA_DIRS/desktop-directories/ + as set forth in the XDG menu + specification. - - + + + <DefaultAppDirs> + + This is an instruction which indicates + that all the available desktop entries from + $XDG_DATA_DIRS/applications/ + should be scanned. If this instruction is not included, then these + locations are not scanned for desktop entries. + + + + <DefaultDirectoryDirs> + + This is an instruction which indicates + that all the available directory entries from + $XDG_DATA_DIRS/desktop-directories/ + should be scanned. If the instruction is not included, then these + locations are not scanned for directory entries. + + + + <Include> + + Contains a list of matching rules by + which the contents of a menu are generated. May include the + <Filename>, + <Category>, + <And>, <Or>, + <Not>, or <All> + matching rules. If more than one rule is present, the rules are + logically ORed so that desktop entries that + match any rule are included. + + - - - <Folder> - - - - Contains the elements that define -the name, content, and structure of the menu. - + <Exclude> + + The opposite of + <Include> since any desktop + entries that are matched in this element are excluded + from the previous set of included elements. For this reason, this + element must appear after the <Include> + element. + - - - <Name> - - - - Specifies the name of the menu. - + <Filename> + + A matching rule that selects a + desktop entry when the Desktop File-Id + matches the contents of the <Filename> + element. + - - - <Desktop> - - - - Specifies the name of the directory -entry file that specifies the name, comment, and icon for the menu. - + <Category> + + A matching rule that selects a + desktop entry when the Categories key matches + the contents of the <Category> + element. + - - - <Query> - - - - 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. - The query in the excerpt -searches for desktop entry files that contain the keywords Application and Utility in the Categories -key. Desktop entry files that match are displayed in the Applications menu. - This element is optional. - + <And> + + A matching rule that selects a + desktop entry when it is selected by + all the nested matching rules in the + <And> element. + - - - <DontShowIfEmpty/> - - - - If this -element is present, the menu is not displayed if the menu does not contain -any items. - This element is optional. - + <Or> + + A matching rule that selects a + desktop entry when it is selected by + any of the nested matching rules in the + <Or> element. + + + + <Not> + + A matching rule that does not select a + desktop entry when it is selected by + any of the nested matching rules in the + <Not> element. + + + + <All> + + A matching rule which selects all + desktop entries. - + + Desktop Entry Files + + + desktop entry files + .desktop files + desktop entry files - A desktop entry file 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 .desktop file extension. + + A desktop entry file 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. + + Desktop entry files must reside in the + $XDG_DATA_DIRS/applications directory and must have a + .desktop file extension. If + $XDG_DATA_DIRS + $XDG_DATA_DIRS is the environment variable defined in the XDG base + directory specification. + is not set, then the default path is + /usr/share/ is used. This also implies that user + specific desktop entries may be located at + $XDG_DATA_HOME/applications/ which is + searched first. If $XDG_DATA_HOME is not set, then the + default path ~/.local/share is used. Desktop entries + are collected from all directories in the $XDG_DATA_DIRS + environment variable. Directories which appear first in + $XDG_CONFIG_DIRS are given precedence when there are + several .desktop files with the same name. + The following is a sample desktop entry file: - [Desktop Entry] + + [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 - describes the most important keys -in desktop entry files. +Categories=GTK;GNOME;Application;Utility; + + describes the most important + keys in desktop entry files. To get more information about desktop entry + files, see the XDG Desktop + Entry Specification. + Desktop Entry Keys + - - + + + + - - Desktop Entry Key - - - Description - + Desktop Entry Key + + Description + - - - Encoding - - - - Specifies the encoding of the desktop entry file. - + Encoding + + + Specifies the encoding of the desktop + entry file. + - - - Name - - - - Specifies the name of the item. This name is displayed -on the item in the menu. - + Name + + Specifies the name of the item. This + name is displayed on the item in the menu. + - - - Comment - - - - Specifies a short description of the item. The comment -is displayed as a tooltip when you point to the item in the menu. - + Comment + + + Specifies a short description of the + item. The comment is displayed as a tooltip when you point to the + item in the menu. + - - - Exec - - - - Specifies a command to execute when you choose the item -from the menu. - + Exec + + Specifies a command to execute when you + choose the item from the menu. + - - - Icon - - - - Specifies the filename of an -icon that represents the item. Does not specify the path to the filename, -or the file extension. - + + Icon + + Specifies the + filename of an icon that represents the item. Does not specify the + path to the filename, or the file extension. + - - - Terminal - - - - Specifies whether the command -in the Exec key runs in a terminal window. If the value -is true the command runs in a terminal window. - If the command does not create a window in which to run, the value of this -key must be true. - + + Terminal + + Specifies whether the + command in the Exec key runs in a terminal + window. If the value is true the command runs + in a terminal window. If the command does not create + a window in which to run, the value of this key must be + true. + - - - Type - - - - Specifies the type of item. This -value is one of the following: - + + Type + + Specifies the type of + item. This value is one of the following: + + Application: An item that starts an + application. + + - Application: Enter this option for an -item that starts an application. + Link: An item that links to a file, + folder, or FTP site. + - Link: Enter this option for an item that -links to a file, folder, or FTP site. + FSDevice: An item that is a file + system device. - - + + + Directory: An item that is a + Directory. + + + - - - Categories - - - - 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: - - http://www.freedesktop.org - - The vfolder information -files map the keywords to menus. - + + Categories + + 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: + + http://www.freedesktop.org/Standards/menu-spec + Menu + Definition Files map desktop entries to menus by using + matching rules against the Categories key. + - - - X-GNOME-DocPath - - - - Specifies -the help file to display when you choose Help on application-name from the menu item popup menu. - + MimeType + + Specifies the MIME types - For more information on the keys in desktop entry files, see the desktop -entry specification at the following URL: + + For more information on the keys in desktop entry files, see the + desktop entry specification at the following URL: + - http://www.freedesktop.org + http://www.freedesktop.org/Standards/desktop-entry-spec + 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. + 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. + Directory Entry Files + directory entry files + .directory files + directory entry files - A directory entry file 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 .directory file extension. + + A directory entry file 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 .directory file extension. + + Directory entry files must reside at + $XDG_DATA_DIRS/desktop-directories/. If + $XDG_DATA_DIRS is not set, then the default path is + /usr/share/ is used. This also implies that user + specific directory entries may be located at + $XDG_DATA_HOME/desktop-directories/ + which is searched first. If $XDG_DATA_HOME is not set, then + the default path ~/.local/share/ is used. Directory + entries are collected from all directories in the + $XDG_DATA_DIRS environment variable. Directories which + appear first in $XDG_DATA_DIRS are given precedence when + there are several .directory files with the same + name. + The following is a sample directory entry file: - [Desktop Entry] + + [Desktop Entry] Name=Accessories Comment=Accessories menu Icon=gnome-util.png -Type=Directory - describes the most important keys -in directory entry files. +Type=Directory + + describes the most important + keys in directory entry files. + Directory Entry Keys + - - + + + + - - Directory Entry Key - - - Description - + Directory Entry Key + + Description + - - - Name - - - - Specifies the name of the menu. -This name is displayed on the menu. - + + Name + + Specifies the name of + the menu. This name is displayed on the menu. + - - - Comment - - - - Specifies a short description -of the menu. The comment is displayed as a tooltip when you point to the menu. - + + Comment + + Specifies a short + description of the menu. The comment is displayed as a tooltip + when you point to the menu. + - - - Icon - - - - Specifies the filename of an -icon that represents the menu. Does not specify the path to the filename, -or the file extension. - + + Icon + + Specifies the + filename of an icon that represents the menu. Does not specify the + path to the filename, or the file extension. + - - - Type - - - - Specifies the type of menu. The value of this key is always Directory. - + Type + + Specifies the type of menu. The value of + this key is always Directory. + - Editing Menus + Editing System Menus + + + menus + editing - You use the following GNOME Desktop components to edit menus: - - - Nautilus file manager - - - Menus on panels - - - 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. -lists the menus to which you can add items, and the URI locations that correspond -to the menus. - When you use panels to customize menus for all users, you use the menu -item popup menu. For more information, see Working With Menus -in the GNOME 2.6 Desktop User Guide. - You can also use menu configuration files and menu data files to customize -menus. + + You can edit menu configuration files and menu data files manually + to customize menus. + Adding Menus - You can add menus for all users in the following ways: - + + + + + + + menus + + adding + + + To add a menu for all users, perform the following steps: + + - Use the file manager. + Create a directory entry file for the item that you want to + add. Place the directory entry file in the + $XDG_DATA_DIRS/desktop-directories/ + directory. For more information on directory entry files, see . + - Modify the menu configuration files and menu data files. + Locate the + $XDG_CONFIG_DIRS/menus/applications.menu + file. - - - To Add a Menu Using the File Manager - - menus - adding using file manager - - - file manager - adding menus -with - - To add a menu for all users, perform the -following steps: - - - In a file manager window, access the location where you want -to add the menu. For example, to add a menu to the Applications -menu, type applications-all-users:/// in the Location field, then press Return. - - - Choose FileNew Folder. An untitled folder is added to the -view pane. The name of the folder is selected. - - - Type a name for the folder, then press Return. -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. - - - The next time that users log in, the menu is in the assigned location. - - - To Add a Menu Using Menu Files - - menus - adding using menu files - - To add a menu for all users, perform the following steps: - - - Create a directory entry file for the item that you want to -add. Create the directory entry file in the /usr/share/gnome/vfolders directory. For more information on directory entry files, see . - - - Locate the vfolder information file for the location where -you want to add the menu. For example, to add a menu to the Applications menu, locate the file /etc/gnome-vfs-2.0/vfolders/applications-all-users.vfolder-info. - - - In the vfolder information file, add a <Folder> element for the new menu. For more information on vfolder information -files, see . - - - The next time that users log in, the menu is in the assigned location. - + + + In the .menu file, add a + <Menu> element for the new menu. For more + information on .menu files, see . + + + + Create a <Name> element below + <Menu>. The content of the element should + contain the name for the menu. + + + + Create a <Directory> element below + <Menu>. The content of the element should + contain the name of the directory entry file. + + + + See for how to add an item + to the menu. + + + + The next time that users log in, the menu should appear in the + menu bar. + + + Missing Menu? + + If you did not specify any matching rules in the + <Include> element, or if the rule did not + match any desktop entries, then you may not see the menu in the menu + bar. + + - To Add an Item to a Menu + Adding an Item to a Menu + menus + adding items to + To add an item to a menu for all users, perform the following -steps: + steps: + - Create a desktop entry file for the item that you want to -add. For more information on desktop entry files, see . + Create a desktop entry file for the item that you want to add. + For more information on desktop entry files, see . + - Open a file manager window. Choose FileNew Window to open a second -file manager window. + Place the desktop entry file in the folder + $XDG_DATA_DIRS/applications/ + - In one window, access the location where you want to add the -menu item. For example, to add a menu item to the Preferences -menu, type preferences-all-users:/// in the Location field, then press Return. + Locate the + $XDG_CONFIG_DIRS/menus/applications.menu + file. + - 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. - Alternatively, you can copy the desktop entry file, then paste the file -into the location where you want to add the menu item. + Verify that a <Menu> element contains + an <Include> element with a matching rule + that selects the desktop entry file made in step 1. - The next time that users log in, the menu item is in the assigned location. + + The next time that users log in, the menu item is in the assigned + location. + - To Edit the Properties of a Menu + Editing the Properties of a Menu + menus + editing properties of - To edit the properties of a menu for all users, perform -the following steps: + + To edit the properties of a menu for all users, perform the + following steps: + - From a panel, open the menu that you want to edit. Right-click -on any item in the menu. + Locate the + $XDG_CONFIG_DIRS/menus/applications.menu + file. + - Choose Entire menuProperties. A Launcher Properties dialog is displayed. + Find the <Menu> entry in this file + that corresponds to the menu you want to modify. Note the filename + of the directory entry in the <Directory> + element. + - Modify the properties of the menu in the Launcher Properties dialog. For more information on the elements in the Launcher Properties dialog, see Working With Panels in the GNOME 2.6 Desktop User Guide. - - - Click OK. + Locate the directory entry for this menu. Modify the contents + to change the properties of the menu. For more information on + .directory files, see . + - To Edit a Menu Item + Editing a Menu Item + menus + editing menu items + To edit a menu item, perform the following steps: + - 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. - - - Choose Properties. A Launcher Properties dialog is displayed. - - - Modify the properties of the menu item in the Launcher Properties dialog. For more information on the elements in the Launcher Properties dialog, see Working With Panels in the GNOME 2.6 Desktop User Guide. + Locate the desktop entry in + $XDG_DATA_DIRS/applications/ + corresponding to the menu item. + - Click OK. + Edit the desktop entry to change the properties of the menu + item. For more information on desktop entry files, see . + - To Delete an Item from a Menu + Deleting an Item from a Menu + menus + deleting menu items - 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 Remove this item. - The next time that users log in, the menu item is not displayed in the -menu. + + To delete an item from a menu for all users: + + + + Locate the + $XDG_CONFIG_DIRS/menus/applications.menu + file. + + + + Find the <Menu> element in this file + that contains the desktop entry you want to delete. + + + + Insert an <Exclude> element after the + closing tag for the <Include> element. Make + sure this is in the <Menu> element + determined in step 2. + + + + Insert the <Filename> matching rule + as a subelement of <Exclude> to + specifically exclude a desktop entry. + + + + The next time that users log in, the menu item is not displayed in + the menu. shows how this + done in the applications.menu file. The desktop + entry for dasher.desktop is explicitly excluded + from showing up in the accessibility menu. + + + Deleting an Item from a Menu + + <!-- ... --> + + <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> + +<!-- ... --> + + - - To Configure Menus That Users Cannot Modify + + + Editing User Menus and Menu Merging + menus - configuring menus that users -cannot modify + + editing user menus - Users cannot modify a menu if the -following conditions are true: + + You can use the following GNOME Desktop applications to edit menus + for users: + - A vfolder information file that corresponds to the menu is -present in the /etc/gnome-vfs-2.0/vfolders directory. - - - The vfolder information file has the same name as the URI -location that corresponds to the menu. - - - The user permissions for the vfolder information file are -set to read only. + GNOME Menu Editor - To configure a menu so that users cannot modify the menu, perform the -following steps: - - - Create a vfolder information file for the menu that you want -to configure in the /etc/gnome-vfs-2.0/vfolders directory. - - - 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 Applications menu, create a vfolder information called applications.vfolder-info in the /etc/gnome-vfs-2.0/vfolders directory. - - - Set the permissions on the vfolder information file to read -only. - - + + A simple menu editor is available for users to edit their menus. For + more information, see Working With Menus in the + GNOME User Guide. Alternatively, you + can manually create and edit a user menu file. + + To manually create a custom menu for a user, the + $XDG_CONFIG_HOME/menus/applications.menu + must exist. In the case that $XDG_CONFIG_HOME is not set, + the default ~/.config/ is used. Since this is the + first location that is searched for the + applications.menu file, it takes precedence over all + other menu files. + + User menus can contain all the elements described in . For a complete list of the elements + allowed, see the XDG menu + specification. + + Since user menu files take precedence over the system menu file, it + will completely replace the system menu unless it explicitly + merges the system menu. Information on menu merging + is available in the following subsections. + + + Merging the System Menu + + + menus + + merging the system menu + + + 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 <MergeFile> + element with the attribute type="parent" within the + user's applications.menu file. + + The <MergeFile> element allows a menu to + be merged with the contents of the user's menu file. When you specify + the attribute type="parent", then the contents of the + <MergeFile> element are ignored and the next + applications.menu file in + $XDG_CONFIG_DIRS/menus/ is used for + merging. + + + Older Specifications + + Older specifications did not include the type + attribute and simply required the location of the menu file to be + merged as the content of the <MergeFile> + element. As a result, you may still see a location specified in the + contents of <MergeFile>, even when + type="parent". + + + The merging is performed as follows: + + + + The children of the root <Menu> + element in the merged menu file + Merged menu file refers to the next + applications.menu in + $XDG_CONFIG_DIRS/menus/ + are substituted for the + <MergeFile> element in the base menu + file. + + + + All child <Menu> elements with the + same name are consolidated into a single + <Menu> element. This is by done appending + all child elements of each <Menu> element + with the same name into the last occurrence of + the menu element. + + + + shows an example of a + user menu file explicitly merging the system menu file. + + + Merging the System Menu + + <!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> + + + + + + Merging Arbitrary Menus + + + menus + + merging arbitrary menus + + + Arbitrary menu files can be merged in much the same way as system + menus. The difference is that the type attribute must + be set to path or must be excluded from the + <MergeFile> element in order to do this type of + merge. + + The merge is performed in the same way except that the location of + the merged menu file is specified in the contents + of the <MergeFile> element. + 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 @@ + MIME Types + + + + - This chapter describes how applications detect MIME types, -how to register MIME types, and how to add applications to the GNOME Desktop. + This chapter describes how applications detect MIME types, how to + register MIME types, and how to add applications to the GNOME + Desktop. - + + 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 + not attempt to go into details where it is not + necessary. For the gory details, it is recommended that you refer to the + XDG + shared mime info specification. + + Introduction to MIME Types + + MIME types + introduction + A Multipurpose Internet Mail Extension -(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. - The Nautilus 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: + [MIME] 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 gedit. + + As another example, the Nautilus file + manager needs to know the MIME type of a file to perform the following + tasks: + Open the file in an appropriate application. + Display a string that describes the type of file. + Display an appropriate icon to represent the file. + - Display a list of other applications that can open the file. + Display a list of other applications that can open the + file. - 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. - 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. + + 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 media type followed by a + subtype identifier, separated by a forward slash + character, /. One example of a MIME type + is image/jpeg. The media type in this example is + image and the subtype identifier is + jpeg. 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. + + There are eight media types currently blessed by the + IANA [Internet Assigned Naming Authority]. These eight + media types are + application + + audio + + image + + message + + model + + multipart + + text + + video + . Many subtypes exist for each media type; for more + information, see MIME Media + Types at the IANA web + site. + + Implementation of MIME types in GNOME follows the XDG + shared mime info specification. This specification provides the + following advantages: + + + + Standard locations for all MIME related files. + + + + A standard way for applications to register information about a + new MIME type. + + + + A standard way to retrieve the MIME type for a file. + + + + A standard way to retrieve information about a MIME type. + + + + 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. - - Detecting the MIME Type for a File + + + The MIME Database + + + MIME types - detecting - - - detecting MIME types + + database - Applications -can detect the MIME type of a file as follows: - + + The MIME database is a collection of files that make up: + + - The application uses file content sniffers -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. + The set of known MIME types + - If file content sniffers do not identify the MIME type, then -the application can check the filename. The application checks the filename -against the MIME type registry. 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. + The method for determing the MIME type of a file - - The following sections provide further information on file content sniffers -and the MIME type registry. - - File Content Sniffers - - MIME types - file content sniffers - - - file content sniffers - - File content sniffers are specified in the file /etc/gnome-vfs-mime-magic. The following is an example of a file content sniffer: - 0 string \x89PNG image/png - The syntax for file content sniffers is as follows: - offset_start[:offset_end] pattern_type pattern [&pattern_mask] type - describes the fields in a file content -sniffer. - - Fields in a File Content Sniffer - - - - - - - Field - - - Description - - - - - - - - offset_start - - - - Specifies the number of characters to ignore in -the file before searching for a text pattern. - - - - - - pattern_type - - - - Specifies the type of pattern to search for. The string pattern type is the only pattern type that is supported at -the time of publication of this guide. - - - - - - pattern - - - - Specifies the pattern to search for. - - - - - - pattern_mask - - - - Specifies a pattern mask, -in hexadecimal format. For more information on pattern masks, see the next -section. - This field is optional. This field is not present in -the example. - - - - - - type - - - - Specifies the MIME type to associate with files that match -this entry. - - - - -
- - - Pattern Masks - - MIME types - pattern mask - - - pattern mask - - 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: - 0 string BMxxxx\000\000 &0xffff00000000ffff image/bmp - The pattern and mask in the example are as follows: - - - - - - - - - - - - - - - Pattern - - - - B - - - - - M - - - - - x - - - - - x - - - - - x - - - - - x - - - - - \000 - - - - - \000 - - - - - - Mask - - - - ff - - - - - ff - - - - - 00 - - - - - 00 - - - - - 00 - - - - - 00 - - - - - ff - - - - - ff - - - - - - - The pattern and mask specify a file with the following characteristics: - + + + Meta information regarding a MIME type, such as a human readable + description to use when displaying files of this type. + + + + + Location + + 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 XDG + shared mime info specification was drafted by the X Desktop + Group, it also makes use of the XDG base + directory specification. 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. + + The MIME database is created from the set of files located in the + $XDG_DATA_HOME/mime and + $XDG_DATA_DIRS/mime directories. If + these environment variables are unset, then they default to the values + ~/.local/share and + /usr/local/share:/usr/share respectively. As can be + seen from the default value for $XDG_DATA_DIRS , each + environment variable is actually a colon separated list of directories. + The user's database at + $XDG_DATA_HOME/mime has precedence + over the system database at + $XDG_DATA_DIRS/mime when conflicting + definitions are encountered. Similar to the XDG shared mime + specification, we will refer to this set of directories as + <MIME> in the rest of this document. + + For example, assuming default paths for the environment variables, + Load + <MIME>/text/plain.xml + means to load the following files: + + - The file begins with BM. + ~/.local/share/mime/text/plain.xml + - BM is followed by four bytes with any values. + /usr/local/share/mime/text/plain.xml + - The four bytes are followed by \000\000. + /usr/share/mime/text/plain.xml - - The file content sniffer specifies that the MIME type of files that -match the pattern and mask is image/bmp. + - - MIME Type Registry - - MIME types - MIME type registry - - The MIME type registry is located in /usr/share/mime-info. The MIME type registry contains the following files: - - - - - - - - File - - - File Extension - - - - - - - MIME information file - - - - .mime - - - - - - MIME keys file - - - - .keys - - - - - - - The following sections describe MIME information files and MIME keys -files. - - MIME Information Files - - MIME types - MIME information files - - MIME information files -associate MIME types with one or both of the following: - + + + Contents + + The following is a list of directories and files that are found + inside the MIME database along with brief descriptions: + + + + <MIME>/packages/ + - File extensions + This directory contains any number of XML files, each of + which describe a collection of MIME types. By default, the + freedesktop.org.xml file is installed in the + /usr/share/mime/packages directory. This file + contains all the default MIME types that are widely used and + recognized. + + Applications which provide information about new MIME types + are to install a single new XML file here. + Depending on the prefix where the application is installed, it + will create the file in the /mime/package + subdirectory of one of the directories in + $XDG_DATA_HOME:$XDG_DATA_DIRS. For example, an + application installed to /usr/bin should + install a new source XML file to the + /usr/share/mime/packages directory. For more + information about the XML files in the + packages directory, please see . + + + + <MIME>/MEDIA/SUBTYPE.xml + - Filename patterns + These directories and files are automatically generated from + the collection of source XML files in the + <MIME>/packages/ subdirectory by the + update-mime-database application. For + example, for each mime-type element in the + /usr/share/mime/packages/freedesktop.org.xml + file, a directory is created at + /usr/share/mime/ with the media + type of the MIME type. An XML file is created in that + directory with the subtype identifier of that + MIME type as well. The contents of the created XML file include + comments (and translations for them), subclasses designations and + aliases. + + + Example: + <filename>/usr/share/mime/text/plain.xml</filename> file + + <?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> +This file is generated by the + update-mime-database application, + using the default source XML file + freedesktop.org.xml. + - - 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. - In MIME information files, the filename pattern to search for is written -as a regular expression. - The format of MIME type entries in MIME information files is as follows: - MIME-type - ext[,priority]: list-of-extensions - regex[,priority]: list-of-regular-expressions - 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 1 to the .gz extension, and assign a higher priority of 2 -to the .tar.gz extension. In this case, the file abc.tar.gz takes the MIME type for .tar.gz. - - You must indent the ext field and the regex field with a tab character (\t). - - The following MIME type entries are samples from the gnome-vfs.mime MIME information file: - 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.* - - 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 abc.mime -and def.mime, the MIME type in abc.mime -is used. - - - - MIME Keys Files - - MIME types - MIME keys files - - MIME keys file 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. - The following is a sample from a MIME keys file: - 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 - - You must indent the keys in a MIME keys file with a tab character -(\t). - - describes the most important keys in -MIME keys files. Typically, the description key and the category key are localized. - - Keys in MIME Keys Files - - - - - - - Key - - - Description - - - - - - - - can_be_executable - - - - Specifies -whether files of this MIME type can be executed. - - - - - - description - - - - Describes the MIME type. This description can be -displayed in the file manager and other applications. - - - - - - icon_filename - - - - Specifies the filename of an icon to represent the -MIME type. Does not specify the path to the filename, or the file extension. - This icon can be displayed in the file manager and other applications. - - - - - - default_action_type - - - - Specifies the category of action to take when a -file of this MIME type is opened by the user. Enter application -for this MIME type for most applications. - - - - - - short_list_application_ids -_for_novice_user_level - - - - 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. - - - - - - category - - - - Specifies a category for the MIME type. The value -of this key determines the location of the MIME type in the File Types and Programs preference tool. - - - - -
- + + + + <MIME>/globs + + + 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 XDG shared mime + specification. + + This file is also generated by the + update-mime-database application, using + the default source XML file + freedesktop.org.xml. + + + + + <MIME>/magic + + + A binary file which contains information on how to resolve + MIME types by sniffing the content of the file. + This is generally a set of one or more rules such as check + for the string %PDF- at byte offset 0 in the + file; if found, assign it the MIME type + application/pdf. + + This file is also generated by the + update-mime-database + application. + + + + + <MIME>/XMLnamespaces + + + 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. + + This file is also generated by the + update-mime-database + application. + + + + + <MIME>/aliases + + + 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. + + This file is also generated by the + update-mime-database + application. + + + + + <MIME>/subclasses + + + Contains a list of subclassed MIME types and their + parent MIME type. From the XDG shared + mime specification:
+ 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). +
The format of this file is similar to the + aliases 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. + + This file is also generated by the + update-mime-database + application. + + + + + + + Refreshing the MIME Database + + 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 + update-mime-database is intended for this + purpose. + + For example, if an application installs information about a new + MIME type to /usr/share/mime/packages/diff.xml, + then update-mime-database must be called with + the parameter /usr/share/mime. + + # update-mime-database /usr/share/mime +*** +* Updating MIME database in /usr/share/mime... +*** + + + The MIME database is refreshed by scanning all the source XML + files in the directory + <MIME>/packages. - - Registering Applications for MIME Types + + + The source XML files + + + + MIME types - registering applications -for + + source XML files - - applications - registry - - The application registry 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: + + Located in the <MIME>/packages directory, + these XML files provide all the information regarding MIME types that is + installed into the database by the + update-mime-database application. There are a + few rules about the XML file itself: + - The command to use to start the application. + It must specify the namespace as + http://www.freedesktop.org/standards/shared-mime-info + + + + The root element must be mime-info + - MIME types to associate with the application. + Zero or more mime-type elements can be + specified as children of the mime-info element. The + type attribute is used to specify the MIME type + that is being defined. - An application registration file can contain one or more application -registrations. Application registration files have a .applications extension. - The location of the application registry is /usr/share/application-registry. This directory contains a default application registration file -that is called gnome-vfs.applications. - To register an application, add a registration file for the application -to the application registry. - The following is an example of an application registration: - 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 - describes the keys in application registration -files. - - Keys for an Application Registration + + By default, the freedesktop.org.xml file is + installed to the packages directory in one of the + <MIME> paths (usually + /usr/share/mime/packages). + + gives a brief + description for each of the elements that can occur as children to the + mime-type element. + +
+ Child elements of <literal><mime-info></literal> + - - + + + + - - Key - - - Description - + Element (and attributes) + + Description + - - Application identifier - - - 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. - - - - - - command - - - - Specifies the command to use to start the application, -and any options to use with the command. - - - - - - name - - - - Specifies a name for the application. The name is used -in the user interface. For example, the name is used in the Open -With submenu in the file manager. - + <glob + pattern="*.xyz"> + + This element specifies a glob pattern against filenames. If + the filename matches, then it is assigned the MIME type of the + parent mime-type element. The + pattern attribute is mandatory. + - - - can_open_multiple_files - - - - Specifies whether the application can open several -files at the same time. - + <magic + priority="50"> + + This element contains a list of match + elements as its children. The priority + attribute is optional, and specifies a priority between 0 and 100, + with 100 being the highest matching priority. Each child + match element has three required attributes: + + type + + offset + + value + and a fourth optional attribute, + mask. For details on these attributes, see the + XDG + shared mime info specification. + - - - expects_uris - - - - Specifies whether the application can process URIs. -If the value of this key is true, the application registration -entry must also contain a supported_uri_schemes key. - + <alias + type="media/subtype"> + + This element defines an alias for the parent + mime-type element. An alias is simply a MIME + type that is sometimes known as another type. For example, + application/x-pdf is an alias for the MIME type + application/pdf. + - - - supported_uri_schemes - - - - Specifies -the URI schemes that the application can process. - + <sub-class-of + type="media/subtype"> + + This element defines the parent + mime-type element as a subclass of the MIME + type specified in the type attribute. For + example, image/svg is a sub class of the MIME + type text/xml, text/plain, + and application/octet-stream. + - - - requires_terminal - - - - Specifies whether to run the application in a terminal -window. Enter true for this field for an application that -does not create a window in which to run. - + <comment + xml:lang="locale"> + + 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 + xml:lang attribute. + - - - mime_types - - - - Specifies the MIME types that the application can -use. - + <root-XML + namespaceURI="namespace" + localName=""> + + If a file is determined to an XML file, then this element + helps to further classify it through the use of the + namespaceURI and localName + attributes, both of which are required. The attribute + namespaceURI is the namespace of the document, + and localName is the name of the root element + for the document. If localName is present but + its value is empty, then the root element may have any name, but + the namespace must still match.
+ + The easiest way to understand these files is to take a look at an + example. Borrowing from the XDG shared mime + specification, + displays the contents of a source XML file called + diff.xml. This example defines the MIME type + text/x-diff. There are multiple + comment 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 and through + the use of content sniffing (better known as + magic rules). Any file with the extension + .diff or .patch will resolve to + this MIME type. Additionally any file whose contents start with the + strings specified in the value attributes of the + match element, will resolve to the + text/x-diff MIME type. + + The order in which glob patterns and magic rules apply is beyond the + scope of this document. For details on this, see the XDG + shared mime info specification. + + + Example of a source XML file: + <filename>diff.xml</filename> + + <?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> + + + + Modifying MIME types + + + MIME types + + verifying changes + + + + MIME types + + modifying + + + You should never directly modify the source XML files that are + installed to the <MIME>/packages directory by + applications. Instead, modify the Overrides.xml file. + This file has precedence over all other source XML files installed into + the same packages 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 + <MIME>/packages directory (your + Makefile will take care of this, of course). + + 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 + Overrides.xml in the + $XDG_DATA_DIRS/mime/packages + directory. To modify the database for a single user, make changes to the + file Overrides.xml in the + $XDG_DATA_HOME/mime/packages + directory. + + After changes are made, you must always run the + update-mime-database application, with the + directory location of the MIME database as the first parameter. + + + Adding or Modifying MIME types + + To add one or more MIME types for all users: + + + + Create or modify an existing + Overrides.xml source XML file, containing the + definitions for the MIME types. For more information, see . + + + + Place the Overrides.xml file in the + /usr/share/mime/packages directory. + + + + Update the MIME database by running + update-mime-database using the system + account.# update-mime-database /usr/share/mime + + + + To add one or more MIME types for a single user, follow the same + steps, except place your Overrides.xml file in the + ~/.local/share/mime/packages directory. + Additionally, call update-mime-database with + ~/.local/share/mime/packages as the first + parameter. + + + + Verifying Changes + + + 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 + gnomevfs-info application. This application + prints the MIME type and other useful information about a file. + + Running gnomevfs-info on a SVG file + gives you the output shown below. You'll notice the default application + for this MIME type is eog.desktop; We will discuss + default applications in . + + $ gnomevfs-info mime-diagram.svg +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 +$ + + + walks through the steps of + creating a new MIME type and then verifying the changes using + gnomevfs-info. + + + + <literal>application/x-newtype</literal> Example + + To create (or override) a MIME type and verify the changes: + + + + Make a new, empty file in your home directory called + testing.xyz. + + + + Use gnomevfs-info on the file to + find out the MIME type.The MIME type for this file should be + detected as text/plain because there are not any + glob patterns or magic rules that match it + When no glob patterns or magic rules match a file, then it + is resolved to the MIME type text/plain if it + contains textual data or + application/octet-stream for binary data. If + the file is empty, then it defaults to + text/plain. + . + + + + Create (or modify) the Overrides.xml file + as described in with the + contents given in . + + + + Refresh the database using + update-mime-database. + + + + Use gnomevfs-info to verify that + your change has taken effect. You should see the MIME type for the + testing.xyz file resolved as + application/x-newtype. + + $ gnomevfs-info testing.xyz | grep MIME +MIME type : application/x-newtype +$ + + + + + <filename>Overrides.xml</filename> file + + <?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> + + + + + + Registering Applications for MIME Types + + + + + MIME types + + registering applications for + + + + applications + + registry + + + Registering applications to handle MIME types is fairly + straightforward. Applications are registered by creating a + MimeType key in their .desktop + entry file and listing each MIME type separated by a semicolon. The + MimeType key should only be used in + .desktop files whose Type key has + the value Application. For more + information on .desktop files, see . + + After creating or modifying a .desktop entry + file, you must update the application database using the + update-desktop-database application (very + similar to update-mime-database, except it does not take a + parameter). This will create a + mimeinfo.cache file in the + applications subdirectory for each directory in + $XDG_DATA_HOME:$XDG_DATA_DIRS. + The cache file is necessary so that all the .desktop + files do not need to be scanned for just the MimeType + key, as this causes unnecessary disk I/O. + + Default applications to use for specific MIME types should be + specified in a file called defaults.list. This file + is located in the applications subdirectory for each + directory in $XDG_DATA_HOME and + $XDG_DATA_DIRS. The format for this file consists of the + MIME type, the = symbol and the Desktop File ID (which + is the filename for the desktop entry file). is a short example of a + defaults.list file in a user's + ~/.local/share/applications directory. + + + A User's <filename>defaults.list</filename> file + + [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 + + + + + XDG Desktop Entry Specification + + How to register MIME types for applications is part of the XDG desktop entry specification, rather than the + XDG + shared mime info specification. + + + Adding an Application to the GNOME Desktop + MIME types + adding applications + applications + adding - To add an application to the GNOME Desktop, perform the -following steps: + + To add an application to the GNOME Desktop, perform the following + steps: + - Add a menu item for the application. For more information -on how to add an item to a menu, see . - - - Add an icon for the application to /usr/share/icons/theme-name/icon-size/apps. -For more information on icons and themes, see . - - - 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 . + Add a menu item for the application. For more information on how + to add an item to a menu, see . + - 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 . + Add an icon for the application to + /usr/share/icons/theme-name/icon-size/apps. + For more information on icons and themes, see . + - Add a MIME keys file for the application to the MIME type -registry. For more information on MIME keys files, see . + If the application uses a new MIME type, add a source XML file + to the MIME database. For more information, see . + If the application uses a new MIME type, add an icon for the -MIME type to /usr/share/icons/theme-name/icon-size/mimetypes. For more information on icons -and themes, see . + MIME type to + /usr/share/icons/theme-name/icon-size/mimetypes. + For more information on icons and themes, see . + - 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 . + To associate the application with a MIME type, include a + MimeType key in your .desktop + file. For more information, see . -- cgit