initial commit

1 files changed, 99 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4b7cb99
--- /dev/null
+++ b/README.md
@@ -0,0 +1,99 @@
+    phrollo: a phlogroll in a shellscript    
+=============================================
+
+`phrollo` is a simple tool to manage a phlog roll. It uses a simple
+configuration file and outputs the relevant selectors to be added to a
+gophermap. The list of selectors of updated phlogs is sorted in
+decreasing order of update time (meaning that more recent updates appear
+at the top of the list). `phrollo` also outputs an updaterd config file,
+to be used for future calls.
+
+`phrollo` detects updates by using `shasum -a 256`, i.e. by computing 
+a hash of the resource and comparing it with the hash obtained when the 
+resource was last seen. 
+
+   Usage   
+===========
+
+1) 
+```
+./phrollo status.txt
+```
+
+In this case, `phrollo` will put a new config file in `status.txt.new`,
+and output the sorted list of gopher selectors. The config file received
+on input will also be saved in `status.txt.bak`.
+2) 
+
+```
+ cat config.txt | ./phrollo
+```
+
+In this case, the new config file will be put in `phrollo.out`, and
+output the sorted list of gopher selectors.
+ 
+IMPORTANT: The next time `phrollo` is run, it must be given the last
+config file generated.
+
+   Configuration file   
+========================
+
+The format of the `phrollo` config file is as follows:
+
+DATE \t DESCRIPTION \t URI \t HOST \t PORT \t SHASUM
+
+where:
+
+  - DATE: is the last time the phlog was updated, or an empty string for
+    a new phlog;
+  - DESCRIPTION: is the description of the phlog (e.g., the name of the
+    author)
+  - URI: is the path of the phlog
+  - HOST: well, the host
+  - PORT: normally 70
+  - SHASUM: the shasum of the phlog at the time of the latest change, or
+    an empty string for a new phlog
+
+   Example   
+=============
+
+Let us construct an initial `phrollo` config file containing all the
+phlogs we would like to follow. Since `phrollo` has never seen any of
+those phlogs, both DATE and SHASUM will be ignored. We will indicated 
+them with a "-" dash. Notice that fields are separated by actual TABs:
+
+```
+-	Slugmax	/~slugmax/cgi-bin/slerm	zaibatsu.circumlunar.space	70	-
+-	RPDO	/Phlog	1436.ninja	70	-
+-	Alex Shroeder	/	alexschroeder.ch	70	-
+-	Solderpunk	/~solderpunk/phlog	zaibatsu.circumlunar.space	70	-
+-	Tomasino	/phlog	gopher.black	70	-
+-	KatolaZ	/~katolaz/phlog	republic.circumlunar.space	70	-
+```
+
+Now we can feed this file to `phrollo` to get:
+
+```
+1(20190126) Alex Shroeder	/	alexschroeder.ch	70
+1(20190126) KatolaZ	/~katolaz/phlog	republic.circumlunar.space	70
+1(20190126) RPDO	/Phlog	1436.ninja	70
+1(20190126) Slugmax	/~slugmax/cgi-bin/slerm	zaibatsu.circumlunar.space	70
+1(20190126) Solderpunk	/~solderpunk/phlog	zaibatsu.circumlunar.space	70
+1(20190126) Tomasino	/phlog	gopher.black	70
+```
+
+which is a list of selectors corresponding to the phlogs specified in
+the config file. Moreover, `phrollo` will also create the updated 
+config file `phrollo.out`:
+
+```
+20190126	Tomasino	/phlog	gopher.black	70	bd141abfc29522e3e2b5d00f1a656212201ae5def60de90a7ce847cddeb6d0db
+20190126	Solderpunk	/~solderpunk/phlog	zaibatsu.circumlunar.space	70	4df8feff5237db12a4fb1c43d95f254dc26b0e35e3b008d53cc5004ad2c6acb9
+20190126	Slugmax	/~slugmax/cgi-bin/slerm	zaibatsu.circumlunar.space	70	bfd0e14e2c5b08fff6b968804dd253e488c5e0bfd9d80cec4ca7599928fac53f
+20190126	RPDO	/Phlog	1436.ninja	70	d61e34dfc71a10f5b45c6ccf7f6d96e4f976832efdd179e71a0981695b317dc9
+20190126	KatolaZ	/~katolaz/phlog	republic.circumlunar.space	70	af9b99199b344b027addeb09ba71621123bf799605b6190a65be145221bcefde
+20190126	Alex Shroeder	/	alexschroeder.ch	70	36d66161d096c5c729a6433c411fad9da978931cdfab40e9bd57787aa0e0b1f6
+```
+
+Then, we can run `phrollo` again using the latest updated config file
+(i.e., `phrollo.out`) to detect updates.