[PATCH weston 6/6] Add informal notes file

[Nick Kisialiou]

Kristian,

What do you have in mind as a real documentation? Are you thinking of a
100+ pages user manual? If so, I can envision the following problems with
this route:

(1) Your developers' time is a precious resource. Someone in your team will
have to stop development work to write it.
(2) The longer the documentation, the fewer people will actually have time
to read it.
(3) Wayland protocol is still evolving, so the big documentation will
quickly become outdated.

I don't mean to tell anyone what to do and how to do it. I'm just thinking
of more useful alternatives:

Would it actually be better to host a wiki on
http://www.freedesktop.org/wiki/ and populate it with short articles like
the one posted by Pekka? When an article becomes outdated it can simply be
deleted. And as new additions are made (tablet shell, android,
multi-threading, debugging strategies etc) developers can simply add a
small article to describe the intended protocol or client usage while it is
still fresh in their memory. It seems like it will be easier on developers
and signal-to-noise ratio of such articles is much higher than lengthy user
guides.

There are of course downsides to the wiki: information may be spread
around. But then again, it is easier to assemble a full user guide out
of these articles than it is to write it all from scratch.

Nick




On Thu, Oct 25, 2012 at 12:02 PM, Kristian Høgsberg <hoegsberg at gmail.com>wrote:

> On Wed, Oct 24, 2012 at 09:43:10AM +0300, Pekka Paalanen wrote:
> > By request on the wayland-devel mailing list, we could start collecting
> > useful writings here.
> >
> > However, this is not meant to be a substitute to proper documentation,
> > though I understand it may very well become one. Better than nothing, I
> > guess, and hopefully helps in writing real documentation.
>
> I suppose we can do this, but it becomes hard to manage pretty fast.
> Ideally we'd work this into the documentation instead.  Over time a
> lot of small snippets like this becomes hard to search or make sense of.
>
> This and the previous 5 patches committed.
>
> Kristian
>
> > Feel free to add stuff.
> >
> > Signed-off-by: Pekka Paalanen <ppaalanen at gmail.com>
> > ---
> >  notes.txt |   77
> +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
> >  1 files changed, 77 insertions(+), 0 deletions(-)
> >  create mode 100644 notes.txt
> >
> > diff --git a/notes.txt b/notes.txt
> > new file mode 100644
> > index 0000000..e49052b
> > --- /dev/null
> > +++ b/notes.txt
> > @@ -0,0 +1,77 @@
> > +This file is a collection of informal notes, with references to where
> > +they were originally written. Each note should have a source and date
> > +mentioned. Let's keep these in date order, newest first.
> > +
> > +
> > +
> > +-----------------------------------------------------------------------
> > +2012-10-23; Pekka Paalanen <ppaalanen at gmail.com>
> > +
> http://lists.freedesktop.org/archives/wayland-devel/2012-October/005969.html
> > +
> > +For anyone wanting to port or write their own window manager to Wayland:
> > +
> > +Most likely you have a desktop window manager. A quick way to get
> > +started, is to fork Weston's desktop-shell plugin and start hacking it.
> > +Qt could be another good choice, but I am not familiar with it.
> > +
> > +You also need to understand some concepts. I'm repeating things I wrote
> > +to the wayland-devel list earlier, a little rephrased.
> > +
> > +We need to distinguish three different things here (towards Wayland
> > +clients):
> > +
> > +- compositors (servers)
> > +     All Wayland compositors are indistinguishable by definition,
> > +     since they are Wayland compositors. They only differ in the
> > +     global interfaces they advertise, and for general purpose
> > +     compositors, we should aim to support the same minimum set of
> > +     globals everywhere. For instance, all desktop compositors
> > +     should implement wl_shell. In X, this component corresponds to
> > +     the X server with a built-in compositing manager.
> > +
> > +- shells
> > +     This is a new concept compared to an X stack. A shell defines
> > +     how a user and applications interact. The most familiar is a
> > +     desktop (environment). If KDE, Gnome, and XFCE are desktop
> > +     environments, they all fall under the *same* shell: the desktop
> > +     shell. You can have applications in windows, several visible at
> > +     the same time, you have keyboards and mice, etc.
> > +
> > +     An example of something that is not a desktop shell
> > +     could be a TV user interface. TV is profoundly different:
> > +     usually no mouse, no keyboard, but you have a remote control
> > +     with some buttons. Freely floating windows probably do not make
> > +     sense. You may have picture-in-picture, but usually not several
> > +     applications showing at once. Most importantly, trying to run
> > +     desktop applications here does not work due to the
> > +     incompatible application and user interface paradigms.
> > +
> > +     On protocol level, a shell is the public shell interface(s),
> > +     currently for desktop it is the wl_shell.
> > +
> > +- "window managers"
> > +     The X Window Managers correspond to different wl_shell
> > +     implementations, not different shells, since they pratically
> > +     all deal with a desktop environment. You also want all desktop
> > +     applications to work with all window managers, so you need to
> > +     implement wl_shell anyway.
> > +
> > +I understand there could be special purpose X Window Managers, that
> > +would better correspond to their own shells. These window managers
> > +might not implement e.g. EWMH by the spec.
> > +
> > +When you implement your own window manager, you want to keep the public
> > +desktop shell interface (wl_shell). You can offer new public
> > +interfaces, too, but keep in mind, that someone needs to make
> > +applications use them.
> > +
> > +In Weston, a shell implementation has two parts: a weston plugin, and a
> > +special client. For desktop shell (wl_shell) these are src/shell.c and
> > +clients/desktop-shell.c. The is also a private protocol extension that
> > +these two can explicitly communicate with.
> > +
> > +The plugin does window management, and the client does most of user
> > +interaction: draw backgrounds, panels, buttons, lock screen dialog,
> > +basically everything that is on screen.
> > +
> > +-----------------------------------------------------------------------
> > --
> > 1.7.8.6
> >
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freedesktop.org/archives/wayland-devel/attachments/20121025/3effe282/attachment-0001.html>