diff --git a/docs/DocBook/capabilities.sgml b/docs/DocBook/capabilities.sgml index a8c6ef6e7..bfa32d472 100644 --- a/docs/DocBook/capabilities.sgml +++ b/docs/DocBook/capabilities.sgml @@ -20,6 +20,11 @@ 18 Feb 2004 Initial Docbook translation + + 0.2 + 04 Sep 2004 + Update Docbook translation + @@ -68,49 +73,49 @@ “anticapability” for that command. An anticapability is a capability that, instead of saying “what a user can do”, says what a user cannot do. It's - formed rather simply by adding a dash (“-”) to the - beginning of a capability; rot13 is a - capability, and -rot13 is an - anticapability. Anyway, when a user issues the bot a command, - perhaps calc or - help, the bot first checks to make sure - the user doesn't have the -calc or the - -help capabilities before even - considering responding to the user. So commands can be turned on - or off on a per user basis, offering - finegrained control not often (if at all!) seen in other bots. + formed rather simply by adding a dash (“-”) to the + beginning of a capability; rot13 is a + capability, and -rot13 is an + anticapability. Anyway, when a user issues the bot a command, + perhaps calc or + help, the bot first checks to make sure + the user doesn't have the -calc or the + -help capabilities before even + considering responding to the user. So commands can be turned on + or off on a per user basis, offering + finegrained control not often (if at all!) seen in other bots. Channel capabilities But that's not all! The capabilities system also supports Channel capabilities, which are - capabilities that only apply to a specific channel; they're of - the form #channel.capability. - Whenever a user issues a command to the bot in a channel, the - command dispatcher also checks to make sure the user doesn't - have the anticapability for that command in that - channel and if the user does, the bot won't respond - to the user in the channel. Thus now, in addition to having - the ability to turn individual commands on or off for an - individual user, we can now turn commands on or off for an - individual user on an individual channel! + capabilities that only apply to a specific channel; they're of + the form #channel,capability. + Whenever a user issues a command to the bot in a channel, the + command dispatcher also checks to make sure the user doesn't + have the anticapability for that command in that + channel and if the user does, the bot won't respond + to the user in the channel. Thus now, in addition to having + the ability to turn individual commands on or off for an + individual user, we can now turn commands on or off for an + individual user on an individual channel! So when a user foo sends a command - bar to the bot on channel - #baz, first the bot checks to see if the - user has the anticapability for the command by itself, - -bar. If so, it returns right then - and there, compltely ignoring the fact that the user issued - that command to it. If the user doesn't have that - anticapability, then the bot checks to see if the user issued - the command over a channel, and if so, checks to see if the - user has the antichannelcapability for that command, - #baz.-bar. If so, again, he returns - right then and there and doesn't even think about responding - to the bot. If neither of these anticapabilities are present, - then the bot just responds to the user like normal. + bar to the bot on channel + #baz, first the bot checks to see if the + user has the anticapability for the command by itself, + -bar. If so, it returns right then + and there, compltely ignoring the fact that the user issued + that command to it. If the user doesn't have that + anticapability, then the bot checks to see if the user issued + the command over a channel, and if so, checks to see if the + user has the antichannelcapability for that command, + #baz,-bar. If so, again, he returns + right then and there and doesn't even think about responding + to the bot. If neither of these anticapabilities are present, + then the bot just responds to the user like normal. @@ -119,7 +124,7 @@ A programmer's perspective - From a programmatical perspective, capabilties are easy to use + From a programming perspective, capabilties are easy to use and flexible. Any command can check if a user has any capability, even ones not thought of when the bot was originally written. Commands/Callbacks can add their own @@ -140,6 +145,7 @@ bot to follow for users that haven't yet registered in his user database. + It's really a revolution! @@ -148,11 +154,11 @@ Hard-coded supybot capabilities There are several default capabilities the bot uses. The most - important of these is the owner - capability. This capability allows the person having it to use - any command. It's best to keep this - capability reserved to people who actually have access to the - shell the bot is running on. + important of these is the owner + capability. This capability allows the person having it to use + any command. It's best to keep this + capability reserved to people who actually have access to the + shell the bot is running on. There is also the admin capability for @@ -164,41 +170,50 @@ people with the next capability. - People who are to administer channels with the bot should have the - #channel.op capability -- whatever - channel they are to administrate, they should have that channel - capability for op. For example, since I - want inkedmn to be an administrator in - #supybot, I'll give him the - #supybot.op capability. This is in - addition to his admin capability, since - the admin capability doesn't give the - person having it control over channels. - #channel.op is used for such things as - giving/receiving ops, kickbanning people, lobotomizing the bot, - ignoring users in the channel, and managing the channel - capabilities. The #channel.op capability - is also basically the equivalent of the owner capability for - capabilities involving #channel – - basically anyone with the #channel.op - capability is considered to have all positive capabilities and no - negative capabilities for #channel. + People who are to administer channels with the bot should have the + #channel,op capability – whatever + channel they are to administrate, they should have that channel + capability for op. For example, since I + want inkedmn to be an administrator in + #supybot, I'll give him the + #supybot,op capability. This is in + addition to his admin capability, since + the admin capability doesn't give the + person having it control over channels. + #channel.op is used for such things as + giving/receiving ops, kickbanning people, lobotomizing the bot, + ignoring users in the channel, and managing the channel + capabilities. The #channel,op capability + is also basically the equivalent of the owner capability for + capabilities involving #channel – + basically anyone with the #channel,op + capability is considered to have all positive capabilities and no + negative capabilities for #channel. - One other globally important capability exists: - trusted. This is a command that - basically says “This user can be trusted not to try and - crash the bot.” It allows users to call commands like - Math.icalc, which potentially could cause the - bot to begin a calculation that could potentially never return (a - calculation like 10**10**10**10). Another command that requires - the trusted capability is Utilties.re, which - (due to the regular expression implementation in Python (and any - other language that uses NFA regular expressions, like Perl or - Ruby or Lua or …) which can allow a regular expression to - take exponential time to process). Consider what would happen if - the someone gave the bot the command re [strjoin "" s/./ - [dict go] /] [dict go]. + One other globally important capability exists: + trusted. This is a command that + basically says “This user can be trusted not to try and + crash the bot.” It allows users to call commands like + Math.icalc, which potentially could cause the + bot to begin a calculation that could potentially never return (a + calculation like 10**10**10**10). Another command that requires + the trusted capability is Utilties.re, which + (due to the regular expression implementation in Python (and any + other language that uses NFA regular expressions, like Perl or + Ruby or Lua or …) which can allow a regular expression to + take exponential time to process). Consider what would happen if + the someone gave the bot the command re [strjoin "" s/./ + [dict go] /] [dict go]. + + + + Other capabilities + + Other plugins may require different capabilities; the + Factoids plugin requires + #channel,factoids, the Topic + plugin requires #channel,topic, etc.