
Option order is relevant...

Startup looks like this:

  load *gnc:startup-file*

    may be overriden with --startup-file

      default is --share-dir /gnucash/scm/startup.scm

    sets up *gnc:load-path* (most other files respect this)
      default is '("$HOME/.gnucash/scm" "$prefix/usr/share/gnucash/scm::")
        and all the subdirectories of these directories.

      may be overridden by --load-path
        the default path can be referenced as *gnc:load-path*
        you can indicate that subdirs should be scanned with a trailing ::
        i.e.  --load-path '(append *gnc:load-path* (gnc:subdirs "/my/dir/"))'

  --load-path=<>:/usr/lib/foo:.:    


  load *gnc:config-dir* / config
    *gnc:config-dir* may be overriden with --config-dir

  load $HOME/.gnucash/config.user or load $HOME/.gnucash/config.auto


This means that all code can be overriden by either --startup-file and
--load-path.


This file is out of date.  Recent implementation has surpassed its
contents.  It will be updated later...


This directory should hold the UI independent parts of the
configuration engine.  In particular, this sub-system is concerned
with support for command line options, help strings for these options,
and general preferences.  It is also concerned with integrating these
things with the startup config file.

Current notes:

1) One goal is to make it really easy to add preference options, and
   to make sure that changes in one place propagate everywhere they're
   relevant.  You should be able to enter the option description in
   one place, and then this information should be used to parse
   command line options, automatically extend the options the config
   file supports, generate the usage message, and annotate the config
   file.

   I propose that each subdir in the gnucash tree be allowed to contain
   an ./prefs.def.scm file which will look like this:

   (gnucash:describe-pref name value-name type description
                          default-value
                          arg-convert-func
                          arg-verify-func)
   i.e.

     (gnucash:describe-pref
       "ledger-height" "height" 'integer
       "The default height of a newly opened ledger in number of lines."
       12
       gnucash:prefs-handle-integer-arg
       #f)

    At the C level, all these objects will be returned as the guile
    SCM type, but translating this to the relevant C type is
    completely straightforward (guile has a set of functions for
    this).  In most cases, you'll know what the expected C type is,
    and just use the relevant guile function to get it, but if not,
    there are type query functions.  There are also C level "foreach"
    and list stepping functions to handle any lists.

    The option-definitions files will be used to determine the config
    system's initial configuration behavior.


[ OUT OF DATE -- implementation in flux ]

  The following functions for interaction with the config system will
  be available:

    guile-level:
      (gnucash:preference-list) => list of prefs
      (gnucash:preference-exists?) => list of prefs
      (gnucash:preference-lookup-by-name name) => pref
      (gnucash:preference-get-name pref) => name
      (gnucash:preference-get-type pref) => type
      (gnucash:preference-get-value pref) => value
      (gnucash:preference-set-value! pref value) => <undefined>
      (gnucash:preference-get-documentation! pref) => documentation

    c-level: There will be an equivalent set of functions for querying
      the state of the preference engine, and there will be some
      helper functions to make interactions with the scheme level less
      awkward.

      There will also be a callback mechanism whereby the C level can
      register functions to be called whenever a given preference
      changes.  This will allow us to keep guileisms out of code that
      we want to keep strictly C/C++ (this feature addresses one of
      Linas' primary concerns).

   --name="value" on the command line will be handled identically to
   (gnucash:preference-set-value! name value) in a config file, and will 

   gnucash --help" will display a list of all options, their types, their
   default values, and their documentation strings, all gathered from
   the config files.

2) The config file will just be guile code, and the startup procedure
   should work as follows.  (This approach needs to be substantially
   more sophisticated later to handle UI selected options vs. user
   config-file options more intelligently, but this will do for now.)

   By default, gnucash (or whatever we call it) writes all automatically
   generated (by user interaction in the GUI or whatever) config info
   to a file ~/.gnucash/config.auto in the form of guile code. Then at
   startup, gnucash *first* tries to read ~/.gnucash/config.user. If it
   can't, it falls back to ~/.gnucash/config.auto, but only if
   ~/.gnucash/config.user doesn't exist.

   Normal users will only have a ~/.gnucash/config.auto file, and they'll
   be happy. Users who want to tweak things manually will be able to
   create an ~/.gnucash/config.user file and go nuts in there, loading
   ~/.gnucash/config.auto whenever they feel like it (or not at all).

   Justification for guile code as the config file format rather than
   something less complex:

   Want a to run a particular set of functions on startup? Put

       (gnc:load "config.auto")

       (my-first-function)
       (my-second-function)
       ...

     Also this makes hook functions possible (essentially callbacks on
     certain events into user provided guile functions).

Unknown:

1) How does this scheme integrate with gtk's config rc file mechanism?
   I know we'll pass argc, argv off to gtk_init, but do we need to
   think about anything else?
