docs: rewrite using manpage style (#327)

This still needs cleanup, but this is a first pass the cleans some
cruft and documents our style (in middleware.md) and makes all the
docs match that style.

middleware/middleware.md

@@ -0,0 +1,24 @@
+# Middleware
+
+
+# Documentation
+
+Each middleware should have a README.md explaining what the middleware does and how it is
+configured. The file should have the following layout:
+
+* Title: use the middleware's name
+* Subsection titled: "Syntax"
+* Subsection titled: "Examples"
+
+More sections are of course possible.
+
+## Style
+
+We use the Unix manual page style:
+
+* The name of middleware in the running text should be italic: *middleware*.
+* all CAPITAL: user supplied argument, in the running text references this use strong text: `**`:
+  **EXAMPLE**.
+* Optional text: in block quotes: `[optional]`.
+* Use three dots to indicate multiple options are allowed: `arg...`.
+* Item used literal: `literal`.