summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorKatolaZ <katolaz@freaknet.org>2019-01-26 22:48:20 +0000
committerKatolaZ <katolaz@freaknet.org>2019-01-26 22:48:20 +0000
commitd679c9b229da21f8c356828891c0753f9b7ecfa5 (patch)
treed1c912d595d3f5f1466cff6aa66e7884e976edb6 /README.md
initial commit
Diffstat (limited to 'README.md')
-rw-r--r--README.md99
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.