/* $Id: README,v 1.666 2004/09/20 10:50:27 shrike Exp $ */
	COMM_IRC patch v1.4
	Author: Cronel (cronel@mube.net) [Pedro J. Romero Duhau]

	This patch adds IRC connectivity to a SMAUG mud. The original
	idea and first implementation was from Unilynx (arnold@poboxes.com),
	for SMAUG 1.2. I (Cronel) redid it from scratch using his code
	as reference, updating things for version 1.4, and adding many
	new features to the code.

	The patch allows the mud to connect to the IRC network and lets
	IRC users (clients) login to the mud and play, without actualy
	connecting to the mud. It also allows for DCC chat connections
	and many other things.


	FILES

	comm_irc.doc		This file
	comm_irc.c		The main C
	comm_irc.patch		A 5-line context diff
	comm_irc.spatch		A 2-line context diff
	comm_irc.help		Help topics you can add directly


	THE STORY

	I'll make it short...
	Originaly, some guys decided to set up a SMAUG mud for their
	IRC network (Icenet). Unilynx made the necessary code changes
	and this mud ran for a long time.
	Later, Icenet went down, and it was (sort of) reborn as Xnet.
	The mud was moved to Xnet. It still ran on the same code. In
	this mud I was made immortal and head coder. As time passed
	I wanted to add features to the irc-connect code but kept
	pushing it, so one day SMAUG 1.4 was released and I decided
	it was easier to redo the irc part from scratch using 1.4
	comm.c as base than trying to translate Uni's code to 1.4,
	and since I was doing it from scratch I could add all the
	new features.


	INSTALLATION

	The code consists of a new "comm_irc.c" file, a lot of modifications
	to "comm.c", and a few minor changes to a couple of other files
	(act_comm.c, act_info.c, act_wiz.c, mapout.c, save.c, tables.c).
	Installing consists in copying ircdata.dat to your system directory,
	comm_irc.c and comm_irc.patch to your src directory and, while
	in the src directory, running

		patch <comm_irc.patch

	(After this you should check that there are no *.reject files.
	 These files result from the patch utility being unable to patch
	 in the modifications. This could possibly happen if you've
	 heavily modified the stock comm.c. If it can't patch your
	 comm.c, you'll have to add everything by hand, so I hope you
	 can code...).

	If everything went well so far, type "make clean", then "make".

	At this point, you can set the IRC data (such as the server you'll
	connect to, the mud's nick, etc) directly by changing the ircdata.dat.
	As you see the format is like all the other SMAUG .dat files. Change
	the servers and ports to the ones you'll be connecting to.
	Alternatively, you can just boot it up and set it online and have
	the mud try to connect again using "ircconnect".
	Remember the ircdata.dat must be moved to the /system directory in
	the SMAUG distribution.

	If at any point you have problems, such as patch failing, the code
	not compiling, or whatever, please do NOT mail the smaug mailing
	list about it; mail me at cronel@mube.net.

	You will also need to create the commands using "cedit" once inside
	the game. The commands you need to create are: ircconnect, ircdisconnect,
	ircset, color and irclink (with their respective do_* functions).
	For instance, you would type:
		cedit ircset create do_ircset

	FEATURES

	* IRC logins
	* DCC logins
	* mIRC color support (including attributes like bold,
	  underlined, and reverse)
	* Connection to irc in both server and client mode
	* Online configuration for all the IRC settings
	* Interaction with the services (nickserv) instead of/along
	  with passwords to authenticate players
	* Support for sending mIRC sound requests (this will only
	  work for irc-logged-in players)


	PURE IRC LOGINS

	By 'pure irc login' I mean that an IRC user can "connect" to
	your mud only by means of messages in the IRC network, as 
	opposed to actualy establishing a connection. This could
	be desirable for a number of reasons. If it's not, you
	can disable it by commenting out the "login" and "slogin"
	parts of the "msg_from_known_nick" function.
	This way you can have the mud simply act as a bot that will 
	redirect all "!login" requests as DCC chats to the telnet port, 
	and still take advantage of the mIRC color code and other 
	features.
	If you decide to use it, there are two ways of logging in:
	"login" and "slogin". The login mode will make it so that
	an irc user can only play a character named like his irc
	nickname; when he changes nicks, he will go link-dead. The 
	slogin mode makes the irc nickname and the player name 
	totaly independent.


	SERVER OR CLIENT MODE

	The mud can connect to the IRC network in two modes: server and
	client. To connect as a server you will need a link from another
	server. It's not likely that you'll get one unless you already
	are an op or an admin for an irc server or are otherwise connected
	to the administration of an irc network. Luckily, to connect as a
	client, you don't need anything.
	When connected as server, the mud will appear to be a normal IRC
	server in all respects (except that people can't actualy connect
	to it with their irc client, of course). This pseudo-server will 
	"login" (actualy only announce to the network) a new irc client
	("mud"). 
	The client mode is actualy just an emergency mode. The mud is not
	IRC playable in client mode because its too laggy. There's nothing
	that can be done about that (it happens because of how the irc
	daemons work). However, the mud, connected as client, will still
	be open to DCC login requests, so it's still playable.
	Another difference to the user will be that when the mud is 
	connected as client, players are required to be in the mud channel 
	to play. 


	mIRC COLORS

	There are two sets of colors for mIRC; one for people who use mIRC
	with black background, and one for white background. The 
	translation tables for ANSI->mIRC colors is found in the function
	create_color_code, you're free to change it if you don't like the
	colors. Normal SMAUG color sequences (like "&C", "&z", etc) are
	translated to ANSI or to mIRC color sequences depending on what
	the player wants. 
	Special mIRC attributes, like bold, are escaped via 'S':
		&SB 	Bold
		&SU 	Underlined
		&SR 	Reverse
		&SP 	Plain
		&SC 	Color escape
		&SS	CTCP escape
	None of this will work for people with ANSI. 


	IRC SETTINGS & COMMANDS

	The code needs to know a few things to connect. These are all
	specified in the ircdata.dat file, and can be set using the
	"ircset" command. The meaning of each one of the fields specified
	in ircdata.dat is (first the ircdata.dat field is given, then
	the ircset subcommand in parentheses):

	Mode (mode)		It can be "server" (1) or "client" (0).

	SServer	(sserver)	When the mud is acting as a server, this
				is the server it will try to connect to,
	SPort (sport)		this, the port it will connect to, and
	SPwd (spwd)		this is the server password it will use.

	MudServer (mud_server)	This is the server that the mud will "be",
				as it will appear in /links, when acting as
				server.
	PseudoHost (mud_host)	When acting as server, this is the host that
				the mud nick will appear to be to other users
				(in /whois, for instance). You can set it to
				whatever you want. It's just a nice detail.

	CServer (cserver)	When the mud is acting as a client, these
	CPort (cport)		are the server/port it will connect to.

	CPwd (cpwd)		This is the nickserv password for the mud
				nick. It's necessary in both modes.

	Timeout (timeout)	This is the time, in seconds, that the code
				will wait for a response from the server
				it's connecting to. If there is no response
				the connection will be closed.

	MudNick (mud_nick)	The irc nickname for the mud.
	MudChannel		The mud channel.
	 (mud_channel)

	DccPort (dcc_port)	The port that will be used to redirect all
				DCC connections.
	DccTimeout		The time in seconds that the code will wait
	 (dcc_timeout)		before closing the port to DCC connections
				after a "!login" request.

	Desc (desc)		This is just a one line description of the
				mud. Generaly, set it to something like
				"<Whatever> MUD! How cool! /query
				 <mud_nick> to play". This text will appear
				when people type /whois <mud_nick> and in
				the /links list if mud is acting as a server.

	Reconnect (reconnect)	This is a flag (0 or 1). If 1, the mud will
				try to reconnect to IRC when its connection
				goes down (not when you manualy disconnect it).

	The ircdata.dat fields must finished by an "End" line, and enclosed
	between an "#IRCDATA" and an "#END" line.

	You also have the "ircconnect" and "ircdisconnect" commands, that
	will connect and disconnect the mud from irc, using the ircdata.
	Most of the changes you can make via ircset will not take effect
	until you reconnect.

	The sserver, sport, spwd, and mud_server fields will usualy be
	given to you by whoever is giving you the link from the other
	IRC server (the "S line" as they are called).

	Also note that the code has a fallback feature. If it's
	set to connect as a server and it can't, it will fall back to
	trying to connect as a client, and only if it can't do that
	either will it declare that it failed and abandon all hope.
	So If you're set to connect as a server to a certain other
	server, it's recommended that you still set the cserver/cport
	to something valid (and different from the other server) so
	that if the server you're connecting to goes down, the mud
	will still be available. This, coupled with the reconnect flag,
	will make it so that even if the other server suddenly goes
	down, your mud will reconnect in client mode.


	NON-OBVIOUS CHANGES

	To make the irc connecting code more integrated with SMAUG, I
	changed	several immortal commands. These are:

	- users:  	It shows the type of login (IRC, DCC, TELNet)
		  	and in the case of IRC logins, it shows the irc nick
		  	instead of the descriptor/port.

	- whois:  	It shows the type of login of the person, his
		  	nick, and his login mode.

	- forceclose:	besides accepting descriptor numbers as
		  	argument, it now accepts the nick of irc players.

	- rip/ansi:	these two commands were erasen, and their
		  	functionality passed to a new command "color". This
		  	is in comm_irc.c now, not act_comm.c. Color is no
		  	longer a couple of bits in ch->act, but a new whole
		  	field ch->color.

	- config:	The config [+/-] ansi and rip were also removed, of 
			course. A new config +msg was added. This lets the
			users configure wether they want the mud to respond
			to them via NOTICEs or PRIVMSGs. Notices are the 
			default since they are the correct behavior for
			bots (and mud is a bot.. a special bot).

	- echo:		If connected to IRC, all echoes will also be sent
			as notices to the mud channel.


	CONNECTION RESTRICTIONS

	Since in our mud we went IRC all the way, I placed restrictions so
	that
		a) Only immortals and non-auths can connect via telnet.
		b) Everyone can connect via DCC, but their connection is
		   closed as soon as they leave the IRC network (or the
		   channel if in client mode).
	To remove the first restriction, type these lines at the beginning
	of comm_irc.c:
		#undef CAN_TELNET
		#define CAN_TELNET (TRUE)
	And everyone will be able to telnet to your mud.
	To remove the second restriction, type this line at the beginning
	of comm_irc.c
		#define ALLOW_PURE_DCC
	And, once connected to the mud via DCC, everyone can disconnect
	from the IRC network without consequences.


	KNOWN PROBLEMS

	*All* the code in ibuild.c is written under the assumption that
	the character wants ANSI colors (it never actualy checks).
	Furthermore, it uses ANSI sequences that are meaningless in
	mIRC (such as clear screen). So I didn't touch any of this
	code; as a consequence, if you use this feature in an IRC
	connection, you will see ANSI escapes.

	The 1.4 snoop command sends to you exactly what is being sent
	to the victim; thus, you will be sent the victim's color
	sequences. No easy way around this. It's not so important
	anyway, since the input from the snooped victim will be visible,
	but the ouptut they see might not look too good to you.

	The nickserv interaction was done using the Xnet Nickserv
	service at the time. I make no guarantee as to how standard
	it is. I might need changing for current services.

	Besides this, I don't know of any bugs in the code, though I'm
	sure there are some. If you spot any, report them to me at
	cronel@mube.net.


	LICENSE

	In order to use or distribute this patch, you must
	follow the licenses of SMAUG, Merc, and Diku, and also:
	- Original copyright notice must remain in the
	  source file, even in modified versions.
	- You must create a help topic "irc code" that
	  contains the following:
	   "COMM_IRC patch v1.4"
	   "Low-level IRC connecting module for SMAUG 1.4a"
	   "Copyright (C) 1998-2002 by Cronel"
	   "Based on original code by Unilynx"
	  This help topic is included in the "comm_irc.help"
	  file, for your convenience. The level for this
	  help topic should be 1.
	- The USERINFO, and VERSION CTCP replies cannot be
	  removed or modified. To display information specific
	  to your mud, change the FINGER reply.
        Although not required, sending me a mail would be
        nice too.