Rev 5522: Fix some tweaks from review. in file:///home/vila/src/bzr/experimental/config/

[Vincent Ladeuil]

At file:///home/vila/src/bzr/experimental/config/

------------------------------------------------------------
revno: 5522
revision-id: v.ladeuil+lp at free.fr-20101202083525-okkgcwlpf9d0hv90
parent: v.ladeuil+lp at free.fr-20101124171736-wpoioh4an96csyik
committer: Vincent Ladeuil <v.ladeuil+lp at free.fr>
branch nick: doc-new-config
timestamp: Thu 2010-12-02 09:35:25 +0100
message:
  Fix some tweaks from review.
-------------- next part --------------
=== modified file 'doc/developers/configuration.txt'
--- a/doc/developers/configuration.txt	2010-11-12 15:12:58 +0000
+++ b/doc/developers/configuration.txt	2010-12-02 08:35:25 +0000
@@ -39,7 +39,7 @@
 * Defining a new option requires adding a new method in the ``Config``
   object to get access to features like:
 
-  * should the option be inheritd by more specific sections,
+  * should the option be inherited by more specific sections,
 
   * should the inherited value append the relative path between the
     section one and the location it applies to.
@@ -49,6 +49,10 @@
 
   * priority between sections and various config files
 
+  A related problem is that, in the actual implementation, some
+  configuration options have defined methods, other don't and this is
+  inconsistent.
+
 * Access to the 'active' configuration option value from the command line
   doesn't give access to specific section.
 
@@ -96,11 +100,11 @@
   specific than another. (This may not be a problem in real life since
   longer globs are generally more specific than shorter ones and explicit
   paths should also be longer than matching globs. That may leave a glob and
-  a path of equal lenght in a grey area but in practive using ``bzr config``
+  a path of equal length in a gray area but in practice using ``bzr config``
   should give enough feedback to address them).
 
 * Internally, configuration files (and their fallbacks, ``bazaar.conf`` and
-  ``locatons.conf`` for ``branch.conf``) are read every time *one* option is
+  ``locations.conf`` for ``branch.conf``) are read every time *one* option is
   queried. Likewise, setting or deleting a configuration option implies
   writing the configuration file *immediately* after re-reading the file to
   avoid racing updates.
@@ -119,10 +123,11 @@
 
 * There is no easy way to define dicts (the most obvious one being to use a
   dedicated section which is already overloaded). Using embedded sections
-  for this would not be practivcal either if we keep using a no-name section
-  for default values. As a last resort, the value of such a configuration
-  option can be bencoded but that won't be user-friendly. This is not a big
-  concern so far as very few needs required dicts as option values.
+  for this would not be practical either if we keep using a no-name section
+  for default values. In a few known cases, a bencoded dict is stored in a
+  config value, so while this isn't user-friendly, not providing a better
+  alternative shouldn't be a concern.
+
 
 Proposed implementation
 =======================
@@ -132,13 +137,13 @@
 ------------------------------
 
 While of course configurations files can be versioned they are not intended
-to be accessed in sync with the files they refer too (one can imagine
+to be accessed in sync with the files they refer to (one can imagine
 handling versioned properties this way but this is *not* what the bazaar
 configuration files are targeted at). ``bzr`` will always refer to
 configuration files as they exist on disk when an option is queried or set.
 
 The configuration files are generally local to the file system but some of
-them can be accessed remotely (branch.conf, repo.conf).
+them can be accessed remotely (``branch.conf``, ``repo.conf``).
 
 
 Naming
@@ -170,10 +175,12 @@
 expect their content to be validated. Instead, the code using options should
 be ready to handle *invalid* values by warning the user and fallback to a
 default value. Likely, if an option is not defined in any configuration
-file, the code should fallback to a default value.
+file, the code should fallback to a default value (helpers should be
+provided by the API to handle common cases, warning the user, getting a
+particular type of value, returning a default value).
 
 This also ensures compatibility with values provided via environment
-variables of from the command line.
+variables or from the command line.
 
 Interpolation
 -------------
@@ -321,7 +328,7 @@
 
 Depending on the files involved, a working tree, branch or repository object
 should be provided to access the corresponding configuration files. Note
-that providing a working tree object also implicitely provides the
+that providing a working tree object also implicitly provides the
 associated branch and repository object so only one of them is required (or
 none for configuration files specific to the user like bazaar.conf and
 locations.conf).