Spec draft (was Re: Rework of the org.freedesktop.ScreenSaver API?)

[Simon McVittie]

On 21/12/12 15:16, Bastien Nocera wrote:
> So this is what I ended up with:
> http://people.freedesktop.org/~hadess/idle-inhibition-spec/

> Idle inhibition is achieved by ... calling an Inhibit function ... on
> a well-known D-Bus name.

s/function/method/ - D-Bus doesn't have functions.

It seems pretty strange that the "API documentation" chapter is so vague
- you have to read the "API reference" to know what's actually going on.
Rename to "API overview" maybe, and/or add more hyperlinks?

> API notes

"Design notes" or "Rationale"?

> org.freedesktop.ScreenSaver — The Idle Inhibition Service manages the
> inhibition requests.

There's nothing here to say that the process with the o.f.S well-known
name must implement the o.f.S interface. There's also nothing here to
say which object-path in that process must have that interface. By
inspecting the GNOME implementation, it appears to be
/org/freedesktop/ScreenSaver.

I suggest re-wording to:

    The Idle Inhibition service manages inhibition requests.
    Implementations of this well-known bus name must have an object
    /org/freedesktop/ScreenSaver which implements the
    _org.freedesktop.ScreenSaver_ interface.

where _..._ is a hyperlink.

Oswald wrote:
> the spec is ridiculously over-structured for its contents.

I think it would seem less ridiculous if it was (only) published as a
single HTML page with the same content, which I think is just a matter
of using different XSLT? The single page / multi-page split can happen
if it grows more methods later.

   S