From e45daca1ae1e4c034209c8c7f73a1f06dd01e355 Mon Sep 17 00:00:00 2001 From: unknown_lamer Date: Mon, 4 Jul 2005 21:44:01 +0000 Subject: [PATCH] [project @ 2005-07-04 21:44:00 by unknown_lamer] More documentation work --- ChangeLog | 13 +++- NEWS | 1 + TODO | 4 +- bobot++.info | 176 +++++++++++++++++++++++++++--------------------- bobot++.texinfo | 113 +++++++++++++++++++------------ 5 files changed, 181 insertions(+), 126 deletions(-) diff --git a/ChangeLog b/ChangeLog index a2aaca2..bce144a 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,6 +1,17 @@ 2005-07-04 Clinton Ebadi - * source/DCCManager.C (checkInput): + * bobot++.texinfo: Grammar fixes on the title page + (Configuration): Added more info on config files. + (bot.conf): Added xrefs for server syntax and channel syntax + (server syntax): Added more detail and moved a paragraph + (channel syntax): Added more details, revised the examples, and + moved some text around + (User Levels): Clarified + (Protection): Cleaned up + (Automatic Op): Improved substantially + + * source/DCCManager.C (checkInput): Call hooks/dcc/chat-end if the + DCC CHAT has died * scripts/bobot-utils.scm (bot:log): Updated to use bot:logport instead of bot-logport diff --git a/NEWS b/NEWS index a2a7eb2..492749c 100644 --- a/NEWS +++ b/NEWS @@ -20,6 +20,7 @@ Version 2.1.9: - Documention + Reorganized a few sections + Every hook is now documented + + Using bot section is now much more usable - The code was cleaned up a bit Version 2.1.8: diff --git a/TODO b/TODO index ced8d56..25ef4a2 100644 --- a/TODO +++ b/TODO @@ -1,4 +1,4 @@ -Done: +Done (2.2): * DCC CHAT min user level * Lots of hooks related stuff that I never wrote down * Abstract DCC support so that DCC FILE may be easily implemented @@ -69,6 +69,4 @@ Definitely 3.0: implement those. Maybe: -* New config values in config db should be added before old values - (this is faster but breaks the way server lists work in 2.x) * Make it possible to use Scheme functions in the Parser itself \ No newline at end of file diff --git a/bobot++.info b/bobot++.info index 5883a10..7450cf6 100644 --- a/bobot++.info +++ b/bobot++.info @@ -2,7 +2,7 @@ This is bobot++.info, produced by makeinfo version 4.7 from bobot++.texinfo. This file documents Bobot++ by Clinton Ebadi and Etienne Bernard -(original author, no longer works on program). +(The original author who no longer works on the program). Copyright 2002,2004,2005 Clinton Ebadi @@ -16,9 +16,9 @@ Texts. File: bobot++.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) This document describes Bobot++ by Clinton Ebadi and Etienne Bernard -(original author, no longer works on program). +(The original author who no longer works on the program). - This document applies to version 2.2 of the program named Bobot++ + This document applies to version 2.2 of the program named Bobot++. Copyright 2002,2004,2005 Clinton Ebadi @@ -105,6 +105,10 @@ File: bobot++.info, Node: Configuration, Next: Using the Bot, Prev: Introduct Bobot++ is easy to configure. See the `examples' directory for an example configuration. + The main configuration file is `bot.conf'. There are several +auxiliary configuration files (a user list, aliases file, ban list, and +a script autoexec). + * Menu: * Configuration File Placement:: @@ -118,7 +122,7 @@ File: bobot++.info, Node: Configuration File Placement, Next: Configuration Fi Bobot++ will look in `/etc/bobotpp/default/' for its default config if none is specified on the command line. Put the configuration files you -want to be loaded by default in this directory. If you are not root or +want to be loaded by default in this directory. If you are not root, or you want to have your own personal configuration, put it in `~/.bobotpp/config/default/'. @@ -139,12 +143,7 @@ File: bobot++.info, Node: bot.conf, Next: bot.users, Prev: Configuration File 2.2.1 bot.conf -------------- -* Menu: - -* server syntax:: -* channel syntax:: - - `bot.conf' contains key value pairs separated by `='. +`bot.conf' contains key value pairs separated by `='. ` = ' @@ -156,6 +155,14 @@ of the line_. configuration variables are listed below in the format "VARIABLE : description" + A few of the options have more complex syntax, they are documented in +their own subsections. + +* Menu: + +* server syntax:: +* channel syntax:: + * NICKNAME : The nickname of the bot (NICK is an alias for NICKNAME) @@ -169,16 +176,17 @@ configuration variables are listed below in the format "VARIABLE * USERLIST : Name of the file where the userlist is stored - * SHITLIST : Name of the file where the shitlist is stored + * SHITLIST : Name of the file where the shitlist (ban + list) is stored * LOGFILE <$LOGDIR/bot.log>: Location of the bot logfile (set this to `/dev/null' to disable logging). - * SERVER : This specifies the server to connect to. Note that - this has a special syntax. + * SERVER : This specifies the server to which the bot will + connect. Note that this has a special syntax *note server syntax::. - * CHANNEL : This specifies a channel the bot will join when it - starts up. This also has a special syntax. + * CHANNEL : This specifies the channels the bot will join when + it starts up. This has a special syntax *note channel syntax::.  @@ -187,18 +195,20 @@ File: bobot++.info, Node: server syntax, Next: channel syntax, Prev: bot.conf 2.2.1.1 server syntax ..................... -SERVER = SERVER_NAME [PORT [PASSWORD]] +The server syntax in `bot.conf' allows you to specify an alternate port +to connect on, and a password to send the server. + + You may use more than one server line; Bobot++ will attempt to +connect to the first one, and will connect to the next one in the list +if it fails. The bot will continue cycling through the server list +until it is able to connect to one. There is a command (`!cycle') to +make the bot to cycle servers. + + SERVER = SERVER_NAME [PORT [PASSWORD]] This will make Bobot++ attempt to connect to SERVER_NAME on port PORT with the password PASSWORD. SERVER_NAME should be the address of -the server. PORT and PASSWORD are optional. You may use more than one -server line; Bobot++ will attempt to connect to the first one and, if -it fails, will connect to the next one in the list. There is also a -command to cause the bot to cycle servers. At the present time Bobot++ -cannot connect to more than one server at a time. This is a planned -feature of 3.0 (which is a very long way away; the current structure of -the program would make it very difficult to add support for connecting -to multiple servers at a time in a usable manner). +the server. PORT and PASSWORD are optional.  File: bobot++.info, Node: channel syntax, Prev: server syntax, Up: bot.conf @@ -206,23 +216,28 @@ File: bobot++.info, Node: channel syntax, Prev: server syntax, Up: bot.conf 2.2.1.2 channel syntax ...................... -CHANNEL = NAME:INITIAL_MODES:MODES_TO_KEEP:CHANNEL_KEY +The channel syntax in `bot.conf' allows you to specify the initial +modes the bot should set on a channel, the modes the bot should +maintain, and a key if the channel needs it. You may have any number of channel lines. When Bobot++ starts it will -attempt to join and gain ops in every channel listed. It will join NAME -and set the channel modes to INITIAL_MODES (e.g. "nt") if it is able to -gain operator status. It will then maintain MODES_TO_KEEP. If the -channel requires a key to enter simply set CHANNEL_KEY. Every argument -except for NAME is optional. +attempt to join and gain operator status in every channel listed. + + CHANNEL = NAME:INITIAL_MODES:MODES_TO_KEEP:CHANNEL_KEY + + The bot will join NAME and set the channel modes to INITIAL_MODES +(e.g. "nt") if it is able to gain operator status. It will then +maintain MODES_TO_KEEP. If the channel requires a key to enter simply +set CHANNEL_KEY. Every argument except for NAME is optional. A few example lines: - `CHANNEL = #foo:nt:nt:bar' + CHANNEL = #foo:nt:nt:bar The bot will join `#foo' with the channel key `bar' and will then maintain the modes `nt'. - `CHANNEL = #bar:::' + CHANNEL = #bar::: The bot will join `#bar' and will not set any modes nor will it attempt to maintain any modes. @@ -278,7 +293,7 @@ File: bobot++.info, Node: Starting the Bot, Next: User Levels, Prev: Using th ==================== The bot is usually installed with the binary name `bobotpp'. It accepts -the following command line arguments: +the following command line arguments. * `[--help][-h]' - Shows detailed help and exits @@ -322,9 +337,9 @@ File: bobot++.info, Node: User Levels, Next: Protection, Prev: Starting the B There are several user levels available in Bobot++ to provide gradated access to commands. `!adduser' and `bot.users' use the numeric code; -Scheme uses the textual name for the level. By default (if no catch-all -setting is found in *Note bot.users::.) a user has access to commands -with the level `bot:user-none'. +Scheme uses the textual name for the level. By default (if the user is +not found in the userlist) a user has access to commands with the level +`bot:user-none'. 0. `bot:user-none' - No *built-in* commands may be executed _by default_ (commands may be added from Scheme that can be executed @@ -355,18 +370,19 @@ File: bobot++.info, Node: Protection, Next: Automatic Op, Prev: User Levels, ============== A user added via Scheme, the `bot.users' file, or `!adduser' may be -protected from being deoped, kicked, or banned. There are currently no -symbolic levels in Scheme; just use the numeric code. +protected from being deoped, kicked, or banned. The user list and IRC +commands use the numeric codes, Scheme uses the symbolic names. - 0. No protection + 0. `bot:protection/none' No protection - 1. No ban. If a user is banned the bot will unban him.. + 1. `bot:protection/no-ban' No ban. If a user is banned the bot will + unban him.. - 2. No kick. The user may still be kicked but the bot will kickban the - user who kicked the protected user. + 2. `bot:protection/no-kick' No kick. The user may still be kicked but + the bot will kickban the user who kicked the protected user. - 3. No deop. The bot will ensure that the user always maintains - operator status. + 3. `bot:protection/no-deop' No deop. The bot will ensure that the + user always maintains operator status.  File: bobot++.info, Node: Automatic Op, Next: Built-In Commands, Prev: Protection, Up: Using the Bot @@ -375,8 +391,12 @@ File: bobot++.info, Node: Automatic Op, Next: Built-In Commands, Prev: Protec ================ A user may be automatically given operator status upon entering a -channel. Set the AOP field to "0" to disable auto-op or "1" to enable -auto-op. +channel. Scheme uses the symbolic name, the user list (`bot.users') and +IRC commands use the numeric value. + + 0. `bot:aop/no' Do not automatically op the user + + 1. `bot:aop/yes' Do automatically op the user  File: bobot++.info, Node: Built-In Commands, Prev: Automatic Op, Up: Using the Bot @@ -1383,37 +1403,37 @@ Variable Index  Tag Table: -Node: Top527 -Node: Introduction1925 -Node: Configuration2117 -Node: Configuration File Placement2404 -Node: Configuration Files2904 -Node: bot.conf3097 -Node: server syntax4535 -Node: channel syntax5399 -Node: bot.users6242 -Node: Using the Bot7145 -Node: Starting the Bot7395 -Node: User Levels8904 -Node: Protection10306 -Node: Automatic Op10914 -Node: Built-In Commands11203 -Node: Scripting18182 -Node: Adding New Commands19254 -Node: Hooks20575 -Node: Creating a Hook21415 -Node: Hook Types22621 -Node: Received Message Hooks23185 -Node: Sent Message Hooks28412 -Node: DCC CHAT Hooks29809 -Node: Miscellaneous Hooks30849 -Node: Scheme User Levels31298 -Node: Sending Messages32432 -Node: High Level Message Functions33048 -Node: Low Level Message Functions33828 -Node: Misc Scripting Stuff34891 -Node: Concept Index41467 -Node: Function Index41686 -Node: Variable Index52922 +Node: Top538 +Node: Introduction1948 +Node: Configuration2140 +Node: Configuration File Placement2584 +Node: Configuration Files3085 +Node: bot.conf3278 +Node: server syntax4885 +Node: channel syntax5683 +Node: bot.users6727 +Node: Using the Bot7630 +Node: Starting the Bot7880 +Node: User Levels9389 +Node: Protection10777 +Node: Automatic Op11495 +Node: Built-In Commands11914 +Node: Scripting18893 +Node: Adding New Commands19965 +Node: Hooks21286 +Node: Creating a Hook22126 +Node: Hook Types23332 +Node: Received Message Hooks23896 +Node: Sent Message Hooks29123 +Node: DCC CHAT Hooks30520 +Node: Miscellaneous Hooks31560 +Node: Scheme User Levels32009 +Node: Sending Messages33143 +Node: High Level Message Functions33759 +Node: Low Level Message Functions34539 +Node: Misc Scripting Stuff35602 +Node: Concept Index42178 +Node: Function Index42397 +Node: Variable Index53633  End Tag Table diff --git a/bobot++.texinfo b/bobot++.texinfo index 47f1d53..38f5ec2 100644 --- a/bobot++.texinfo +++ b/bobot++.texinfo @@ -7,7 +7,7 @@ @ifinfo This file documents Bobot++ by Clinton Ebadi and Etienne Bernard -(original author, no longer works on program). +(The original author who no longer works on the program). Copyright 2002,2004,2005 Clinton Ebadi @@ -40,10 +40,10 @@ Texts. @ifinfo This document describes Bobot++ by Clinton Ebadi and Etienne Bernard -(original author, no longer works on program). +(The original author who no longer works on the program). This document applies to version 2.2 of the program named -Bobot++ +Bobot++. Copyright 2002,2004,2005 Clinton Ebadi @@ -127,7 +127,11 @@ content. @chapter Configuration Bobot++ is easy to configure. See the @file{examples} directory for an -example configuration. +example configuration. + +The main configuration file is @file{bot.conf}. There are several +auxiliary configuration files (a user list, aliases file, ban list, +and a script autoexec). @menu * Configuration File Placement:: @@ -140,7 +144,7 @@ example configuration. Bobot++ will look in @file{/etc/bobotpp/default/} for its default config if none is specified on the command line. Put the configuration files you want to be loaded by default in this directory. If you are -not root or you want to have your own personal configuration, put it +not root, or you want to have your own personal configuration, put it in @file{~/.bobotpp/config/default/}. @node Configuration Files, , Configuration File Placement, Configuration @@ -154,11 +158,6 @@ in @file{~/.bobotpp/config/default/}. @node bot.conf, bot.users, Configuration Files, Configuration Files @subsection bot.conf -@menu -* server syntax:: -* channel syntax:: -@end menu - @file{bot.conf} contains key value pairs separated by @code{=}. @code{ = } @@ -171,6 +170,14 @@ bot.conf is the main configuration file for a Bobot++. The available configuration variables are listed below in the format ``@var{variable} : description'' +A few of the options have more complex syntax, they are documented in +their own subsections. + +@menu +* server syntax:: +* channel syntax:: +@end menu + @itemize @bullet @item @var{nickname} : The nickname of the bot (@var{nick} is an @@ -182,56 +189,69 @@ the bot (@var{command} is an alias for @var{cmdchar}) the bot (@var{realname} is an alias for @var{ircname}) @item @var{userlist} : Name of the file where the userlist is stored -@item @var{shitlist} : Name of the file where the shitlist is -stored +@item @var{shitlist} : Name of the file where the shitlist +(ban list) is stored @item @var{logfile} <$LOGDIR/bot.log>: Location of the bot logfile (set this to @file{/dev/null} to disable logging). -@item @var{server} : This specifies the server to connect -to. Note that this has a special syntax. -@item @var{channel} : This specifies a channel the bot will join -when it starts up. This also has a special syntax. +@item @var{server} : This specifies the server to which the bot +will connect. Note that this has a special syntax @pxref{server +syntax}. +@item @var{channel} : This specifies the channels the bot will join +when it starts up. This has a special syntax @pxref{channel +syntax}. @end itemize @node server syntax, channel syntax, bot.conf, bot.conf @subsubsection server syntax +The server syntax in @file{bot.conf} allows you to specify an +alternate port to connect on, and a password to send the server. + +You may use more than one server line; Bobot++ will attempt to connect +to the first one, and will connect to the next one in the list if it +fails. The bot will continue cycling through the server list until it +is able to connect to one. There is a command (@code{!cycle}) to make +the bot to cycle servers. + @var{server} = @var{server_name} [@var{port} [@var{password}]] This will make Bobot++ attempt to connect to @var{server_name} on port @var{port} with the password @var{password}. @var{server_name} should be the address of the server. @var{port} and @var{password} are -optional. You may use more than one server line; Bobot++ will attempt -to connect to the first one and, if it fails, will connect to the next -one in the list. There is also a command to cause the bot to cycle -servers. At the present time Bobot++ cannot connect to more than one -server at a time. This is a planned feature of 3.0 (which is a very -long way away; the current structure of the program would make it very -difficult to add support for connecting to multiple servers at a time -in a usable manner). +optional. @node channel syntax, , server syntax, bot.conf @subsubsection channel syntax +The channel syntax in @file{bot.conf} allows you to specify the +initial modes the bot should set on a channel, the modes the bot +should maintain, and a key if the channel needs it. + +You may have any number of channel lines. When Bobot++ starts it will +attempt to join and gain operator status in every channel listed. + @var{channel} = @var{name}:@var{initial_modes}:@var{modes_to_keep}:@var{channel_key} -You may have any number of channel lines. When Bobot++ starts it will -attempt to join and gain ops in every channel listed. It will join -@var{name} and set the channel modes to @var{initial_modes} -(e.g. ``nt'') if it is able to gain operator status. It will then -maintain @var{modes_to_keep}. If the channel requires a key to enter -simply set @var{channel_key}. Every argument except for @var{name} is -optional. +The bot will join @var{name} and set the channel modes to +@var{initial_modes} (e.g. ``nt'') if it is able to gain operator +status. It will then maintain @var{modes_to_keep}. If the channel +requires a key to enter simply set @var{channel_key}. Every argument +except for @var{name} is optional. A few example lines: -@code{@var{channel} = #foo:nt:nt:bar} +@example +@var{channel} = #foo:nt:nt:bar +@end example The bot will join @code{#foo} with the channel key @code{bar} and will then maintain the modes @code{nt}. -@code{@var{channel} = #bar:::} +@example +@var{channel} = #bar::: +@end example The bot will join @code{#bar} and will not set any modes nor will it attempt to maintain any modes. @@ -281,7 +301,7 @@ FIXME: stuff here... @section Starting the Bot The bot is usually installed with the binary name @file{bobotpp}. It -accepts the following command line arguments: +accepts the following command line arguments. @itemize @item @code{[--help][-h]} - Shows detailed help and exits @@ -317,8 +337,8 @@ The bot defaults to running in the background as a daemon. There are several user levels available in Bobot++ to provide gradated access to commands. @command{!adduser} and @file{bot.users} use the numeric code; Scheme uses the textual name for the level. By default -(if no catch-all setting is found in @xref{bot.users}.) a user has -access to commands with the level @code{bot:user-none}. +(if the user is not found in the userlist) a user has access to +commands with the level @code{bot:user-none}. @enumerate 0 @@ -350,15 +370,15 @@ access to every feature of the bot. A user added via Scheme, the @file{bot.users} file, or @command{!adduser} may be protected from being deoped, kicked, or -banned. There are currently no symbolic levels in Scheme; just use the -numeric code. +banned. The user list and IRC commands use the numeric codes, Scheme +uses the symbolic names. @enumerate 0 -@item No protection -@item No ban. If a user is banned the bot will unban him.. -@item No kick. The user may still be kicked but the bot will kickban +@item @code{bot:protection/none} No protection +@item @code{bot:protection/no-ban} No ban. If a user is banned the bot will unban him.. +@item @code{bot:protection/no-kick} No kick. The user may still be kicked but the bot will kickban the user who kicked the protected user. -@item No deop. The bot will ensure that the user always maintains +@item @code{bot:protection/no-deop} No deop. The bot will ensure that the user always maintains operator status. @end enumerate @@ -366,8 +386,13 @@ operator status. @section Automatic Op A user may be automatically given operator status upon entering a -channel. Set the @var{aop} field to ``0'' to disable auto-op or ``1'' -to enable auto-op. +channel. Scheme uses the symbolic name, the user list +(@file{bot.users}) and IRC commands use the numeric value. + +@enumerate 0 +@item @code{bot:aop/no} Do not automatically op the user +@item @code{bot:aop/yes} Do automatically op the user +@end enumerate @node Built-In Commands, , Automatic Op, Using the Bot @section Built-In Commands -- 2.20.1