desktop-entry: Improvements to specification of actions

Structure and reorganize the text with subsections, and reword for
clarifications.

Also make the Icon key a localestring, like it is for Desktop Entry.

Add a link to the Exec key section in the description of [Desktop
Entry]/Exec.

1 files changed, 112 insertions, 95 deletions

diff --git a/desktop-entry/desktop-entry-spec.xml b/desktop-entry/desktop-entry-spec.xml
index bb32e10..7d99d0a 100644
--- a/desktop-entry/desktop-entry-spec.xml
+++ b/desktop-entry/desktop-entry-spec.xml
@@ -483,7 +483,9 @@
 	  <row>
 	    <entry id="key-exec"><varname>Exec</varname></entry>
 	    <entry>
-           Program to execute, possibly with arguments.
+           Program to execute, possibly with arguments. See the <link
+           linkend="exec-variables"><varname>Exec</varname> key</link> for
+           details on how this key works.
 	    </entry>
 	    <entry>string</entry>
 	    <entry>YES</entry>
@@ -881,100 +883,115 @@ application/x-bar=bar.desktop;</programlisting>
       submenu) within the context of the application. This is used to build
       so called "Quicklists" or "Jumplists".
     </para>
-    <para>
-      Application actions should be supported by implementors. However, in
-      case they are not supported, implementors can simply ignore the
-      <varname>Actions</varname> key and the associated <varname>Desktop
-      Action</varname> action groups, and keep using the <varname>Desktop
-      Entry</varname> group. Therefore, the primary way to invoke the application
-      should be through the main Exec line, as well as the primary Name and Icon.
-    </para>
-    <para>
-      Also, it is not expected that other desktop components showing app lists
-      (eg. software installers) will provide any UI for these actions, therefore
-      applications must only include actions that make sense as general launchers.
-    </para>
-    <para>
-      Each action action is identified by a string, following the same rules
-      as key names (see <xref linkend="entries"/>). Each identifier is associated
-      with an action group that must be present in the <filename>.desktop</filename>
-      file. The action group is a group named <varname>Desktop Action %s</varname>,
-      where <varname>%s</varname> is the action identifier.
-    </para>
-    <para>
-      It is not valid to have an action group for an action identifier not
-      mentioned in the <varname>Actions</varname> key. Such an action group
-      must be ignored by implementors.
-    </para>
-    <para>
-      The following keys are supported within each action group. If a
-      REQUIRED key is not present in an action group, then the implementor
-      should ignore this action.
-    </para>
-    <table>
-      <title>Action group keys</title>
-      <tgroup cols="5">
-        <thead>
-          <row>
-            <entry>Key</entry>
-            <entry>Description</entry>
-            <entry>Value Type</entry>
-            <entry>REQ?</entry>
-          </row>
-        </thead>
-        <tbody>
-          <row>
-            <entry id="key-action-group-name"><varname>Name</varname></entry>
-            <entry>
-              The label that will be shown to the user. Since actions will be
-              always shown in the context of a specific application (that is, as
-              a submenu of a launcher), this only needs to be unambiguous within
-              one app and should not include the application name.
-            </entry>
-            <entry>localestring</entry>
-            <entry>YES</entry>
-          </row>
-          <row>
-            <entry id="key-action-group-exec"><varname>Exec</varname></entry>
-            <entry>
-              Program to execute for this action, possibly with arguments. See <link
-              linkend="XXX">the Exec key</link> for details on how this key works.
-            </entry>
-            <entry>string</entry>
-            <entry>YES</entry>
-          </row>
-          <row>
-            <entry id="key-action-group-icon"><varname>Icon</varname></entry>
-            <entry>
-              The icon to be shown togheter with the action. If the name is
-              an absolute path, the given file will be 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.
-              A string to be interpreted as [Desktop Entry]/Icon, that is,
-              according to the icon theme. Implementations may choose to ignore it.
-            </entry>
-            <entry>string</entry>
-            <entry>NO</entry>
-          </row>
-          <row>
-            <entry id="key-action-group-osi-nsi">
-              <varname>OnlyShowIn</varname>, <varname>NotShowIn</varname>
-            </entry>
-            <entry>
-              A list of strings to be interpreted according to the <ulink
-              url="http://www.freedesktop.org/Standards/menu-spec">Desktop
-              Menu Specification</ulink>, but affect only the visibility of
-              the specific action. These are to be interpreted in addition to,
-              and not to replace, the keys in the main group with the same
-              name.
-            </entry>
-            <entry>string(s)</entry>
-            <entry>NO</entry>
-          </row>
-        </tbody>
-      </tgroup>
-    </table>
+    <sect2 id="extra-actions-identifier">
+      <title>Action identifier</title>
+      <para>
+        Each action is identified by a string, following the same format
+        as key names (see <xref linkend="entries"/>). Each identifier is associated
+        with an action group that must be present in the <filename>.desktop</filename>
+        file. The action group is a group named <varname>Desktop Action %s</varname>,
+        where <varname>%s</varname> is the action identifier.
+      </para>
+      <para>
+        It is not valid to have an action group for an action identifier not
+        mentioned in the <varname>Actions</varname> key. Such an action group
+        must be ignored by implementors.
+      </para>
+    </sect2>
+    <sect2 id="extra-actions-keys">
+      <title>Action keys</title>
+      <para>
+        The following keys are supported within each action group. If a
+        REQUIRED key is not present in an action group, then the implementor
+        should ignore this action.
+      </para>
+      <table>
+        <title>Action Specific Keys</title>
+        <tgroup cols="5">
+          <thead>
+            <row>
+              <entry>Key</entry>
+              <entry>Description</entry>
+              <entry>Value Type</entry>
+              <entry>REQ?</entry>
+            </row>
+          </thead>
+          <tbody>
+            <row>
+              <entry id="key-action-group-name"><varname>Name</varname></entry>
+              <entry>
+                Label that will be shown to the user. Since actions are
+                always shown in the context of a specific application (that is, as
+                a submenu of a launcher), this only needs to be unambiguous within
+                one application and should not include the application name.
+              </entry>
+              <entry>localestring</entry>
+              <entry>YES</entry>
+            </row>
+            <row>
+              <entry id="key-action-group-icon"><varname>Icon</varname></entry>
+              <entry>
+                Icon to be shown togheter with the action. If the name is
+                an absolute path, the given file will be 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.
+                Implementations may choose to ignore it.
+              </entry>
+              <entry>localestring</entry>
+              <entry>NO</entry>
+            </row>
+            <row>
+              <entry id="key-action-group-osi-nsi">
+                <varname>OnlyShowIn</varname>, <varname>NotShowIn</varname>
+              </entry>
+              <entry>
+                A list of strings identifying the environments that should
+                display/not display this specific action. These keys are to be
+                interpreted in addition to the <varname>OnlyShowIn</varname>
+                and <varname>NotShowIn</varname> keys of the <varname>Desktop
+                Entry</varname> group, and are not replacing them. Only one of
+                these keys, either <varname>OnlyShowIn</varname> or
+                <varname>NotShowIn</varname>, may appear in each action group
+                (for possible values see the <ulink
+                url="http://www.freedesktop.org/Standards/menu-spec">Desktop
+                Menu Specification</ulink>).
+              </entry>
+              <entry>string(s)</entry>
+              <entry>NO</entry>
+            </row>
+            <row>
+              <entry id="key-action-group-exec"><varname>Exec</varname></entry>
+              <entry>
+                Program to execute for this action, possibly with arguments.
+                See the <link linkend="exec-variables"><varname>Exec</varname>
+                key</link> for details on how this key works.
+              </entry>
+              <entry>string</entry>
+              <entry>YES</entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </table>
+    </sect2>
+    <sect2 id="extra-actions-implementation-notes">
+      <title>Implementation notes</title>
+      <para>
+        Application actions should be supported by implementors. However, in
+        case they are not supported, implementors can simply ignore the
+        <varname>Actions</varname> key and the associated <varname>Desktop
+        Action</varname> action groups, and keep using the <varname>Desktop
+        Entry</varname> group: the primary way to describe and invoke the
+        application is through the Name, Icon and Exec keys from the
+        <varname>Desktop Entry</varname> group.
+      </para>
+      <para>
+        It is not expected that other desktop components showing application
+        lists (software installers, for instance) will provide any user
+        interface for these actions. Therefore applications must only include
+        actions that make sense as general launchers.
+      </para>
+    </sect2>
   </sect1>
   <sect1 id="extending">
     <title>Extending the format</title>