<!-- ##### SECTION Title ##### -->
gnome-config

<!-- ##### SECTION Short_Description ##### -->

Simple access to configuration values (50% done)

<!-- ##### SECTION Long_Description ##### -->

<para>gnome-config routines provide a simple way of retrieving and
storing configuration values (the routines provide handling of default
values to simplify the code).</para>

  
  <formalpara>
   <title>Definitions</title>

  </formalpara>
  <para>
    <itemizedlist>
      <listitem><para><emphasis>config path:</emphasis> a string that
        specifies which item to retrieve from the configuration
        database.  The config path is composed of three elements: the
        first one is the filename where the information is stored, the
        second component is the section and the third one is the key
        inside the section</para>

        <para>For example, a config path of "/myapp/toolbox/showit"
        could be used to retrieve the setting for whether 'myapp'
        should display its toolbox or not.  In this example "myapp" is
        the file name (which is stored in
        <filename>~/.gnome</filename> directory), "toolbox" is the
        section and "showit" is the key.</para>

        <para>If you want to access an absolute file instead of a
        <filename>~/.gnome</filename>-relative file, then you need to
        surround the filename with equal signs, for example, to access
        the key "mykey" from the section "mysection" in a
        configuration file located in
        <filename>/gnome/var/myconfig</filename> you need to use this
        path: "=/gnome/var/myconfig=/mysection/mykey".</para></listitem>

      <listitem><para><emphasis>default:</emphasis> when retrieving a
        config item, specifies the value to be used if the item is not
        found.</para></listitem>

      <listitem><para><emphasis>private configuration data</emphasis>
        - Normally, config item data is located in files under the
        ~user/.gnome directory in a .ini-like format. These files are
        world-readable. Items that have security or privacy
        implications are stored and retrieved using the "private"
        versions of the gnome-config routines, and the data for these
        items is stored in files under the ~user/.gnome_private
        directory, which is not accessable by anyone except that user
        and the system administrator.</para></listitem>

      <listitem><para>"translated" strings - GNOME's multilingual
       	support means that multiple languages must be supported for
       	configuration items.  The
       	gnome_config_*get_translated_string() and
       	gnome_config_*set_translated_string() routines allow you to
       	specify which language a string item should be accessed for.
       	</para></listitem>

      <listitem><para>"section" - a group of config items and other
      config sections</para></listitem>
    </itemizedlist>
   </para>


<formalpara>
  <title>How Config Items are Read</title>

</formalpara>
<para>
    GNOME has a versatile method of storing config items.  When a
    config item is written by a program, it is written to a file under
    the <filename>~/.gnome</filename> hierarchy.  However, when config
    items are read, the process is a little more complicated.  There
    are a number of places that are searched.  If the config item is
    not found in one, then the next place is checked, finally falling
    back to the default value provided by the application.  The
    locations are as follows:
    <itemizedlist>
      <listitem><para><filename>$(sysconfdir)/gnome/config-override</filename>
        - a system administrator would put config items in this directory
        that they don't want to be configurable.</para></listitem>
      <listitem><para><filename>~/.gnome</filename> - this is where the
        user's config items are written to and is the next place that is
        searched</para></listitem>
      <listitem><para><filename>$(sysconfdir)/gnome/config</filename>
        - this directory would hold system wide default configuration values.
        </para></listitem>
    </itemizedlist>
  </para>

  <para>
    Possible uses for this are setting system wide defaults such as
    proxy servers for the system (either using
    <filename>config-override</filename> to enforce such a policy or
    the <filename>config</filename> directory to suggest such a
    default).  It is also possible to configure the application
    through its graphical interface, and then copy the configuration
    file accross to the appropriate system-wide directory.
    The <filename>config-override</filename> directory should be used
    sparingly, as it could annoy or confuse some users.  Note also
    that some applications will not read the config items every time
    they are needed, so putting defaults into the
    <filename>config-override</filename> directory will not always
    completely enforce a setting.
</para>


<para>There are two types of routines</para> 

<para>FIXME: Finish this.  Explain the different types of routines,
explain the _private versions, explain the vector use, etc</para>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### MACRO gnome_config_get_string_with_default ##### -->
<para>

</para>

@path: 
@def: 


<!-- ##### MACRO gnome_config_get_translated_string_with_default ##### -->
<para>

</para>

@path: 
@def: 


<!-- ##### MACRO gnome_config_get_int_with_default ##### -->
<para>

</para>

@path: 
@def: 


<!-- ##### MACRO gnome_config_get_float_with_default ##### -->
<para>

</para>

@path: 
@def: 


<!-- ##### MACRO gnome_config_get_bool_with_default ##### -->
<para>

</para>

@path: 
@def: 


<!-- ##### MACRO gnome_config_get_vector_with_default ##### -->
<para>

</para>

@path: 
@argcp: 
@argvp: 
@def: 


<!-- ##### MACRO gnome_config_private_get_string_with_default ##### -->
<para>

</para>

@path: 
@def: 


<!-- ##### MACRO gnome_config_private_get_translated_string_with_default ##### -->
<para>

</para>

@path: 
@def: 


<!-- ##### MACRO gnome_config_private_get_int_with_default ##### -->
<para>

</para>

@path: 
@def: 


<!-- ##### MACRO gnome_config_private_get_float_with_default ##### -->
<para>

</para>

@path: 
@def: 


<!-- ##### MACRO gnome_config_private_get_bool_with_default ##### -->
<para>

</para>

@path: 
@def: 


<!-- ##### MACRO gnome_config_private_get_vector_with_default ##### -->
<para>

</para>

@path: 
@argcp: 
@argvp: 
@def: 


<!-- ##### MACRO gnome_config_get_string ##### -->
<para>

</para>

@path: 


<!-- ##### MACRO gnome_config_get_translated_string ##### -->
<para>

</para>

@path: 


<!-- ##### MACRO gnome_config_get_int ##### -->
<para>

</para>

@path: 


<!-- ##### MACRO gnome_config_get_float ##### -->
<para>

</para>

@path: 


<!-- ##### MACRO gnome_config_get_bool ##### -->
<para>

</para>

@path: 


<!-- ##### MACRO gnome_config_get_vector ##### -->
<para>

</para>

@path: 
@argcp: 
@argvp: 


<!-- ##### MACRO gnome_config_private_get_string ##### -->
<para>

</para>

@path: 


<!-- ##### MACRO gnome_config_private_get_translated_string ##### -->
<para>

</para>

@path: 


<!-- ##### MACRO gnome_config_private_get_int ##### -->
<para>

</para>

@path: 


<!-- ##### MACRO gnome_config_private_get_float ##### -->
<para>

</para>

@path: 


<!-- ##### MACRO gnome_config_private_get_bool ##### -->
<para>

</para>

@path: 


<!-- ##### MACRO gnome_config_private_get_vector ##### -->
<para>

</para>

@path: 
@argcp: 
@argvp: 


<!-- ##### MACRO gnome_config_set_string ##### -->
<para>

</para>

@path: 
@new_value: 


<!-- ##### MACRO gnome_config_set_translated_string ##### -->
<para>

</para>

@path: 
@value: 


<!-- ##### MACRO gnome_config_set_int ##### -->
<para>

</para>

@path: 
@new_value: 


<!-- ##### MACRO gnome_config_set_float ##### -->
<para>

</para>

@path: 
@new_value: 


<!-- ##### MACRO gnome_config_set_bool ##### -->
<para>

</para>

@path: 
@new_value: 


<!-- ##### MACRO gnome_config_set_vector ##### -->
<para>

</para>

@path: 
@argc: 
@argv: 


<!-- ##### MACRO gnome_config_private_set_string ##### -->
<para>

</para>

@path: 
@new_value: 
<!-- # Unused Parameters # -->
@val: 


<!-- ##### MACRO gnome_config_private_set_translated_string ##### -->
<para>

</para>

@path: 
@new_value: 
<!-- # Unused Parameters # -->
@val: 


<!-- ##### MACRO gnome_config_private_set_int ##### -->
<para>

</para>

@path: 
@new_value: 
<!-- # Unused Parameters # -->
@value: 


<!-- ##### MACRO gnome_config_private_set_float ##### -->
<para>

</para>

@path: 
@new_value: 
<!-- # Unused Parameters # -->
@value: 


<!-- ##### MACRO gnome_config_private_set_bool ##### -->
<para>

</para>

@path: 
@new_value: 
<!-- # Unused Parameters # -->
@value: 


<!-- ##### MACRO gnome_config_private_set_vector ##### -->
<para>

</para>

@path: 
@argc: 
@argv: 


<!-- ##### MACRO gnome_config_has_section ##### -->
<para>

</para>

@path: 


<!-- ##### MACRO gnome_config_private_has_section ##### -->
<para>

</para>

@path: 
<!-- # Unused Parameters # -->
@Path: 


<!-- ##### MACRO gnome_config_init_iterator ##### -->
<para>

</para>

@path: 


<!-- ##### MACRO gnome_config_private_init_iterator ##### -->
<para>

</para>

@path: 


<!-- ##### MACRO gnome_config_init_iterator_sections ##### -->
<para>

</para>

@path: 


<!-- ##### MACRO gnome_config_private_init_iterator_sections ##### -->
<para>

</para>

@path: 


<!-- ##### FUNCTION gnome_config_iterator_next ##### -->
<para>

</para>

@iterator_handle: 
@key: 
@value: 


<!-- ##### FUNCTION gnome_config_drop_all ##### -->
<para>

</para>



<!-- ##### FUNCTION gnome_config_sync ##### -->
<para>

</para>



<!-- ##### MACRO gnome_config_sync_file ##### -->
<para>

</para>

@path: 


<!-- ##### MACRO gnome_config_private_sync_file ##### -->
<para>

</para>

@path: 


<!-- ##### MACRO gnome_config_drop_file ##### -->
<para>

</para>

@path: 


<!-- ##### MACRO gnome_config_private_drop_file ##### -->
<para>

</para>

@path: 


<!-- ##### MACRO gnome_config_clean_file ##### -->
<para>

</para>

@path: 


<!-- ##### MACRO gnome_config_private_clean_file ##### -->
<para>

</para>

@path: 


<!-- ##### MACRO gnome_config_clean_section ##### -->
<para>

</para>

@path: 


<!-- ##### MACRO gnome_config_private_clean_section ##### -->
<para>

</para>

@path: 
<!-- # Unused Parameters # -->
@Path: 


<!-- ##### MACRO gnome_config_clean_key ##### -->
<para>

</para>

@path: 


<!-- ##### MACRO gnome_config_private_clean_key ##### -->
<para>

</para>

@path: 


<!-- ##### MACRO gnome_config_get_real_path ##### -->
<para>

</para>

@path: 


<!-- ##### MACRO gnome_config_private_get_real_path ##### -->
<para>

</para>

@path: 


<!-- ##### FUNCTION gnome_config_push_prefix ##### -->
<para>

</para>

@path: 


<!-- ##### FUNCTION gnome_config_pop_prefix ##### -->
<para>

</para>



<!-- ##### FUNCTION gnome_config_make_vector ##### -->
<para>

</para>

@string: 
@argcp: 
@argvp: 


<!-- ##### FUNCTION gnome_config_assemble_vector ##### -->
<para>

</para>

@argc: 
@argv: 
@Returns: 


<!-- ##### FUNCTION gnome_config_set_set_handler ##### -->
<para>

</para>

@func: 
@data: 


<!-- ##### FUNCTION gnome_config_set_sync_handler ##### -->
<para>

</para>

@func: 
@data: