From 6a578c95b6c20062e593e51f99501fbfe7af3017 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Damir=20Jeli=C4=87?= <poljar@termina.org.uk>
Date: Fri, 24 May 2019 13:48:51 +0200
Subject: [PATCH] README: Update the readme to the current pantalaimon version.

---
 README.md | 66 +++++++++++++++++++++++++++++++++++++++++++++----------
 setup.py  |  5 +++++
 2 files changed, 60 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index d48f0ab..5540117 100644
--- a/README.md
+++ b/README.md
@@ -1,30 +1,74 @@
 pantalaimon
 ===========
 
-A E2E aware matrix proxy daemon.
+Pantalaimon is an end-to-end encryption aware Matrix reverse proxy daemon.
+Pantalaimon acts as a good man in the midle that handles the encryption for you.
+
+Messages are transparently encrypted and decrypted for clients inside of
+pantalaimon.
 
-This still in an early development phase.
 
 Installation
-===========
+============
 
-The [Olm](https://git.matrix.org/git/olm/) C library is required to be installed
-before installing pantalaimon.
+The [Olm](https://gitlab.matrix.org/matrix-org/olm) C library is required to
+be installed before installing pantalaimon.
 
-Instalation works like usually with python packages:
+If your distribution provides packages for libolm it is best to use those, note
+that a recent version of libolm is required (3.1+). If your distribution doesn't
+provide a package building from source is required. Please refer to the Olm
+[readme](https://gitlab.matrix.org/matrix-org/olm/blob/master/README.md)
+to see how to build the C library from source.
+
+Installing pantalaimon works like usually with python packages:
 
     python setup.py install
 
+Pantalaimon can also be found on pypi:
+
+    pip install pantalaimon
+
+Do note that man pages can't be installed with pip.
+
 Usage
 =====
 
-Running the daemon is relatively easy:
+While pantalaimon is a daemon, it is mean to be run as your own user. It won't
+verify devices for you automatically, unless configured to do so, and requires
+user interaction to verify, ignore or blacklist devices.
 
-    pantalaimon https://example.org:443
+Pantalaimon requires a configuration file to run. The configuration file
+specifies one or more homeservers for pantalaimon to connect to.
 
-After running the daemon configure your client to connect to the daemon instead
+A minimal pantalaimon configuration looks like this:
+```dosini
+[local-matrix]
+Homeserver = https://localhost:8448
+ListenAddress = localhost
+ListenPort = 8009
+```
+
+The configuration file should be placed in `~/.config/pantalaimon/pantalaimon.conf`.
+
+The full documentation for the pantalaimons configuration can be found in
+the man page `pantalaimon(5)`.
+
+Now that pantalaimon is configured it can be run:
+
+    pantalaimon --log-level debug
+
+After running the daemon, configure your client to connect to the daemon instead
 of your homeserver. The daemon listens by default on localhost and port 8009.
 
-The listening address and port can be configured:
+Note that logging in to the daemon is required to start a sync loop for a user.
+After that clients can connect using any valid access token for the user that
+logged in. Multiple users per homeserver are supported.
 
-    pantalaimon -l 127.0.0.1 -p 8008 https://example.org:8008
+For convenience a systemd service file is provided.
+
+To control the daemon an interactive utility is provided in the form of
+`panctl`.
+
+`panctl` can be used to verify, blacklist or ignore devices, import or export
+session keys, or to introspect devices of users that we share encrypted rooms
+with.
diff --git a/setup.py b/setup.py
index a765df8..9023c46 100644
--- a/setup.py
+++ b/setup.py
@@ -2,6 +2,9 @@
 
 from setuptools import find_packages, setup
 
+with open('README.md') as f:
+    long_description = f.read()
+
 setup(
     name="pantalaimon",
     version="0.1",
@@ -10,6 +13,8 @@ setup(
     author_email="poljar@termina.org.uk",
     description=("A Matrix proxy daemon that adds E2E encryption "
                  "capabilities."),
+    long_description=long_description,
+    long_description_content_type="text/markdown",
     license="Apache License, Version 2.0",
     packages=find_packages(),
     install_requires=[