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/errors/README.md

@@ -1,18 +1,22 @@
 # errors
 
-`errors` allows you to set custom error pages and enable error logging.
-By default, error responses (HTTP status >= 400) are not logged and the client receives a plaintext error message.
-Using an error log, the text of each error will be recorded so you can determine what is going wrong without exposing those details to the clients. With error pages, you can present custom error messages and instruct your visitor with what to do.
-
+*errors* enables error logging.
+TODO: what are errors.
 
 ## Syntax
 
 ~~~
-errors [logfile]
+errors [LOGFILE]
 ~~~
 
-* `logfile` is the path to the error log file to create (or append to), relative to the current working directory. It can also be stdout or stderr to write to the console, syslog to write to the system log (except on Windows), or visible to write the error (including full stack trace, if applicable) to the response. Writing errors to the response is NOT advised except in local debug situations. The default is stderr.
-The above syntax will simply enable error reporting on the server. To specify custom error pages, open a block:
+* **LOGFILE** is the path to the error log file to create (or append to), relative to the current
+  working directory. It can also be `stdout` or `stderr` to write to the console, syslog to write to the
+  system log (except on Windows), or visible to write the error (including full stack trace, if
+  applicable) to the response. Writing errors to the response is NOT advised except in local debug
+  situations. The default is stderr. The above syntax will simply enable error reporting on the
+  server. To specify custom error pages, open a block:
+
+TODO(miek): check what is actually implemented and clean this up!
 
 ~~~
 errors {