chiark / gitweb /
Add shibboleth support
[irc.git] / servus.html
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE html 
3      PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
4      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
5 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
6
7 <head>
8 <title>Servus Documentation</title>
9 <style type="text/css">
10 body {background: white; color: black; text-align: left}
11 h1 {text-align: center; font-weight: bold; font-size: xx-large}
12 h2 {font-weight: bold; font-size: x-large}
13 h3, h4, h5, h6 {font-weight: bold; font-size: large}
14 li {list-style-type: circle}
15 hr {clear: both}
16 span.code {font-family: courier, monospace}
17 </style>
18 </head>
19
20 <body>
21 <h1>Servus Documentation</h1> 
22
23 <h2>Introduction</h2>
24 <p>Servus is one of the IRC bots on <span
25 class="code">#chiark</span>. This page documents the available
26 commands. You can get a copy of the source code by running <span
27 class="code">git-clone <a
28 href="http://www.chiark.greenend.org.uk/~matthewv/irc/.git">http://www.chiark.greenend.org.uk/~matthewv/irc/.git</a></span>,
29 or via <span class="code">gitweb</span> at <a href="http://www.chiark.greenend.org.uk/ucgi/~matthewv/git/irc.git/">http://www.chiark.greenend.org.uk/ucgi/~matthewv/git/irc.git/</a>.</p>
30
31 <h2>Invocation</h2>
32 <p>Servus may be invoked in-channel using either <span
33 class="code">!command</span> or <span
34 class="code">~command</span>. Alternatively, you may pass commands by
35 <span class="code">/msg</span>.
36 </p>
37
38 <h2>Commands</h2>
39
40 <ul>
41 <li><a href="#define">define</a></li>
42 <li><a href="#die">die</a></li>
43 <li><a href="#do">do</a></li>
44 <li><a href="#fish">fish</a></li>
45 <li><a href="#flirt">flirt</a></li>
46 <li><a href="#google">google</a></li>
47 <li><a href="#help">help</a></li>
48 <li><a href="#info">info</a></li>
49 <li><a href="#karma">karma</a></li>
50 <li><a href="#karmadel">karmadel</a></li>
51 <li><a href="#karmalist">karmalist</a></li>
52 <li><a href="#list">list</a></li>
53 <li><a href="#nsfw">nsfw</a></li>
54 <li><a href="nws">nws</a></li>
55 <li><a href="#quiet">quiet</a></li>
56 <li><a href="#quit">quit</a></li>
57 <li><a href="#reload">reload</a></li>
58 <li><a href="#rot13">rot13</a></li>
59 <li><a href="#say">say</a></li>
60 <li><a href="#slash">slash</a></li>
61 <li><a href="#trout">trout</a></li>
62 <li><a href="#twit">twit</a></li>
63 <li><a href="#units">units</a></li>
64 <li><a href="#url">url</a></li>
65 </ul>
66
67 <hr />
68
69 <h3><a name="define">define</a></h3>
70 <p>This command returns (either on-channel or by <span
71 class="code">/msg</span>) a definition of the argument(s) of the
72 "define" command. This is done by using a "define:" query on
73 google, so the results may be a little unusual at times...</p>
74
75 <h3><a name="die">die</a></h3>
76 <p>This command must be invoked by <span class="code">/msg</span> only,
77 and is only effective if invoked by the bot's owner. The bot
78 exits.</p>
79
80 <h3><a name="do">do</a></h3>
81 <p>This command must be invoked by <span class="code">/msg</span>, and
82 is only effective if invoked by the bot's owner. The syntax is:<br />
83 <span class="code">/msg Servus do thing</span><br />...which results
84 in output to the channel of the form:<br />
85 <span class="code">* Servus/#chiark thing</span></p>
86
87 <h3><a name="fish">fish</a></h3>
88 <p>This command must be invoked by <span class="code">/msg</span>, and
89 is only effective if invoked by the bot's owner. It
90 returns some details about the internal state of the "fishpond" (a
91 simple rate-limiting feature for restricting the over-use of <span
92 class="code">trout</span>, <span class="code">flirt</span>, and <span
93 class="code">slash</span>).</p>
94
95 <h3><a name="flirt">flirt</a></h3>
96 <p>The syntax is:<br /> <span
97 class="code">flirt target</span><br /> Servus picks a flirt at random
98 from the flirts list (<span
99 class="code">/home/matthew/programming/irc/bot/flirts</span> on rapun),
100 and substitutes "target" for "%s" in the flirt line. If this command
101 is invoked by <span class="code">/msg</span>, there is a 10% chance
102 of Servus stating who invoked it by adding "(but nick is their secret
103 admirer)" to the end of the flirt. Further suggestions for flirts
104 should be submitted by email; a list of current flirts may be found
105 online at <a
106 href="flirts">http://www.chiark.greenend.org.uk/~matthewv/irc/flirts</a>.</p>
107
108 <h3><a name="google">google</a></h3>
109 <p>This command returns (either on-channel or by <span
110 class="code">/msg</span>) the "I'm feeling lucky" result of google
111 searching for the argument(s) of the "google" command.</p>
112
113 <h3><a name="help">help</a></h3>
114 <p>This command returns (either on-channel or by <span
115 class="code">/msg</span>) the location of this help file.</p>
116
117 <h3><a name="info">info</a></h3>
118 <p>This command returns (either on-channel or by <span
119 class="code">/msg</span>) information about the software version
120 running, which channel the bot is on, the bot's owner, and how many
121 items have karma recorded about them</p>
122
123 <h3><a name="karma">karma</a></h3>
124 <p>The syntax is:<br />
125 <span class="code">karma target</span><br />
126 It returns (either on-channel or by <span class="code">/msg</span>)
127 the current karma value for <span class="code">target</span> or "<span
128 class="code">target has no karma set.</span>" as appropriate. Items
129 gain or lose karma as the result of commands of the form:<br />
130 <span class="code">target++</span><br />or<br />
131 <span class="code">target--</span><br />
132 Note that if issued in-channel, the initial <span
133 class="code">!</span> or <span class="code">~</span> should not be
134 included. Karma targets must be one word only.</p>
135
136 <h3><a name="karmadel">karmadel</a></h3>
137 <p>The syntax is:<br /> <span
138 class="code">karmadel target</span><br /> <span
139 class="code">target</span>'s karma entry is deleted. An error message
140 is produced if <span class="code">target</span> has no karma set.</p>
141
142 <h3><a name="karmalist">karmalist</a></h3>
143 <p><span style="font-weight: bold">Do not use this
144 command</span>. Servus has too long a list of karma items, so
145 attempting to use this command will DoS the bot (it gets temporarily
146 removed from channel for excess flooding).</p>
147
148 <h3><a name="list">list</a></h3>
149 <p>This command returns (either on-channel or by <span
150 class="code">/msg</span>) a list of the commands Servus
151 understands</p> 
152
153 <h3><a name="nsfw">nsfw</a></h3>
154 <p>This command is the same as <a href="#url">url</a>, only you should
155 use it for URLs that are not work-safe. Servus will replace the "http"
156 in your URL with "nsfw", before passing it to <a href="#url">url</a>.</p>
157
158 <h3><a name="nws">nws</a></h3>
159 <p>This is an alias for <a href="nsfw">nsfw</a>.</p>
160
161 <h3><a name="quiet">quiet</a></h3>
162 <p>This command prevents the use of <span
163 class="code">trout</span>, <span class="code">flirt</span>, and <span
164 class="code">slash</span> for a short period of time (and will tell
165 anyone who attempts to do so that you have invoked this command).</p> 
166
167 <h3><a name="quit">quit</a></h3>
168 <p>This command is identical to <a href="#die">die</a>.</p>
169
170 <h3><a name="reload">reload</a></h3>
171 <p>This command may only be invoked by <span class="code">/msg</span>,
172 and only by the bot's owner. It causes Servus to re-load its <span
173 class="code">trout</span>, <span class="code">flirt</span>, and <span
174 class="code">slash</span> files, and to re-stock its fishpond.</p>
175
176 <h3><a name="rot13">rot13</a></h3>
177 <p>The syntax is:<br />
178 <span class="code">rot13 some text</span><br />
179 It returns by <span class="code">/msg</span>
180 the argument rot13d (so "<span class="code">fbzr grkg</span>" in this
181 case).</p>
182
183 <h3><a name="say">say</a></h3>
184 <p>This command must be invoked by <span class="code">/msg</span>, and
185 is only effective if invoked by the bot's owner. The syntax is:<br />
186 <span class="code">/msg Servus say thing</span><br />...which results
187 in output to the channel of the form:<br />
188 <span class="code">&lt;Servus&gt; thing</span></p>
189
190 <h3><a name="slash">slash</a></h3>
191 <p>The syntax is:<br /> <span
192 class="code">slash target1 / target2 </span><br /> Servus picks a slash at random
193 from the slashes list (<span
194 class="code">/home/matthew/programming/irc/bot/slashes</span> on rapun),
195 and substitutes "target1" for the first "%s" and "target2" for the
196 second "%s" in the slash line. If this command
197 is invoked by <span class="code">/msg</span>, there is a 10% chance
198 of Servus stating who invoked it by adding "(while nick watches)" to
199 the end of the slash. Further suggestions for slashes should be
200 submitted by email; a list of current slashes may be found online at <a
201 href="slashes">http://www.chiark.greenend.org.uk/~matthewv/irc/slashes</a>.</p>
202
203 <h3><a name="trout">trout</a></h3>
204 <p>The syntax is:<br /> <span
205 class="code">trout target</span><br /> Servus picks a trout at random
206 from the trouts list (<span
207 class="code">/home/matthew/programming/irc/bot/trouts</span> on rapun),
208 and substitutes "target" for "%s" in the trout line. If this command
209 is invoked by <span class="code">/msg</span>, there is a 10% chance
210 of Servus stating who invoked it by adding "(at the instigation of
211 nick)" to the end of the trout. Further suggestions for trouts should
212 be submitted by email; a list of current trouts may be found online at
213 <a href="trouts">http://www.chiark.greenend.org.uk/~matthewv/irc/trouts</a>.</p>
214
215 <h3><a name="twit">twit</a></h3>
216 <p>The syntax is:<br /><span
217 class="code">twit twitter-url</span><br /> Servus returns (either on-channel or by <span
218 class="code">/msg</span>) the content
219 of the tweet and the twitter user who posted it.</p>
220
221 <h3><a name="units">units</a></h3>
222 <p>The syntax is:<br /> <span
223 class="code">units x unit1 as unit2</span><br />or:<br /> <span
224 class="code">units unit1 as unit2</span><br />or:<br /> <span
225 class="code">units x unit1 as ?</span><br />or:<br /> <span
226 class="code">units unit1 as ?</span><br />
227 The first two will give the first value in terms of the second unit;
228 the latter two forms convert the first value into SI units. This
229 command is implemented by calling <span class="code">units(1)</span>.</p>
230
231 <h3><a name="url">url</a></h3>
232 <p>Servus now tracks URLs pasted into <span
233 class="code">#chiark</span>, and will comment if you post a duplicate
234 URL. The <span class="code">url</span> command provides a way for you
235 to check if a URL has been posted before (if not, Servus posts it on
236 your behalf). The syntax is:<br /> <span class="code">/msg Servus url
237 http://some.url</span><br /> Servus will either paste the URL into
238 channel, or <span class="code">/msg</span> you to tell you it was a
239 duplicate; in the latter case, the URL will be sent to <span
240 class="code">#urls</span>. Although you can use this command
241 in-channel (and get a response by <span class="code">/msg </span>),
242 this is discouraged. Servus also understands <span
243 class="code">nsfw://</span> and <span class="code">nsfws://</span>
244 URLs, and knows they are an obfuscation of the relevant <span
245 class="code">http://</span> or <span class="code">https://</span> URL
246 for URLs that are not work-safe. You can make your firefox understand
247 <span class="code">nsfw://</span> URLS by visiting <a
248 href="http://www.chiark.greenend.org.uk/~owend/free/nsfw/">http://www.chiark.greenend.org.uk/~owend/free/nsfw/</a>.</p>
249
250 <hr />
251 <address>
252   <a href="mailto:matthewv@chiark.greenend.org.uk">Matthew Vernon</a><br />
253   Coventry, England
254 </address>
255  <p>
256 <a href="http://validator.w3.org/check/referer"><img
257         src="http://www.w3.org/Icons/valid-xhtml10"
258         alt="Valid XHTML 1.0!" height="31" width="88" /></a>
259 <a href="http://jigsaw.w3.org/css-validator/check/referer">
260 <img style="width:88px;height:31px"
261        src="http://jigsaw.w3.org/css-validator/images/vcss" 
262        alt="Valid CSS!" />
263 </a>
264 </p>
265 </body>
266 </html>
267