Actions: grouping vs. extensibility

[Jakob Petsovits]

On Monday, 16. July 2007, Rodney Dawes wrote:
> On Mon, 2007-07-16 at 12:23 +0200, Jakob Petsovits wrote:
> > The spec has a series of document-* icons, like document-new,
> > document-open, document-save, and others. The problem with this approach
> > is that there is no generic fallback if I want to create or open
> > something other than a document, say, a project which consists of
> > multiple documents. The specification in its current form just creates a
> > new "namespace" for the most common items address-book, application,
> > contact, document and window (for the "new" action), but if we want to
> > put something else into kdelibs (bookmark-new, project-new, tab-new)
> > we'll break the spec. Which is bad.
>
> How does foo-new break the spec exactly? The specific action is the more
> specific part here.

Having icons like project-new breaks the spec in the way that
1. We'll provide, say, project-new in kdelibs.
2. KDE applications make use of that icon.
3. A user chooses an icon theme that only contains specified icons.
4. Bam! Instead of a sensible fallback, you get the icon in kdelibs.

The reason that I want KDE to follow the naming specification is so that 
themes which don't care about KDE at all work great with KDE applications 
nevertheless.

We can of course add a whole new bunch of new base namespaces, but those are 
not in the spec, and thus can't be expected to be present. Moreover, not all 
the icons that we require need to be present in the spec, or are appropriate 
for inclusion at all. All I want for those icons is that they can be left out 
by the respective theme and the application falls back to the next 
appropriate specified icon in grace.

So, I can see three possibilities:

a) The spec provides all icons that we possibly need.
   I'd be fine with that, but you and Jakub already made clear that the spec
   is supposed to provide a minimal set of icons rather than a comprehensive
   one. So that possibility has no chance for realization, and that's ok.

b) The spec provides proper fallbacks so that we can add more specific icons
   in a safe way. Given the fact that a) doesn't apply, I assumed that this
   must be a major goal of the spec. If it's not, c) applies.

c) We add icons to kdelibs that conform to the naming scheme of the spec,
  (e.g. project-new) but are not listed in the spec. project-open cannot fall
  back to a generic open but instead uses the Oxygen icon which is likely
  out of place in the given current theme. document-close, window-close
  and project-close will probably be exact copies of the same icon.
  Icon theme designers have no choice but to implement KDE icons in addition
  to the spec, and if they don't, we're screwed in cross-desktop
  compatibility for no good reason. Imho.

> > Therefore, I demand that the spec is changed as follows:
>
> Demand is such a rude word. Suggestions, constructive criticism, etc...
> are welcome, but demands are not.

Hm, you're right. I'm sorry for the improper wording, it negatively affects 
the basis for the conversation in a way that I didn't intend. (If you don't 
mind, I'll use my non-native-speaker status as a bad excuse here.) "Request", 
as proposed by Aaron, would have really been the right word instead.

> > * Add a "new" icon
> >   "The icon for the create action."
> >
> > * Add a "close" icon
> >   "The icon for the close action."
>
> What will the metaphor be?

Repeating Aaron for completeness, "probably an "x" for close and 
page-with-star for new or something along those lines."
I think that's pretty much it, and has so far worked sufficiently for most,
if not all, instances of where those icons have been required.

> How will these icons relate to all formats? 

"new", as a generic icon that's probably very similar to document-new, will be 
used to indicate that *something* is created by selecting this action.
By overriding the generic icon with something like new-podcast, applications 
can have more specific versions of "new" while still having a sensible 
fallback. That was the idea of the 'levels of specificity' stuff, right?

> > * Remove the "document-" prefix
> >   from the open, open-recent, save and save-as actions
>
> You're misinterpreting the term document here, to mean "files formatted
> for print that primarily contain text," which is incorrect. All of the
> files a user can view/edit/play/etc... are documents.

If you assume that everything that needs to be saved is a single file, yes.
Projects consist of multiple documents, thus a project should not be marked as 
a more specific for of a document, because it's a document container instead.

Settings are also not documents. They can be stored in databases, INI files, 
whatever. In any case, they are not documents in the way that the user 
opens/saves/views/edits them.

