Rev 5755: Add some documentation about option and sections. in file:///home/vila/src/bzr/experimental/config/

[Vincent Ladeuil]

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

------------------------------------------------------------
revno: 5755
revision-id: v.ladeuil+lp at free.fr-20110408145929-las6n20ari31dtan
parent: v.ladeuil+lp at free.fr-20110408141111-84ypaqkii5vgsd0c
committer: Vincent Ladeuil <v.ladeuil+lp at free.fr>
branch nick: config-section
timestamp: Fri 2011-04-08 16:59:29 +0200
message:
  Add some documentation about option and sections.
-------------- next part --------------
=== added file 'doc/developers/configuration.txt'
--- a/doc/developers/configuration.txt	1970-01-01 00:00:00 +0000
+++ b/doc/developers/configuration.txt	2011-04-08 14:59:29 +0000
@@ -0,0 +1,23 @@
+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
+
+Sections
+--------
+
+Options are grouped into sections which share some properties with the well
+known dict objects:
+
+- the key is the name,
+- you can get, set and remove an option,
+- the value is a unicode string.
+
+MutableSection are needed to set or remove an option, ReadOnlySection should
+be used otherwise.
+

=== modified file 'doc/developers/index.txt'
--- a/doc/developers/index.txt	2011-01-06 06:26:23 +0000
+++ b/doc/developers/index.txt	2011-04-08 14:59:29 +0000
@@ -36,9 +36,10 @@
 .. toctree::
    :maxdepth: 1
 
+   configuration
+   fetch
    transports
    ui
-   fetch
 
 Releasing and Packaging
 =======================

=== modified file 'doc/en/user-guide/configuring_bazaar.txt'
--- a/doc/en/user-guide/configuring_bazaar.txt	2011-02-07 01:39:42 +0000
+++ b/doc/en/user-guide/configuring_bazaar.txt	2011-04-08 14:59:29 +0000
@@ -37,6 +37,24 @@
 which shouldn't be reached by the proxy.  (See
 <http://docs.python.org/library/urllib.html> for more details.)
 
+Various ways to configure
+-------------------------
+
+As shown in the example above, there are various ways to
+configure Bazaar, they all share some common properties though,
+an option has:
+
+- a name which is generally a valid python identifier,
+
+- a value which is a string. In some cases, Bazzar will be able
+  to recognize special values like 'True', 'False' to infer a
+  boolean type, but basically, as a user, you will always specify
+  a value as a string.
+
+Options are grouped in various contexts so their name uniquely
+identify them in this context. When needed, options can be made
+persistent by recording them in a configuration file.
+
 
 Configuration files
 -------------------