From: Charles Plessy Date: Sat, 15 Feb 2014 02:12:30 +0000 (+0900) Subject: Document the FreeDesktop menu entries and media type declarations. X-Git-Url: https://git.donarmstrong.com/?p=debian%2Fdebian-policy.git;a=commitdiff_plain;h=ba679bff76f5b9152f43d5bc901b9b3aad257479 Document the FreeDesktop menu entries and media type declarations. The Debian menu is optionally supported. Wording: Charles Plessy Seconded: Lisandro Damián Nicanor Pérez Meyer Seconded: Cyril Brulebois (for the menu entries) Seconded: Russ Allbery Closes: #707851 --- diff --git a/policy.sgml b/policy.sgml index dad8d23..1743552 100644 --- a/policy.sgml +++ b/policy.sgml @@ -8054,38 +8054,75 @@ Reloading description configuration...done. Menus

- The Debian menu package provides a standard - interface between packages providing applications and - menu programs (either X window managers or - text-based menu programs such as pdmenu). + Packages shipping applications that comply with minimal requirements + described below for integration with desktop environments should + register these applications in the desktop menu, following the + FreeDesktop standard, using text files called + desktop entries. Their format is described in the + Desktop Entry Specification at + + and complementary information can be found in the + Desktop Menu Specification at + .

- All packages that provide applications that need not be - passed any special command line arguments for normal - operation should register a menu entry for those - applications, so that users of the menu package - will automatically get menu entries in their window - managers, as well in shells like pdmenu. + The desktop entry files are installed by the packages in the + directory /usr/share/applications and the FreeDesktop + menus are refreshed using dpkg triggers. It is therefore + not necessary to depend on packages providing FreeDesktop menu + systems.

- Menu entries should follow the current menu policy. + Entries displayed in the FreeDesktop menu should conform to the + following minima for relevance and visual integration. + + + + Unless hidden by default, the desktop entry must point to a PNG + or SVG icon with a transparent background, providing at least + the 22×22 size, and preferably up to 64×64. The icon + should be neutral enough to integrate well with the default icon + themes. It is encouraged to ship the icon in the default + hicolor icon theme directories, or to use an existing + icon from the hicolor theme. + + + + If the menu entry is not useful in the general case as a + standalone application, the desktop entry should set the + NoDisplay key to true, so that it can be + configured to be displayed only by those who need it. + + + + In doubt, the package maintainer should coordinate with the + maintainers of menu implementations through the + debian-desktop mailing list in order to avoid problems + with categories or bad interactions with other icons. Especially + for packages which are part of installation tasks, the contents + of the NotShowIn/OnlyShowIn keys should be + validated by the maintainers of the relevant environments. + +

- The menu policy can be found in the menu-policy - files in the debian-policy package. - It is also available from the Debian web mirrors at - . + Since the FreeDesktop menu is a cross-distribution standard, the + desktop entries written for Debian should be forwarded upstream, + where they will benefit to other users and are more likely to + receive extra contributions such as translations.

-

- Please also refer to the Debian Menu System - documentation that comes with the menu - package for information about how to register your - applications. +

+ Packages can, to be compatible with Debian additions to some window + managers that do not support the FreeDesktop standard, also provide a + Debian menu file, following the Debian menu policy, + which can be found in the menu-policy files in the + debian-policy package. It is also available from the Debian + web mirrors at .

@@ -8093,42 +8130,109 @@ Reloading description configuration...done. Multimedia handlers

- MIME (Multipurpose Internet Mail Extensions, RFCs 2045-2049) - is a mechanism for encoding files and data streams and - providing meta-information about them, in particular their - type (e.g. audio or video) and format (e.g. PNG, HTML, - MP3). + Media types (formerly known as MIME types, Multipurpose Internet Mail + Extensions, RFCs 2045-2049) is a mechanism for encoding files and + data streams and providing meta-information about them, in particular + their type and format (e.g. image/png, text/html, + audio/ogg).

- Registration of MIME type handlers allows programs like mail + Registration of media type handlers allows programs like mail user agents and web browsers to invoke these handlers to - view, edit or display MIME types they don't support directly. + view, edit or display media types they don't support directly.

- Packages which provide programs to view/show/play, compose, edit or - print MIME types should register them as such by placing a file in - format (RFC 1524) in the directory - /usr/lib/mime/packages/. The file name should be the - binary package's name. + There are two overlapping systems to associate media types to programs + which can handle them. The mailcap system is found on a + large number of Unix systems. The FreeDesktop system is + aimed at Desktop environments. In Debian, FreeDesktop entries are + automatically translated in mailcap entries, therefore packages + already using desktop entries should not use the mailcap system + directly.

-

- The mime-support package provides the - update-mime program, which integrates these - registrations in the /etc/mailcap file, using dpkg - triggers - Creating, modifying or removing a file in - /usr/lib/mime/packages/ using maintainer scripts will - not activate the trigger. In that case, it can be done by calling - dpkg-trigger --no-await /usr/lib/mime/packages from - the maintainer script after creating, modifying, or removing - the file. - . - Packages using this facility should not depend on, - recommend, or suggest mime-support. -

+ + Registration of media type handlers with desktop entries + +

+ Packages shipping an application able to view, edit or point to + files of a given media type, or open links with a given URI scheme, + should list it in the MimeType key of the application's + desktop entry. For URI schemes, + the relevant MIME types are x-scheme-handler/* (e.g. + x-scheme-handler/https). +

+ + + + Registration of media type handlers with mailcap entries + +

+ Packages that are not using desktop entries for registration should + install a file in format (RFC + 1524) in the directory /usr/lib/mime/packages/. The + file name should be the binary package's name. +

+ +

+ The mime-support package provides the + update-mime program, which integrates these + registrations in the /etc/mailcap file, using dpkg + triggers + Creating, modifying or removing a file in + /usr/lib/mime/packages/ using maintainer scripts will + not activate the trigger. In that case, it can be done by calling + dpkg-trigger --no-await /usr/lib/mime/packages from + the maintainer script after creating, modifying, or removing + the file. + . + +

+ Packages installing desktop entries should not install mailcap + entries for the same program, because the + mime-support package already reads desktop + entries. +

+ +

+ Packages using these facilities should not depend on, + recommend, or suggest mime-support. +

+ + + + Providing media types to files + +

+ The media type of a file is discovered by inspecting the file's + extension or its pattern, and + interrogating a database associating them with media types. +

+ +

+ To support new associations between media types and files, their + characteristic file extensions and magic patterns should be + registered to the IANA (Internet Assigned Numbers Authority). See + and RFC 6838 + for details. This information will then propagate to the systems + discovering file media types in Debian, provided by the + shared-mime-info, + mime-support and file + packages. If registration and propagation can not be waited for, + support can be asked to the maintainers of the packages mentioned + above. +

+ +

+ For files that are produced and read by a single application, it + is also possible to declare this association to the + Shared MIME Info system by installing in the directory + /usr/share/mime/packages a file in the XML format + specified at . +

+