Rev 5531: Clarify some points about configuration options. in file:///home/vila/src/bzr/experimental/config/

[Vincent Ladeuil]

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

------------------------------------------------------------
revno: 5531
revision-id: v.ladeuil+lp at free.fr-20110311170023-nhesi7mpamr8gkxm
parent: v.ladeuil+lp at free.fr-20110311143659-nb19fex1gt8sl11k
committer: Vincent Ladeuil <v.ladeuil+lp at free.fr>
branch nick: doc-new-config
timestamp: Fri 2011-03-11 18:00:23 +0100
message:
  Clarify some points about configuration options.
-------------- next part --------------
=== modified file 'doc/developers/configuration.txt'
--- a/doc/developers/configuration.txt	2011-02-03 10:45:03 +0000
+++ b/doc/developers/configuration.txt	2011-03-11 17:00:23 +0000
@@ -54,14 +54,16 @@
   inconsistent.
 
 * Access to the 'active' configuration option value from the command line
-  doesn't give access to specific section.
+  doesn't give access to the specific section.
 
-* Rules for configuration options are not clearly defined for remote
-  branches (they may differ between dumb and smart servers).
+* Rules for configuration options are not clearly defined for remote branches
+  (they may differ between dumb and smart servers the former will use the
+  local ``bazaar.conf`` and ``locations.conf`` files while later will use the
+  remote ones).
 
 * The features offered by the Bazaar configuration files should be easily
   accessible to plugin authors either by supporting plugin configuration
-  options in the configuration files or allowing plugin to define their
+  options in the configuration files or allowing the plugins to define their
   own configuration files.
 
 * While the actual configuration files support sections, they are used in
@@ -90,18 +92,19 @@
   subtree.
 
 * Since sections allow different definitions for the same option, a total
-  order should be defined between sections to select the right definition
-  for a given path. Allowing globs for section names is harmful in this
-  respect since the order is currently defined as being the lexicographical
-  one. The caveat here is that if the order is always defined for a given
-  set of sections it can change when one or several globs are modified and
-  the user may get surprising and unwanted results in these cases. The
-  lexicographical order is otherwise fine to define what section is more
-  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 length in a gray area but in practice using ``bzr config``
-  should give enough feedback to address them).
+  order should be defined between sections to select the right definition for
+  a given context (paths or globs for ``locations.conf`` but other schemes can
+  be used, window names for qbzr for exmaple). Allowing globs for section
+  names is harmful in this respect since the order is currently defined as
+  being the lexicographical one. The caveat here is that if the order is
+  always defined for a given set of sections it can change when one or several
+  globs are modified and the user may get surprising and unwanted results in
+  these cases. The lexicographical order is otherwise fine to define what
+  section is more 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 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
   ``locations.conf`` for ``branch.conf``) are read every time *one* option is