Extending the Desktop Entry spec for static app actions

[Giovanni Campagna]

Updated patch. More comments inline...

Il giorno lun, 19/12/2011 alle 16.54 +0100, Vincent Untz ha scritto:
> Hi,
> 
> Le dimanche 18 décembre 2011, à 22:57 +0100, Giovanni Campagna a écrit :
>[...]
>
> I suggest this:
>  Identifiers for application actions. This can be used to tell the
>  application to make a specific action, different from the default
>  behavior. The <xref linkend="extra-actions">Application actions</>
>  section describes how actions work.

Included.

> [...]
> 
> >    </sect1>
> > +  <sect1 id="extra-actions">
> > +    <title>Additional applications actions</title>
> > +    <para>
> > +      Desktop entries of type Application can optionally include one or more
> > +      actions. This represent additional ways to invoke the particular
> > +      application; it is expected that application launchers will expose them
> > +      in some way (for example, as a submenu) within the context of the application,
> > +      to build so called "Quicklists" or "Jumplists".
> 
> 
> I suggest this:
>  Desktop entries of type Application can include one or more actions. An
>  action represents an additional way to invoke the application.
>  Application launchers should expose them to the user (for example, as a
>  submenu) within the context of the application. This is used to build
>  so called "Quicklists" or "Jumplists".

Included

> > +    </para>
> > +    <para>
> > +      Each action must be accompained with an "action group", that is a group
> > +      called <varname>[Desktop Action %s]</varname>, where %s is replaced by an
> > +      action ID (as specified by the Actions key). Action groups not included in
> > +      the Actions key must be ignored by the implementation.
> 
> I suggest this:
>  Each action 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.
> 
>  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.

Included.

> > +    </para>
> > +    <para>
> > +      Identifiers must be composed only of lowercase alphabetic characters
> > +      from the ASCII set, plus underscore and minus. Some implementations may
> 
> Hrm, why not use A-Za-z0-9- like for key names? Also the example
> (fooview) use some uppercase characters.

Ok, changed to use same rules as keys, and merged with previous
paragraph.

> > +      give special meanings to some identifiers (for example, replacing a
> > +      default new window action with a shortcut idenfied by new-window),
> > +      though this is not required.
> 
> Hrm, we should either not mention this at all or reserve some action
> identifier (like new-window). Else, this is a bit confusing.

I see, removed (though I liked the idea to remove the standard "New
window" item we place in gnome-shell when the application had a
new-window action).

> > +    </para>
> > +    <para>
> > +      The following keys are supported within each action group. The absence of
> > +      a REQUIRED key within a group makes the group invalid but does not affect
> > +      the validity of the overall desktop entry. Other than that, the usual
> > +      rules on extensibility apply.
> 
> I suggest this:
>  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.
> 
> There's no need to talk about extensibility here, there's a whole
> paragraph later.

Fine, included.

> > +    </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. There is no provision
> > +	      for Comment or GenericName, as it is expected that this is always shown
> > +	      in the context of a specific application (that is, as a submenu of a
> > +	      launcher) and therefore only need to be unambiguous within one app.
> 
> I don't think we need to mention Comment/GenericName here. But saying
> something like "Action names for an application should not be ambiguous
> between each other."

I hope I clarified what should and should not be in the action name (and
corrected the example).

> > +	    </entry>
> > +	    <entry>localestring</entry>
> > +	    <entry>YES</entry>
> > +	  </row>
> > +	  <row>
> > +	    <entry id="key-action-group-exec"><varname>Exec</varname></entry>
> > +	    <entry>
> > +	      A string to be interpreted as [Desktop Entry]/Exec, including macro
> > +	      expansion and PATH resolution. This is only way to activate the
> 
> I suggest this:
>  Program to execute for this action, possibly with arguments. See <xref
>  linkend="XXX">the Exec key</xref> for details on how this key works.

Ok, included.

> > +	      action as of current version of the specification and therefore
> > +	      it's required; future version may account for different mechanisms
> > +	      (like activation by a DBus call) and make this optional.
> 
> I don't think we need to write this in the spec. (And I'm not sure it'd
> be okay to change from requires to optional, but that's another topic to
> discuss once different mechanism are added)

