chiark / gitweb /
new trout from rjk (ref Stross)
[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.<br /> 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="#blame">blame</a></li>
42 <li><a href="#currency">currency</a></li>
43 <li><a href="#define">define</a></li>
44 <li><a href="#die">die</a></li>
45 <li><a href="#do">do</a></li>
46 <li><a href="#fish">fish</a></li>
47 <li><a href="#flirt">flirt</a></li>
48 <li><a href="#google">google</a></li>
49 <li><a href="#help">help</a></li>
50 <li><a href="#info">info</a></li>
51 <li><a href="#karma">karma</a></li>
52 <li><a href="#karmadel">karmadel</a></li>
53 <li><a href="#karmalist">karmalist</a></li>
54 <li><a href="#list">list</a></li>
55 <li><a href="#nsfw">nsfw</a></li>
56 <li><a href="nws">nws</a></li>
57 <li><a href="#quiet">quiet</a></li>
58 <li><a href="#quit">quit</a></li>
59 <li><a href="#reload">reload</a></li>
60 <li><a href="#rot13">rot13</a></li>
61 <li><a href="#say">say</a></li>
62 <li><a href="#slash">slash</a></li>
63 <li><a href="#trout">trout</a></li>
64 <li><a href="#twit">twit</a></li>
65 <li><a href="#units">units</a></li>
66 <li><a href="#url">url</a></li>
67 </ul>
68
69 <hr />
70
71 <h3><a name="blame">blame</a></h3>
72 <p>The syntax is:<br />
73 <span class="code">blame text</span><br />or:<br />
74 <span class="code">blame #trouts text</span><br />or:<br />
75 <span class="code">blame #flirts text</span><br />or:<br />
76 <span class="code">blame #slashes text</span><br />or:<br />
77 <span class="code">blame #last</span><br />
78 The first form will search for <span class="code">text</span> in the
79       trouts, flirts, and slashes lists, and return information on
80       when the relevant item was added, and by whom. The next three
81       forms restrict the search to the specified list. The last form
82       is a special case that searches for the last trout, flirt, or
83       slash that Servus emitted.</p>
84
85 <h3><a name="currency">currency</a></h3>
86 <p>The syntax is:<br />
87 <span class="code">currency curr1 as curr2</span><br />
88 This will give the first currency in terms of the second
89       currency. Currencies must be specified using their standard <a
90         href="http://en.wikipedia.org/wiki/ISO_4217">currency
91         code</a>. The currency conversion is performed using xe.com's
92       currency converter.</p>
93
94 <h3><a name="define">define</a></h3>
95 <p>This command no longer works, as google have broken 'define'-style
96       searches; it will return an error message if invoked.</p> 
97
98 <h3><a name="die">die</a></h3>
99 <p>This command must be invoked by <span class="code">/msg</span> only,
100 and is only effective if invoked by the bot's owner. The bot
101 exits.</p>
102
103 <h3><a name="do">do</a></h3>
104 <p>This command must be invoked by <span class="code">/msg</span>, and
105 is only effective if invoked by the bot's owner. The syntax is:<br />
106 <span class="code">/msg Servus do thing</span><br />...which results
107 in output to the channel of the form:<br />
108 <span class="code">* Servus/#chiark thing</span></p>
109
110 <h3><a name="fish">fish</a></h3>
111 <p>This command must be invoked by <span class="code">/msg</span>, and
112 is only effective if invoked by the bot's owner. It
113 returns some details about the internal state of the "fishpond" (a
114 simple rate-limiting feature for restricting the over-use of <span
115 class="code">trout</span>, <span class="code">flirt</span>, and <span
116 class="code">slash</span>).</p>
117
118 <h3><a name="flirt">flirt</a></h3>
119 <p>The syntax is:<br /> <span
120 class="code">flirt target</span><br /> Servus picks a flirt at random
121 from the flirts list (<span
122 class="code">/home/matthew/programming/irc/bot/flirts</span> on rapun),
123 and substitutes "target" for "%s" in the flirt line. If this command
124 is invoked by <span class="code">/msg</span>, there is a 10% chance
125 of Servus stating who invoked it by adding "(but nick is their secret
126 admirer)" to the end of the flirt. Further suggestions for flirts
127 should be submitted by email; a list of current flirts may be found
128 online at <a
129 href="flirts">http://www.chiark.greenend.org.uk/~matthewv/irc/flirts</a>.</p>
130
131 <h3><a name="google">google</a></h3>
132 <p>This command returns (either on-channel or by <span
133 class="code">/msg</span>) the "I'm feeling lucky" result of google
134 searching for the argument(s) of the "google" command.</p>
135
136 <h3><a name="help">help</a></h3>
137 <p>This command returns (either on-channel or by <span
138 class="code">/msg</span>) the location of this help file.</p>
139
140 <h3><a name="info">info</a></h3>
141 <p>This command returns (either on-channel or by <span
142 class="code">/msg</span>) information about the software version
143 running, which channel the bot is on, the bot's owner, and how many
144 items have karma recorded about them</p>
145
146 <h3><a name="karma">karma</a></h3>
147 <p>The syntax is:<br />
148 <span class="code">karma target</span><br />
149 It returns (either on-channel or by <span class="code">/msg</span>)
150 the current karma value for <span class="code">target</span> or "<span
151 class="code">target has no karma set.</span>" as appropriate. Items
152 gain or lose karma as the result of commands of the form:<br />
153 <span class="code">target++</span><br />or<br />
154 <span class="code">target--</span><br />
155 Note that if issued in-channel, the initial <span
156 class="code">!</span> or <span class="code">~</span> should not be
157 included. Karma targets must be one word only.</p>
158
159 <h3><a name="karmadel">karmadel</a></h3>
160 <p>The syntax is:<br /> <span
161 class="code">karmadel target</span><br /> <span
162 class="code">target</span>'s karma entry is deleted. An error message
163 is produced if <span class="code">target</span> has no karma set.</p>
164
165 <h3><a name="karmalist">karmalist</a></h3>
166 <p><span style="font-weight: bold">Do not use this
167 command</span>. Servus has too long a list of karma items, so
168 attempting to use this command will DoS the bot (it gets temporarily
169 removed from channel for excess flooding).</p>
170
171 <h3><a name="list">list</a></h3>
172 <p>This command returns (either on-channel or by <span
173 class="code">/msg</span>) a list of the commands Servus
174 understands</p> 
175
176 <h3><a name="nsfw">nsfw</a></h3>
177 <p>This command is the same as <a href="#url">url</a>, only you should
178 use it for URLs that are not work-safe. Servus will replace the "http"
179 in your URL with "nsfw", before passing it to <a href="#url">url</a>.</p>
180
181 <h3><a name="nws">nws</a></h3>
182 <p>This is an alias for <a href="nsfw">nsfw</a>.</p>
183
184 <h3><a name="quiet">quiet</a></h3>
185 <p>This command prevents the use of <span
186 class="code">trout</span>, <span class="code">flirt</span>, and <span
187 class="code">slash</span> for a short period of time (and will tell
188 anyone who attempts to do so that you have invoked this command).</p> 
189
190 <h3><a name="quit">quit</a></h3>
191 <p>This command is identical to <a href="#die">die</a>.</p>
192
193 <h3><a name="reload">reload</a></h3>
194 <p>This command may only be invoked by <span class="code">/msg</span>,
195 and only by the bot's owner. It causes Servus to re-load its <span
196 class="code">trout</span>, <span class="code">flirt</span>, and <span
197 class="code">slash</span> files, and to re-stock its fishpond.</p>
198
199 <h3><a name="rot13">rot13</a></h3>
200 <p>The syntax is:<br />
201 <span class="code">rot13 some text</span><br />
202 It returns by <span class="code">/msg</span>
203 the argument rot13d (so "<span class="code">fbzr grkg</span>" in this
204 case).</p>
205
206 <h3><a name="say">say</a></h3>
207 <p>This command must be invoked by <span class="code">/msg</span>, and
208 is only effective if invoked by the bot's owner. The syntax is:<br />
209 <span class="code">/msg Servus say thing</span><br />...which results
210 in output to the channel of the form:<br />
211 <span class="code">&lt;Servus&gt; thing</span></p>
212
213 <h3><a name="slash">slash</a></h3>
214 <p>The syntax is:<br /> <span
215 class="code">slash target1 / target2 </span><br /> Servus picks a slash at random
216 from the slashes list (<span
217 class="code">/home/matthew/programming/irc/bot/slashes</span> on rapun),
218 and substitutes "target1" for the first "%s" and "target2" for the
219 second "%s" in the slash line. If this command
220 is invoked by <span class="code">/msg</span>, there is a 10% chance
221 of Servus stating who invoked it by adding "(while nick watches)" to
222 the end of the slash. Further suggestions for slashes should be
223 submitted by email; a list of current slashes may be found online at <a
224 href="slashes">http://www.chiark.greenend.org.uk/~matthewv/irc/slashes</a>.</p>
225
226 <h3><a name="trout">trout</a></h3>
227 <p>The syntax is:<br /> <span
228 class="code">trout target</span><br /> Servus picks a trout at random
229 from the trouts list (<span
230 class="code">/home/matthew/programming/irc/bot/trouts</span> on rapun),
231 and substitutes "target" for "%s" in the trout line. If this command
232 is invoked by <span class="code">/msg</span>, there is a 10% chance
233 of Servus stating who invoked it by adding "(at the instigation of
234 nick)" to the end of the trout. Further suggestions for trouts should
235 be submitted by email; a list of current trouts may be found online at
236 <a href="trouts">http://www.chiark.greenend.org.uk/~matthewv/irc/trouts</a>.</p>
237
238 <h3><a name="twit">twit</a></h3>
239 <p>The syntax is:<br /><span
240 class="code">twit twitter-url</span><br /> Servus returns (either on-channel or by <span
241 class="code">/msg</span>) the content
242 of the tweet and the twitter user who posted it.</p>
243
244 <h3><a name="units">units</a></h3>
245 <p>The syntax is:<br /> <span
246 class="code">units x unit1 as unit2</span><br />or:<br /> <span
247 class="code">units unit1 as unit2</span><br />or:<br /> <span
248 class="code">units x unit1 as ?</span><br />or:<br /> <span
249 class="code">units unit1 as ?</span><br />
250 The first two will give the first value in terms of the second unit;
251 the latter two forms convert the first value into SI units. This
252 command is implemented by calling <span class="code">units(1)</span>.</p>
253
254 <h3><a name="url">url</a></h3>
255 <p>Servus now tracks URLs pasted into <span
256 class="code">#chiark</span>, and will comment if you post a duplicate
257 URL. The <span class="code">url</span> command provides a way for you
258 to check if a URL has been posted before (if not, Servus posts it on
259 your behalf). The syntax is:<br /> <span class="code">/msg Servus url
260 http://some.url</span><br /> Servus will either paste the URL into
261 channel, or <span class="code">/msg</span> you to tell you it was a
262 duplicate; in the latter case, the URL will be sent to <span
263 class="code">#urls</span>. Although you can use this command
264 in-channel (and get a response by <span class="code">/msg </span>),
265 this is discouraged. Servus also understands <span
266 class="code">nsfw://</span> and <span class="code">nsfws://</span>
267 URLs, and knows they are an obfuscation of the relevant <span
268 class="code">http://</span> or <span class="code">https://</span> URL
269 for URLs that are not work-safe. You can make your firefox understand
270 <span class="code">nsfw://</span> URLS by visiting <a
271 href="http://www.chiark.greenend.org.uk/~owend/free/nsfw/">http://www.chiark.greenend.org.uk/~owend/free/nsfw/</a>.</p>
272
273 <hr />
274 <address>
275   <a href="mailto:matthewv@chiark.greenend.org.uk">Matthew Vernon</a><br />
276   Cambridge, England
277 </address>
278  <p>
279 <a href="http://validator.w3.org/check/referer"><img
280         src="http://www.w3.org/Icons/valid-xhtml10"
281         alt="Valid XHTML 1.0!" height="31" width="88" /></a>
282 <a href="http://jigsaw.w3.org/css-validator/check/referer">
283 <img style="width:88px;height:31px"
284        src="http://jigsaw.w3.org/css-validator/images/vcss" 
285        alt="Valid CSS!" />
286 </a>
287 </p>
288 </body>
289 </html>
290