Bug#707851: Soften the the wording recommending menu files: let's do it in Jessie.
Charles Plessy
plessy at debian.org
Sun Jan 5 05:53:12 UTC 2014
Dear all,
Based on Josselin's contribution and the comments of Russ, I have written
a patch for the Debian Policy, that documents the use of the FreeDesktop
standards for the use of Desktop menus and media types (MIME).
First of all, about the core of Sune's request to “soften the the wording
recommending menu files”, in the current policy, it is already a should. To
make this one softer would be to turn it completely optional at the
maintainer's discretion, which does not make sense for a menu that aims at
being comprehensive. Therefore, I propose to another way to “soften” the
situation by writing, in the section on the Debian menu system, that it is
superseded by the FreeDesktop menu system in GNOME and KDE.
Here is how the Policy looks after the patch is applied. I have indicated with
comments signs the parts that do not change significantly, and added numbers in
the margin for my comments that follow the text.
9.6. Menus
----------
Two menu systems are used in Debian: the _FreeDesktop menu_ and the
1 _Debian menu system_. Packages shipping applications that belong to
one or both menu systems should provide the necessary entry files to
integrate with them.
9.6.1. The FreeDesktop menu
---------------------------
The FreeDesktop menu is a cross-distribution standard menu that is
available in a large number of desktop environment including _GNOME_,
_KDE_ or _Xfce_. Applications are registered through text files
called _desktop entries_. Their format is described in the _Desktop
Entry Specification_ at
http://standards.freedesktop.org/desktop-entry-spec/latest/ and
complementary information can be found in the _Desktop Menu
Specification_ at http://standards.freedesktop.org/menu-spec/latest/.
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.
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
22x22 size, and preferably up to 64x64. The icon should be
neutral enough to ingrate 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.
Since the FreeDesktop menu is a cross-distribution standard, the
2 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.
9.6.2. The Debian menu system
-----------------------------
The Debian menu unifies the menu systems of window managers. In some
desktop environments such as _GNOME_ and _KDE_, it has been superseded
by the FreeDesktop menu and is hidden by default.
# 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').
# 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'.
# Menu entries should follow the current menu policy.
# 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 `/doc/packaging-manuals/menu-policy/
# (http://www.debian.org/doc/packaging-manuals/menu-policy/)'.
# Please also refer to the _Debian Menu System_ documentation that comes
# with the `menu' package for information about how to register your
# applications.
9.7. Multimedia handlers
------------------------
Media types (formerly known as MIME types, Multipurpose Internet Mail
3 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 media type handlers allows programs like mail user
# agents and web browsers to invoke these handlers to view, edit or
# display media types they don't support directly.
Packages which provide programs to view/show/play, compose, edit or
print media types should register them using either the _FreeDesktop_
system or the _mailcap_ system.
9.7.1. 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').
9.7.2. Registration of media type handlers with mailcap entries
---------------------------------------------------------------
Packages that are not using desktop entries for registration should
install a file in mailcap(5) 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.
# Footnote: 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'.
9.7.3. Providing media types to files
-------------------------------------
The media type of a file is discovered by inspecting the file's
extension or its magic(5) 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
4 to the IANA (Internet Assigned Numbers Authority). See
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 `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
http://standards.freedesktop.org/shared-mime-info-spec/latest/.
Here are my comments:
1: I think that it is fair to ask to support entries in both menu systems as
long as there is a real demand (that is: no political bullying), and ideally
contribution via patches. Also, if I understand well, the KDE team has a
converter that can be used at package build time.
2: One may wonder if this belongs to the Policy, but I would argue that it is
a minor bug to keep the burden of maintaining a file that will be better
maintained upstream.
3: I replaced “MIME” by “media types” since it is the current terminology. I
also made the minor change to replace the mp3 example with ogg.
4: The IANA's procedures and website have positively evolved last year, and now
there are even machine-readable lists of media types available for download.
I think that we should encourage registration instead of sending requests
downstream (for instance to FreeDesktop's shared-mime-info database).
First of all, thank you for reading so far. I would welcome constructive
comments on the patch attached. By constructive I mean focused (please quote
the parts you comment), backed by explanations and, in case of strong
objections, some background about what are the stakes of the commenter in the
maintenance or use of menu systems and media types.
Have a nice day,
--
Charles Plessy
Tsurumi, Kanagawa, Japan
More information about the pkg-gnome-maintainers
mailing list