GSettings schema writing guidance [was: dconf/GSettings namespace]

[Christian Persch <chpe gnome org>]

Hi;

I think we should provide a more in-depth guide on how to write schemas
for gsettings, convering e.g.:

- schema names: tld.foo.FooApp vs. tld.foo.foo-app vs ...

- paths: /tld/foo/foo-app/ vs /apps/foo-app/ vs ...

- what key names to use

- how the <summary> and <description> should differ and what they
  should (and should not) contain.
  (E.g. IMHO for enum and flags settings, the GConf schemas used to
  contain a complete enumeration of the valid values. Since these are
  stored in the schema itself for gsettings, I think the description
  need not do this anymore.) [Actually I wonder if we should just drop
  the summary altogether and only provide the description?]

- how to store some common data types:

  * colours: should they be stored as "s" ('rrggbb' or '#rrggbb' or
    '#rrrrggggbbb' or ...) or "(yyy)" (tuple of 3 bytes) or
    "(nnn)" (tuple of 3 int16's) ? And should it always contain also
    the alpha component?

  * remind the programmer that filenames need to be "ay" not "s" (and
    advise to just use URIs instead which can be stored as "s" ?)

  * command lines as one line ("s" / "ay"), or argv ("as" / "aay")

  * enums, flags should use the built-in gsettings support for them

  * (host, port) pairs (e.g. in the proxy settings): separate keys for
    host and port, or an "(si)" tuple ?

  * window sizes, should they be two "i" settings for width and height,
    or an "(ii)" tuple? same for window positions

  * generalising the two above, when to use several individual settings,
    and when to just one setting containing an tuple

  * etc.

- when to use child schemas

- when to use settings lists

Regards,
	Christian