Fine, removed.

> > +	    </entry>
> > +	    <entry>string</entry>
> > +	    <entry>YES</entry>
> > +	  </row>
> > +	  <row>
> > +	    <entry id="key-action-group-icon"><varname>Icon</varname></entry>
> > +	    <entry>
> > +	      A string to be interpreted as [Desktop Entry]/Icon, that is,
> > +	      according to the icon theme. Implementations may choose to ignore it.
> 
> Maybe rewrite to be a bit closer to the [Desktop Entry]/Icon
> description?

Now it's mostly the same, hope it's clear enough.

> > +	    </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. OnlyShowIn/NotShowIn for the whole entry
> > +	      take precedence over these.
> 
> Hrm, why would a general OnlyShowIn/NotShowIn take precedence over
> these? It feels more natural to me that both should be respected. For
> instance:
> 
> [Desktop Entry]
> NotShowIn=KDE;
> Actions=foo;
> 
> [Desktop Action foo]
> OnlyShowIn=GNOME;
> 
> This allows me to hide the app in KDE, and only show the action in GNOME
> (and not in Unity, or XFCE).

That was the idea, except that saying "OnlyShowIn=GNOME" for the app and
"OnlyShowIn=KDE" for the action would hide the action. This seems
probably obvious, but you never know. In any case, I reworded this
description.

> > +	    </entry>
> > +	    <entry>string(s)</entry>
> > +	    <entry>NO</entry>
> > +	  </row>
> > +	</tbody>
> > +      </tgroup>
> > +    </table>
> > +    <para>
> > +      It is still perfectly legal for any consumer of this specification to
> > +      ignore secondary actions, so the primary way to invoke the application
> > +      should be through the main Exec line, as well as the primary Name and
> > +      Icon.
> 
> This should be mentioned earlier, and I'd rewrite this way:
>  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.

Included, but I kept the advice for applications, just in case.

> > +    </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 should only include actions that make sense as general launchers.
> 
> I'd move this in the first paragraph of this section, and replace should
> with must.

Ok.

> > +    </para>
> > +    <para>
> > +      Additionally, the current version of the specification does not include
> > +      any provision to check that the application is actually running when
> > +      these additional actions are invoked or shown, or to associate these
> > +      actions with a mime type, different or the same as the primary MimeType
> > +      associated with the application. A future version may be extended to
> > +      handled these cases too.
> 
> Keep this out of the spec :-) It's good to know, but I don't think we
> need to write this here.

Ok.

> > +    </para>
> > +  </sect1>
> >    <sect1 id="extending">
> >      <title>Extending the format</title>
> >      <para>
> > @@ -880,9 +998,19 @@ TryExec=fooview
> >  Exec=fooview %F
> >  Icon=fooview
> >  MimeType=image/x-foo;
> > +Actions=Inverse;Edit;
> >  X-KDE-Library=libfooview
> >  X-KDE-FactoryName=fooviewfactory
> > -X-KDE-ServiceType=FooService</programlisting>
> > +X-KDE-ServiceType=FooService
> > +
> > +[Desktop Action Inverse]
> > +Exec=fooview --inverse %f
> > +Name=Foo Viewer (inverse image)
> > +
> > +[Desktop Action Edit]
> > +Exec=fooview --edit %f
> > +Name=Foo Viewer (edit image)
> > +Icon=fooview-edit.png</programlisting>
> 
> Please remove the extension from Icon ;-)
> 
> Also, I'd choose two actions that would make sense even if no file is
> passed as argument (fooview --inverse sounds completely useless without
> a file).

I went with Gallery and Create. Hope they'll be better.
Also, I removed the X-KDE stuff.

Giovanni
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0001-desktop-entry-spec-restore-support-for-Desktop-Actio.patch
Type: text/x-patch
Size: 6867 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/xdg/attachments/20111219/641e557a/attachment.bin>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 316 bytes
Desc: This is a digitally signed message part
URL: <http://lists.freedesktop.org/archives/xdg/attachments/20111219/641e557a/attachment.pgp>