Only convert to unicode when needed

[irker.git] / irkerd.xml

diff --git a/irkerd.xml b/irkerd.xml
index 345c05363a4b457d3e56a0f17642daa1abd7e6d2..2a6c1bbfc517d9f074c08e529801f548c4c8e512 100644 (file)
--- a/irkerd.xml
+++ b/irkerd.xml
@@ -22,7 +22,10 @@
      <arg>-l <replaceable>logfile</replaceable></arg>
      <arg>-n <replaceable>nick</replaceable></arg>
      <arg>-p <replaceable>password</replaceable></arg>
+     <arg>-i <replaceable>ITC-URL</replaceable></arg>
      <arg>-V</arg>
+     <arg>-h</arg>
+     <arg choice='opt'><replaceable>message text</replaceable></arg>
 </cmdsynopsis>
 </refsynopsisdiv>
 
@@ -33,6 +36,11 @@ client intended to be used for shipping notification messages to IRC
 channels. The use case in mind when it was designed was broadcasting
 notifications from commit hooks in version-control systems.</para>
 
+<para>The main advantage of relaying through this daemon over
+individual scripted sends from applications is that it can maintain
+connection state for multiple channels, rather than producing obnoxious
+join/leave channel spam on every message.</para>
+
 <para><application>irkerd</application> is a socket server that
 listens on for UDP or TCP packets on port 6659 for textual request
 lines containing JSON objects and terminated by a newline. Each JSON
@@ -44,6 +52,7 @@ Examples:
 {"to":"irc://chat.freenode.net/git-ciabot", "privmsg":"Hello, world!"}
 {"to":["irc://chat.freenode.net/#git-ciabot","irc://chat.freenode.net/#gpsd"],"privmsg":"Multichannel test"}
 {"to":"irc://chat.hypothetical.net:6668/git-ciabot", "privmsg":"Hello, world!"}
+{"to":"irc://chat.hypothetical.net:6668/git-private?key=topsecret", "privmsg":"Keyed channel test"}
 </programlisting></para>
 
 <para>If the channel part of the URL does not have one of the prefix
@@ -57,10 +66,16 @@ colon, as shown in the third example; otherwise
 <application>irkerd</application> sends messages to the the default 6667 IRC
 port of each server.</para>
 
-<para>An empty message is legal and will cause 
+<para>To join password-protected (mode +k) channels, the channel part of the
+URL may be followed with a query-string indicating the channel key, of the
+form <quote>?secret</quote> or <quote>?key=secret</quote>, where
+<quote>secret</quote> is the channel key.</para>
+
+<para>An empty message is legal and will cause
 <application>irkerd</application> to join the target channels without
 actually emitting a message.  This may be useful for advertising that
-an instance is up and running.</para>
+an instance is up and running, or for joining a channel to log its
+traffic.</para>
 </refsect1>
 
 <refsect1 id='options'><title>OPTIONS</title>
@@ -78,7 +93,7 @@ consult the source code for details.</para></listitem>
 <term>-l</term>
 <listitem><para>Takes a following filename, logs traffic to that file.
 Each log line consists of three |-separated fields; a numeric
-timestamp in Unix time, the fqdn of the sending server, and the
+timestamp in Unix time, the FQDN of the sending server, and the
 message data.</para></listitem>
 </varlistentry>
 <varlistentry>
@@ -92,13 +107,23 @@ in the event of a nick collision.</para></listitem>
 <term>-p</term>
 <listitem><para>Takes a following value, setting a nickserv
 password to be used. If given, this password is shipped to
-authenticate the nick on receipt of a welcom message.</para></listitem>
+authenticate the nick on receipt of a welcome message.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>-i</term>
+<listitem><para>Immediate mode, to be run in foreground. Takes two
+following values interpreted as a channel URL and a message
+string. Sends the message, then quits.</para></listitem>
 </varlistentry>
 <varlistentry>
 <term>-V</term>
 <listitem><para>Write the program version to stdout and
 terminate.</para></listitem>
 </varlistentry>
+<varlistentry>
+<term>-h</term>
+<listitem><para>Print usage instructions and terminate.</para></listitem>
+</varlistentry>
 </variablelist>
 
 </refsect1>
@@ -141,8 +166,7 @@ discarded. </para>
 project page at <ulink
 url='http://www.catb.org/~esr/irker'>http://www.catb.org/~esr/irker</ulink>
 for updates and other resources, including an installable repository
-hook script. The implementation uses the Python IRC library by Joe
-Rosdahl and Jason R. Coombs.</para>
+hook script.</para>
 </refsect1>
 </refentry>