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