[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Bug#707851: Debian Menu Systems : Implementation of the TC decision

Le Tue, Sep 29, 2015 at 09:24:20AM +0200, Didier 'OdyX' Raboud a écrit :
> 
> For what I'm concerned, at least for the "cherry-picking" part of the TC 
> decision, please go ahead.

Commited and pushed!

I attached a consolidated patch that summarises the changes.

Cheers,

-- 
Charles Plessy
Tsurumi, Kanagawa, Japan

diff --git a/debian/changelog b/debian/changelog
index d48eac8..d3ddfe7 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -31,6 +31,14 @@ debian-policy (3.9.7.0) unstable; urgency=low
     Seconded: Bill Allombert <ballombe@debian.org>
     Seconded: Charles Plessy <plessy@debian.org>
     Closes: #106073
+  * Policy, as per decision of the Technical Committee:
+    [9.6] Document the FreeDesktop menu entries.  Packages providing a .desktop
+    file must not also provide a .menu file for the same application.
+    [9.7] Document the FreeDesktop media type declarations.
+    See: <https://lists.debian.org/debian-devel-announce/2015/09/msg00000.html>
+    Wording: Charles Plessy <plessy@debian.org>
+    Wording: Didier 'OdyX' Raboud <odyx@debian.org>
+    Closes: #707851
 
  -- Bill Allombert <ballombe@debian.org>  Fri, 08 May 2015 15:10:02 +0200
 
diff --git a/policy.sgml b/policy.sgml
index 404dc73..40f9f3f 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -8130,81 +8130,189 @@ 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&times;22 size, and preferably up to 64&times;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>
+	  Applications that are <em>not</em> registered in the desktop menu can optionally 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>
+
+        <p>
+          Applications that are registred in the desktop menu must not also
+          provide a <em>Debian menu</em> file for the same application.
+        </p>
       </sect>
 
       <sect id="mime">
 	<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>
diff --git a/upgrading-checklist.sgml b/upgrading-checklist.sgml
index ebb17fc..7db0197 100644
--- a/upgrading-checklist.sgml
+++ b/upgrading-checklist.sgml
@@ -59,6 +59,24 @@ Released xxx, 2015.
   <item> recommend to ship additional documentation for package
   <prgn>pkg</prgn> in a separate package <prgn>pkg-doc</prgn> and install it
   into <file>/usr/share/doc/pkg</file>.
+  </item>
+<tag>9.6</tag>
+  <item>The requirements for the <em>FreeDesktop menu entries</em> are now
+  documented, in particular regarding the icon size and format, when to display
+  the entry, and where to coordinate the integration of the entries in menus of
+  specific desktop systems.
+  </item>
+<tag>9.6</tag>
+  <item> Packages providing a .desktop file must not also provide a .menu file
+  for the same application.
+  </item>
+<tag>9.7</tag>
+  <item>Packages already shipping <em>FreeDesktop menu entries</em> should use
+  them to associate applications with media types.  Only in the absence of
+  desktop entries, a file in <em>mailcap</em> format should be used.
+  Associations between media types and files should be done via upstream
+  databases, nevertheless it is also possible to register these associations
+  directly in Debian if needed.
   </item> </taglist></p>
 
 <sect id="3.9.6.0"> Version 3.9.6.0
Reply to: