[PATCH] Documentation for the prepare_lock_surface event description, is incorrect

[Bryce Harrington]

On Fri, Jul 10, 2015 at 09:36:45AM +0300, Pekka Paalanen wrote:
> On Thu, 9 Jul 2015 13:46:46 -0400
> Christopher Michael <cpmichael at osg.samsung.com> wrote:
> 
> > Here is an updated patch which changes the wording to match what Giulio 
> > offered.
> > 
> > Documentation for the prepare_lock_surface event description is
> > incorrect. The summary says "Tell the client..." however the full-text
> > description says "tell the shell..."
> > 
> > Signed-off-by: Chris Michael <cp.michael at samsung.com>
> > ---
> >   protocol/desktop-shell.xml | 2 +-
> >   1 file changed, 1 insertion(+), 1 deletion(-)
> > 
> > diff --git a/protocol/desktop-shell.xml b/protocol/desktop-shell.xml
> > index fb0b748..6ec9dfa 100644
> > --- a/protocol/desktop-shell.xml
> > +++ b/protocol/desktop-shell.xml
> > @@ -44,7 +44,7 @@
> > 
> >       <event name="prepare_lock_surface">
> >         <description summary="tell the client to create, set the lock 
> > surface">
> > -	Tell the shell we want it to create and set the lock surface, which is
> > +	Tell the client we want it to create and set the lock surface, which is
> >   	a GUI asking the user to unlock the screen. The lock surface is
> >   	announced with 'set_lock_surface'. Whether or not the shell actually
> >   	implements locking, it MUST send 'unlock' request to let the normal
> 
> Acked-by: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
> but I think you could do even better.
> 
> There's another "shell" in the context here that also refers to the client.
> 
> To be exact, shells currently in Weston have two parts: the plugin, and
> the helper client. The shell helper client is a privileged client that
> alone has access to the desktop-shell.xml protocol.
> 
> "We" in the above excerpt seems to refer to the compositor or the shell
> plugin specifically. I have found using such pronouns in spec language
> to be confusing, as it is not always obvious who "you" or "we" are.
> 
> Maybe this helps you to revise and clarify the whole desktop-shell.xml
> wording?
> 
> However, using the term "plugin" in protocol spec language is not
> really good either, because the shell's compositor side implementation
> may not be a plugin. Libweston is heading this way, eventually
> eliminating shells as plugins and turning them into main executables.
> 
> So, we have the shell helper client and the shell implementation in the
> compositor. I don't have good short terms to suggest for these two
> concepts.

Maybe just keep it simple, as in "shell frontend" and "shell backend"?

Bryce
 
> Thanks,
> pq
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel