Document command redirection

1 files changed, 75 insertions, 0 deletions

diff --git a/README.redirection.txt b/README.redirection.txt
new file mode 100644
index 0000000..7e8769a
--- /dev/null
+++ b/README.redirection.txt
@@ -0,0 +1,75 @@
+This isn't specific to the plugins in this repo. I just want to
+document it somewhere I can find it later.
+
+Command redirection is a way to get the bot to highlight someone
+else, other than the one who ran the command.
+
+Imaginary conversation:
+
+<newuser> How do I print number in C?
+<oldguy> !man 3 printf
+<bot> oldguy: printf(3): formatted output conversion
+
+oldguy is using the bot to answer newuser's question. What
+redirection does is:
+
+<newuser> How do I print number in C?
+<oldguy> !man 3 printf > newuser
+<bot> newuser: printf(3): formatted output conversion
+
+All that's changed is who gets highlighted (the <user>: stuff). The
+syntax mimics the shell's I/O redirection, if you're familiar with
+that.
+
+The bits & pieces to make this work already exist in limnoria. The
+user 'val' in libera #limnoria put them together (for which I owe much
+thanks), I'm just documenting the process here.
+
+The indented lines are bot commands. Run them in private (a /query or
+/msg window).
+
+First of all, you need these plugins loaded:
+
+  load Utilities
+  load Conditional
+  load Format
+  load MessageParser
+
+(If you get "already loaded" errors, just ignore them)
+
+Next, *get rid* of the prefix character:
+
+  config reply.whenaddressedby.chars ""
+
+And use [] for nesting:
+
+  config supybot.commands.nested.brackets []
+
+Now the preparations are complete, and you're ready to cast the
+actual spell:
+
+  messageparser add global "^!(.+?)( *> *(\S+)\s*)?$" "cif [ceq \"$3\" [concat $ 3]] \"$1\" \"echo $3: [$1]\""
+
+The above is one long line, and it's very sensitive to spacing, so
+be cautious when copy/pasting it. In particular, there should be no
+spaces after the any of the $ symbols *except* for the 3rd one, the
+one that comes right after "concat".
+
+After that, the !command syntax will work even though you've removed
+the reply.whenaddressedby.chars entirely. And "!command > user" will
+also work as desired, for all commands (including factoids). Actually
+the spaces before and after the > are optional. "!command>user" works
+just fine.
+
+If you're using some other prefix char besides !, change it in the
+'messageparser add' command. You could do this on a per-channel basis
+by replacing 'global' with your channel (run the command once per
+channel).
+
+If you get message like 'Error: there is no command "> user"', you've
+missed a step, or messed up the messageparser add command.
+
+Note that there's no attempt to verify that the part after the >
+is actually a valid IRC nick. You have to spell it correctly or use
+nick-completion in your client. Typos don't hurt anything, but they
+don't highlight the user, either.