Update the documentation and fix its formatting

* Make the options-chart hackage-safe (hackage does not support
  markdown tables)
* Add --title and --server-name
* Elaborate the package's description

2 files changed, 34 insertions, 14 deletions

diff --git a/README.md b/README.md
index fd25dfb..f806920 100644
--- a/README.md
+++ b/README.md
@@ -8,26 +8,25 @@ Example usage:
 
     gopher-proxy --host foo.org --http-port 8080
 
-In this particular example, gopher-proxy would proxy the foo.org gopher server and bind its http service on `127.0.0.1:8080` (to be proxied to by another web server like `nginx`).
+In this particular example, gopher-proxy would proxy the `foo.org` gopher server and bind its http service on `127.0.0.1:8080` (to be proxied to by another web server like `nginx`).
 
-There are these additional flags which allow tweaking of exact behavior as well:
+These are all optional flags which allow to change default behavior:
 
-option                | meaning
-----------------------|--------------------------------------------------------------------------------------------------------
-`--port`              | The port of the gopher server, defaults to `70`
-`--css-url`           | Use some specific css file instead of the default one.
-`--css-url`           | The http path of the css file, defaults to `/gopher-proxy.css` (should be changed, if your gopher server has a file with the same name
-`--base-url`          | The path of the directory which will appear as root directory of gopher-proxy to the user, defaults to `/`. Should be changed if you configured your proxying web server to expose gopher-proxy as, say `/gopher-space/`.
-`--listen-public`     | If this flag is set, gopher-proxy will accept connections on its public IP address(es).
-`--default-mime-type` | Mime type to use if spacecookie can't guess it, defaults to "application/octet-stream"
-`--timeout`           | Timeout when connecting in milliseconds, defaults to 10 seconds.
+* `--port`: The port of the gopher server, defaults to `70`
+* `--css-url`: Use some specific css file instead of the default one.
+* `--css-url`: The http path of the css file, defaults to `/gopher-proxy.css` (should be changed, if your gopher server has a file with the same name
+* `--base-url`: The path of the directory which will appear as root directory of gopher-proxy to the user, defaults to `/`. Should be changed if you configured your proxying web server to expose gopher-proxy as, say `/gopher-space/`.
+* `--listen-public`: If this flag is set, gopher-proxy will accept connections on its public IP address(es).
+* `--default-mime-type`: Mime type to use if spacecookie can't guess it, defaults to "application/octet-stream"
+* `--timeout`: connection timeout in milliseconds, defaults to 10 seconds.
+* `--server-name`: The server name of the server to proxy, defaults to the host name. This value is used to detect wether a menu item is pointing to another gopher server than the proxied one. This is particularly useful, if you use e. g. `127.0.0.1` instead of the public host name.
 
 ## Things to keep in mind
 
-* Your gopher server must send UTF-8-encoded gopher menus
+* Your gopher server must send UTF-8-encoded gopher responses
 * gopher-proxy might misinterpret certain content, because of the context-sensitive nature of gopher
 * gopher-proxy does not support Gopher+
 
 ## Roadmap
 
-[ ] Add Logging
+- [ ] Add Logging
diff --git a/gopher-proxy.cabal b/gopher-proxy.cabal
index 1242027..22101a8 100644
--- a/gopher-proxy.cabal
+++ b/gopher-proxy.cabal
@@ -4,7 +4,28 @@
 name:                gopher-proxy
 version:             0.1.0.2
 synopsis:            proxy gopher over http
-description:         A simple gopher-over-http proxy to http-ify gopher spaces.
+description:
+  @gopher-proxy@ allows to proxy gopher over HTTP, which is mainly useful for HTTP-ifying a specific gopher space.
+  .
+  A simple invocation looks like this:
+  .
+  @
+  gopher-proxy --host example.org --http-port 8080
+  @
+  .
+
+  In this particular example @gopher-proxy@ does the following things:
+  .
+  * Takes HTTP requests on @127.0.0.1:8080@ (to be used by a proxying web server, like nginx), converts those to gopher requests to @example.org@ and returns the gopher responses as HTTP responses
+  .
+  * Links menu items pointing to external servers to @gopher://@ URLs (this ensures that only one gopher server is proxied) and recognizes <https://en.wikipedia.org/wiki/Gopher_(protocol)#URL_links URL links> which are converted to normal HTML links
+  .
+  * Tries to guess the correct mime-type for every gopher-served file (as it is not included in the response) and wraps text files in a HTML container.
+  .
+  * And generally works hard to offer the best HTTP equivalent of a given gopher space :)
+  .
+  To learn about the other parameters for tweaking the behavior of @gopher-proxy@ <#readme see the readme>.
+
 license:             GPL-3
 license-file:        LICENSE
 author:              sternenseemann