Well, since I just explained this issue to Benoit on IRC, I thought I could just post it here.

If somebody (Benoit?) considers it helpful, you might add it somewhere to CVS.

How to add a preferences option

This text explains how to add options to the global preference dialog from a module. The text uses the example of one simple boolean option in the import-export/hbci module ("Cache password in memory?").
The option is created in the file src/import-export/hbci/hbci.scm, with the following function call as a top-level function in that file:

(gnc:register-configuration-option
 (gnc:make-simple-boolean-option
  (N_ "Online Banking & Importing") (N_ "HBCI Remember PIN in memory")
  "b" (N_ "Remember the PIN for HBCI in memory during a session")
  #f))

The actual option is created by the function call to gnc:make-simple-boolean-option. Its first (string) argument is the tab (page) name. If the option is supposed to appear on an existing tab (page), the string has to match exactly the string used in src/app-utils/prefs.scm. The second (string) argument above is the actual option name. For lookup, this exact string will need to be used again.

For other (more complex) types of options, look up the gnc:make-xyz-option function to create your favorite option type in src/app-utils/options.scm. Also, if one or more options are supposed to go on a new tab/page, simply specify a tab/page name that didn't exist yet. It will automatically be added.

During the actual program run, the option is looked up only once, in src/import-export/hbci/hbci-interaction.c line 53:

cache_pin = 
    gnc_lookup_boolean_option(N_("Online Banking & Importing"),
                  "HBCI Remember PIN in memory",
                              FALSE);

The third argument here is the default value in case the lookup fails. The C function prototypes for lookup of other options can be found in src/app-utils/global-options.h. A lookup of a global preference in Scheme can be seen e.g. in src/report/reports/standard/register.scm line 556:

  (gnc:option-value (gnc:lookup-global-option "User Info" "User Name"))

I.e., the option itself has to be looked up first by gnc:lookup-global-option (from src/app-utils/prefs.scm), and then the function gnc:option-value returns the actual value of the option (defined in src/app-utils/options.scm).