Properties: made automatch in bcfg2.conf a default, not absolute; cleaned up docs

3 files changed, 31 insertions, 14 deletions

diff --git a/doc/server/plugins/connectors/properties.txt b/doc/server/plugins/connectors/properties.txt
index b1f92c3d2..9e1100610 100644
--- a/doc/server/plugins/connectors/properties.txt
+++ b/doc/server/plugins/connectors/properties.txt
@@ -89,11 +89,12 @@ Automatch
 
 .. versionadded:: 1.3.0
 
-You can enable ``XMLMatch()`` for all Property files by setting
-``automatch`` to ``true`` in the ``[properties]`` section of
-``bcfg2.conf``.  This makes ``metadata.Properties`` values
-lxml.etree._Element objects that contain only matching data.  (This
-makes it impossible to do
+You can enable
+:func:`Bcfg2.Server.Plugins.Properties.PropertyFile.XMLMatch()` for
+all Property files by setting ``automatch`` to ``true`` in the
+``[properties]`` section of ``bcfg2.conf``.  This makes
+``metadata.Properties`` values :class:`lxml.etree._Element` objects
+that contain only matching data.  (This makes it impossible to do
 :ref:`server-plugins-connectors-properties-write-back` as a
 side-effect.)
 
@@ -114,7 +115,10 @@ simply::
     %}
 
 You can also enable automatch for individual Property files by setting
-the attribute ``automatch="true"`` in the top-level ``<Property>`` tag.
+the attribute ``automatch="true"`` on the top-level ``<Property>``
+tag.  Conversely, if automatch is enabled by default in
+``bcfg2.conf``, you can disable it for an individual Property file by
+setting ``automatch="false"`` on the top-level ``<Property>`` tag.
 
 If you want to see what ``XMLMatch()``/automatch would produce for a
 given client on a given Properties file, you can use :ref:`bcfg2-info
@@ -127,6 +131,15 @@ it anyway with ``-f``::
 
     bcfg2-info automatch -f props.xml foo.example.com
 
+.. note::
+
+    Be sure to notice that enabling automatch changes the type of the
+    data in ``metadata.Properties``; with automatch disabled, the
+    values of the ``metadata.Properties`` dict are
+    :class:`Bcfg2.Server.Plugins.Properties.PropertyFile` objects.
+    With automatch enabled, they are :class:`lxml.etree._Element`
+    objects.
+
 .. _server-plugins-connectors-properties-write-back:
 
 Writing to Properties files
@@ -135,7 +148,8 @@ Writing to Properties files
 .. versionadded:: 1.2.0
 
 If you need to make persistent changes to properties data, you can use
-the ``write`` method of the ``PropertyFile`` class::
+the ``write`` method of the
+:class:`Bcfg2.Server.Plugins.Properties.PropertyFile` class::
 
     {% python
     import lxml.etree
diff --git a/src/lib/Bcfg2/Server/Plugins/Properties.py b/src/lib/Bcfg2/Server/Plugins/Properties.py
index 5b48a2b8f..1b925ce46 100644
--- a/src/lib/Bcfg2/Server/Plugins/Properties.py
+++ b/src/lib/Bcfg2/Server/Plugins/Properties.py
@@ -125,12 +125,15 @@ class Properties(Bcfg2.Server.Plugin.Plugin,
         SETUP = core.setup
 
     def get_additional_data(self, metadata):
-        automatch = self.core.setup.cfp.getboolean("properties", "automatch",
-                                                   default=False)
+        if self.core.setup.cfp.getboolean("properties", "automatch",
+                                          default=False):
+            default_automatch = "true"
+        else:
+            default_automatch = "false"
         rv = dict()
         for fname, pfile in self.store.entries.items():
-            if (automatch or
-                pfile.xdata.get("automatch", "false").lower() == "true"):
+            if pfile.xdata.get("automatch",
+                               default_automatch).lower() == "true":
                 rv[fname] = pfile.XMLMatch(metadata)
             else:
                 rv[fname] = copy.copy(pfile)
diff --git a/src/sbin/bcfg2-info b/src/sbin/bcfg2-info
index 4725e05a3..95a18b608 100755
--- a/src/sbin/bcfg2-info
+++ b/src/sbin/bcfg2-info
@@ -445,9 +445,9 @@ class infoCore(cmd.Cmd, Bcfg2.Server.Core.BaseCore):
 
         pname, client = alist
         try:
-            automatch = self.core.setup.cfp.getboolean("properties",
-                                                       "automatch",
-                                                       default=False)
+            automatch = self.setup.cfp.getboolean("properties",
+                                                  "automatch",
+                                                  default=False)
 
             pfile = self.plugins['Properties'].store.entries[pname]
             if (not force and