Warning, /frameworks/kconfig/docs/DESIGN.kconfig is written in an unsupported language. File is not indexed.

 kconfigdata_p.h contains definitions of the data formats used by kconfig.
 
 Configuration entries are stored as "KEntry". They are indexed with "KEntryKey".
 The primary store is a "KEntryMap" which is defined as a std::map from "KEntryKey"
 to "KEntry"
 
 KEntry's are stored in order in the KEntryMap. The most significant sort 
 criteria is mGroup. This means that all entries who belong in the same group,
 are grouped in the std::map as well.
 
 The start of a group is indicated with a KEntryKey with an empty mKey and a 
 dummy KEntry. This allows us to search for the start of the group and then to 
 iterate until we end up in another group. That way we will find all entries
 of a certain group.
 
 Entries that are localised with the _current_ locale are stored with bLocal 
 set to true. Entries that are localised with another locale are either not
 stored at all (default), or with the localization as part of the key (when
 reading a file in order to merge it). 
 [WABA: Does it make sense to keep both localized and non-localised around?
 Can't we just let the localised version override the non-localised version?]
 
 Currently the localization bit is the least significant sort criteria, that 
 means that the localised version always follows the non-localised version
 immediately.
 
 <Changed for KDE 3.0>
 Entries that are being read from a location other than the location to
 which is written back are marked as "default" and will be added both as
 normal entry as well as an entry with the key marked as default.
 
 When entries are written to disk, it is checked whether the entry to write 
 is equal to the default, if so the entry will not be written. The default
 entry always follows directly after the normal entry, due to the sorting.
 (After that the localised version follows)
 
 When entries are written to disk, it is checked whether the entry to write 
 is equal to the default, if so the entry will not be written.
 </Changed>
 
 Open question:
 Should unmodified entries that are written back be compared with the default
 too? This seems to be mostly a transition issue.
 
 <Changed during KDE 3.0 / 3.2>
 Extra functions:
 
 bool isEntryImmutable(key); // Can entry be modified?
 bool hasDefault(key); // Is there a system wide default set for the entry?
 void revertToDefault(key); // Restore to default
 void deleteEntry(key); // Remove entry
 
 Note that there is a subtle difference between revertToDefault() and deleteEntry().
 revertToDefault() will change the entry to the default value set by the system 
 administrator (Via e.g. $KDEDIR/share/config) or, if no such default was set,
 non-existent.
 deleteEntry() will make the entry non-existent.
 
 Entries are marked "immutable" if the key is followed by [$i]. This means
 that a user can not override these entries.
 
 Entries can be marked as deleted if they are followed by [$d]. This
 is needed if the system administrator has specified a default value but the
 entry was deleted (made 'non-existant'). In that case we can't just leave 
 the entry out since that would mean we get the default from the system 
 administrator back the next time we read the file.
 </changed>
 
 When an entry is read with readEntry(key, defaultValue), non-existing
 entries will return "defaultValue" while hasKey(key) will return "false"
 for such entries.
 
 Currently all entries are stored in memory. When KConfig is "sync()'ed"
 it reads the file that it is about to overwrite (for the second time), it 
 then merges in the entries it has in memory and writes the result back to 
 the file. It does NOT update its map of entries in memory with the entries
 (re)read from disk. It only updates the entries in memory when 
 "reparseConfiguration()" is called.
 
 
 Open Question: The standard writeEntry() function returns the original value,
 is this needed? Nobody seems to use it. 
 
 Open Question: The bPersistent flag doesn't seem to be used... could it be removed?
 
 Open Question: Is the bNLS flag needed? Localised entries seem to be mostly
 useful for default files, are they ever created by the user itself?
 
 Open Question: Would it be worthwhile to lock a user option that is equal to the 
 default so that it doesn't change when the default changes?
 
 
 KDE3.0 Changes
 ==============
 
 *) writeEntry now returns void instead of QString.
 *) deleteEntry functions added
 
 
 ------------------------------------------------------------------------------
 
 KConfig XT
 ==========
 
 My buzzword picker offered KConfig XT ("eXtended Technology") and KConfig NG 
 ("Next Generation").  Since the planned changes are meant to be evolutionary 
 rather than revolutionary, KConfig NG was dropped.
 
 Goals
 =====
 
 * Have the default value for config entries defined in 1 place. Currently it is
 not uncommon to have them defined in three places:
   1) In the application that reads the setting in order to use it
   2) In the settings dialog when reading the setting
   3) In the settings dialog when selecting "Use defaults".
 
 * Provide type-information about config entries to facilitate "KConfEdit" like 
 tools. Ideally type-information also includes range-information; this is even
 mandatory if enums become an explicit type.
 
 * Facilitate the documentation of config entries.
 
 
 Instead of relying on the defaults that are hard-coded in the application, 
 rely on default configuration files being installed in $KDEDIR. The technical
 changes required for this are very minimal, it is mostly a change in policy.
 
 Type information can be provide by preceding every entry with a formalized 
 comment.
 
 Work to be done:
 * KConfig needs to be extended to provide access to the default values provided 
 by the default config files. KConfig already stores this information internally.
 (DONE)
 * A formal comment structure needs to be designed that can convey type-information.
 Preferably in such a way that it is easily parsable by both machine and user.
 * KConfig needs to be extended, or another class created, that is able to parse
 the formalized comments.
 * A tool needs to be developed that can assist developers with the generation
 and verification of default configuration files including type-information.
 
 Drawbacks:
 * We rely on default configuration files being properly installed. 
 * The user can break applications by making improper modifications to these 
 files.
 * It is not possible to store defaults settings in a config file that are 
 of a dynamic nature. Examples are settings derived from other settings, 
 e.g. a color setting could be derived from the current color theme, or
 e.g. the default high score user name which is determined by the user
 currently logged in.
 
 
 Some random ideas:
 * The format of the entries would be something like this:
 
 [Mail Settings]
 #!Type=string
 #!Description=SMTP server to use for sending mail
 #!Description[nl]=SMTP server voor het versturen van mail
 Host=wantelbos.zogje.fr
 
 - the type could be subclassed more, e.g. strings can be "email", "hostname",
   "url", etc.
 
 - having translations in these files is very arguable. external po's would be
   better.
 
 
 
 Class overview
 
                        KConfigBase
                             |
                             v
  KConfigBackend  <-----> KConfig <------> KConfigSkeleton           /--< myapp.kcfg
        |                    |                    |                 /
        v                    v                    |*---------------<
 KConfigINIBackend      KSimpleConfig             |kconfig_compiler \
                                                  |                  \--< myconfig.kcfg-codegen
                                                  v                                                    
                                              MyConfig <-----KConfigDialogManager----> MyConfigWidget *---< myconfigwidget.ui
                                                                                                       uic
 
 KConfigBase: defines API for generic config class
 
 KConfig: functional generic config class that supports merging of cascaded
          configuration files
 
 KSimpleConfig: functional generic config class without support for cascading
                configuration files.
 
 KConfigBackend: defines API for config backend, t.i. the actual handling
                 of the storage method and storage format.
 
 KConfigINIBackend: the standard (and only one so far) class that implements
                    the config backend using the file-based .INI format
                    for configuration files
 
 KConfigSkeleton: base class for deriving classes that store application
                  specific options providing type-safety and single-point
                  defaults.
 
 MyConfig: An application specific class that offers configuration options
           to the applications via variables or accessor functions and that
           handles type-safety and defaults. MyConfig is just an example
           name, the application developer choses the actual name.
 
 myapp.kcfg: File describing the configuration options used by a specific
             application. myapp.kcfg is just an example name, the application
             developer choses the actual name.
 
 myconfig.kcfg-codegen: Implementation specific code generation instructions
                        for the MyConfig class. myconfig.kcfg-codegen is
                        just an example name, the application developer
                        choses the actual name.
 
 KConfigDialogManager: Class that links widgets in a dialog up with their
                       corresponding configuration options in a configuration
                       object derived from KConfigSkeleton.
 
 MyConfigWidget: Dialog generated from a .ui description file. Widget names
                 in the dialog that start with "kcfg_" refer to configuration
                 options.