On lun, 2006-08-07 at 19:35 -0700, Bastian, Waldo wrote:
> I would like to declare the Desktop Entry Spec to be "1.0" after
> proposing and including changes related to the following issues that
> have been brought up on this list:
>
> http://lists.freedesktop.org/archives/xdg/2006-April/008012.html
> http://lists.freedesktop.org/archives/xdg/2006-June/008248.html
> http://lists.freedesktop.org/archives/xdg/2006-May/008132.html
> http://lists.freedesktop.org/archives/xdg/2006-April/008090.html
>
> I will propose patches to the spec for review for these issues over the
> course of this week. If there are additional issues that should be
> clarified before the "1.0" release, please speak up now. Goal of the 1.0
> spec is to reflect existing practice by current implementations.
Here are some patches:
+ sortorder.diff: deprecate the SortOrder key
+ filepattern.diff: deprecate the FilePattern key
+ unique.diff: explicitly forbid keys/groups with the same name
+ versionkey.diff: make the Version key a string since it's really
not an integer. But specify its format.
+ regexp.diff: specify that regexps are POSIX 1003.2 extended
+ fixexample.diff: fix the example to contain an Actions key and
use a valid MimeType value
+ mime.diff: wording fixes. Also comments the "Caching MIME Types" and
the "Priority of MIME Types and desktop files" subsections. Not sure
this is okay, but I do not feel this should be part of this spec.
+ icon-theme-spec.diff: link to the icon theme spec for the Icon key.
I wonder if we should also explicitly tell that there shouldn't be
any extension in the value (eg: start-here and not start-here.png)
+ actions.diff: proposed explanation of how Actions work
This needs some proofreading, and consensus ;-)
The only remaining stuff that I'd like to do is verify the usage of
must/should/may/might/etc. and deprececate or move to the KDE specific
appendix the FSDevice type.
Vincent
--
Les gens heureux ne sont pas pressés.
Index: desktop-entry-spec/desktop-entry-spec.xml
===================================================================
--- desktop-entry-spec.orig/desktop-entry-spec.xml 2006-08-08 13:19:26.000000000 +0200
+++ desktop-entry-spec/desktop-entry-spec.xml 2006-08-08 13:19:35.000000000 +0200
@@ -511,7 +511,7 @@
<row>
<entry id="key-actions"><varname>Actions</varname></entry>
<entry>
- Additional actions possible, see MIME type discussion in <xref linkend="mime-types"/>.
+ Additional action(s) possible, see <xref linkend="actions"/>.
</entry>
<entry>string(s)</entry>
<entry>NO</entry>
@@ -827,6 +827,30 @@
</sect2>
-->
</sect1>
+ <sect1 id="actions">
+ <title>Actions</title>
+ <para>
+ Actions specify alternative ways to launch an application.
+ </para>
+ <para>
+ For each action name <varname>ActionName</varname> defined in the
+ <literal>Actions</literal> key, an associated group named
+ <varname>Desktop Action ActionName</varname> must exist in the desktop
+ entry file. This group must contain the alternative command in a
+ <literal>Exec</literal> key and can contain the following keys that will
+ be used to represent this action: <literal>Name</literal>,
+ <literal>GenericName</literal>, <literal>Comment</literal>,
+ <literal>Icon</literal>.
+ </para>
+ <para>
+ When a <literal>MimeType</literal> key is present, the actions should
+ only be available in a context where files with MIME types listed in the
+ value of the <literal>MimeType</literal> key are available to the
+ implementation. For example, a file manager might allow to use a defined
+ action if the MIME types of the currently selected files are all listed
+ in the value of the <literal>MimeType</literal> key.
+ </para>
+ </sect1>
<sect1 id="extending">
<title>Extending the format</title>
<para>
Index: desktop-entry-spec/desktop-entry-spec.xml
===================================================================
--- desktop-entry-spec.orig/desktop-entry-spec.xml 2006-06-13 14:52:46.000000000 +0200
+++ desktop-entry-spec/desktop-entry-spec.xml 2006-06-13 14:52:56.000000000 +0200
@@ -449,19 +449,6 @@
<entry>1-4</entry>
</row>
<row>
- <entry id="key-filepattern"><varname>FilePattern</varname></entry>
- <entry>
- A list of regular expressions to match against for a
- file manager to determine if this entry's icon should be
- displayed. Usually simply the name of the main
- executable and friends.
- </entry>
- <entry>regexp(s)</entry>
- <entry>NO</entry>
- <entry>NO</entry>
- <entry>1</entry>
- </row>
- <row>
<entry id="key-tryexec"><varname>TryExec</varname></entry>
<entry>
File name of a binary on disk used to determine if the
@@ -977,6 +964,15 @@
</listitem>
<listitem>
<para>
+ The <literal>FilePattern</literal> key is deprecated. It is of type
+ <literal>regexp(s)</literal>. The value is a list of regular
+ expressions to match against for a file manager to determine if this
+ entry's icon should be displayed. Usually simply the name of the main
+ executable and friends.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
Historically some booleans have been represented by the numeric
entries <constant>0</constant> or <constant>1</constant>. With
this version of the standard they are now to be represented as a
Index: desktop-entry-spec/desktop-entry-spec.xml
===================================================================
--- desktop-entry-spec.orig/desktop-entry-spec.xml 2006-06-13 15:27:35.000000000 +0200
+++ desktop-entry-spec/desktop-entry-spec.xml 2006-06-24 15:28:20.000000000 +0200
@@ -858,7 +858,8 @@
TryExec=fooview
Exec=fooview %F
Icon=fooview.png
-MimeType=image/x-foo
+MimeType=image/x-foo;
+Actions=Inverse;Edit;
X-KDE-Library=libfooview
X-KDE-FactoryName=fooviewfactory
X-KDE-ServiceType=FooService
Index: desktop-entry-spec/desktop-entry-spec.xml
===================================================================
--- desktop-entry-spec.orig/desktop-entry-spec.xml 2006-06-24 15:31:39.000000000 +0200
+++ desktop-entry-spec/desktop-entry-spec.xml 2006-08-08 13:19:26.000000000 +0200
@@ -425,9 +425,10 @@
<entry>
Icon to display in file manager, menus, etc. If the
name is an absolute path, the given file will be
- used. If the name is not an absolute path, an
- implementation-dependent search algorithm will be used
- to locate the icon.
+ used. If the name is not an absolute path, the algorithm described
+ in the <ulink
+ url="http://freedesktop.org/wiki/Standards/icon-theme-spec";>Icon
+ Theme Specification</ulink> will be used to locate the icon.
</entry>
<entry>localestring</entry>
<entry>NO</entry>
Index: desktop-entry-spec/desktop-entry-spec.xml
===================================================================
--- desktop-entry-spec.orig/desktop-entry-spec.xml 2006-06-24 15:28:20.000000000 +0200
+++ desktop-entry-spec/desktop-entry-spec.xml 2006-06-24 15:31:39.000000000 +0200
@@ -520,7 +520,7 @@
<row>
<entry id="key-mimetype"><varname>MimeType</varname></entry>
<entry>
- The MIME type(s) supported by this entry.
+ The MIME type(s) supported by this application.
</entry>
<entry>string(s)</entry>
<entry>NO</entry>
@@ -754,18 +754,17 @@
<title>Registering MIME Types</title>
<para>
The <varname>MimeType</varname> key is used to indicate the MIME
- Types that an application knows how to handle. Applications that
- can handle multiple MIME Types would list all of the ones it can
- handle in a ';' separated list, as normal. It is expected that
+ Types that an application knows how to handle. It is expected that
for some applications this list could become long. An application
is expected to be able to reasonably open files of these types
- using the command listed in the <varname>Exec</varname> keyword.
+ using the command listed in the <varname>Exec</varname> key.
</para>
<para>
There should be no priority for MIME Types in this field, or any
form of priority in the desktop file. Priority for applications
is handled external to the <filename>.desktop</filename> files.
</para>
+<!--
<sect2 id="mime-caching">
<title>Caching MIME Types</title>
<para>
@@ -825,6 +824,7 @@
type, as we felt that that cannot work.
</para>
</sect2>
+-->
</sect1>
<sect1 id="extending">
<title>Extending the format</title>
Index: desktop-entry-spec/desktop-entry-spec.xml
===================================================================
--- desktop-entry-spec.orig/desktop-entry-spec.xml 2006-06-13 15:09:12.000000000 +0200
+++ desktop-entry-spec/desktop-entry-spec.xml 2006-06-13 15:27:35.000000000 +0200
@@ -169,6 +169,12 @@
</listitem>
<listitem>
<para>
+ Values of type <literal>regexp</literal> are POSIX 1003.2 extended
+ regular expressions.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
Values of type <literal>boolean</literal> must either be the string
<literal>true</literal> or <literal>false</literal>.
</para>
Index: desktop-entry-spec/desktop-entry-spec.xml
===================================================================
--- desktop-entry-spec.orig/desktop-entry-spec.xml 2006-06-13 14:32:25.000000000 +0200
+++ desktop-entry-spec/desktop-entry-spec.xml 2006-06-13 14:52:46.000000000 +0200
@@ -620,16 +620,6 @@
<entry>NO</entry>
<entry>3</entry>
</row>
- <row>
- <entry id="key-sortorder"><varname>SortOrder</varname></entry>
- <entry>
- This may specify the order in which to display files.
- </entry>
- <entry>string(s)</entry>
- <entry>NO</entry>
- <entry>NO</entry>
- <entry>4</entry>
- </row>
</tbody>
</tgroup>
</table>
@@ -977,6 +967,16 @@
</listitem>
<listitem>
<para>
+ The <literal>SortOrder</literal> key is deprecated. It is of type
+ <literal>string(s)</literal> and may be used to specify the order in
+ which to display files. The <ulink
+ url="http://www.freedesktop.org/Standards/menu-spec";>Desktop
+ Menu Specification</ulink> defines another mechanism for defining the
+ order of menu items.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
Historically some booleans have been represented by the numeric
entries <constant>0</constant> or <constant>1</constant>. With
this version of the standard they are now to be represented as a
Index: desktop-entry-spec/desktop-entry-spec.xml
===================================================================
--- desktop-entry-spec.orig/desktop-entry-spec.xml 2006-06-13 15:04:10.000000000 +0200
+++ desktop-entry-spec/desktop-entry-spec.xml 2006-06-13 15:05:57.000000000 +0200
@@ -105,6 +105,9 @@
<literal>[</literal> and <literal>]</literal> and control characters.
</para>
<para>
+ Multiple groups may not have the same name.
+ </para>
+ <para>
All <literal>{key,value}</literal> pairs following a group header until
a new group header belong to the group.
</para>
@@ -130,12 +133,17 @@
<literal>=</literal> sign is the actual delimiter.
</para>
<para>
- Key names must contain only the characters <literal>A-Za-z0-9-</literal>
+ Key names must contain only the characters
+ <literal>A-Za-z0-9-</literal>.
</para>
<para>
As the case is significant, the keys <varname>Name</varname> and
<varname>NAME</varname> are not equivalent.
</para>
+ <para>
+ Multiple keys in the same group may not have the same name. Two keys in
+ different groups may have the same name.
+ </para>
</sect2>
</sect1>
<sect1 id="value-types">
Index: desktop-entry-spec/desktop-entry-spec.xml
===================================================================
--- desktop-entry-spec.orig/desktop-entry-spec.xml 2006-06-13 15:05:57.000000000 +0200
+++ desktop-entry-spec/desktop-entry-spec.xml 2006-06-13 15:09:12.000000000 +0200
@@ -353,17 +353,20 @@
<row>
<entry id="key-version"><varname>Version</varname></entry>
<entry>
- Version of Desktop Entry Specification
+ Version of Desktop Entry Specification. It is in the following
+ format: <literal>x.y.z</literal>, where <literal>x</literal>,
+ <literal>y</literal> and <literal>z</literal> are unsigned
+ integers.
(While the version field is not required to be present,
it should be in all newer implementations of the Desktop
Entry Specification. If the version number is not
present, a "pre-standard" desktop entry file is to be
assumed).
</entry>
- <entry>numeric</entry>
+ <entry>string</entry>
<entry>NO</entry>
<entry>YES</entry>
- <entry>1-4</entry>
+ <entry>1-4</entry>
</row>
<row>
<entry id="key-name"><varname>Name</varname></entry>
_______________________________________________
xdg mailing list
xdg@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/xdg
