Add const cast to this macro.

1999-11-13  Havoc Pennington  <hp@pobox.com>

        * gconf/gconf-value.h (gconf_meta_info_schema): Add const cast to
	        this macro.

		        * gconf/gconf.c (gconf_set_list): allow list of schemas
			        (from_primitive): handle schemas
				        (primitive_value): handle schemas
					        (gconf_get_list): handle schemas

						        *
doc/gconf/tmpl/gconf-value.sgml: docs!

        * doc/gconf/tmpl/gconf.sgml: docs!

	        * doc/gconf/gconf-sections.txt: add set/get list/pair

		        * gconf/gconf.c (gconf_set_list): Fix dumb bug
(assign back to the
        original list!)

4 files changed, 487 insertions, 135 deletions

diff --git a/doc/gconf/gconf-sections.txt b/doc/gconf/gconf-sections.txt
index 31a50a1e..2947e234 100644
--- a/doc/gconf/gconf-sections.txt
+++ b/doc/gconf/gconf-sections.txt
@@ -194,11 +194,15 @@ gconf_get_int
 gconf_get_string
 gconf_get_bool
 gconf_get_schema
+gconf_get_list
+gconf_get_pair
 gconf_set_float
 gconf_set_int
 gconf_set_string
 gconf_set_bool
 gconf_set_schema
+gconf_set_list
+gconf_set_pair
 </SECTION>
 
 <SECTION>
diff --git a/doc/gconf/tmpl/gconf-unused.sgml b/doc/gconf/tmpl/gconf-unused.sgml
index e69de29b..451dac2f 100644
--- a/doc/gconf/tmpl/gconf-unused.sgml
+++ b/doc/gconf/tmpl/gconf-unused.sgml
@@ -0,0 +1,6 @@
+<!-- ##### SECTION ./tmpl/gconf-unused.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
diff --git a/doc/gconf/tmpl/gconf-value.sgml b/doc/gconf/tmpl/gconf-value.sgml
index 7b532355..40a12e19 100644
--- a/doc/gconf/tmpl/gconf-value.sgml
+++ b/doc/gconf/tmpl/gconf-value.sgml
@@ -1,12 +1,29 @@
 <!-- ##### SECTION Title ##### -->
-gconf-value
+GConfValue, GConfEntry, GConfMetaInfo
 
 <!-- ##### SECTION Short_Description ##### -->
 
+A #GConfValue stores a
+dynamically-typed value. A #GConfEntry stores a key-value pair.
+A #GConfMetaInfo stores metainformation about a key.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
+#GConfValue stores one of the value types GConf understands; GConf
+uses #GConfValue to pass values around because it doesn't know the
+type of its values at compile time. 
+</para>
+
+<para>
+A #GConfEntry pairs a relative key
+name with a value, for example if the value "10" is stored at the key 
+"/foo/bar/baz", the #GConfEntry will store "baz" and "10".
+</para>
 
+<para>
+A #GConfMetaInfo object holds metainformation about a key, such as 
+its last modification time and the name of the schema associated with
+it. You should rarely if ever need to use #GConfMetaInfo.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -16,110 +33,167 @@ gconf-value
 
 <!-- ##### ENUM GConfValueType ##### -->
 <para>
-
+Used to indicate the type of a #GConfValue.
 </para>
 
