From c3fa8b2a47d5d2ddf3c7ca6a1b0b511ef99f369d Mon Sep 17 00:00:00 2001
From: Tobias Diekershoff <tobias.diekershoff@gmx.net>
Date: Sat, 7 Jan 2023 19:36:22 +0100
Subject: [PATCH] updates to the README

---
 README.md | 88 +++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 79 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 29619ed..3ccab8d 100644
--- a/README.md
+++ b/README.md
@@ -1,20 +1,17 @@
 # Brew Server Blocklist
 
 Friendica publishes the server wide blocklists for other servers in the
-fediverse. This script will collect the blocklists of servers of your
+Fediverse. This script will collect the blocklists of servers of your
 choice and create a merged blocklist from them that you can then import
 into your own Friendica server.
 
-To make certain that you don't block just any instance in the fediverse
-because $somebody has it on their blocklist you assign _trustlevels_ to
-the correctnes of the blocklists of the other servers. Only when a server
-is blocked with a total trustlevel that is above a confidence level, it
+To make certain that you don't block just any instance in the Fediverse
+because $somebody has it on their blocklist you assign _trust levels_ to
+the correctness of the blocklists of the other servers. Only when a server
+is blocked with a total trust level that is above a confidence level, it
 will be added to resulting blocklist automatically. Otherwise the user
 will be ask if they want to add a node to their blocklist or not.
 
-The entries of your own servers blocklist will always gain enough trust
-so that they are added on the final blocklist again.
-
 ## Config file
 
 To use the script you have to create a config file. The structure of the
@@ -34,13 +31,86 @@ trust = 50
 trust = 90
 ```
 
-it assignes _trust_ values to nodes in the network. The node domain names
+it assigns _trust_ values to nodes in the network. The node domain names
 are given in the `[]`. These are the nodes that the script will collect
 the server blocklists from.
 
 Trust levels can be negative. Once their summed value does reach a value of
 100 the blocklist entry is trusted automatically without user interaction.
 
+## Installation
+
+You can install the script with [pipx](https://github.com/pypa/pipx) by running
+
+```
+pipx install git+https://git.friendi.ca/tobias/brewserverblocklist.git
+```
+
+Assuming pipx was installed correctly the script `brewserverblocklist` is now
+available on your system (or for your user) to be executed.
+
+## Usage
+
+### Creating a config file
+
+Before you can use the script, you have to define a configuration file.
+For details of the format of the file, see the section above. You might
+want to enter your own Friendica node and assigning it a trust value of 100.
+
+Trust values can have negative values. If you know an admin that has the
+opposite preference on their blocklist, you can add their node and assign
+a trust value of -100 to it.
+
+An example config file (lets call it `test.config`) might look like:
+
+```
+[myfriendicanode.com]
+trust = 100
+
+[coolnode.net]
+trust = 60
+
+[nicenode.net]
+trust = 40
+
+[othernicenode.com]
+trust = 30
+
+[bullshitnode.com]
+trust = -50
+```
+
+### Running the script
+
+You have to supply the file name of the configuration file on the command
+line when you run the script. This is done using the `-c` parameter.
+
+The script will then collect all the blocklists from the Friendica nodes in
+the configuration file and merge the lists. While merging, each entry in the
+combined blocklist is assigned a trust value that is equal to the trust values
+of the node that have the entry in their blocklist.
+
+Say `coolnode.net` and `othernicenode.com` both have `example.com` on their
+blocklists. Their combined trust level to block the node would be `60 + 30 = 90`.
+This combined value is compared to the *confidence level* that by default is 100.
+In this example `example.com` has a lower combined trust level then the confidence
+level - so the script will ask you about your opinion - do you want to include the
+entry in your new blocklist or not.
+
+Another node is on the blocklists of `coolnode.net` and `nicenode.net` thus has
+a combined trust level of 100 which is equal to the confidence level. So the
+script will automatically assume that this node should be included on the new
+blocklist.
+
+If you and the admin of `bullshitnode.com` both add a node on the blocklist the
+combined trust level for automatically blocking it would be `50`.
+
+### Other parameters
+
+* `-o filename`  will cause the script to write the list into the passed file
+* `-C N`  will set the confidence level to the value N
+* `-y` and `-n` activate the auto-mode of the script, either accepting or discarding all entries to the blocklist with a trust level smaller then the confidence level
+
 ## Author
 
 * Tobias Diekershoff <tobias(dot)diekershoff(att)gmx(dot)net>