Re: Bug#707851: Soften the the wording recommending menu files: let's do it in Jessie.
Le Sun, Jan 05, 2014 at 02:53:12PM +0900, Charles Plessy a écrit :
>
> patch attached.
Oops, here it is attached for real. Sorry for the noise !
--
Charles
diff --git a/policy.sgml b/policy.sgml
index dad8d23..1f0a006 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -8054,81 +8054,224 @@ 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>).
+ Two menu systems are used in Debian: the <em>FreeDesktop menu</em>
+ and the <em>Debian menu system</em>. Packages shipping applications
+ that belong to one or both menu systems should provide the necessary
+ entry files to integrate with them.
</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>.
- </p>
+ <sect1 id="freedesktop-menu">
+ <heading>The FreeDesktop menu</heading>
- <p>
- Menu entries should follow the current menu policy.
- </p>
+ <p>
+ The FreeDesktop menu is a cross-distribution standard menu that
+ is available in a large number of desktop environment including
+ <em>GNOME</em>, <em>KDE</em> or <em>Xfce</em>. Applications are
+ registered through 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>
- 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>.
- </p>
+ <p>
+ 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>
- 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>
+ <p>
+ 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 ingrate 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>
+ 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>
+ </sect1>
+
+ <sect1 id="debian-menu">
+ <heading>The Debian menu system</heading>
+
+ <p>
+ The Debian menu unifies the menu systems of window managers. In
+ some desktop environments such as <em>GNOME</em> and <em>KDE</em>,
+ it has been superseded by the FreeDesktop menu and is hidden by
+ default.
+ </p>
+
+ <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>).
+ </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>.
+ </p>
+
+ <p>
+ Menu entries should follow the current menu policy.
+ </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>.
+ </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>
+ </sect1>
</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.
- </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>.
+ print media types should register them using either the
+ <em>FreeDesktop</em> system or the <em>mailcap</em> system.
</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="freedesktop-menu">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>
Reply to: