Rev 6335: Better tweaks (the value is not a property of the option). in file:///home/vila/src/bzr/reviews/doc/

[Vincent Ladeuil]

At file:///home/vila/src/bzr/reviews/doc/

------------------------------------------------------------
revno: 6335
revision-id: v.ladeuil+lp at free.fr-20111201114005-4ctbmk5nnzoqeh2b
parent: v.ladeuil+lp at free.fr-20111201105253-zcd41vhd2jpf9g1g
committer: Vincent Ladeuil <v.ladeuil+lp at free.fr>
branch nick: doc
timestamp: Thu 2011-12-01 12:40:05 +0100
message:
  Better tweaks (the value is not a property of the option).
-------------- next part --------------
=== modified file 'doc/developers/configuration.txt'
--- a/doc/developers/configuration.txt	2011-12-01 10:52:53 +0000
+++ b/doc/developers/configuration.txt	2011-12-01 11:40:05 +0000
@@ -11,9 +11,11 @@
 As a Bazaar developer there are three things you need to know about
 configuration.
 
-1: To get a value, you construct or get a reference to a ConfigStack
-subclass that's relevant to the context where you want to look up a value.
-For instance, given a branch::
+1. Get a value.
+
+You construct or get a reference to a ConfigStack subclass that's relevant
+to the context where you want to look up a value. For instance, given a
+branch::
 
   print branch.get_config_stack().get('log_format')
 
@@ -21,19 +23,24 @@
 The value returned is of the type declared for that Option and if nothing
 is specifically declared you will get the default for that option.
 
-2: To add a new option, you add a new `Option` to the `option_registry`,
-either inside ``bzrlib/config.py`` or during initialization of your
-plugin.  New plugins should have systematic hierarchical names so that
-related values are grouped together.  ::
+2. Add a new option.
+
+You add a new ``Option`` to the ``option_registry``, either inside
+``bzrlib/config.py`` or during initialization of your plugin. New plugins
+should have systematic hierarchical names so that related values are grouped
+together::
 
   option_registry.register(
       Option('dirstate.fdatasync', default=True,
             from_unicode=bool_from_store,
             help="Flush dirstate changes onto physical disk? ...."))
 
-3: There is (as of late 2011) some older and some newer configuration
-code.  The old code has specific methods for various checks or uses
-classes like `GlobalConfig`.  Don't add to to it; try to remove it.
+
+3. Old and new configuration code.
+
+There is (as of late 2011) some older and some newer configuration code. The
+old code has specific methods for various checks or uses classes like
+``GlobalConfig``.  Don't add to to it; try to remove it.
 
 Option
 ------
@@ -43,10 +50,6 @@
 * name: a name: a valid python identifier (even if it's not used as an
   identifier in python itself). This is also used to register the option.
 
-* a value: a unicode string. By using ``from_unicode`` you can turn this
-  string into a more appropriate representation (a list of unicode strings
-  for example).
-
 * from_unicode: a callable accepting a unicode string and returning a
   suitable value for the option. If the string cannot be coerced it should
   return None.
@@ -60,12 +63,17 @@
 
 * help: a doc string describing the option, the first line should be a
   summary and can be followed by a blank line and a more detailed
-  explanation. This will be displayed to the user with ``bzr help <option
-  name>``.
+  explanation. This will be displayed to the user with::
+
+    bzr help <option name>
 
 * invalid: the action to be taken when an invalid value is encountered in a
   store (during a Stack.get()).
 
+The value of an option is a unicode string or ``None`` if it's not
+defined. By using ``from_unicode`` you can turn this string into a more
+appropriate representation (a list of unicode strings for example).
+
 Sections
 --------
 
@@ -151,8 +159,8 @@
 Stacks
 ------
 
-An option can take different values depending on the context it is used. Such
-a context can involve configuration files, options from the command line,
+An option can take different values depending on the context it is
+used. This can involve configuration files, options from the command line,
 default values in bzrlib and then some.
 
 Such a context is implemented by creating a list of ``Section`` stacked upon