Merge lp:~vila/bzr/mergetool-doc into lp:bzr

[Vincent Ladeuil]

Clarify how `mergetool` templates should be used with `bzr config`.

Basde on an IRC discussion with mgz.

I think that should address
https://answers.launchpad.net/bzr/+question/196441 confusion.

[Martin Packman (gz)]

So, I don't like "the following will (rightly) break", and perhaps we don't want to give the "wrong" version at all, but perhaps it's useful for people doing a search on the error message? So, just tone down the "we write software that's hard to use on purpose" angle and this should be fine.

review: Approve

[lp:~vila/bzr/mergetool-doc]

6566. By Vincent Ladeuil on 2012-09-19

Tone down ;)

[Vincent Ladeuil (vila)]

Is that better ?

[Martin Packman (gz)]

Typo, 'conflit'. But actually I find the sentence still rather hard to read, let's see if I can help...

"""
Because mergetool and config itself both use curly braces as interpolation markers, trying to display the mergetool line results in the following problem:

...

To avoid this, config can be instructed not to try expanding variables:

...
"""

Something like that? This is user-focused after all, so they shouldn't really care too much about the details.

[lp:~vila/bzr/mergetool-doc]

6567. By Vincent Ladeuil on 2012-10-10

Don't explain gory details, most users won't care.

6568. By Vincent Ladeuil on 2012-10-10

Fix formattting.

[Vincent Ladeuil (vila)]

> Typo, 'conflit'. But actually I find the sentence still rather hard to read,
> let's see if I can help...

Thanks ;)

> Something like that? This is user-focused after all, so they shouldn't really
> care too much about the details.

Agreed, done.

[Vincent Ladeuil (vila)]

sent to pqm by email

=== modified file 'bzrlib/help_topics/en/configuration.txt'
--- bzrlib/help_topics/en/configuration.txt	2012-06-20 13:58:18 +0000
+++ bzrlib/help_topics/en/configuration.txt	2012-10-10 18:32:18 +0000
@@ -713,6 +713,22 @@
 
   bzr.mergetool.kdiff3 = kdiff3 {base} {this} {other} -o {result}
 
+Because ``mergetool`` and ``config`` itself both use curly braces as
+interpolation markers, trying to display the mergetool line results in the
+following problem::
+
+
+  $ bzr config bzr.mergetool.kdiff3='kdiff3 {base} {this} {other} -o {result}'
+  $ bzr config bzr.mergetool.kdiff3
+  bzr: ERROR: Option base is not defined while expanding "kdiff3 {base} {this} {other} -o {result}".
+
+To avoid this, ``config`` can be instructed not to try expanding variables::
+
+  $ bzr config --all bzr.mergetool.kdiff3
+  branch:
+    bzr.mergetool.kdiff3 = kdiff3 {base} {this} {other} -o {result}
+
+
 bzr.default_mergetool
 ~~~~~~~~~~~~~~~~~~~~~