From 82954c1c2984f1ad1c667353d02b5760862a673d Mon Sep 17 00:00:00 2001
From: varyoo <varyoo@users.noreply.github.com>
Date: Tue, 25 Jul 2017 22:14:01 +0200
Subject: [PATCH] resolve #789 (#791)

---
 middleware/dnstap/README.md | 43 +++++++++++++++++++++++++++++++------
 1 file changed, 36 insertions(+), 7 deletions(-)

diff --git a/middleware/dnstap/README.md b/middleware/dnstap/README.md
index a9d47d501..f8b710998 100644
--- a/middleware/dnstap/README.md
+++ b/middleware/dnstap/README.md
@@ -1,20 +1,49 @@
 # Dnstap
 
+*dnstap* enables logging to dnstap, a flexible, structured binary log format for DNS software: http://dnstap.info.
+
+There is a buffer, expect at least 13 requests before the server sends its dnstap messages to the socket.
+
 ## Syntax
 
-`dnstap SOCKET [full]`
+~~~ txt
+dnstap SOCKET [full]
+~~~
 
 * **SOCKET** is the socket path supplied to the dnstap command line tool.
-* `full` to include the wire-format dns message.
+* `full` to include the wire-format DNS message.
+
+## Examples
+
+Log information about client requests and responses to */tmp/dnstap.sock*.
+
+~~~ txt
+dnstap /tmp/dnstap.sock
+~~~
+
+Log information including the wire-format DNS message about client requests and responses to */tmp/dnstap.sock*.
+
+~~~ txt
+dnstap /tmp/dnstap.sock full
+~~~
 
 ## Dnstap command line tool
 
-```sh
+~~~ sh
 go get github.com/dnstap/golang-dnstap
 cd $GOPATH/src/github.com/dnstap/golang-dnstap/dnstap
 go build
-./dnstap -u /tmp/dnstap.sock
-./dnstap -u /tmp/dnstap.sock -y
-```
+./dnstap
+~~~
 
-There is a buffer, expect at least 13 requests before the server sends its dnstap messages to the socket.
+The following command listens on the given socket and decodes messages to stdout.
+
+~~~ sh
+dnstap -u /tmp/dnstap.sock
+~~~
+
+The following command listens on the given socket and saves message payloads to a binary dnstap-format log file.
+
+~~~ sh
+dnstap -u /tmp/dnstap.sock -w /tmp/test.dnstap
+~~~