clone 741573 -1 reassign -1 debian-policy retitle -1 Deprecating menu files and transition to desktop files thanks
In #741573, the CTTE has determined that Debian should use .desktop files as appropriate. We had intended that this decision would start a discussion of the policy necessary to generate this transition, using the changes in https://anonscm.debian.org/cgit/dbnpolicy/policy.git/commit/?id=ba679bff76f5b9152f43d5bc901b9b3aad257479 (attached). I'm now trying to start that discussion in the hopes of generating a changeset to policy which in addition to incorporating the CTTE changes provides the framework for an orderly transition from the Debian menu system to desktop standard. I hope that this will happen within the normal policy discussion framework in a reasonable timeframe; baring that, I will implement the CTTE decision by applying ba679bff76 and NMUing policy. -- Don Armstrong http://www.donarmstrong.com
From ba679bff76f5b9152f43d5bc901b9b3aad257479 Mon Sep 17 00:00:00 2001 From: Charles Plessy <ple...@debian.org> Date: Sat, 15 Feb 2014 11:12:30 +0900 Subject: [PATCH] Document the FreeDesktop menu entries and media type declarations. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Debian menu is optionally supported. Wording: Charles Plessy <ple...@debian.org> Seconded: Lisandro Damián Nicanor Pérez Meyer <perezme...@gmail.com> Seconded: Cyril Brulebois <k...@debian.org> (for the menu entries) Seconded: Russ Allbery <r...@debian.org> Closes: #707851 --- policy.sgml | 200 +++++++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 152 insertions(+), 48 deletions(-) diff --git a/policy.sgml b/policy.sgml index dad8d23..1743552 100644 --- a/policy.sgml +++ b/policy.sgml @@ -8054,38 +8054,75 @@ Reloading <var>description</var> configuration...done. <heading>Menus</heading> <p> - The Debian <tt>menu</tt> package provides a standard - interface between packages providing applications and - <em>menu programs</em> (either X window managers or - text-based menu programs such as <prgn>pdmenu</prgn>). + 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 + <em>FreeDesktop</em> standard, using text files called + <em>desktop entries</em>. Their format is described in the + <em>Desktop Entry Specification</em> at + <url id="http://standards.freedesktop.org/desktop-entry-spec/latest/";> + and complementary information can be found in the + <em>Desktop Menu Specification</em> at + <url id="http://standards.freedesktop.org/menu-spec/latest/";>. </p> <p> - 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 <tt>menu</tt> package - will automatically get menu entries in their window - managers, as well in shells like <tt>pdmenu</tt>. + The desktop entry files are installed by the packages in the + directory <file>/usr/share/applications</file> and the FreeDesktop + menus are refreshed using <em>dpkg triggers</em>. It is therefore + not necessary to depend on packages providing FreeDesktop menu + systems. </p> <p> - 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. + + <list> + <item> + 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 + <em>hicolor</em> icon theme directories, or to use an existing + icon from the <em>hicolor</em> theme. + </item> + + <item> + If the menu entry is not useful in the general case as a + standalone application, the desktop entry should set the + <tt>NoDisplay</tt> key to <var>true</var>, so that it can be + configured to be displayed only by those who need it. + </item> + + <item> + In doubt, the package maintainer should coordinate with the + maintainers of menu implementations through the + <em>debian-desktop</em> 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 <tt>NotShowIn</tt>/<tt>OnlyShowIn</tt> keys should be + validated by the maintainers of the relevant environments. + </item> + </list> </p> <p> - The menu policy can be found in the <tt>menu-policy</tt> - files in the <tt>debian-policy</tt> package. - It is also available from the Debian web mirrors at - <tt><url name="/doc/packaging-manuals/menu-policy/" - id="http://www.debian.org/doc/packaging-manuals/menu-policy/";></tt>. + 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. </p> - <p> - Please also refer to the <em>Debian Menu System</em> - documentation that comes with the <package>menu</package> - package for information about how to register your - applications. + <p> + Packages can, to be compatible with Debian additions to some window + managers that do not support the FreeDesktop standard, also provide a + <em>Debian menu</em> file, following the <em>Debian menu policy</em>, + which can be found in the <tt>menu-policy</tt> files in the + <tt>debian-policy</tt> package. It is also available from the Debian + web mirrors at <tt><url name="/doc/packaging-manuals/menu-policy/" + id="http://www.debian.org/doc/packaging-manuals/menu-policy/";></tt>. </p> </sect> @@ -8093,42 +8130,109 @@ Reloading <var>description</var> configuration...done. <heading>Multimedia handlers</heading> <p> - 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. <tt>image/png</tt>, <tt>text/html</tt>, + <tt>audio/ogg</tt>). </p> <p> - 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. </p> <p> - Packages which provide programs to view/show/play, compose, edit or - print MIME types should register them as such by placing a file in - <manref name="mailcap" section="5"> format (RFC 1524) in the directory - <file>/usr/lib/mime/packages/</file>. 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 <em>mailcap</em> system is found on a + large number of Unix systems. The <em>FreeDesktop</em> 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. </p> - <p> - The <package>mime-support</package> package provides the - <prgn>update-mime</prgn> program, which integrates these - registrations in the <file>/etc/mailcap</file> file, using dpkg - triggers<footnote> - Creating, modifying or removing a file in - <file>/usr/lib/mime/packages/</file> using maintainer scripts will - not activate the trigger. In that case, it can be done by calling - <tt>dpkg-trigger --no-await /usr/lib/mime/packages</tt> from - the maintainer script after creating, modifying, or removing - the file. - </footnote>. - Packages using this facility <em>should not</em> depend on, - recommend, or suggest <prgn>mime-support</prgn>. - </p> + <sect1 id="media-types-freedesktop"> + <heading>Registration of media type handlers with desktop entries</heading> + + <p> + 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 <tt>MimeType</tt> key of the application's + <qref id="menus">desktop entry</qref>. For URI schemes, + the relevant MIME types are <tt>x-scheme-handler/*</tt> (e.g. + <tt>x-scheme-handler/https</tt>). + </p> + </sect1> + + <sect1 id="mailcap"> + <heading>Registration of media type handlers with mailcap entries</heading> + + <p> + Packages that are not using desktop entries for registration should + install a file in <manref name="mailcap" section="5"> format (RFC + 1524) in the directory <file>/usr/lib/mime/packages/</file>. The + file name should be the binary package's name. + </p> + + <p> + The <package>mime-support</package> package provides the + <prgn>update-mime</prgn> program, which integrates these + registrations in the <file>/etc/mailcap</file> file, using dpkg + triggers<footnote> + Creating, modifying or removing a file in + <file>/usr/lib/mime/packages/</file> using maintainer scripts will + not activate the trigger. In that case, it can be done by calling + <tt>dpkg-trigger --no-await /usr/lib/mime/packages</tt> from + the maintainer script after creating, modifying, or removing + the file. + </footnote>. + + <p> + Packages installing desktop entries should not install mailcap + entries for the same program, because the + <package>mime-support</package> package already reads desktop + entries. + </p> + + <p> + Packages using these facilities <em>should not</em> depend on, + recommend, or suggest <prgn>mime-support</prgn>. + </p> + </sect1> + + <sect1 id="file-media-type"> + <heading>Providing media types to files</heading> + + <p> + The media type of a file is discovered by inspecting the file's + extension or its <manref name="magic" section="5"> pattern, and + interrogating a database associating them with media types. + </p> + + <p> + 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 + <url id="http://www.iana.org/assignments/media-types";> and RFC 6838 + for details. This information will then propagate to the systems + discovering file media types in Debian, provided by the + <package>shared-mime-info</package>, + <package>mime-support</package> and <package>file</package> + packages. If registration and propagation can not be waited for, + support can be asked to the maintainers of the packages mentioned + above. + </p> + + <p> + For files that are produced and read by a single application, it + is also possible to declare this association to the + <em>Shared MIME Info</em> system by installing in the directory + <file>/usr/share/mime/packages</file> a file in the XML format + specified at <url id="http://standards.freedesktop.org/shared-mime-info-spec/latest/";>. + </p> + </sect1> </sect> <sect> -- 2.6.2
