From ffd4f9c8b9fb7aa3a1f26ec0db13836803e14d14 Mon Sep 17 00:00:00 2001
From: ed <s@ocv.me>
Date: Sat, 13 Jul 2024 01:32:26 +0200
Subject: [PATCH] hooks: describe examples better

---
 bin/hooks/discord-announce.py | 21 +++++++++++++++------
 bin/hooks/msg-log.py          | 27 ++++++++++++++++++++-------
 bin/hooks/wget.py             | 28 ++++++++++++++++++++--------
 3 files changed, 55 insertions(+), 21 deletions(-)

diff --git a/bin/hooks/discord-announce.py b/bin/hooks/discord-announce.py
index 9c5412ad..b1cfc92a 100755
--- a/bin/hooks/discord-announce.py
+++ b/bin/hooks/discord-announce.py
@@ -12,19 +12,28 @@ announces a new upload on discord
 example usage as global config:
     --xau f,t5,j,bin/hooks/discord-announce.py
 
+parameters explained,
+    xau = execute after upload
+    f  = fork; don't delay other hooks while this is running
+    t5 = timeout if it's still running after 5 sec
+    j  = this hook needs upload information as json (not just the filename)
+
 example usage as a volflag (per-volume config):
     -v srv/inc:inc:r:rw,ed:c,xau=f,t5,j,bin/hooks/discord-announce.py
                            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
     (share filesystem-path srv/inc as volume /inc,
      readable by everyone, read-write for user 'ed',
-     running this plugin on all uploads with the params listed below)
+     running this plugin on all uploads with the params explained above)
 
-parameters explained,
-    xbu = execute after upload
-    f  = fork; don't wait for it to finish
-    t5 = timeout if it's still running after 5 sec
-    j  = provide upload information as json; not just the filename
+example usage as a volflag in a copyparty config file:
+    [/inc]
+      srv/inc
+      accs:
+        r: *
+        rw: ed
+      flags:
+        xau: f,t5,j,bin/hooks/discord-announce.py
 
 replace "xau" with "xbu" to announce Before upload starts instead of After completion
 
diff --git a/bin/hooks/msg-log.py b/bin/hooks/msg-log.py
index c6330533..0d7258d7 100755
--- a/bin/hooks/msg-log.py
+++ b/bin/hooks/msg-log.py
@@ -14,19 +14,32 @@ except:
     from datetime import datetime
 
 
-"""
+_ = r"""
 use copyparty as a dumb messaging server / guestbook thing;
+accepts guestbook entries from 📟 (message-to-server-log) in the web-ui
 initially contributed by @clach04 in https://github.com/9001/copyparty/issues/35 (thanks!)
 
-Sample usage:
-
+example usage as global config:
     python copyparty-sfx.py --xm j,bin/hooks/msg-log.py
 
-Where:
+parameters explained,
+    xm = execute on message (📟)
+    j  = this hook needs message information as json (not just the message-text)
 
-    xm = execute on message-to-server-log
-    j = provide message information as json; not just the text - this script REQUIRES json
-    t10 = timeout and kill download after 10 secs
+example usage as a volflag (per-volume config):
+    python copyparty-sfx.py -v srv/log:log:r:c,xm=j,bin/hooks/msg-log.py
+                                             ^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    (share filesystem-path srv/log as volume /log, readable by everyone,
+     running this plugin on all messages with the params explained above)
+
+example usage as a volflag in a copyparty config file:
+    [/log]
+      srv/log
+      accs:
+        r: *
+      flags:
+        xm: j,bin/hooks/msg-log.py
 """
 
 
diff --git a/bin/hooks/wget.py b/bin/hooks/wget.py
index 784f09e0..973f9346 100755
--- a/bin/hooks/wget.py
+++ b/bin/hooks/wget.py
@@ -9,25 +9,37 @@ import subprocess as sp
 _ = r"""
 use copyparty as a file downloader by POSTing URLs as
 application/x-www-form-urlencoded (for example using the
-message/pager function on the website)
+📟 message-to-server-log in the web-ui)
 
 example usage as global config:
     --xm f,j,t3600,bin/hooks/wget.py
 
+parameters explained,
+    xm = execute on message-to-server-log
+    f = fork; don't delay other hooks while this is running
+    j = provide message information as json (not just the text)
+    c3 = mute all output
+    t3600 = timeout and abort download after 1 hour
+
 example usage as a volflag (per-volume config):
     -v srv/inc:inc:r:rw,ed:c,xm=f,j,t3600,bin/hooks/wget.py
                            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
     (share filesystem-path srv/inc as volume /inc,
      readable by everyone, read-write for user 'ed',
-     running this plugin on all messages with the params listed below)
+     running this plugin on all messages with the params explained above)
 
-parameters explained,
-    xm = execute on message-to-server-log
-    f = fork so it doesn't block uploads
-    j = provide message information as json; not just the text
-    c3 = mute all output
-    t3600 = timeout and kill download after 1 hour
+example usage as a volflag in a copyparty config file:
+    [/inc]
+      srv/inc
+      accs:
+        r: *
+        rw: ed
+      flags:
+        xm: f,j,t3600,bin/hooks/wget.py     
+
+the volflag examples only kicks in if you send the message
+while you're in the /inc folder (or any folder below there)
 """