imove over from the prefs directory

git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@1770 57a11ea4-9604-0410-9ed3-97b8803252fd

src/scm/design.txt

@@ -0,0 +1,150 @@
+
+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 xacc 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:
+      (xacc:preference-list) => list of prefs
+      (xacc:preference-exists?) => list of prefs
+      (xacc:preference-lookup-by-name name) => pref
+      (xacc:preference-get-name pref) => name
+      (xacc:preference-get-type pref) => type
+      (xacc:preference-get-value pref) => value
+      (xacc:preference-set-value! pref value) => <undefined>
+      (xacc: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
+   (xacc:preference-set-value! name value) in a config file, and will 
+
+   xacc --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, xacc (or whatever we call it) writes all automatically
+   generated (by user interaction in the GUI or whatever) config info
+   to a file ~/.xacc/config.auto in the form of guile code.  Then at
+   startup, xacc *first* tries to read ~/.xacc/config.user.  If it
+   can't, it falls back to ~/.xacc/config.auto, but only if
+   ~/.xacc/config.user doesn't exist.
+
+   Normal users will only have a ~/.xacc/config.auto file, and they'll
+   be happy.  Users who want to tweak things manually will be able to
+   create an ~/.xacc/config.user file and go nuts in there, loading
+   ~/.xacc/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 particular set of accounts to open on startup?  Put
+
+       (load "~/.xacc.auto")
+       (my-personally-coded-run-automated-transactions-function today)
+       (xacc-open-account "foo")
+       (xacc-open-account "bar")
+       (xacc-open-account "baz")
+
+     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?