--- a/README	Tue Feb 24 17:48:00 2015 +0200
+++ b/README	Tue Feb 24 17:48:10 2015 +0200
@@ -1,3 +1,27 @@
 = pvl-hosts =
-DNS/DHCP hosts management for ISC bind9 and dhcpd
 
+DNS/DHCP hosts management/integration for ISC bind9 and dhcpd.
+
+Also includes network SNMP discovery.
+
+== Hosts ==
+The `pvl.hosts-* etc/hosts/test` tools read hosts files as input, which have an ini format, using section names as hostnames to configure attributes for that host:
+
+    [foo]
+        ip  = 127.0.0.1
+
+    [bar]
+        ip  = 127.0.0.2
+
+The default mechanism uses the basename of the given config file as the domain name, so this example file would generate something like the following output for use in a `zone "test" { ... }` zonefile:
+
+    $ pvl.hosts-dns --forward-zone=test etc/hosts/test
+    foo                               A     127.0.0.1
+    bar                               A     127.0.0.2
+
+And correspondingly, the reverse zone for 127.0.0.0/8:
+
+    $ pvl.hosts-dns --reverse-zone=127 etc/hosts/test
+    1.0.0                             PTR   foo.test.
+    2.0.0                             PTR   bar.test.
+