[kde-doc-english] KDE/kdebase/workspace/doc/kcontrol/colors

[Matthew Woehlke]

Arturo Silva wrote:
> Wow, since I rarely use this module (even in the 3.x days), I never realized
> how flexible this was.
> 
> Perhaps I'm using an old edition of the KDE Help Center (the Colors section
> refers to a Revision 3.2), but I don't actually see this documentation
> anywhere.

Correct; the new version only hit svn a few days ago, so it isn't in
4.3.0. If you want to see it in khelpcenter, you'll need to build trunk.

> So either I'm looking in the wrong place, or this revision is
> old, or this is a new addition to that document.  Either way, I couldn't
> compare this to anything preexisting.

The version being patched in the referenced commit didn't exist
(publicly) until August 24, and then only in svn. You could compare the
Sep 1 version against the Aug 24 version, I guess, but that's the point
I made in our previous exchange; since this is a total rewrite, right
now it is best to ignore the old (3.2) doc and just look at the whole
thing as it is currently in svn.

> Judging by the symbols, it seems this is only a DIFF from the source
> document, so there are likely snippets here and there of unrelated
> documentation left over.

Right. The whole thing is here:
http://websvn.kde.org/trunk/KDE/kdebase/workspace/doc/kcontrol/colors/index.docbook?view=markup

On to your specific points...

> In the line:
> 
> +  a custom scheme.</para>
> 
> I would suggest "custom scheme" if possible.  The wording "color scheme" as
> used in the sentence almost seemed to imply I could take any scheme from the
> list (say, Magma), change it to all sorts of wacky colors, and then have
> that scheme save permanently with said wacky colors.  The reality, however,
> is that the color changes will ONLY affect the virtual scheme called
> "Current", which will not be permanent unless explicitly saved with the Save
> Scheme button.

Good point. I'm not very fond of "custom scheme" however, but I changed
this line to "the active color scheme", a term which is explained
above¹. Do you think that is sufficient?

(¹ "The 'active' scheme is the set of colors as has been most recently
edited by you, i.e. what you would get if you choose [Apply].")

> In the line:
> 
>    that you save your scheme when you are done.</para>
> 
> I would recommend referencing the Scheme tab, as in "save your scheme in the
> Scheme tab".  It sounds like an obsessive precaution, but it may not be
> necessarily obvious to the initiate where the Save Scheme button is.

That's reasonable. Changed as follows:
-  that you save your scheme when you are done.</para>
+  that you save your scheme (via the <guilabel>Scheme</guilabel> tab)
+  when you are done.</para>

> The entire section from:
> 
>     +  <para>The <guilabel>Common Colors</guilabel> set, which is displayed
> to
>     +  all, and can only be changed (if needed) by selecting the appropriate
>     +  set.</para>
> 
> ...is not technically wrong -- in fact, it's admirably detailed.  However,
> it does seem like it goes into too great length to explain what Common
> Colors is, which, as I would describe it, is merely the "Simple View" of the
> Colors tab, whereas the View, Window, Button, Selection and Tooltip combined
> make up a kind of "Advanced View".

Ironically, I made that change based on comments from Burkhard Lück,
generally in the vein that the things there explained were not explained
before.

I'm going to cross-post this part to -usability and see what they think
as well.

> I'm not sure what:
> 
>      <para>The choice of color role is left to the developer; the above are
>      guidelines intended to represent typical usage.</para>
> 
> ...refers to unfortunately.  :(

Basically, that the use of the various roles, as described above this
part, is advisory to developers, who may choose to ignore that advice.

It could probably be worded better. I'll think about this; meanwhile,
anyone else have ideas?

> In the lines:
> 
>     +        used to draw the title bar background, borders, and/or
> decorations for
>     +        active window (that is, the one with input focus). Not all
> window
> 
> I would add the "the" before "active window", so the phrase will read as
> "used to draw the title bar background, borders, and/or decorations for the
> active window...".

Oops, yes, that's clearly a simple typo. Thanks for the catch!

> For the section:
> 
>     +        used to draw the title bar text when Active Titlebar is used to
> draw
>     +        the title bar background. May also be used for other foreground
>     +        elements which use Active Titlebar as the background.
> 
> I understand what it means, but I can't shake the feeling that "Active
> Titlebar" alone sounds a bit broken.  But I can't really say that "the
> Active Titlebar role" will make it any better.  :(

Yes, the color role name is being used as a noun. I'm basically in
agreement with everything you said. Maybe some other method, such as
putting all role names in quotes, or making them bold, or some such,
would be better?

> Looking back on the entire section of Window Manager Roles, I can't help but
> feel a small contradiction regarding the role of Common Colors, given it
> does indeed contain UNIQUE elements not found in View, Window, Button,
> Selection, or Tooltip.  In reality, there really should be a Window Manager
> set too in order for the Common Colors pseudo-set to be true to its name.
> But again, this is a dev issue.  ;)

I could do that, but it would have four colors ;-). (At one point, there
was thought of having rather more WM roles, but so far nothing has
happened there.)

The problem is that "common" here means more along the lines of
"popular", not "shared"... an ambiguity in the English language. Any
ideas on a better (less ambiguous) word?

> And that concludes my analysis. Sorry for the length,

No worries :-), the feedback is much appreciated.

> Thank you for allowing me to use this as my first substantial contribution
> to KDE.  It's not much, but I hope it's a start.  ^___^

:-D

-- 
Matthew
Please do not quote my e-mail address unobfuscated in message bodies.
-- 
Hey! Where's the witty punchline?
(with apologies to Hostess)