-@GCONF_VALUE_INVALID: 
-@GCONF_VALUE_STRING: 
-@GCONF_VALUE_INT: 
-@GCONF_VALUE_FLOAT: 
-@GCONF_VALUE_BOOL: 
-@GCONF_VALUE_SCHEMA: 
-@GCONF_VALUE_LIST: 
-@GCONF_VALUE_PAIR: 
-@GCONF_VALUE_IGNORE_SUBSEQUENT: 
+@GCONF_VALUE_INVALID: Never the type of a #GConfValue obtained from GConf functions; used to indicate errors and the like.
+@GCONF_VALUE_STRING: String value (#gchar*).
+@GCONF_VALUE_INT: Integer value (#gint).
+@GCONF_VALUE_FLOAT: Floating point value (#gdouble).
+@GCONF_VALUE_BOOL: Boolean value (#gboolean).
+@GCONF_VALUE_SCHEMA: Schema value (#GConfSchema).
+@GCONF_VALUE_LIST: List of #GConfValue; #GConfValue elements must have
+a primitive type (i.e. they may not be lists or pairs), and all elements
+of a list must have the same type.
+@GCONF_VALUE_PAIR: Pair of #GConfValue; the first field (car) and the second
+field (cdr) may have different types.
+@GCONF_VALUE_IGNORE_SUBSEQUENT: Used internally, ignore it.
 
 <!-- ##### STRUCT GConfValue ##### -->
 <para>
+Represents a dynamically-typed value. The @type field tells you the
+type of the value; the other fields should be accessed with the
+accessor functions and macros.
+</para>
 
+<para>
+<emphasis>A #GConfValue should always
+be initialized before use. That is, you should not use a #GConfValue
+unless you have called one of the functions beginning with
+"gconf_value_set_".</emphasis>. For lists, initialization has two
+steps: first you must set the list element type, then you must set the
+list value.
 </para>
 
-@type: 
+@type: The #GConfValueType of this #GConfValue. The only field of
+#GConfValue you should access directly.
 
 <!-- ##### MACRO gconf_value_string ##### -->
 <para>
+Returns a <symbol>const gchar*</symbol> for a #GConfValue with type
+%GCONF_VALUE_STRING. The returned string is <emphasis>not</emphasis> a
+copy, don't try to free it. It is "owned" by the #GConfValue and will
+be destroyed when the #GConfValue is destroyed.
+</para>
 
+<para>
+If the #GConfValue is not initialized (i.e. no one has called
+gconf_value_set_string()) then the string may be
+<symbol>NULL</symbol>, but of course you should not try to use an
+uninitialized #GConfValue.
 </para>
 
-@x: 
+@x: a #GConfValue.
 
 
 <!-- ##### MACRO gconf_value_int ##### -->
 <para>
-
+Returns a #gint for a #GConfValue with type %GCONF_VALUE_INT. 
 </para>
 
-@x: 
+@x: a #GConfValue.
 
 
 <!-- ##### MACRO gconf_value_float ##### -->
 <para>
-
+Returns a #gdouble for a #GConfValue with type %GCONF_VALUE_DOUBLE.
 </para>
 
-@x: 
+@x: a #GConfValue.
 
 
 <!-- ##### MACRO gconf_value_list_type ##### -->
 <para>
-
+Returns the type of the list elements in a #GConfValue with type 
+%GCONF_VALUE_LIST.
 </para>
 
-@x: 
+@x: a #GConfValue.
 
 
 <!-- ##### MACRO gconf_value_list ##### -->
 <para>
-
+Returns a #GSList containing #GConfValue objects. Each #GConfValue in
+the returned list will have the type returned by
+gconf_value_list_type(). Remember that the empty #GSList is equal to
+<symbol>NULL</symbol>.  The list is not a copy; it is "owned" by the
+#GConfValue and will be destroyed when the #GConfValue is destroyed.
 </para>
 
-@x: 
+@x: a #GConfValue.
 
 
 <!-- ##### MACRO gconf_value_car ##### -->
 <para>
+Returns the first member (car) of a #GConfValue with type
+%GCONF_VALUE_PAIR. The car is another #GConfValue, with a primitive
+type (bool, int, float, string, schema).
+</para>
 
+<para>
+The returned value is not a copy; it is "owned" by the pair and will
+be destroyed when the pair is destroyed.
 </para>
 
-@x: 
+@x: a #GConfValue.
 
 
 <!-- ##### MACRO gconf_value_cdr ##### -->
 <para>
+Returns the second member (cdr) of a #GConfValue with type
+%GCONF_VALUE_PAIR. The cdr is another #GConfValue, with a primitive
+type (bool, int, float, string, schema).
+</para>
 
+<para>
+The returned value is not a copy; it is "owned" by the pair and will
+be destroyed when the pair is destroyed.
 </para>
 
-@x: 
+@x: a #GConfValue.
 
 
 <!-- ##### MACRO gconf_value_bool ##### -->
 <para>
-
+Returns a #gboolean for a #GConfValue with type %GCONF_VALUE_BOOL. 
 </para>
 
-@x: 
+@x: a #GConfValue.
 
 
 <!-- ##### MACRO gconf_value_schema ##### -->
 <para>
+Returns a #GConfSchema for a #GConfValue with type
+%GCONF_VALUE_SCHEMA. If the #GConfValue is uninitialized, it 
+may return <symbol>NULL</symbol>; but of course you should have
+initialized the #GConfValue. The GConf library will not return values
+with a <symbol>NULL</symbol> schema.
+</para>
 
+<para>
+The returned value is not a copy; it is "owned" by the #GConfValue and will
+be destroyed when the #GConfValue is destroyed.
 </para>
 
-@x: 
+@x: a #GConfValue.
 
 
 <!-- ##### FUNCTION gconf_value_new ##### -->
 <para>
-
+Creates a new #GConfValue with type @type. The type is immutable after
+creation; values have a fixed type. You <emphasis>must</emphasis>
+initialize the #GConfValue after creation; that is, you must set its 
+value with one of the "setter" functions.
 </para>
 
-@type: 
-@Returns: 
+@type: type of the new #GConfValue.
+@Returns: newly-allocated #GconfValue.
 
 
 <!-- ##### FUNCTION gconf_value_new_from_string ##### -->
 <para>
-
+Tries to parse a string and create a primitive #GConfValue from
+it. This is an internal function for now; don't use it.
 </para>
 
 @type: 
@@ -130,7 +204,7 @@ gconf-value
 
 <!-- ##### FUNCTION gconf_value_new_list_from_string ##### -->
 <para>
-
+This function does not work. Don't use it.
 </para>
 
 @list_type: 
@@ -140,7 +214,7 @@ gconf-value
 
 <!-- ##### FUNCTION gconf_value_new_pair_from_string ##### -->
 <para>
-
+This function does not work. Don't use it.
 </para>
 
 @car_type: 
@@ -151,19 +225,21 @@ gconf-value
 
 <!-- ##### FUNCTION gconf_value_copy ##### -->
 <para>
-
+Copies a #GConfValue. The copy is a deep copy, that is, any allocated
+memory inside the #GConfValue will also be copied.
 </para>
 
-@src: 
-@Returns: 
+@src: a #GConfValue to copy.
+@Returns: a newly-allocated #GConfValue identical to @src.
 
 
 <!-- ##### FUNCTION gconf_value_destroy ##### -->
 <para>
-
+Deallocates a #GConfValue. Also deallocates any allocated memory
+inside the #GConfValue (such as lists, pair members, strings, and schemas).
 </para>
 
-@value: 
+@value: a #GConfValue to destroy.
 
 
 <!-- ##### FUNCTION gconf_value_set_int ##### -->
@@ -306,7 +382,7 @@ gconf-value
 
 </para>
 
-@x: 
+@x:
 
 
 <!-- ##### MACRO gconf_meta_info_mod_user ##### -->
@@ -314,7 +390,7 @@ gconf-value
 
 </para>
 
-@x: 
+@x:
 
 
 <!-- ##### MACRO gconf_meta_info_mod_time ##### -->
@@ -322,7 +398,7 @@ gconf-value
 
 </para>
 
-@x: 
+@x:
 
 
 <!-- ##### FUNCTION gconf_meta_info_new ##### -->
diff --git a/doc/gconf/tmpl/gconf.sgml b/doc/gconf/tmpl/gconf.sgml
index 9737a967..c0bfce13 100644
--- a/doc/gconf/tmpl/gconf.sgml
+++ b/doc/gconf/tmpl/gconf.sgml
@@ -32,7 +32,7 @@ Initializes the GConf library. Creates a connection to a CORBA ORB unless
 you have previously called gconf_set_orb().
 </para>
 
-@err: the return location for a #GConfError, or <symbol>NULL</symbol> to ignore errors.
+@err: the return location for an allocated #GConfError, or <symbol>NULL</symbol> to ignore errors.
 @Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> otherwise.
 
 
@@ -78,7 +78,7 @@ notification request; 0 is an invalid ID, and is returned if an error occurs.
 @namespace_section: the directory or key to watch; you will be notified of changes at or below this point.
 @func: the callback to invoke when a notification is received from the server.
 @user_data: the data to pass to the callback.
-@err: the return location for a #GConfError, or <symbol>NULL</symbol> to ignore errors. 
+@err: the return location for an allocated #GConfError, or <symbol>NULL</symbol> to ignore errors.
 @Returns: an ID for the notification request, or 0 on error.
 
 
@@ -93,181 +93,419 @@ Removes a notification request.
 
 <!-- ##### FUNCTION gconf_get ##### -->
 <para>
-
+Returns the #GConfValue stored at @key, or <symbol>NULL</symbol> if no
+value is set. You must call gconf_value_destroy() to free the returned
+value. If you know the expected type of the value, you probably want
+to use the type-specific convenience wrappers (gconf_get_int(), etc.)
+because they will do the type-checking for you and return the
+appropriate type.
 </para>
 
-@conf: 
-@key: 
-@err: the return location for a #GConfError, or <symbol>NULL</symbol> to ignore errors. 
-@Returns: 
+@conf: a #GConfEngine to get the value from.
+@key: the key to get.
+@err: the return location for an allocated #GConfError, or <symbol>NULL</symbol> to ignore errors.
+@Returns: newly-allocated #GConfValue, or <symbol>NULL</symbol> if unset.
 
 
 <!-- ##### FUNCTION gconf_get_with_locale ##### -->
 <para>
-
+Requests the value appropriate for a particular locale. Right now,
+only values of type %GCONF_VALUE_SCHEMA are localized; the locale is
+meaningless for other value types. Also, gconf_get() automatically
+requests the value in the user's current locale. So this function is
+only useful if you want a schema for some locale other than the user's
+current locale. Except for the additional argument, this function is
+identical to gconf_get() in all respects.
 </para>
 
-@conf: 
-@key: 
-@locale: 
-@err: the return location for a #GConfError, or <symbol>NULL</symbol> to ignore errors. 
-@Returns: 
+@conf: a #GConfEngine to get the value from.
+@key: the key to get.
+@locale: preferred locale (as in the locale-related environment variables).
+@err: the return location for an allocated #GConfError, or <symbol>NULL</symbol> to ignore errors.
+@Returns: newly-allocated #GConfValue, or <symbol>NULL</symbol> if unset.
 
 
 <!-- ##### FUNCTION gconf_set ##### -->
 <para>
+Sets the value of @key to @value. Does not modify the passed-in
+#GConfValue, you must free it yourself. You may prefer a type-specific
+convenience wrapper, such as gconf_set_int().
+</para>
 
+<para>
+ An error of note is %GCONF_OVERRIDDEN, indicating that the system
+administrator has "forced" a value for this key. If no writeable
+configuration sources exist, it is not an error, but GConf will just
+forget all your values; this allows users to have a configuration-free
+setup without a constant barrage of error messages.
 </para>
 
-@conf: 
-@key: 
-@value: 
-@err: the return location for a #GConfError, or <symbol>NULL</symbol> to ignore errors. 
-@Returns: 
+@conf: a #GConfEngine to set the value in.
+@key: the key to set.
+@value: the new value of @key.
+@err: the return location for an allocated #GConfError, or <symbol>NULL</symbol> to ignore errors.
+@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> on error.
 
 
 <!-- ##### FUNCTION gconf_unset ##### -->
 <para>
-
+Unsets the value of @key; if @key is already unset, has no effect.  An
+error of note is %GCONF_OVERRIDDEN, indicating that the system
+administrator has "forced" a value for this key.
 </para>
 
-@conf: 
-@key: 
-@err: the return location for a #GConfError, or <symbol>NULL</symbol> to ignore errors. 
-@Returns: 
+@conf: a #GConfEngine to affect.
+@key: the key to unset.
+@err: the return location for an allocated #GConfError, or <symbol>NULL</symbol> to ignore errors.
+@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> on error.
 
 
 <!-- ##### FUNCTION gconf_associate_schema ##### -->
 <para>
-
+Directs GConf to find the schema for @key at location
+@schema_key. That is, the value stored at @schema_key should have type
+#GCONF_VALUE_SCHEMA, and be descriptive of @key. Normally you don't
+call this function from C code; you can ship a special file with your
+application and ask <application>gconftool</application> to install
+schema associations into the database during "make install."
 </para>
 
-@conf: 
-@key: 
-@schema_key: 
-@err: the return location for a #GConfError, or <symbol>NULL</symbol> to ignore errors. 
-@Returns: 
+@conf: a #GConfEngine to affect.
+@key: the key to associate the schema with.
+@schema_key: the key where the schema will be stored.
+@err: the return location for an allocated #GConfError, or <symbol>NULL</symbol> to ignore errors.
+@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> on error.
 
 
 <!-- ##### FUNCTION gconf_all_entries ##### -->
 <para>
-
+Lists the key-value pairs in @dir. Does not list subdirectories; for
+that use gconf_all_dirs(). The returned list contains #GConfEntry
+objects. A #GConfEntry contains a <emphasis>relative</emphasis> key
+and a value. The list is not recursive, it contains only the immediate
+children of @dir.  To free the returned list, gconf_entry_destroy()
+each list element, then g_slist_free() the list itself.
 </para>
 
-@conf: 
-@dir: 
-@err: the return location for a #GConfError, or <symbol>NULL</symbol> to ignore errors. 
-@Returns: 
+@conf: a #GConfEngine. 
+@dir: Directory to list.
+@err: the return location for an allocated #GConfError, or <symbol>NULL</symbol> to ignore errors.
+@Returns: List of #GConfEntry.
 
 
 <!-- ##### FUNCTION gconf_all_dirs ##### -->
 <para>
-
+Lists the subdirectories in @dir. The returned list contains allocated
+strings; you should g_free() each string in the list, then
+g_slist_free() the list itself.
 </para>
 
-@conf: 
-@dir: 
-@err: the return location for a #GConfError, or <symbol>NULL</symbol> to ignore errors. 
-@Returns: 
+@conf: a #GConfEngine.
+@dir: Directory to get subdirectories from.
+@err: the return location for an allocated #GConfError, or <symbol>NULL</symbol> to ignore errors.
+@Returns: List of allocated subdirectory names.
 
 
 <!-- ##### FUNCTION gconf_suggest_sync ##### -->
 <para>
-
+Suggests to <application>gconfd</application> that you've just finished
+a block of changes, and it would be an optimal time to sync to
+permanent storage. This is only a suggestion; and
+<application>gconfd</application> will eventually sync even if you
+don't call gconf_suggest_sync(). This function is just a "hint"
+provided to <application>gconfd</application> to maximize efficiency
+and minimize data loss.
 </para>
 
-@conf: 
-@err: the return location for a #GConfError, or <symbol>NULL</symbol> to ignore errors. 
+@conf: the #GConfEngine to suggest syncing to.
+@err: the return location for an allocated #GConfError, or <symbol>NULL</symbol> to ignore errors.
 
 
 <!-- ##### FUNCTION gconf_dir_exists ##### -->
 <para>
-
+Queries whether the directory @dir exists in the GConf
+database. Returns <symbol>TRUE</symbol> or <symbol>FALSE</symbol>.
 </para>
 
-@conf: 
-@dir: 
-@err: the return location for a #GConfError, or <symbol>NULL</symbol> to ignore errors. 
-@Returns: 
+@conf: a #GConfEngine.
+@dir: Directory to check for.
+@err: the return location for an allocated #GConfError, or <symbol>NULL</symbol> to ignore errors.
+@Returns: <symbol>TRUE</symbol> or <symbol>FALSE</symbol>.
 
 
 <!-- ##### FUNCTION gconf_valid_key ##### -->
 <para>
-
+Asks whether a key is syntactically correct, that is, it ensures that
+the key consists of slash-separated strings and contains only legal
+characters. Normally you shouldn't need to call this function; the
+GConf functions all check this for you and return an error if the key
+is invalid. However, it may be useful to validate input to an entry
+field or the like. If you pass a non-<symbol>NULL</symbol> address as
+the @why_invalid argument, an allocated string is returned explaining
+why the key is invalid, if it is. If the key is valid the @why_invalid
+argument is unused.
 </para>
 
-@key: 
-@why_invalid: 
-@Returns: 
-
+@key: key to check.
+@why_invalid: return location for an explanation of the problem, if any. g_free() the returned string.
+@Returns: <symbol>TRUE</symbol> if the key is valid, or <symbol>FALSE</symbol> if not.
 
 <!-- ##### FUNCTION gconf_key_is_below ##### -->
 <para>
-
+Asks whether the key @below would be found below the key @above, were
+they both to exist in the database. For example, <symbol>/foo</symbol>
+is always found below <symbol>/</symbol> and above
+<symbol>/foo/bar</symbol>. This probably isn't useful but GConf uses
+it internally so here it is if you need it.
 </para>
 
-@above: 
-@below: 
-@Returns: 
+@above: the key on the "left hand side" of the predicate.
+@below: the key on the "right hand side."
+@Returns: <symbol>TRUE</symbol> or <symbol>FALSE</symbol>.
 
 
 <!-- ##### FUNCTION gconf_get_float ##### -->
 <para>
-
+Requests the floating point number (%GCONF_VALUE_FLOAT) stored at
+@key. Automatically performs type-checking, so if a non-float is
+stored at @key, an error is returned. On error, or if @key is unset, 
+@def is returned.
 </para>
 
-@conf: 
-@key: 
-@def: 
-@err: the return location for a #GConfError, or <symbol>NULL</symbol> to ignore errors. 
-@Returns: 
-
+@conf: a #GConfEngine.
+@key: key you want the value of.
+@def: default value in case of error or unset value.
+@err: the return location for an allocated #GConfError, or <symbol>NULL</symbol> to ignore errors.
+@Returns: the value of @key, or @def if no value is obtained.
 
 <!-- ##### FUNCTION gconf_get_int ##### -->
 <para>
+Requests the integer (%GCONF_VALUE_INT) stored at
+@key. Automatically performs type-checking, so if a non-integer is
+stored at @key, an error is returned. On error, or if @key is unset, 
+@def is returned.
+</para>
+
+@conf: a #GConfEngine.
+@key: key you want the value of.
+@def: default value in case of error or unset value.
+@err: the return location for an allocated #GConfError, or <symbol>NULL</symbol> to ignore errors.
+@Returns: the value of @key, or @def if no value is obtained.
 
+<!-- ##### FUNCTION gconf_get_string ##### -->
+<para>
+Requests the string (%GCONF_VALUE_STRING) stored at
+@key. Automatically performs type-checking, so if a non-string is
+stored at @key, an error is returned. On error, or if @key is unset, 
+a copy of @def is returned (or if @def is <symbol>NULL</symbol>,
+<symbol>NULL</symbol> is returned). @def is copied so you can always
+safely g_free() the returned string.
 </para>
 
-@conf: 
-@key: 
-@def: 
-@err: the return location for a #GConfError, or <symbol>NULL</symbol> to ignore errors. 
-@Returns: 
+@conf: a #GConfEngine.
+@key: key you want the value of.
+@def: default value in case of error or unset value. 
+@err: the return location for an allocated #GConfError, or <symbol>NULL</symbol> to ignore errors.
+@Returns: allocated string (value of @key), or copy of @def if no value is obtained.
 
 
-<!-- ##### FUNCTION gconf_get_string ##### -->
+<!-- ##### FUNCTION gconf_get_bool ##### -->
 <para>
+Requests the boolean value (%GCONF_VALUE_BOOL) stored at
+@key. Automatically performs type-checking, so if a non-bool is
+stored at @key, an error is returned. On error, or if @key is unset, 
+@def is returned.
+</para>
+
+@conf: a #GConfEngine. 
+@key: key you want the value of. 
+@def: default value in case of error or unset value. 
+@err: the return location for an allocated #GConfError, or <symbol>NULL</symbol> to ignore errors.
+@Returns: the value of @key, or @def if no value is obtained.
 
+
+<!-- ##### FUNCTION gconf_get_schema ##### -->
+<para>
+Requests the schema (%GCONF_VALUE_SCHEMA) stored at @key.
+Automatically performs type-checking, so if a non-schema is stored at
+@key, an error is returned. If no value is set or an error occurs,
+<symbol>NULL</symbol> is returned.
 </para>
 
-@conf: 
-@key: 
-@def: 
-@err: the return location for a #GConfError, or <symbol>NULL</symbol> to ignore errors. 
-@Returns: 
+@conf: a #GConfEngine. 
+@key: key you want the value of. 
+@err: the return location for an allocated #GConfError, or <symbol>NULL</symbol> to ignore errors.
+@Returns: the value of @key as an allocated #GConfSchema, or <symbol>NULL</symbol> if no value was obtained. 
 
 
-<!-- ##### FUNCTION gconf_get_bool ##### -->
+<!-- ##### FUNCTION gconf_get_list ##### -->
 <para>
+Requests the list (%GCONF_VALUE_LIST) stored at @key.  Automatically
+performs type-checking, so if a non-list is stored at @key, or the
+list does not contain elements of type @list_type, an error is
+returned. If no value is set or an error occurs, <symbol>NULL</symbol>
+is returned. Note that <symbol>NULL</symbol> is also the empty list,
+so if you need to distinguish the empty list from an unset value, you
+must use gconf_get() to obtain a raw #GConfValue.
+</para>
 
+<para>
+<emphasis>Remember that GConf lists can only store primitive types:
+%GCONF_VALUE_FLOAT, %GCONF_VALUE_INT, %GCONF_VALUE_BOOL,
+%GCONF_VALUE_STRING, %GCONF_VALUE_SCHEMA.</emphasis> Also remember
+that lists must be uniform, you may not mix types in the same list.
 </para>
 
-@conf: 
-@key: 
-@def: 
-@err: the return location for a #GConfError, or <symbol>NULL</symbol> to ignore errors. 
-@Returns: 
+<para>
+The type of the list elements depends on @list_type. A #GConfValue
+with type %GCONF_VALUE_LIST normally stores a list of more #GConfValue
+objects. gconf_get_list() automatically converts to primitive C
+types. Thus, the list-&gt;data fields in the returned list 
+contain:
+ 
+<informaltable pgwide=1 frame="none">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>%GCONF_VALUE_INT</entry>
+<entry>The integer itself, converted with GINT_TO_POINTER()</entry>
+</row>
+
+<row>
+<entry>%GCONF_VALUE_BOOL</entry>
+<entry>The bool itself, converted with GINT_TO_POINTER()</entry>
+</row>
+
+<row>
+<entry>%GCONF_VALUE_FLOAT</entry>
+<entry>A pointer to #gdouble, which should be freed with g_free()</entry>
+</row>
+
+<row>
+<entry>%GCONF_VALUE_STRING</entry>
+<entry>A pointer to #gchar, which should be freed with g_free()</entry>
+</row>
+
+<row>
+<entry>%GCONF_VALUE_SCHEMA</entry>
+<entry>A pointer to #GConfSchema, which should be freed with gconf_schema_destroy()</entry>
+</row>
+
+</tbody></tgroup></informaltable>
+
+In the %GCONF_VALUE_FLOAT and %GCONF_VALUE_STRING cases, you must
+g_free() each list element. In the %GCONF_VALUE_SCHEMA case you must
+gconf_schema_destroy() each element. In all cases you must free the
+list itself with g_slist_free().
+</para>
 
+@conf: a #GConfEngine. 
+@key: key you want the value of. 
+@list_type: type of each list element.
+@err: the return location for an allocated #GConfError, or <symbol>NULL</symbol> to ignore errors.
+@Returns: an allocated list, with elements as described above.
 
-<!-- ##### FUNCTION gconf_get_schema ##### -->
+<!-- ##### FUNCTION gconf_get_pair ##### -->
 <para>
+Requests the pair (%GCONF_VALUE_PAIR) stored at @key.  Automatically
+performs type-checking, so if a non-pair is stored at @key, or the
+pair does not have the right @car_type and @cdr_type, an error is
+returned. Remember that the <firstterm>car</firstterm> of a pair is
+its first value, and the <firstterm>cdr</firstterm> is its second
+value, in the Lisp tradition. 
+</para>
 
+<para>
+<emphasis>Remember that GConf pairs can only store primitive types:
+%GCONF_VALUE_FLOAT, %GCONF_VALUE_INT, %GCONF_VALUE_BOOL,
+%GCONF_VALUE_STRING, %GCONF_VALUE_SCHEMA.</emphasis>
 </para>
 
-@conf: 
-@key: 
-@err: the return location for a #GConfError, or <symbol>NULL</symbol> to ignore errors. 
-@Returns: 
+<para>
+gconf_get_pair() stores the two fields of the pair in the locations
+pointed to by @car_retloc and @cdr_retloc. The type of these pointers
+depends on the corresponding @car_type and @cdr_type:
+ 
+<informaltable pgwide=1 frame="none">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>%GCONF_VALUE_INT</entry>
+<entry>pointer to #gint</entry>
+</row>
+
+<row>
+<entry>%GCONF_VALUE_BOOL</entry>
+<entry>pointer to #gboolean</entry>
+</row>
+
+<row>
+<entry>%GCONF_VALUE_FLOAT</entry>
+<entry>pointer to #gdouble</entry>
+</row>
+
+<row>
+<entry>%GCONF_VALUE_STRING</entry>
+<entry>pointer to #gchar*</entry>
+</row>
+
+<row>
+<entry>%GCONF_VALUE_SCHEMA</entry>
+<entry>pointer to #GConfSchema*</entry>
+</row>
+
+</tbody></tgroup></informaltable>
+
+In the %GCONF_VALUE_STRING case, you must g_free() the string(s)
+stored in the return location(s). In the %GCONF_VALUE_SCHEMA case you
+must gconf_schema_destroy() the returned schema. If there's an error
+or the value is unset, @car_retloc and @cdr_retloc are left unchanged.
+</para>
+
+<para>
+gconf_get_pair() returns <symbol>TRUE</symbol> on success.
+</para>
+
+<para>
+An example of gconf_get_pair() in action:
+<programlisting>
+gdouble car = 10.0;
+gchar* cdr  = NULL; 
+GConfError* error = NULL;
+
+if (!gconf_get_pair(conf, "/foo", 
+                    GCONF_VALUE_FLOAT,
+                    GCONF_VALUE_STRING, 
+                    &amp;car, &amp;cdr, &amp;error))
+  {
+    /* Note: car/cdr should be untouched, because an error occurred */
+    g_assert(error != NULL);
+    fprintf(stderr, "Error: %s\n", error->str);
+    gconf_error_destroy(error);
+    error = NULL;
+  }
+else
+  {
+    /* Note: car/cdr may be untouched even though there was no error, 
+       if no value was set for "/foo"
+     */
+    printf("Found pair (%g,%s)\n", car, cdr);
+    if (cdr != NULL)
+      g_free(cdr);
+  }
+</programlisting>
+</para>
+
+@conf: a #GConfEngine. 
+@key: key you want the value of. 
+@car_type: desired type of the pair's first field (car).
+@cdr_type: desired type of the pair's second field (cdr).
+@car_retloc: address of a return location for the car.
+@cdr_retloc: address of a return location for the cdr.
+@err: the return location for an allocated #GConfError, or <symbol>NULL</symbol> to ignore errors.
+@Returns: <symbol>TRUE</symbol> on success, <symbol>FALSE</symbol> on error.
 
 
 <!-- ##### FUNCTION gconf_set_float ##### -->
@@ -275,10 +513,10 @@ Removes a notification request.
 
 </para>
 
-@conf: 
+@conf: a #GConfEngine. 
 @key: 
 @val: 
-@err: the return location for a #GConfError, or <symbol>NULL</symbol> to ignore errors. 
+@err: the return location for an allocated #GConfError, or <symbol>NULL</symbol> to ignore errors.
 @Returns: 
 
 
@@ -287,10 +525,10 @@ Removes a notification request.
 
 </para>
 
-@conf: 
+@conf: a #GConfEngine. 
 @key: 
 @val: 
-@err: the return location for a #GConfError, or <symbol>NULL</symbol> to ignore errors. 
+@err: the return location for an allocated #GConfError, or <symbol>NULL</symbol> to ignore errors.
 @Returns: 
 
 
@@ -299,10 +537,10 @@ Removes a notification request.
 
 </para>
 
-@conf: 
+@conf: a #GConfEngine. 
 @key: 
 @val: 
-@err: the return location for a #GConfError, or <symbol>NULL</symbol> to ignore errors. 
+@err: the return location for an allocated #GConfError, or <symbol>NULL</symbol> to ignore errors.
 @Returns: 
 
 
@@ -311,10 +549,10 @@ Removes a notification request.
 
 </para>
 
-@conf: 
+@conf: a #GConfEngine. 
 @key: 
 @val: 
-@err: the return location for a #GConfError, or <symbol>NULL</symbol> to ignore errors. 
+@err: the return location for an allocated #GConfError, or <symbol>NULL</symbol> to ignore errors.
 @Returns: 
 
 
@@ -323,10 +561,38 @@ Removes a notification request.
 
 </para>
 
-@conf: 
+@conf: a #GConfEngine. 
 @key: 
 @val: 
-@err: the return location for a #GConfError, or <symbol>NULL</symbol> to ignore errors. 
+@err: the return location for an allocated #GConfError, or <symbol>NULL</symbol> to ignore errors.
+@Returns: 
+
+
+<!-- ##### FUNCTION gconf_set_list ##### -->
+<para>
+
+</para>
+
+@conf: a #GConfEngine. 
+@key: 
+@list_type: 
+@list: 
+@err: the return location for an allocated #GConfError, or <symbol>NULL</symbol> to ignore errors.
+@Returns: 
+
+
+<!-- ##### FUNCTION gconf_set_pair ##### -->
+<para>
+
+</para>
+
+@conf: a #GConfEngine. 
+@key: 
+@car_type: 
+@cdr_type: 
+@address_of_car: 
+@address_of_cdr: 
+@err: the return location for an allocated #GConfError, or <symbol>NULL</symbol> to ignore errors.
 @Returns: