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

1 files changed, 21 insertions, 7 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