Add some documentation

4 files changed, 338 insertions, 0 deletions

diff --git a/COPYING b/COPYING
new file mode 100644
index 0000000..8806baf
--- /dev/null
+++ b/COPYING
@@ -0,0 +1,20 @@
+Copyright (c) 2013 Florent Le Coz
+
+This software is provided 'as-is', without any express or implied
+warranty. In no event will the authors be held liable for any damages
+arising from the use of this software.
+
+Permission is granted to anyone to use this software for any purpose,
+including commercial applications, and to alter it and redistribute it
+freely, subject to the following restrictions:
+
+1. The origin of this software must not be misrepresented; you must not
+claim that you wrote the original software. If you use this software
+in a product, an acknowledgment in the product documentation would be
+appreciated but is not required.
+
+2. Altered source versions must be plainly marked as such, and must not be
+misrepresented as being the original software.
+
+3. This notice may not be removed or altered from any source
+distribution.
diff --git a/INSTALL b/INSTALL
new file mode 100644
index 0000000..309ecc0
--- /dev/null
+++ b/INSTALL
@@ -0,0 +1,75 @@
+==============
+ Dependencies
+==============
+
+Build and runtime dependencies:
+
+Libraries:
+- crypto++
+ Sometimes packaged as cryptopp.  This library is used to generate MD5
+ hashes.
+ http://www.cryptopp.com/
+- expat
+ Used to parse XML from the XMPP server.
+ http://expat.sourceforge.net/
+- libiconv
+ Encoding from anything into UTF-8
+ http://www.gnu.org/software/libiconv/
+
+Tools:
+- A C++11 compiler.
+- CMake
+
+
+==============
+  Configure
+==============
+
+Configure the build system using cmake, there are many solutions to do
+  that, the simplest is to just run
+
+% cmake .
+
+in the current directory
+
+You can also configure many parameters of the build (like personnalize
+CFLAGS, the install path, choose the compiler, or enabling some options
+like the POLLER to use), using:
+
+% ccmake .
+
+In ccmake, first use 'c' to configure the build system, edit the values you
+need and finaly use 'g' to generate the Makefiles to build the system and
+quit ccmake.
+
+or
+
+% cmake -i .
+
+and respond to the questions when you are prompted to.
+
+You can select the poller used by biboumi, at compile-time, using the POLLER
+cmake option.  Available values are:
+ POLL: use the standard poll(2). This is the default value because it works on all supported plateforms
+ EPOLL: use the Linux-specific epoll(7)
+
+Example, configure the poller with cmake:
+% cmake . -DPOLLER=EPOLL
+
+
+==============
+    Build
+==============
+
+- Build the project
+
+% make
+
+
+=============
+   Install
+=============
+
+- Install the software system-wide
+
+# make install
diff --git a/README b/README
new file mode 100644
index 0000000..8a4f3b3
--- /dev/null
+++ b/README
@@ -0,0 +1,51 @@
+ _     _ _                           _
+| |__ (_) |__   ___  _   _ _ __ ___ (_)
+| '_ \| | '_ \ / _ \| | | | '_ ` _ \| |
+| |_) | | |_) | (_) | |_| | | | | | | |
+|_.__/|_|_.__/ \___/ \__,_|_| |_| |_|_|
+
+
+Homepage:       http://dev.louiz.org/projects/biboumi
+
+Biboumi is an XMPP gateway that connects to IRC servers and translates
+between the two protocols. It can be used to access IRC channels using any
+XMPP client as if these channels were XMPP MUCs.
+
+It is written in modern C++11 and make great efforts to have as little
+dependencies and to be as simple as possible.
+
+The goal is to provide a way to access most of IRC features using any XMPP
+client.  It doesn’t however try to provide a complete mapping of the
+features of both worlds simply because this is not useful and most probably
+impossible.  For example all IRC modes are not all translatable into an XMPP
+features.  Some of theme are (like +m (mute) or +o (operator) modes), but
+some others are IRC-specific.  If IRC is the limiting factor (for example
+you cannot have a non-ASCII nickname on IRC) then biboumi doesn’t try to
+work around this issue: it just enforces the rules of the IRC server by
+telling the user that he/she must choose an ASCII nickname only.  An
+important goal is to keep the software (and its code) light and simple.
+
+================
+    Install
+================
+Refer to the INSTALL file.
+
+================
+    Authors
+================
+Florent Le Coz (louiz’) <louiz@louiz.org>
+
+=================
+ Contact/Support
+=================
+Jabber ChatRoom:     biboumi@muc.poezio.eu
+Report a bug:        http://dev.louiz.org/projects/biboumi/issues/new
+
+=================
+    License
+=================
+Biboumi is Free Software.
+(learn more: http://www.gnu.org/philosophy/free-sw.html)
+
+Biboumi is released under the zlib license.
+Please read the COPYING file for details.
diff --git a/doc/biboumi.1 b/doc/biboumi.1
new file mode 100644
index 0000000..c874062
--- /dev/null
+++ b/doc/biboumi.1
@@ -0,0 +1,192 @@
+.TH biboumi 1 2013-11-21
+.
+.SH NAME
+.
+\fBbiboumi\fR - XMPP gateway to IRC
+.
+.SH SYNOPSIS
+.
+\fBbiboumi\fR [\fIconfig_filename\fR]
+.
+.SH DESCRIPTION
+.
+Biboumi is an XMPP gateway that connects to IRC servers and translates
+between the two protocols. It can be used to access IRC channels using any
+XMPP client as if these channels were XMPP MUCs.
+.
+.SH OPTIONS
+.
+Available options:
+.TP
+\fBconfig_filename\fR
+Specify the file to read for configuration. See \fBCONFIG\fR section for
+more details on its content.
+.
+.SH CONFIG
+.
+The configuration file uses a simple format of the form
+\fB"option=value"\fR. Here is a description of each possible option:
+.TP
+\fBhostname\fR (mandatory)
+The hostname served by the XMPP gateway.  This domain must be configured in
+the XMPP server as an external component.  See the manual for your XMPP
+server for more information.
+.TP
+\fBpassword\fR (mandatory)
+The password used to authenticate the XMPP component to your XMPP server.
+This password must be configured in the XMPP server, associated with the
+external component on \fBhostname\fR.
+.
+.SH USAGE
+.
+When started, biboumi connects, without encryption (see \fBSECURITY\fR), to
+the local XMPP server on the port \fI5347\fR and provides the configured
+password to authenticate.  Biboumi then serves the configured
+\fIhostname\fR, this means that all XMPP stanza with a \fIto\fR JID on that
+domain will be sent to biboumi, and biboumi will send only send messages
+coming from this hostname.
+.
+When an user joins an IRC channel on an IRC server (see \fBJoin an IRC
+channel\fR), biboumi connects to the remote IRC server, sets the user’s nick
+as requested, and then tries to join the specified channel.  If the same
+user subsequently tries to connect to an other channel on the same server,
+the same IRC connection is used.  If, however, an other user wants to join
+an IRC channel on that same IRC server, biboumi opens a new connection to
+that server.  Biboumi connects once to each IRC server, for each user on it.
+.
+.SS "Addressing"
+.
+IRC entities are represented by XMPP JIDs.  The domain part of the JID is
+the domain served by biboumi, and the local part depends on the concerned
+entity.
+.
+IRC channels and IRC users JIDs have a localpart formed like this: \fIname\fR,
+the '\fI%\fR' separator and the \fIirc_server\fR.
+.
+For an IRC channel, the name starts with '\fI&\fR', '\fI#\fR', '\fI+\fR'
+or '\fI!\fR'. Some other gateway implementations, as well as some IRC
+clients, do not require them to be started by one of these characters,
+adding an implicit '\fI#\fR' in that case.  Biboumi does not do that because
+this gets confusing when trying to understand the difference between
+\fIfoo\fR, \fI#foo\fR, and \fI##foo\fR.
+.
+If the name starts with any other character, this represents an IRC user.
+.
+.SS "Join an IRC channel"
+.
+To join an IRC channel \fI#foo\fR on the IRC server \fIirc.example.com\fR,
+join the XMPP MUC \fI#foo%irc.example.com@hostname\fR.
+.
+.SS "Channel messages"
+.
+On XMPP, unlike on IRC, the displayed order of the messages is the same for
+all participants of a MUC.  Biboumi can not however provide this feature, as
+it cannot know whether the IRC server has received and forwarded the
+messages to other users.  This means that the order of the messages
+displayed in your XMPP may not be the same than the order on other IRC
+users’.
+.
+.SS "Nicknames"
+.
+On IRC, nicknames are server-wide.  This means that one user only has one
+single nickname at one given time on all the channels of a server. This is
+different from XMPP where an user can have a different nick on each MUC,
+even if these MUCs are on the same server.
+.
+This means that the nick you choose when joining your first IRC channel on a
+given IRC server will be your nickname in all other channels that you join
+on that same IRC server.
+If you explicitely change your nickname on one channel, your nickname will
+be changed on all channels on the same server as well.
+.
+.SS "Private messages"
+.
+Private messages are handled differently on IRC and on XMPP.  On IRC, you
+talk directly to one server-user: toto on the channel #foo is the same user
+than toto on the channel #bar (as long as these two channels are on the same
+IRC server).  Using biboumi, there is no way to receive a message from a
+room participant (from a jid like \fI#test%irc.example.com/\fBnickname\fR).
+Instead, private messages are received from and sent to the user (using a
+jid like \fBnickname\fI%irc.example.com\fR).  For conveniance and
+compatibility with XMPP clients sending private messages to the MUC
+participants, a message sent to
+\fB#chan%irc.example.com@irc.example.net/Nickname\fR will be redirected to
+\fBNickname%irc.example.com@irc.example.net\fR, although this is not the
+prefered way to do it.
+.
+.SS "Notices"
+.
+Notices are received exactly like private messages.  It is not possible to
+send a notice.
+.
+.SS "Kicks and bans"
+.
+Kicks are transparently translated from one protocol to another.  However
+banning an XMPP participant has no effect.  To ban an user you need to set a
+mode +b on that user nick or host (see \fBMODES\fR) and then kick it.
+.
+.SS "Encoding"
+.
+On XMPP, the encoding is always \fIUTF-8\fR, whereas on IRC the encoding of
+each message can be anything.
+.
+This means that biboumi has to convert everything coming from IRC into UTF-8
+without knowing the encoding of the received messages.  To do so, it checks
+if each message is UTF-8 valid, if not it tries to convert from
+\fIiso_8859-1\fR (because this appears to be the most common case, at least
+on the channels I visit) to \fIUTF-8\fR.  If that conversion fails at some
+point, a placeholder character '\f�\fR' is inserted to indicate this
+decoding error.
+.
+Messages are always sent in UTF-8 over IRC, no conversion is done in that
+direction.
+.
+.SS "IRC modes"
+.
+One feature that doesn’t exist on XMPP but does on IRC is the \fImodes\fR.
+Although some of these modes have a correspondance in the XMPP world (for
+example the \fI+o\fR mode on an user corresponds to the \fImoderator\fR role
+in XMPP), it is impossible to map all these modes to an XMPP feature.  To
+circumvent this problem, biboumi provides a raw notification when modes are
+changed, and lets the user change the modes directly.
+.
+To change modes, simply send a message starting with “\fB/mode\fR” followed
+by the modes and the arguments you want to send to the IRC server.  For
+example “/mode +aho louiz”.  Note that your XMPP client may
+inteprete messages begining with “/” like a command.  To actually send a
+message starting with a slash, you may need to start your message with
+“//mode” or “/say /mode”, depending on your client.
+.
+When a mode is changed, the user is notified by a message coming from the
+MUC bare JID, looking like “Mode #foo [+ov] [toto tutu]”.  In addition, if
+the mode change can be translated to an XMPP feature, the user will be
+notified of this XMPP event as well. For example if a mode “+o toto” is
+received, then toto’s role will be changed to moderator.  The mapping
+between IRC modes and XMPP features is as follow:
+.
+.TP
+.B +o
+Sets the participant’s role to \fImoderator\fR.
+.
+.TP
+.B +a
+Sets the participant’s role to \admin\fR.
+.
+.TP
+.B +v
+Sets the participant’s affiliation to \fImember\fR.
+.
+.SH SECURITY
+.
+Biboumi does not provide any encryption mechanism: connection to the XMPP
+server MUST be made on localhost.  The XMPP server is not supposed to accept
+non-local connection from components, thus encryption is useless.  IRC
+SSL/TLS is also not implemented although this could be useful for some
+users, this is however not a high priority feature.
+.
+Biboumi also does not check if JIDs are properly formatted using nodeprep.
+This must be done by the XMPP server to which biboumi is directly connected.
+.
+.SH AUTHORS
+.
+Written by Florent Le Coz