Improved documentation

Author: vanrein

P2P-TOOLKIT.MD

@@ -31,7 +31,7 @@ The p2p Toolkit consists of the following tools:
     The work modifies the message flow of TLS such that it can negotiate the
     desired independency; it also works together with classic implementations
     of TLS that insist on either the client or server role.  Symmetric TLS is
-    implemented in GnuTLS.
+    [implemented in GnuTLS](https://github.com/arpa2/gnutls-symmetry).
 
 
 ## Acknowledgements

README README.MDREADME renamed to README.MD

@@ -1,11 +1,35 @@
-README for synergy()
-====================
+# README for SocketSynergy
+
+> *SocketSynergy helps to connect peers behind firewalls.  It is a generic
+> solution to a problem that most peer-to-peer applications run into.*
 
 From: Rick van Rein <rick@openfortress.nl>
 
 
-Quickstart demo
----------------
+## Purpose
+
+The intention of SocketSynergy is to allow peers to connect in spite of
+*both* being behind a firewall.  This is traditionally considered
+impossible, because always one of the firewalls blocks.  That is a problem
+for peer-to-peer applications, but SocketSynergy makes it possible.  And
+easy, all it takes is another call `synergy()` on top of the general
+Socket API.
+
+The assumptions made by SocketSynergy are
+
+  * transparent addressing
+  * firewalls following the general
+    [BEHAVE WG](https://datatracker.ietf.org/wg/behave/charter/)
+    specifications
+
+Specifically note: There is no support for Network Address Translation.
+If we want the network to function, we should rely on IPv6.  Do have a look
+at the other elements in the
+[P2P Toolkit](P2P-TOOLKIT.MD)
+to learn how reasonable this assumption is.
+
+
+## Quickstart demo
 
 Following is a quick intro showing how to use the synergy() library
 call and, perhaps one day, syscall.
@@ -34,7 +58,9 @@ standard tool like netcat6::
 
 It is also possible to do the same things based on UDP.  Just give a
 first argument ``udp`` to ``listendemo`` and add a ``-u`` option
-to the ``nc6`` commandline.  Of course, with UDP there are no sharp
+to the ``nc6`` commandline.  Likewise, SCTP is possible.
+
+Of course, with UDP there are no sharp
 boundaries to the start and end of a session.  The trick used to
 open the port is sending out a UDP packet that, once again, drops
 as soon as it has crossed the last firewall protecting this domain.
@@ -46,8 +72,8 @@ remote firewalls might receive it and respond with RST, causing
 the incoming firewalls to close the just-punched hole).
 
 
-Code reference
---------------
+## Code reference
 
 This code was written based on RFC 2292, "Advanced Sockets API for
 IPv6", by W. Stevens and M. Thomas.
+