Documentation for GNOME color picker dialog

[Liam Hazell <liamh dragon net au>]

Hi all,

Attached is a *rough* draft of the documentation for the GNOME color
picker dialog. FIXMEs appear throughout the source. Comments and
criticism would be welcome. (Unfortunately, it does not at this stage
use the GDP DTD because I can't seem to get it to work on my system: I
keep getting the error message:

cannot generate system identifier for public text "-//GNOME//DTD DocBook
PNG Variant V1.1//EN"

even though I've updated CATALOGS and moved the GDP DTD into the same
directory as docbook.dtd.)

More broadly, working on this documentation has raised a number of
issues for me:

* Will the appearance of Dynamic Document Synthesis in GNOME 2.0 mean
that there will soon be two ways of getting to the documentation for
items such as the color picker - firstly, via the help button and
secondly via the combined documentation? If so, does this affect the
inclusion of images in the documentation? Although it might make sense
for an image of a component to be included in the combined
documentation, which might be read at any time, it seems silly to do so
if the user has opened the documentation via that component.

* What DocBook tag should be used to refer to GNOME components like the
color picker dialog, if any? I've used 'application' just to set it off
in some way, but that seems just a tad excessive.
 
* Does the documentation need to include the license text?
gnome-color-picker.c does not include a reference to the GPL as it is
covered by the GPL for gnome-libs, but given this documentation might
stand alone, might inclusion of the license text be a good idea?

* Has the GDP decided to standardi[s|z]e on the conventions of British
or US English with regards to spelling for English-language docs? In
Australia, 'color', 'colour', 'gray' and 'grey' are all seen as more or
less correctly spelt, depending on who you speak to.

* Most importantly, should we say 'on-line' or 'online'? :-)


Liam.

Title: GNOME color picker

]>

2000 Liam Hazell Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy of the GNU Free Documentation License from the Free Software Foundation by visiting their Web site or by writing to: Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. Many of the names used by companies to distinguish their products and services are claimed as trademarks. Where those names appear in any GNOME documentation, and those trademarks are made aware to the members of the GNOME Documentation Project, the names have been printed in caps or initial caps. This is version 1.0 of the GNOME color picker manual. You can use the GNOME color picker dialog to a specify the color you want in a number of ways: by specifying the color in RGB (Red Green Blue) format. This can be done by adjusting the Red, Green and Blue sliders. Alternatively, you can specify a value between 0 and 1 for each color, where '0' represents none of that color and '1' represents the maximal amount of that color. by using button 1 to click anywhere on the color wheel to set the Hue and Saturation of your color, then using button 1 to click anywhere on the value bar to set the Value of the color. FIXME: Would images of the color wheel and value bar be appropriate here? (An explanation of the terms Hue, Saturation and Value may be found below.) FIXME: Is 'emphasis' the correct tag here? by specifying the color in HSV (Hue Saturation Value) format using the Hue, Saturation and Value sliders. Alternatively, you can specify a value between 0 and 1 for each of these. FIXME: Should a longer explanation of what the values actually represent go here or in the explanation below? The GNOME color picker gives you the option of specifying the color you want in HSV (Hue Saturation Value) format: Hue represents the color. Saturation represents the 'purity' of the color. For example, a Saturation of 1, together with a Hue of 0 and a Value of 1 will result in a pure red. Value represents how 'bright' the color is, or alternately, how much gray is in the color — the brighter the color, the less gray it contains. FIXME: Is the following correct? 'Value' is thus equivalent to Brightness in the HSB color model and Luminosity in the HSL color model. FIXME: Is 'application' the correct tag here? The GNOME color picker was written by Federico Mena (federico nuclecu unam mx). To find more information about the GNOME color picker, please visit the [What?] Web page. Please send all comments, suggestions, and bug reports to the GNOME bug tracking database. (Instructions for submitting bug reports can be found on-line.) You can also use Bug Report Tool (bug-buddy), available in the Utilities submenu of the Main Menu, for submitting bug reports. This manual was written by Liam Hazell (liamh dragon net au). Please send all comments and suggestions regarding this manual to the GNOME Documentation Project by sending an email to docs gnome org. You can also add your comments on-line by using the GNOME Documentation Status Table.