readme: format properly & add details

README.md

@@ -7,12 +7,52 @@ Shrlok listens in the background on a Unix socket for a small header followed by
 data and pushes this data in a directory with some basic treatment. For example,
 text pushed to Shrlok is put into a `pre` tag of an HTML page.
 
-The current expected format is described at the top of the `shrlok.py` module.
 
-Supported types:
 
-- `txt`: put into a `pre` tag in an HTML page;
-- `raw`: put as is.
+Usage
+-----
 
-Example: TODO
+See the `share.sh` script to see how data can be sent to the socket from the
+shell.
 
+### Packet format
+
+The current expected format is described at the top of the `shrlok.py` module,
+but here is the short version:
+
+1. A packet length, as ASCII digits for convenience, ended with a null byte;
+2. A JSON header, ended with a null byte;
+3. Data.
+
+The packet length counts the JSON header, its null byte and the data length, not
+itself nor its own null byte terminator.
+
+The header must contain the key "type" with a supported type value.
+
+Example:
+
+``` python
+28\0{"type":"txt"}\0hello shrlok!
+```
+
+Supported types are:
+
+- `txt`: the data will be put in `pre` tags into an HTML page;
+- `raw`: the data will be written without modifications.
+
+### Header options
+
+| Key   | Value                                 | Supported by |
+|-------|---------------------------------------|--------------|
+| name  | file name (has precedence over `ext`) | raw          |
+| ext   | file extension                        | raw          |
+| title | Web page title                        | txt          |
+
+
+
+About
+-----
+
+I needed something to push stuff into the public folders of a Web server
+possibly from remote, and this is my own cute over-engineered solution that
+refuses to use TCP. Ask Kadaztrof what the name means because I don't know?