And here's the crux of the matter: there is a generic save action, but the 
specification limits it to documents. Sure, documents are the most common 
instance of stuff that needs to be opened or saved, and probably you won't 
ever find more than those three examples (documents, projects, settings) for 
saving stuff, but isn't it all the same action in the end? Why does the same 
action need to be in three different namespaces if it's only one action in 
principle? It does apply to all of those examples, thus I don't see why it 
should specifically be a member of document.

> > * Add an "edit" icon
> >   "The icon for the edit action."
>
> What exactly would this be? Why do we need it? All of the icons under
> edit-* are for things that normally appear in the "Edit" menu of an app.

Please, do have a look at the use cases that I provided in my original mail. 
In general, this would be the action for editing any app specific items, 
which will likely open up some editing dialog.

I'm open for a better base name, but there needs to be some generic edit 
action. "Edit Contact..." in KAddressBook is in the "File" menu, while
"Edit Bookmarks" in Konqueror is in the "Bookmarks" menu, and
edit-preferences is in the "Edit" menu in GNOME apps and in the "Settings" 
menu in KDE apps.

Good luck with sorting actions by menu if they are not totally the same 
everywhere already ;)

Suggestions for a better name than "edit"? I suggested that one because that's 
exactly what the action does, it provides an opportunity for users to edit 
the selected item.

> > * Rename "system-run" to "run"
>
> I don't see any specific benefit for this. For the icons you mentioned
>
> this being useful for, I see the following as better suggestions:
> >     run-build (compile the current selection, used in IDEs)
>
> project-build
>
> >     run-build-file (compile a single file, used in IDEs as well)
>
> project-build-single

Awesome! I really like that one. Now it only needs to go into the 
specification, and we're all happy.

Consider my request for "run" redrawn, and replaced by a request for

* project-build
  The icon used for the "Build Project" action in an integrated development
  environment application.

> >     run-validation (check an XML file for compliance)
>
> document-validate (useful for things other than XML)

+1
Much better than my take. Of course, since there's no "document" fallback 
action, this would also need to go into the spec if it's handled this way.

> The spec was never meant to be an absolute conglomerate of all icons for
> all occasions in all desktops at all times. It is meant to be the base
> minimum set of icons a desktop should require to maintain visual appeal.

I understand that. But do also try to understand my situation: kdelibs is the 
base library that will be used by all KDE applications, and the core Oxygen 
icons that I try to get into shape are all in there. Icons in kdelibs will be 
used whether they comply to the spec or not, so the logical conclusion is to 
provide only specification compatible icons in kdelibs and let apps provide 
their "proprietary" extensions.

If we include non-specified icons in kdelibs, we'll essentially split the 
developer / icon user community in two parts again: the ones that care about 
KDE and implement our icons in addition to the specified icons, and the ones 
that don't.

If there is a way to prevent this fragmentation, I'd like to pursue it.
If we can accommodate a lot of use cases by providing generic fallbacks,
we can get rid of a lot of related issues at once. That's what I try to do 
here. I don't want to get each and every icon required by KDE into the spec, 
I just want the spec to be flexible enough to handle additional stuff without 
requiring KDE to break conformance. I want KDE apps look great in GNOME,
and vice versa.

> The spec is also not 1.0 material yet, and doesn't claim to be. But that
> doesn't mean that we can change the spec so heavily, for one desktop or
> the other. It is nearing 1.0, but is still not solid enough to be called
> such.

I think this is the one major issue with the spec, and that it needs to be 
fixed rather sooner than later. GNOME still largely relies on the mappings 
created by icon-naming-utils, and KDE 4 isn't released yet.
If we don't fix the spec now, it will never be fixed. Better have a disruptive 
change now than living with a broken scheme throughout the next few years or 
maybe even longer than that. That's my opinion on this.

> I don't think the changes you are demanding here are totally necessary,
> or that there is an extensibility issue. The spec was written with
> extensibility at the forefront from the beginning, as it was always
> meant to only include a base minimum set of icon names. As an example of
> this, see the recent work that has gone on with the device names as an
> extension to the spec.

And as I mentioned, the naming scheme for devices totally makes sense, and 
absolutely works great. This, er, request only focuses on actions, which I 
believe is the only part of the spec where grouping by base object does not 
work and prevents extensibility. I think the use cases that I listed in my 
previous mail present a lot of actions that do have a common base action, but 
can not be added to an icon theme without proprietarily extending the spec.

I hope we can get to a satisfactory solution for both of us.

Best wishes,
  Jakob