Proposing the StatusNotifier specification

[Aaron J. Seigo]

On January 19, 2010, you wrote:
> You say that
> the old systray has been abused, and thus all freedom needs to be taken
> away from the application writers.

when it comes to the end visualization, yes.

also note that it isn't a linear line from "old systray was abused" to 
"freedom removed from apps". there is also the issue that we need/want 
visualizations of this information that does not fit into the system tray 
model at all. to accommodate such developments, removing much of the control 
over the visualization from the applications was required.

> And then you turn around and ask for
> total blanket freedom to be given to the 'visualization' writers,
> because 'they aren't idiots'.

when it comes to the visualization of the data, we assume that the people 
writing those visualizations are moderately capable, yes. (if they aren't, the 
results will be poor, but the user can simply use those same apps with a 
different implementation.)

at the same tie, note that the visualization authors are not given any real 
method to alter the data that the applications publish. in that sense, control 
is still quite firmly in the application's realm.
 
> To give some concrete examples of the kind of missing guidance that is
> needed to make this API useful for application writers:
> 
>    org.freedesktop.StatusNotifierItem.Title
>    STRING org.freedesktop.StatusNotifierItem.Title ();
> 
>    It's a name that describes the application, it can be more
> descriptive than Id.
> 
> 
> Is this supposed to be a single word, a line, a paragraph ? Is it
> supposed to include punctuation, or be capitalized ? Should it be the
> same as the name that appears in the menu ?

i'm not sure how many application titles have punctuation in them and titles 
are by definition capitalized according to locale, but if it is felt that we 
need to spell that out we certainly can do so. in that spirit, how about:

"The title is intended to be user visible, and should be localized. Titles 
should be the same as found in the application's desktop menu entry if that 
exists and should be between one and four words. The title should follow the 
capitalization rules for the current locale of the desktop environment and 
should have no ending punctuation."

if you would like to come up with similar verbage for the various bits of API 
that aren't clear to you, that'd be great. otherwise, you could point out 
where you feel you would be lacking enough direction as an application 
developer and one of us can do the writing for you. we can then arrive at text 
we can agree on.

> Not specifying these things sure makes the spec flexible, but it also
> guarantees that you will get a mix-and-match of different styles, which
> will suck for the overall experience.

agreed; so we should extend the direction in the spec to prevent that.

this doesn't affect API (which is great) and can be added as we go over time 
and therefore shouldn't affect approval in a substantial way.

the xembed spec provided absolutely none of this either (less than in this 
spec, even), so this can be another area of improvement brought to the table. 
which is a good thing.

this is also a lot more rigor than has been brought to virtually any other 
fd.o spec in the last few years, which is also a great thing.

i think we're on the same page when it comes to ensuring the spec is 
understandable and provides enough useful direction to developers. as long as 
we don't over-specify areas that would impede desired implementations of 
visualizations, i don't think we'll end up with much in the way of 
disagreement.

> Unless, as Dan pointed out, you
> rely on everybody copying the one reference implementation in its
> behavior - and then why bother with a spec in the first place ?

that obviously doesn't work because there really isn't "one reference 
implementation" when it comes to the visualization side. which makes the idea 
even more untenable than you and Dan put it. ;)

we've discussed a few different points in this conversation that are related 
but not the same. i think a recap might be useful, and please fill in bits i 
miss if you feel it's worthwhile:

* interaction patterns by the visualization is not defined in the spec; this 
is intentional to allow freedom in how visualizations are implemented and to 
keep it from even being specific to system trays themselves (e.g. task bar / 
dock integration)

* there are some API warts to do with naming, we agree on some of the changes 
(e.g. ServiceRegistered) though there is disagreement on others (e.g. the use 
of the word 'Host' being "incorrect and/or confusing enough" to warrant a 
change in the spec); call this one a 50-50 :) hopefully we can reach some 
explicit compromise on those points before we simply move on and forget we 
didn't come to concrete conclusions

* a "principles and philosophy of the design" section needs to be added to 
give readers enough context to understand the rational for the approach this  
spec embodies. personally, i am not sure that such information belongs in a 
spec at all, but i can certainly understand the benefit of such information 
and am not sure where else it could go where it can most effectively reach the 
audience that needs that contextual information.

* additional guidance is needed for application developers when it comes to 
the data that can be published, particularly in the details such as which 
category should be the fallback/default or how to format a title. more input 
on which areas are ambiguous for app developers is welcome. we'll try to mark 
as many as we can on our own, but your input will help us find them all.

* there are some typos and/or grammar issues that have been pointed out. a 
good proof-reading of the language would be useful and welcome. this shouldn't 
be a blocker to agreement, however. 


the good news is that all of the above is easily addressed and besides the API 
warts doesn't impact the API itself or even the implementations of the spec.

we can also improve the spec over time, so approval doesn't mean it is set in 
stone and "that's that, tough luck in the future!". the important bits are 
really the API as those have the greatest cost to change. augmentation to the 
documentation is cheap, English language fixes/improvements are pretty much 
"free" and both of these can be done not only now but in the future as we 
progress.

Marco (spec maintainer) is at a conference this week and not overly available, 
but the spec is in an open git repository on gitorious (his clone of the xdg-
specs one) so others can work on it in his absence if they so desire.

in any case, here is my suggestion: i'd like to ask that people continue to 
point out issues of ambiguity related to app developer direction. i will 
continue to answer questions as best as i can as they arise (others are 
welcome to join in on the answering as well, of course ;), but please keep the 
questions focused and accompanied with use cases as much as possible as they 
are most helpful to guiding the discussion. refraining from empty rhetoric is 
appreciated.  out of all this, we will come back with a set of updates to the 
spec next week that will fold in the various points raised throughout this 
thread for another round of review and, hopefully, reach consensus.

does that make sense to you?

-- 
Aaron J. Seigo
humru othro a kohnu se
GPG Fingerprint: 8B8B 2209 0C6F 7C47 B1EA  EE75 D6B7 2EB1 A7F1 DB43

KDE core developer sponsored by Qt Development Frameworks