[PATCH weston 10/17] xdg-shell: Clarify the meaning of app ID and give example

[Bryce Harrington]

On Tue, Apr 07, 2015 at 05:01:25PM +0800, Jonas Ådahl wrote:
> Signed-off-by: Jonas Ådahl <jadahl at gmail.com>
> ---
>  protocol/xdg-shell.xml | 12 ++++++++++++
>  1 file changed, 12 insertions(+)
> 
> diff --git a/protocol/xdg-shell.xml b/protocol/xdg-shell.xml
> index 3db76ab..c2e1443 100644
> --- a/protocol/xdg-shell.xml
> +++ b/protocol/xdg-shell.xml
> @@ -197,6 +197,18 @@
>  	the surface belongs. The compositor can use this to group multiple
>  	surfaces together, or to determine how to launch a new application.
>  
> +	When applicable, a client should set the app ID to the basename of the
> +	.desktop file associated with the application, for example
> +	"org.freedesktop.FooViewer" where the .desktop file is
> +	"org.freedesktop.FooViewer.desktop".
> +
> +	For D-Bus activatble applications, this will also be D-Bus service

typo

Also:  'be *the* D-Bus service'

> +	name used for activation of the application.

Does D-Bus depend on having the service name constructed to match the
.desktop file name?  If not, perhaps this paragraph should be moved
ahead of the prior one.  I'm guessing the intention is that we're trying
to say that the D-Bus service name will be the same as the app ID.

"used for activation of the application" sounds redundant.

> +	It is not a hard requirement to specify a well formed (as described
> +	above) app ID, but the compositor shell may group the surface
> +	inadequately if the client fail to do so.

s/fail/fails/

The way this is written it sounds like a requirement, that's optional,
but has weird side effects if you don't follow it.  So it's a bit
ambiguous whether you really do need to follow it or not.
You might want to elaborate a bit on the implications of not having
things grouped properly, so it's clear what the trade-off is.

It might help if it was expressed as optional, but with extra features
if you follow it.  Maybe something like:

    The app ID identifies the general class of applications to which                            
    the surface belongs. The compositor can use this to group multiple                          
    applications together, or to determine how to launch a new                                  
    application.                                                                                

    For D-Bus activatable applications, the app ID is used as the D-Bus
    service name.

    The compositor shell will try to group application surfaces together
    by their app ID.  As a best practice, it is suggested to select app
    ID's that match the basename of the application's .desktop file.
    For example, "org.freedesktop.FooViewer" where the .desktop file is
    "org.freedesktop.FooViewer.desktop".
                                                                                                
    See the desktop-entry specification [0] for more details on                                 
    application identifiers and how they relate to well-known DBus                              
    names and .desktop files.


>  	See the desktop-entry specification [0] for more details on
>  	application identifiers and how they relate to well-known D-Bus
>  	names and .desktop files.
> -- 
> 2.1.4
> 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel