Merge lp:~vila/bzr/996401-doc-config into lp:bzr

[Vincent Ladeuil]

Clarify option references expansion for `bzr config`.

This addresses bug #996401 by clarifying the command online help especially
around when option references are expanded.

Option references are described in bzrlib/help_topics/en/configuration.txt
which still seems to be the best place for that.

[John A Meinel (jameinel)]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 9/18/2012 8:42 PM, Vincent Ladeuil wrote:
> Vincent Ladeuil has proposed merging lp:~vila/bzr/996401-doc-config
> into lp:bzr.
>
> Requested reviews: bzr-core (bzr-core) Related bugs: Bug #996401 in
> Bazaar: "'bzr config' fails to display config templates referring
> to "unknown" options" https://bugs.launchpad.net/bzr/+bug/996401
>
> For more details, see:
> https://code.launchpad.net/~vila/bzr/996401-doc-config/+merge/124984
>
> This addresses bug #996401 by clarifying the command online help
> especially around when option references are expanded.
>
> Option references are described in
> bzrlib/help_topics/en/configuration.txt which still seems to be the
> best place for that.
>

 merge: approve

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Using GnuPG with Mozilla - http://www.enigmail.net/

iEYEARECAAYFAlBZTLgACgkQJdeBCYSNAAN6VgCfaopIU9M+UmUrNToA77LE02jS
s38An2lcvtTnYDUApvJrf5qJh1cd/wIz
=1j3N
-----END PGP SIGNATURE-----

review: Approve

[Vincent Ladeuil (vila)]

sent to pqm by email

=== modified file 'bzrlib/config.py'
--- bzrlib/config.py	2012-09-17 08:45:19 +0000
+++ bzrlib/config.py	2012-09-18 16:46:28 +0000
@@ -4085,17 +4085,21 @@
 class cmd_config(commands.Command):
     __doc__ = """Display, set or remove a configuration option.
 
-    Display the active value for a given option.
+    Display the active value for option NAME.
 
     If --all is specified, NAME is interpreted as a regular expression and all
-    matching options are displayed mentioning their scope. The active value
-    that bzr will take into account is the first one displayed for each option.
-
-    If no NAME is given, --all .* is implied.
-
-    Setting a value is achieved by using name=value without spaces. The value
+    matching options are displayed mentioning their scope and without resolving
+    option references in the value). The active value that bzr will take into
+    account is the first one displayed for each option.
+
+    If NAME is not given, --all .* is implied (all options are displayed for the
+    current scope).
+
+    Setting a value is achieved by using NAME=value without spaces. The value
     is set in the most relevant scope and can be checked by displaying the
     option again.
+
+    Removing a value is achieved by using --remove NAME.
     """
 
     takes_args = ['name?']

=== modified file 'doc/en/release-notes/bzr-2.6.txt'
--- doc/en/release-notes/bzr-2.6.txt	2012-09-14 17:22:35 +0000
+++ doc/en/release-notes/bzr-2.6.txt	2012-09-18 16:46:28 +0000
@@ -63,6 +63,9 @@
 
 .. Improved or updated documentation.
 
+* Clarify ``bzr config`` usages especially around other option references
+  expansion. (Vincent Ladeuil, #996401)
+
 API Changes
 ***********
 

=== modified file 'doc/en/user-guide/configuring_bazaar.txt'
--- doc/en/user-guide/configuring_bazaar.txt	2011-05-02 08:15:59 +0000
+++ doc/en/user-guide/configuring_bazaar.txt	2012-09-18 16:46:28 +0000
@@ -129,6 +129,13 @@
 Each configuration file is associated with a given scope whose name is
 displayed before each set of defined options.
 
+If you need to look at a specific option, you can use::
+
+  bzr config <option>
+
+This will display only the option value and is intended to be used in
+scripts.
+
 Modifying the active configuration
 ----------------------------------
 
@@ -136,6 +143,29 @@
 
   bzr config opt=value
 
+An option value can reference another option by enclosing it in curly
+braces::
+
+  bzr config opt={other_opt}/subdir
+
+If ``other_opt`` is set to ``'root``, ``bzr config opt`` will display::
+
+  root/subdir
+
+Note that when ``--all`` is used, the references are left as-is to better
+reflect the content of the config files and make it easier to organize them::
+
+  bzr config --all .*opt
+
+  bazaar:
+    [DEFAULT]
+    opt = {other_opt}/subdir
+    other_opt = root
+
+
+
+
+
 To remove an option use::
 
   bzr config --remove opt