Update documentation accordingly

Author: aanriot

README.rst

@@ -24,8 +24,6 @@ Install the bind package and start the bind service.
 ---------------
 
 Manage the bind configuration file.
-This state can generate some basic zone files if a `records` entry is found in the
-`available_zones`' declaration for the zone (see `pillar.example` for how to write these)
 
 Example Pillar
 ==============
@@ -52,23 +50,6 @@ Example Pillar
               cat: 2.3.4.188
               rat: 1.2.3.231
               live: 1.2.3.236
-
-See *bind/pillar.example* for a more complete example.
-
-On the other hand, if no `records` entry exists, the zone file is not generated by this state
-rather than taken from `salt://zones`. See `pillar.example` for how to overwrite
-this URL.
-
-Example Pillar
-==============
-
-.. code:: yaml
-
-    bind:
-      configured_zones:
-        sub.domain.com:
-          type: master
-          notify: False
       configured_views:
         myview1:
           match_clients:
@@ -79,7 +60,38 @@ Example Pillar
             type: master
             notify: False
 
-See *bind/pillar.example*.
+See *bind/pillar.example* for a more complete example.
+
+Management of zone files
+========================
+
+`named.conf.local`
+------------------
+
+<zone> entries in `named.conf.local` will point to the file declared in
+
+* `bind:configured_zones:<zone>:file` (this takes precedence)
+* `bind:available_zones:<zone>:file`
+
+zone files
+----------
+
+The `config.sls` state will  iterate on `bind:available_zones` and manage
+<zone> files for each <zone> that has bind:available_zones:<zone>:file`
+declared.
+
+* If `bind:available_zones:<zone>:records` exist, a zone file will be created
+  using those records (see pillar.example for more details)
+* If `bind:available_zones:<zone>:records` is **NOT** declared,
+  `bind:available_zones:<zone>:file` should point to an existing zone file
+  that will be **sourced** by the formula.
+
+External zone files
+-------------------
+
+To use an external tool to manage the <zone> file, simply declare the location
+of the zone file in  `bind:configured_zones:<zone>:file` and **don't** add any
+entry for the <zone> in  `bind:available_zones`
 
 Notes
 =====