:::::::::::::::::::
:: Irk807 Manual ::
:::::::::::::::::::

Created by macgeek
Version 0.03 (08/21/06)
http://farhnware.homelinux.com/software/irk807.php

Configuration
*************
Irk807 uses the configuration file .irk807 which
is stored in the same directory as the Irk807
application. The default configuration file has
comments that describe how to set it up. All
settings that can be set in the configuration
file can be set in the program. Here is a list of
all the settings.

Server <address> <port>
	The IRC server to connect to.

AutoConnect [yes|no]
	Whether or not to connect to the IRC
	server automatically on launch.

Account <nickname> <password>
	The nickname for the bot to go by on IRC.
	The password is optional, but required if
	the bot's nickname is registered to
	services.

Trigger <character>
	A single character that lets the bot know
	you are talking to it. If you put more
	than one character, Irk807 will only take
	the first character for the trigger.

NamedReply [yes|no]
	Whether or not to prefix responses with
	the sender's name. Does not apply to
	private messages.

Redirect <word>
	The redirect is a word that tells the bot
	to send the response to another user
	in a private message.

PrivateRedirect [yes|no]
	Whether or not redirected responses
	appear in a private message or are just
	prefixed with the redirectee's nickname.

Lapse <seconds>
	Amount of time that must pass before an
	identical command is allowed to be
	run again.

VainKarma <amount>
	Vain karma is the amount of karma to
	remove from a user if they try to change
	their own karma. Typically 1 or 0.

AutoOp <channel> <nicknames>
	If the bot has ops in a channel, and
	someone joins that channel who is on the
	auto op list for that channel, the bot
	will give them ops. <nicknames> is a
	list of nicknames separated by commas.
	For each channel, you need a separate
	line in the config file. Putting 'all'
	for <nicknames> will give ops to anyone
	who joins the channel.

AutoVoice <channel> <nicknames>
	If the bot has ops in a channel, and
	someone joins that channel who is on the
	auto voice list for that channel, the
	bot will give them voice. <nicknames> is
	a list of nicknames separated by commas.
	For each channel, you need a separate
	line in the config file. Putting 'all'
	for <nicknames> will give voice to anyone
	who joins the channel.

AutoJoin <channel>
	A channel the bot should join when it
	connects to the IRC server. Each channel
	goes on a separate line.

MasterNick <nickname>
	A master nick is a nickname that is
	allowed to issue master commands. For
	each master nick, you need a seperate
	line in the config file.

Blacklist <nickname>
	A blacklisted nickname is not allowed
	to send commands to the bot; the bot
	will simply ignore them. Each nickname
	goes on a separate line.

WelcomeMessage <message>
	A message that gets displayed to users
	who enter a channel that a bot is in.
	Variables can be used in the message:
	%n for nickname of user who joined, %c
	for channel they just joined, and %% for
	a literal percent sign. If you don't want
	a welcome message, simply leave <message>
	blank.

HangmanLoseMessage <message>
	This message gets displayed when a game
	of hangman is lost. There are 4 variables
	that can be used in the message:
	%n for the nickname of the user that
	lost, %c for the channel they lost in,
	%w for the word they didn't guess, and %%
	for a literal percent sign. If this is
	left blank, the default will be used
	instead.

ErrorLog <location>
	The location for the error log. If no
	location is given, the default location
	of ./error.log is used. The bot must be
	able to write to the location given.

ChannelLog <channel> <location>
	NOT FUNCTIONING YET!!!
	Used to log channel activity. If you want
	to log all channels that the bot is in,
	use "all" for the channel. If no location
	is given, the default location of
	./<server>-<channel>.log is used, where
	<server> is the IRC server that <channel>
	is on. The bot must be able to write to
	the location given.

In the rest of the manual, "!" is used to
represent the trigger, and "@" for the redirect.

Factoids
********
Irk807 can handle factoids. You can teach Irk807
factoids with one of the following syntaxes:

!<item> is <description>
!<item> = <description>

You can put variables in factoids. %n represents
the sender's nickname, %c represents the current
channel, and %v the variable passed to factoid.
To put a literal percent sign, use %%. Example:

<foo> !test is Testing %v in %c, %n
<bar> I added the test factoid
<foo> !test variables
<bar> Testing variables in #chan, foo

Factoids can be recalled like so:

!<item>

To send a factoid to a user in a private message,
do this:

!<item> @ <nickname>

If a factoid has outdated or incorrect
information, you can use the keyword now to
change it:

!<item> is now <description>
!<item> = now <description>

You can create aliases for factoids using the
alias keyword:

!<item> is alias <item>

Only master nicknames can delete factoids.
Deleting a factoid uses this syntax:

!delete <item>

Master nicknames can also purge the entire
database, deleting all records:

!purge -yes

If you don't use the -yes option, Irk807
will ask you to if you are sure, and if so,
to use the -yes option.

Karma
*****
Ever seen kudos or props? Irk807 can keep track
of users' karma in a similar manner. To show
a user's karma, do this:

!karma <nickname>

You can also list everybody's karma by using the
following command. This will be displayed in a
private message to person that called it.

!karma

Any user can change another user's karma, like
so:

!karma <nickname> [+|-]

You can only change a user's karma by one, up or
down.

Irk807 has a feature called vain karma. This is
the amount of karma to remove from a user if they
try to change their own karma. It is typically 1
or 0.

Other Commands
**************
Irk807 has a slew of other commands. Here's a list
of all of them, and their syntaxes and
descriptions.

!action <channel> <message>
	Allows master nicks to send CTCP ACTION to
	a channel (or nickname) under the guise
	of the bot.

