Rev 6334: Add a contents directive and fold the initial remarks about config option in the right section. in file:///home/vila/src/bzr/reviews/doc/

[Vincent Ladeuil]

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

------------------------------------------------------------
revno: 6334
revision-id: v.ladeuil+lp at free.fr-20111201105253-zcd41vhd2jpf9g1g
parent: mbp at canonical.com-20111201081230-j76ar868bz9lrd9n
committer: Vincent Ladeuil <v.ladeuil+lp at free.fr>
branch nick: doc
timestamp: Thu 2011-12-01 11:52:53 +0100
message:
  Add a contents directive and fold the initial remarks about config option in the right section.
-------------- next part --------------
=== modified file 'doc/developers/configuration.txt'
--- a/doc/developers/configuration.txt	2011-12-01 08:12:30 +0000
+++ b/doc/developers/configuration.txt	2011-12-01 10:52:53 +0000
@@ -1,12 +1,9 @@
 Configuring Bazaar
 ==================
 
-A configuration option has:
-
-* a name: a valid python identifier (even if it's not used as an
-  identifier in python itself)
-
-* a value: a unicode string or a list of unicode strings.
+.. contents::
+   :depth: 2
+
 
 The short story
 ---------------
@@ -46,6 +43,14 @@
 * 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.
+
 * default: the default value that Stack.get() should return if no
   value can be found for the option.
 
@@ -55,11 +60,8 @@
 
 * 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.
-
-* 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.
+  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()).