summaryrefslogtreecommitdiff
path: root/xN/xN.adoc
diff options
context:
space:
mode:
authorPřemysl Eric Janouch <p@janouch.name>2024-04-02 16:44:01 +0200
committerPřemysl Eric Janouch <p@janouch.name>2024-04-03 15:56:33 +0200
commit53ba996ec9c5c8fc64f66934d8c98509bd7ed06d (patch)
treefe396b25631e5a325c0e7d470dbb3e7e045d66b4 /xN/xN.adoc
parentd450c6cc5fe4caa2f9a1db3f0ec76c84b6a110af (diff)
downloadxK-53ba996ec9c5c8fc64f66934d8c98509bd7ed06d.tar.gz
xK-53ba996ec9c5c8fc64f66934d8c98509bd7ed06d.tar.xz
xK-53ba996ec9c5c8fc64f66934d8c98509bd7ed06d.zip
Add a simple IRC notifier utility
Diffstat (limited to 'xN/xN.adoc')
-rw-r--r--xN/xN.adoc86
1 files changed, 86 insertions, 0 deletions
diff --git a/xN/xN.adoc b/xN/xN.adoc
new file mode 100644
index 0000000..1f5404f
--- /dev/null
+++ b/xN/xN.adoc
@@ -0,0 +1,86 @@
+xN(1)
+=====
+:doctype: manpage
+:manmanual: xK Manual
+:mansource: xK {release-version}
+
+Name
+----
+xN - IRC notifier
+
+Synopsis
+--------
+*xN* [_OPTION_]... IRC-URL...
+
+Description
+-----------
+*xN* is a simple IRC notifier, sending the text it receives on its standard
+input to all IRC targets specified by its command line arguments.
+
+The input text is forced to validate as UTF-8, and it is _not_ split
+automatically to comply with the maximum IRC message length.
+Thus, make sure to make the lines short, or they will be trimmed by the servers.
+
+*xN* does not attempt to appease flood detectors.
+
+Options
+-------
+*-debug*::
+ Print incoming IRC traffic, which may help in debugging any issues.
+
+*-version*::
+ Output version information and exit.
+
+URL format
+----------
+*xN* accepts URLs describing IRC users and channels, roughly as specified by
+the Internet Draft _draft-butcher-irc-url-04.txt_. Note, however, that close
+to no validation is done on these, and you should not pass URLs from untrusted
+sources, so as to avoid command or parameter injection.
+
+Any provided username will be propagated to the nickname, username,
+and realname. The default value for these is the name of your system user.
+
+As an extension, you may use the following options:
+
+*skipjoin*::
+ Do not JOIN channels before sending messages to them.
+ This requires channels to allow external messages
+ (which are disabled by channel mode *+n*).
+*usenotice*::
+ Send a NOTICE rather than a PRIVMSG, which distinguishes automated messages,
+ and is more appropriate for bots.
+
+Examples
+--------
+ $ uptime | xN 'irc://uptime@localhost/%23watch?skipjoin&usenotice'
+
+Send *uptime*(1) information as an external notice to channel *#watch*
+on the local server, using the standard port *6667*.
+
+ $ fortune -s | xN ircs://ohayou@irc.libera.chat/john,isuser
+
+Greet user *john* with a fortune for this day. In compliance with _RFC 7194_,
+the default TLS port is assumed to be *6697*.
+
+ $ xN 'ircs://agent:Password123@irc.cia.gov:1337/#hq?key=123456' <<EOF
+ The red fox trots quietly at midnight.
+ EOF
+
+Connect over TLS to *irc.cia.gov* on port *1337*, use *Password123*
+as the server password, register as user *agent*,
+join channel *#hq* using the channel key *123456*,
+and send a very secret message.
+
+Reporting bugs
+--------------
+Use https://git.janouch.name/p/xK to report bugs, request features,
+or submit pull requests.
+
+See also
+--------
+_Uniform Resource Locator Schemes for Internet Relay Chat Entities_,
+https://datatracker.ietf.org/doc/html/draft-butcher-irc-url-04[].
+
+_Default Port for Internet Relay Chat (IRC) via TLS/SSL_,
+https://datatracker.ietf.org/doc/html/rfc7194[].