!deop [<channel>] <nickname>
	Attempts to remove ops from <nickname> in
	<channel>. If <channel> is empty, uses the
	channel the command was sent from. Only
	usable by a master nick.

!devoice [<channel>] <nickname>
	Attempts to remove voice from <nickname> in
	<channel>. If <channel> is empty, uses the
	channel the command was sent from. Only
	usable by a master nick.

!google [<query>]
	Gives a formatted Google link for <query>.
	If <query> is empty, it gives the Google
	home page.

!guess <letter>
	Guesses a letter or word in hangman. See
	below.

!hangman [<command> [<parameter>]]
	Used to play a hangman game. Passing no
	command starts a new game or shows the
	status of the current game. Here are the	
	commands and parameters:
		add <word>
		guess <letter>
		end
	The first command adds a word to the
	database. The guess command guesses a
	letter in the current word, or guesses
	the entire word. The last command ends
	the current game of hangman.

!help [<command>]
	Displays help in a private message to the
	caller. Supplying <command> provides help
	for that command.

!join <channel>
	Tells the bot to join a channel. Can only
	be called by a master nick. Currently does
	not support channel keys.

!lart [<nickname>]
	The Luser Attitude Readjustment Tool. If
	<nickname> is empty, it attacks the sender.
	Same applies if you try to attack the bot.

!lock
	Only usable by a master nick. Locks the bot
	down from acting on commands, only when
	unlocked.

!map [<location>]
	Gives a Google Maps link for <location>.
	If <location> is empty, returns Google
	Maps home page.

!op [<channel>] <nickname>
	Attempts to give ops to <nickname> in
	<channel>. If <channel> is empty, uses the
	channel the command was sent from. Only
	usable by a master nick.

!part <channel>
	Tells the bot to part a channel. Can only
	be used by a master nick.

!ping [<address>]
	Pings <address> once. If <address> is empty,
	replies to sender with "pong".

!pong
	Display a random ASCII image of a Pong
	game.

!quit
	Only a master nick can use this command.
	Tells the bot to quit from the IRC server.

!radio <address> [<port>]
	Gets the current track on a SHOUTcast
	server and provides a link to tune it.
	If <port> is empty, uses 8000 instead.

!roll [<sides>]
	Rolls an imaginary die with <sides> sides,
	and displays the resulting number. If
	<sides> is empty, uses 6 instead.

!rot13 [<phrase>]
	Performs ROT13 on the passed string. If
	<phrase> is empty, it uses the sender's
	nickname instead.

!rot26 [<phrase>]
	Performs ROT26 on the passed string. If
	<phrase> is empty, it uses the sender's
	nickname instead.

!say <channel> <message>
	Allows master nicks to send messages to
	a channel (or nickname) under the guise
	of the bot.

!set <parameter> <value>
	A master nick can use this to change the
	bot's settings on the fly. Here are the
	valid parameters and values:
		trigger <character>
		namedreply [yes|no]
		redirect <word>
		lapse <seconds>
		vainkarma <amount>
		masternick [-]<nickname>
		blacklist [-]<nickname>
	The masternick parameter is used to add a
	nickname to the master nick list. The
	blacklist parameter adds a nickname to the
	blacklist. Preceding <nickname> with a
	minus sign for masternick or blacklist
	will attempt to remove that nickname from
	the appropriate list.

!tell <nickname> about <item>
	Redirects a factoid to nickname.
	PrivateRedirect is in play here. To tell
	yourself about <item>, use "me" for the
	nickname. You can also use the redirect
	instead of 'about'.

!unlock
	Only a master nick can unlock the bot,
	and it when the bot is locked.

!voice [<channel>] <nickname>
	Attempts to give voice to <nickname> in
	<channel>. If <channel> is empty, uses the
	channel the command was sent from. Only
	usable by a master nick.

!wiki [<query>]
	Returns a formatted link to a Wikipedia
	article. If <query> is empty, uses the
	sender's nickname instead.

Change Log
**********
0.03 (08/17/06)
- Added settings descriptions and change log to
  manual
- Fixed error in !wiki where spaces were not changed
  to underscores
- Commands in PMs now work
- Sending commands with /bot now works
- !ping can now ping other computers
- added variables in factoids
- added factoid aliases
- distinguishes PMs from channel messages by
  inverting the angle brackets
- added !say
- added !action
- added auto join channels
- added blacklist
- added welcome message
- added privateredirect option
- added !radio
- doesn't show welcome message to itself
- error log works and is configurable
- more error checking and logging
- can't ping localhost or 127.0.0.1 any more
- added !map
- added !roll
- fixed error logging method
- added !op
- added !voice
- added !deop
- added !devoice
- now '!roll 2' gives 'heads' or 'tails'
- when using bot's name as nickname for !karma,
  says 'I have unlimited karma'
- fixed !radio so song and artist are in right
  order
- fixed config file saving and eliminated config
  comments
- added setup window if there's no config on launch
- added !tell
- factoids are all lowercase now
- karma nicks are all lowercase now
- can blacklist nicknames with !set now
- can remove master nicknames with !set now
- can remove blacklisted nicknames with !set now
- added !hangman
- rewrote hangman code
- added incorrect guesses limit of 6
- added !guess as supplement for !hangman guess
- help on commands works with or without trigger
- private messages to bot don't require trigger
- you can't do !lart himself
- empty guesses on hangman don't count
- won't allow factoid of the sender
- added !host
- putting 'all' for AutoOp or AutoVoice will tell
  the bot to op or voice anyone who joins that
  channel
0.02 (08/13/06)
- Second public release
