# Desktop menu entries for documents

By default, RPM packages of Publican documents for desktop use appear on the GNOME desktop under the System Documentation menu. When users have large numbers of documents installed on their systems, this menu becomes very cluttered and difficult to navigate. Documentation for many different products and perhaps different languages becomes intermixed, adding to the confusion.

To group documentation for your product under a separate submenu within the GNOME System Documentation menu, you must:

- create and distribute a desktop menu package that creates the new submenu.

- specify the menu category in the document, and optionally, have the documentation package require the desktop menu package.

Note that the Documentation menu does not group entries under a submenu until two or more documents are installed that belong on that submenu. The first document appears under System Documentation.

## Creating an desktop menu package

A desktop menu package consists of:

- a desktop entry (`.directory`) file that provides metadata about the new submenu.

- a desktop menu (`.menu`) file that defines the position of the new submenu within the Documentation menu.

The structure for the `.directory` file for Publican-generated documentation is as follows:

- the group header `[Desktop Entry]`

- the `Name` parameter, set to the name of the submenu that you want to place under the Documentation menu.

- optionally, localizations of the `Name` parameter, in the format `Name[language_code]` where language_code is a language code in glibc format, not the XML format that Publican uses for language codes.

- the `Comment` parameter, set to a description of the new submenu.

- optionally, localizations of the `Comment` parameter, in the format `Comment[language_code]` where language_code is a language code in glibc format, not the XML format that Publican uses for language codes.

- the `Type` parameter, set to `Directory`.

- the `Encoding` parameter, set to `UTF-8`.

### Example .directory file

The following file, `menu-example.directory` illustrates the structure of a desktop entry file.

The desktop entry file is placed in `/usr/share/desktop-directories/`

For a full description of how desktop entries work, refer to the Desktop Entry Specification, available from

A desktop menu file is an XML file that contains:

- a document type declaration for the freedesktop.org Desktop Menu Specification:

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

- a root element, `<Menu>`, that contains:

  - a `<Name>` element with the content `Documentation`

  - another `<Menu>` element that in turn contains:

    - a `<Name>` element with the content `Documentation` (just like the root element)

    - a `<Directory>` element with its content the name of the desktop entry file you created, for example:

          <Directory>menu-example.directory</Directory>

    - an `<Includes>` element with the content `X-category_name`, where category_name is an identifier for the documents that will be grouped together under this menu entry. For example:

          <Includes>X-Example-Docs</Includes>

### Example .menu file

The following file, `menu-example.menu` illustrates the structure of a desktop menu file.

The desktop menu file is placed in `/etc/xdg/menus/settings-merged/`

For a full description of how desktop menus work, refer to the Desktop Menu Specification, available from

## Setting a desktop menu category

To place a document in a submenu of System Documentation, set the `menu_category` parameter in its `publican.cfg` file to match the content of the `<Includes>` element in the corresponding desktop menu file. For example, consider a desktop menu file that contains the element:

    <Includes>X-Example-Docs</Includes>

To place a document in the submenu defined by this desktop menu file, the document's `publican.cfg` file should contain:

    menu_category: X-Example-Docs

Publican will process the string in menu_category and replace `__LANG__` with the current language. This allows menus to be customized on a per language basis.

    menu_category: X-Example-Docs-__LANG__

Note that you can include this parameter in the `defaults.cfg` file or `overrides.cfg` file of a brand so that all documents built with that brand are grouped into this submenu automatically without you having to set the `menu_category` parameter in each document.

If you ship the desktop menu and desktop entry files in an RPM package, you can make RPM packages of documentation require the desktop menu package. With this dependency set, the desktop menu package is installed automatically on users' systems when they install a documentation package, which ensures that the documentation appears under the submenu you have created for your project. Set the dependency with the `dt_requires` parameter in the document's `publican.cfg` file. For example, if you ship a desktop menu package named `foodocs-menu`, set:

    dt_requires: foodocs-menu

Note that you can include this parameter in the `defaults.cfg` file or `overrides.cfg` file of a brand so that all documents built with that brand require the same desktop menu package.