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

[Bastien Nocera]

Hey,

Em Wed, 2013-02-13 às 15:18 +0000, Simon McVittie escreveu:
> 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.

Fixed.

> 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?

Renamed.

> > API notes
> 
> "Design notes" or "Rationale"?

Renamed.

> > 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.

Sigh. That'd be because I didn't read the HTML output at all, other than
looking that it did generate, and the input does contain that
information:
$ git grep '<node ' 
org.freedesktop.ScreenSaver.xml:<node name="/org/freedesktop/ScreenSaver">

>  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.

I've put this in the API overview, otherwise this gets pulled in to the
TOC as the label for the link.

> 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.

I haven't figured out how to do that, and after spending 10 minutes
trying to make it output what I wanted, I think it's quite enough work
for the handful of people that will ever be reading this.

Note that I found out (when VLC wasn't actually inhibiting playback)
that KDE doesn't implement the API on the /org/freedesktop/ScreenSaver
but on /ScreenSaver. I've made a mention of that in the spec as well.

Cheers