docs: recommend proper introducers.yaml syntax

add a test to exercise that this syntax is parseable, and another to point
out that the previously-recommended syntax was not

refs ticket:2862

docs/configuration.rst

@@ -919,8 +919,10 @@ introducer.furl``. To use two or more Introducers, choose a locally-unique
 ``private/introducers.yaml`` like this::
 
   introducers:
-    petname2:  furl = FURL2
-    petname3:  furl = FURL3
+    petname2:
+      furl: FURL2
+    petname3:
+      furl: FURL3
 
 Servers will announce themselves to all configured introducers. Clients will
 merge the announcements they receive from all introducers. Nothing will

src/allmydata/test/test_multi_introducers.py

@@ -92,6 +92,20 @@ class MultiIntroTests(unittest.TestCase):
         e = self.assertRaises(ValueError, Client, self.basedir)
         self.assertEquals(str(e), "'default' introducer furl cannot be specified in introducers.yaml; please fix impossible configuration.")
 
+SIMPLE_YAML = """
+introducers:
+  one:
+    furl: furl1
+"""
+
+# this format was recommended in docs/configuration.rst in 1.12.0, but it
+# isn't correct (the "furl = furl1" line is recorded as the string value of
+# the ["one"] key, instead of being parsed as a single-key dictionary).
+EQUALS_YAML = """
+introducers:
+  one: furl = furl1
+"""
+
 class NoDefault(unittest.TestCase):
     def setUp(self):
         # setup tahoe.cfg and basedir/private/introducers
@@ -119,6 +133,17 @@ class NoDefault(unittest.TestCase):
         tahoe_cfg_furl = myclient.introducer_furls[0]
         self.assertEquals(tahoe_cfg_furl, 'furl1')
 
+    def test_real_yaml(self):
+        self.yaml_path.setContent(SIMPLE_YAML)
+        myclient = Client(self.basedir)
+        tahoe_cfg_furl = myclient.introducer_furls[0]
+        self.assertEquals(tahoe_cfg_furl, 'furl1')
+
+    def test_invalid_equals_yaml(self):
+        self.yaml_path.setContent(EQUALS_YAML)
+        e = self.assertRaises(TypeError, Client, self.basedir)
+        self.assertEquals(str(e), "string indices must be integers")
+
     def test_introducerless(self):
         connections = {'introducers': {} }
         self.yaml_path.setContent(yamlutil.safe_dump(connections))