diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/AUTHORS | 19 | ||||
| -rw-r--r-- | doc/CHANGES | 514 | ||||
| -rw-r--r-- | doc/CREDITS | 61 | ||||
| -rw-r--r-- | doc/FAQ | 103 | ||||
| -rw-r--r-- | doc/INSTALL | 1 | ||||
| -rw-r--r-- | doc/Makefile | 14 | ||||
| -rw-r--r-- | doc/README | 172 | ||||
| -rw-r--r-- | doc/TODO | 40 | ||||
| -rw-r--r-- | doc/bitlbee.8 | 123 | ||||
| -rw-r--r-- | doc/bitlbee.conf.5 | 19 | ||||
| -rw-r--r-- | doc/bitlbee.xinetd | 12 | ||||
| -rw-r--r-- | doc/user-guide/Installation.xml | 114 | ||||
| -rw-r--r-- | doc/user-guide/Makefile | 46 | ||||
| -rw-r--r-- | doc/user-guide/Support.xml | 48 | ||||
| -rw-r--r-- | doc/user-guide/Usage.xml | 47 | ||||
| -rw-r--r-- | doc/user-guide/commands.xml | 690 | ||||
| -rw-r--r-- | doc/user-guide/docbook.xsl | 136 | ||||
| -rw-r--r-- | doc/user-guide/help.txt | 554 | ||||
| -rw-r--r-- | doc/user-guide/help.xml | 60 | ||||
| -rw-r--r-- | doc/user-guide/help.xsl | 156 | ||||
| -rw-r--r-- | doc/user-guide/misc.xml | 131 | ||||
| -rw-r--r-- | doc/user-guide/quickstart.xml | 163 | ||||
| -rw-r--r-- | doc/user-guide/user-guide.html | 446 | ||||
| -rw-r--r-- | doc/user-guide/user-guide.txt | 1209 | ||||
| -rw-r--r-- | doc/user-guide/user-guide.xml | 52 |
25 files changed, 4930 insertions, 0 deletions
diff --git a/doc/AUTHORS b/doc/AUTHORS new file mode 100644 index 00000000..82d81862 --- /dev/null +++ b/doc/AUTHORS @@ -0,0 +1,19 @@ +Current developers: + +Wilmer van der Gaast <wilmer@gaast.net> + Main developer + +Jelmer 'ctrlsoft' Vernooij <jelmer@nl.linux.org> + Documentation, general hacking, Win32 port + +Maurits Dijkstra <mauritsd@xs4all.nl> + Daemon dude, plus some other stuff + + +Retired developer: + +Sjoerd 'lucumo' Hemminga <sjoerd@hemminga-online.nl> + NickServ, documentation + +The development team wishes to thank Sjoerd for his contributions to the +Bee. diff --git a/doc/CHANGES b/doc/CHANGES new file mode 100644 index 00000000..c135535d --- /dev/null +++ b/doc/CHANGES @@ -0,0 +1,514 @@ +Version 0.99: +- Fixed memory initialization bug in OSCAR module that caused crashes on + closing the connection. +- Most likely fixed the bug that caused BitlBee to use 100% CPU time in + some situations. +- Outgoing MSN typing notifications are now understood correctly by the + orignal MS Mac/Windows clients (again). +- Added "account add $protocol" to the documentation, got rid of a lot + of over-markup (i.e. overuse of bold-tags), reviewed some other parts. +- Small changes to help.xsl to fix small flaws in the help.txt formatting. +- Messaging yourself now doesn't make irssi or mIRC crash anymore. + +Finished 3 Nov 2005 + +Version 0.93: +- " is now correctly converted to " instead of '. +- Code cleanup in OSCAR module. +- Some changes for better RFC-compliancy. +- It's now possible to specify an alternate Jabber server. +- bitlbee_save() now also checks the return value of fclose(), which might + solve more problems with lost account data. +- Fixed a file descriptor leak in bitlbee.c. +- Signedness fixes (mainly to keep GCC4 happy). +- Away messages are now sent correctly to most ICQ clients. +- BitlBee knows now which connection sends HTML, so it will strip HTML + automatically, "set html strip" is no longer necessary. Also, outgoing HTML + is escaped correctly. +- info-command works for AIM-connections too now. +- /notices to users will be sent as auto-away replies. +- Messages about a connection now also mention a handle, for people who have + multiple accounts in use of the same protocol. +- Examples are back in help.txt. + +Finished 31 Oct 2005 + +Version 0.92: +- Fixed some formatting issues with the help.txt XSL-sheet. +- Moved the polling of the IRC connections to glib instead of a separate + select(). +- Added ctags generation to the Makefiles. +- Sending a CTCP TYPING message to a user in your buddy list now sends a + typing notification to that person, if the protocol supports it. You + probably want to write/use a script for your IRC client to do this. +- A dash is no longer considered a lowercase underscore in nicknames. +- CTCP's to buddies no longer alter their private/non-private state. +- Clean shutdown (with saving settings) on SIGTERM. +- Fixed a crash on connecting to unreachable Jabber/SSL servers. +- On ICQ, offline messages are now requested after receiving the buddy + list. This should get rid of the "Message from unknown OSCAR handle" + messages on login. +- The linked list of buddies/nicks is now always sorted, which makes the + blist output a bit more useful. +- Fixed a crash on renaming NickServ. (There's no reason to do this, but + still crashing isn't really how BitlBee should tell you that. ;-) +- Now the message about the "new" ICQ server-side buddy lists is only + displayed when the server-side list is still empty. +- The Yahoo! markup language stripper is now less likely to strip things + that shouldn't be stripped. +- Working around a shortcoming in the Yahoo! cleanup code that didn't + cause any serious problems in previous versions, but got pretty nasty + (100% CPU time usage) now with everything in the glib main loop. +- Fixed a bug in http_encode that might have caused buffer overflows + (although not likely to be exploitable) when trying to encode strings + with non-ASCII characters. +- Fixed AIM screenname handling on ICQ connections. +- When blocking someone, the MSN module now closes the conversation you're + having with him/her (if any) so he/she can't continue talking to you + (for as long as the conversation lasts). +- Away messages are only sent when messaging someone outside the control + channel. (And now also when the user is offline instead of just away.) +- Moved charset conversion in serv_buddy_rename() to the right place so + bogus changes are always detected now. +- iso8859-1 is now the default charset because -15 caused some problems + and because -1 is enough for most people anyway. +- Fixed crashes on attempting to add a buddy (or do other things) on + connections that are still initializing. +- Added support for server-side notifies using the WATCH command. +- IRC_MAX_ARGS is dead, at least for IRC commands. +- Fixed a bug that made BitlBee crash on failing fresh MSN switchboard + connections. +- Fixed an invisibility bug in the MSN code that handled transfers to + other servers in the middle of a session. +- Newline stripping added to prevent newline-in-friendlyname attacks. + (Which allowed remote people to make BitlBee send raw custom IRC lines.) + +Finished 23 Feb 2005 + +Version 0.91: +- Full support for ICQ server-side contact lists! + NOTE: BitlBee now ignores your client-side contact list. If you want to + import your ICQ contact list, use the import_buddies command. +- Added the import_buddies command for upgrading purposes. +- Added support for OpenSSL. +- Fixed one major problem with the daemon mode by getting rid of the global + IRC structure. +- Documentation fixes. help.txt is now generated from XML. Also updated the + installation manual. +- Made the quickstart up-to-date. (By Elizabeth Krumbach) +- Some bitlbeed additions. (By Marcus Dennis) +- info-command support for Jabber, MSN, Yahoo! and a more verbose info-reply + for ICQ. (By Frank Thieme) +- Support for Jabber over SSL. +- nick_get() appends a _ on duplicates instead of chopping off the last + character. +- Got rid of an unused piece of code that caused crashes. + (oscar.c:gaim_parse_clientauto) +- When splitting long messages into 450-char chunks, BitlBee now tries not + to cut off in the middle of a line. +- Added a warning when the user specifies an unknown OSCAR server. +- Removed GLib 2.x dependency, BitlBee will work with GLib 1.x again. +- Improved strip_html(), now less likely to strip non-HTML things. +- An invalid account-command will now display an error message. +- Fixed a bug that caused crashes when /CTCP'ing a groupchat channel. +- Hopefully better Unicode/non-ASCII support for ICQ. +- Fixed MSN connection crash on non-ASCII characters in screenname. +- Added some missing charset conversion calls. (serv_got_crap, + serv_buddy_rename) +- "account off" without extra arguments now logs off all connections. +- Fixed a crash-bug on disconnecting Yahoo! connections before they're fully + connected. +- Fixed a bug in helpfile handling which sometimes caused crashes in daemon + mode. +- block and allow commands work with just a nick as an argument again. +- Working around a crash on some probably invalid Yahoo! packets. +- Fixed a possible double free() on shutdown in irc_free(). +- Talking to ICQ people on AIM and vice versa and talking to people with + @mac.com accounts now possible. +- Low ASCII chars are now stripped from away-messages so the Jabber module + won't barf on BitchX and lame-script away messages anymore. + +Finished 25 Sep 2004 + +Version 0.90a: +- Fixed the Yahoo! authentication code. + +Finished 28 Jun 2004 + +Version 0.90: +- A complete rewrite of the MSN module. This gives BitlBee the following + new features/improvements: + * You can now start groupchats with MSN people without having to send them + a bogus message first. + * People who are in your MSN block/allow list, but not in your contact + list, shouldn't show up in your BitlBee buddy lists anymore. + * Passport authentication shouldn't lock up the whole program for a couple + of seconds anymore. Additionally, it should also work behind proxies now. + * Better recognition of incoming file transfers; they're now recognized + when coming from non-English MS Messenger clients too. + * Fixed a problem with MSN passwords with non-alphanumeric characters. + * Mail notification support (also for Yahoo!)... + * Parsing of maintenance messages (ie "Server is going down in x minutes"). + * Hopefully more stability. +- Changes in the OSCAR module: + * Better reading of ICQ-away-states. + * Lots of cleanups. +- Yahoo! module: + * Fixed authentication on 64-bit machines. (Patch from Matt Rogers) + * Better stripping of markup tags. +- Lots of cleanup in all IM-modules. +- Added support for using libnss instead of libgnutls. +- Reverse hostname lookups work on IPv6 sockets too now. (And don't crash + the program anymore.) +- Fixed a little problem with identifying right after registering a nick. +- Restored complete proxy support and added a proxy setting to the conffile. +- BitlBee can now tell you when people in your buddy list change their + "friendly name". +- Instead of an account number, you can also specify the protocol name or + (part of) the username as an account identification with commands like + "account on", "add", etc. +- BitlBee remembers what connection a question (i.e. authorization request) + belongs to and cleans it up when the connection goes down; this fixes + (one of) the last known crash bugs. +- Plus some other changes in question management. (The query_order setting + is one of them. The default behaviour changed a bit, for more information + please read "help set query_order".) +- Also fixed a memory management bug in the question code which caused some + crashes. +- Optimized some nick handling functions and added a hash of all the users + to speed up user_find() a bit (especially good for people with large + buddy and notify lists). +- Lots of changes for the Win32 port (see http://jelmer.vernstok.nl/). +- Added the drop-command. +- Fixed small problem with versions of sed which don't support the + + "operator" (the BSD version, for example, even though the operator is + documented properly in the re_format manpage...). +- Added the default_target setting. +- Added a CenterICQ2BitlBee conversion script. +- Put back the evaluator for "set charset" (which got lost somewhere between + 0.84 and 0.85), so an incorrect charset will be rejected again. +- ISON now (A) gives one single reply and (B) also replies when none of the + persons asked for are on-line. +- Using GConv instead of iconv now. +- Incoming messages larger than 450 characters are now split into parts + before sending them to the user. +- Fixed a bug in irc_exec() which could crash the program when some commands + were called with too little arguments. +- Fixed a dumb NULL pointer dereference in the JOIN command. +- Added rate limiting to bitlbeed. (Against server hammering) +- Added handling of CTCP PINGs (yet another self-ping used by some IRC + clients...) +- Added bitlbee_tab_completion.pl. +- Removed the vCard handling code from Jabber because it's (A) not used and + (B) had a possible format string vulnerability. +- Got rid of strcpy() in account.c. (Thanks to NETRIC for reporting these two + problems.) +- ISO8859-15 is now the default charset. + +Finished 21 May 2004 + +Version 0.85a: +- Fixed an authentication problem with logging into some MSN accounts. +- Removed a non-critical warning message from the ICQ servers when logging + in with an empty contact list. +- Fixed reading the [defaults] section of bitlbee.conf. +- The last newline in outgoing messages when using the buddy_sendbuffer is + now removed correctly. +- Yahoo! colour/font tag stripping now actually works. +- Fixed compilation on *BSD and some Linux architectures. + +Finished 24 Mar 2004 + +Version 0.85: +- Users can specify alternate configuration files/directories at runtime + now. +- Rename now doesn't choke on name changes with only case changes anymore. +- Imported the daemon patch into the main source tree. The daemon mode is + still experimental, this just eases maintenance. This daemon patch brings + a lot of features, including (as the name says) a real daemon mode and + also buffering of the data sent to the user, and flood protection. +- Strips font and colour codes from Yahoo! messages. +- Support for groupchats on Yahoo! +- Fixed removing Yahoo! buddies from a different group than "Buddies". +- Jabber presence packets with error messages are interpreted correctly now. + (They used to be parsed as a signin.) +- bitlbee_save() checks return values from fprintf() and writes to tempfiles + first to make sure no old files get lost when there's a write error. +- ICQ buddies are added all at once instead of once at a time. This should + solve problems with huge buddy lists. +- Made the client pinging timings configurable. (Without requiring + recompilation) +- MSN and Yahoo flag the connection as "wants_to_die" when they're logged + off because of a concurrent login. This means reconnection will be disabled + on concurrent logins. +- BitlBee can now buffer the messages sent to someone before they're actually + sent, and wait for a specified number of seconds for more lines to be added + to the buffer before the message will really be sent. +- Renamed the reconnect_delay setting to auto_reconnect_delay. +- Unknown settings aren't saved anymore. + +Finished 13 Mar 2004 + +Version 0.84: +- Removed the libsoup dependency. +- Fixed AuthMode=Registered: It will now restore your accounts when + identifying. +- Fixed Yahoo! support. +- Fixed a little memory leak in user.c. +- Fixed a security bug in unused code in proxy.c, only people who use + the HTTP proxy support and an untrusted proxy might need this. We + haven't done an emergency release for this fix because proxy support + is disabled by default. +- Fixed some memory leaks in IM-code. + +Finished 13 Feb 2004 + +Version 0.83: +- Fixed a crash bug on connecting to unsupported accounts. +- Fixed a problem with connecting to MSN accounts with empty buddy + lists. +- Fixed another inifite-loop bug in nick_get() and added a piece + of code which detects the infinite loop and asks the user to send + a bug report. +- Fixed iconv-Solaris linking issues. +- Fixed all the problems with spaces in AIM screennames now, we hope. +- Fixed a buffer overflow in the nick handling code. Buffers are + overflowed with static data (nulls), so we don't think it's exploitable. +- Added server-client pinging, useful for remote servers. +- Added the hostname setting. +- Some bitlbeed changes. +- Added a little part to the on-line quickstart about the settings and + other help topics, this hopefully answers a lot of FAQ's. +- Fixed the signal handler to re-raise the signal after the handler quits. + This makes sure the default handler is called after our handler sends + the user a bye-message, so core dumps are created and the parent will + get more useful information back from wait(). +- Added support for ICQ URL messages. +- Fixed strip_html() behaviour on unknown &entities;. +- Fixed a possible problem with Yahoo! +- Fixed a problem with logging into more than one MSN account at once. + +Finished 31 Dec 2003 + +Version 0.82: +- Fixed a little bug in nick.c which could cause a complete hang for + some tricky buddylists. (Thanks to Geert Hauwaerts for helping with + fixing this bug) +- Fixed MSN support. (Lots of thanks to Wouter Paesen!) +- Removed the old login/logout commands. +- Added the qlist command. +- Fixed a buffer overflow in the nick checking code. (Thanks to Jon + Åslund for pointing us at this problem) +- Adds the add_private and add_channel options for set handle_unknown. +- Some documentation updates. +- Added two small utilities to encode/decode BitlCrypted files. + +Finished 31 Oct 2003 + +Version 0.81a: +- This version just fixes some small things we should've fixed before + releasing 0.81: +- Fixed a small bug in the auto-reconnect cleanup code. +- Fixed the Makefile: Now it doesn't just overwrite your etc files when + installing. +- Fixed the Makefile: $prefix/etc/bitlbee/ is the default etcdir now. +- Disabling MSN by default, now that it doesn't work. It'll be back on + as soon as we get the module working again. + +Finished 16 Oct 2003 + +Version 0.81: +- Added a configuration file. +- Added support for the PASS command to restrict access to the daemon to + only the people who know this password. +- Only allowing registered people to use the daemon is possible too. +- In case you, at some time, need to check the currently running BitlBee + version, just CTCP-VERSION someone in the channel. +- Added the auto_connect setting for people who don't want the program + to connect to IM-networks automatically. +- Extended the blist command. +- Applied the auto-reconnect patch from G-Lite. +- Applied the iconv patch from Yuri Pimenov. +- Imported the MSN-friendlyname patch from Wouter Paesen. +- Away-message aliasing code now just parses the beginning of the string, + not the whole string. This allows you to have a more descriptive away + message like "Busy - Fixing bugs in BitlBee" and all the IM connections + will have a busy-like away-state. +- Added some information about away states to the help system. +- MSN file transfers aren't silently ignored anymore. +- Integrated the Yahoo protocol fix from Cerulean Studios (Trillian). + (Thanks to Tony Perrie!) +- Made all protocol plugins optional. (Patch from Andrej Kacian/Ticho) + +Finished 15 Oct 2003 + +Version 0.80: +- Fixed a very stupid bug in the MSN away-state reading. +- nick_cmp() now actually works, RFC-compliant. +- Fixed and cleaned up the away-state handling, there were some very + weird things in the original Gaim code base which broke this completely + all the time. +- The daemon prevents you from using root/NickServ as your nick now, + previous versions crashed on that. +- At last ... GROUP CHAT SUPPORT! :-D +- People who are *not* away get mode +v in #bitlbee now, so you can see + in /names who's away and who's not. +- Crashing BitlBee by using the NICKSERV command without any arguments + is impossible now. +- Added some notes about Darwin/OSX portability. +- Separated connections from accounts. This means restoring a lost + connection can be done using a simple "account on <number>" command. + See "help account" for more information. + *** For now this won't cause problems when upgrading because the login + command still exists (as an alias for "account add"). This alias will + not stay forever, though. +- irc_process() now makes sure it reads the whole available buffer before + executing the commands. Previous versions were very bad at handling + long floods from non-floodprotected clients. The code is still not + perfect, but good enough for local links. +- Allow/Deny questions from msn.c now also mention your own screenname. + This is useful for people who run two (or even more) MSN accounts in + one BitlBee. +- Fixed a little bug in the helpfile-changed-check code. +- A little trick in "make install" makes sure the help function in running + sessions doesn't break while upgrading. +- Added a nifty (and editable) MOTD. +- Added IRIX to the compatibility list. +- Added support for Cygwin. +- Better HTML-stripping, it also handles &entities; correctly now. +- Fixed some problems to make it compile on Solaris. +- Added support for messages from Miranda/Mac ICQ. (Code port from Gaim 0.59) +- Fixed the crash problem when removing yahoo buddies. +- Added the handle_unknown setting. +- Did some editing on a few docs. +- Added a FAQ. +- Added the daemon-patch by Maurits Dijkstra which adds stand-alone daemon + support to BitlBee. +- Jabber now doesn't barf on high ASCII characters in away messages anymore. + (Thanks to Christian Häggström <chm@c00.info>) + +Finished 24 Jun 2003 + +Version 0.74a: +- The music-festivals-are-bad-for-your-mind release. +- This one actually contains the fix for the bug 0.74 claimed to have. + +Finished 11 Jun 2003 + +Version 0.74: +- Fixed a security leak, where using a / in the nickname causes the saved + settings and account information to be stored in undesirable places. + +Finished 10 Jun 2003 + +Version 0.73: +- Fixed the unable-to-remove-icq-users (actually users from any *local* + contact list) bug. +- Fixed away bug in aim protocol. +- Fixed the 'statistics' under the blist command output. +- Removed the commands from the XML documentation because they're 'on-line' + already. +- Added some signal handling; ignoring SIGPIPE should als get rid of some + crashes (for some weird reason this has to be done). Also, crashes because + of things like segfaults are a bit more verbose now. ;-) +- Changed the select() timeout in main(), this might improve some latencies. + (At leasts it speeds up signing on (especially for ICQ) a lot!) +- Made the own-QUIT messages more compliant, probably. +- Fixed some memory-bugs, thanks to valgrind. +- irc_write() now checks the write() return value, and tries to send the rest + of the string, if it could not write it completely the first time. +- Hostname lookups also work on NetBSD now. + (Thanks to David.Edmondson*sun*com (hi spambot)) +- At last, a new protocol. Welcome to ... YAHOO! +- Documentation and code cleanup. Somehow the helpfile documented register + and identify twice, now that's what I call over-documenting.. :-/ +- Added the rename command to the helpfile, somehow I forgot that one. +- Been a bit pedantic about compiler warnings. They're all dead now. +- Fixed a small Makefile problem which gave an error when a clean tree was + "made distclean" +- Fixed a (possible) memory leak in nogaim.c:proto_away() +- Fixed the way proto_away() calls proto_away_alias_find(), now it gives + the *whole* list of away states +- proto_away() doesn't give a NULL message anymore because AIM didn't like + that +- Got rid of the last goto in my code (without ruining the code) +- Created a more samba-like compiling process (without the complete command + lines, just a simple echo) +- "help set ops" works now too, without quoting the "set ops" +- Trying to log in with a protocol without a prpl (ICQ and TOC, for example) + made previous versions crash + +Finished 13 Apr 2003 + +Version 0.72: +- Updated the documentation. +- Improved the MSN friendlyname code. (Although it doesn't seem to be perfect + yet..) +- info-command added to get more information about ICQ users. +- blist-command added to get a complete buddy list. +- Fixed a bug which broke the AIM code when adding a screenname with a space + in it. +- Added the NS alias for the NICKSERV command (Tony Vroon). +- Fixed the USERHOST command implementation (Tony Vroon). +- /me from IM-networks is now converted to a CTCP ACTION correctly. +- Added an utils/ directory with some misc toys and handy things. +- Added a /notice to the on_typing event. Don't use it though, the /notice + flood will just be a big annoyance. ;-) +- Some people like root and themself to be ops, some don't. Now it's + configurable. (set ops) +- Now the umode stuff actually works. Next step: Use those modes... (How?) + +Finished 19 Dec 2002 + +Version 0.71: +- Fixed the help command output layout (alignment) +- Added a sample xinetd file +- Cleaned up, 0.70 released with a build-stamp and DEADJOE file (oops).. +- Messages can be sent like '<user>, <message>' in the control channel now, + instead of just '<user>: <message>' +- Added a debug setting boolean: Set it to true for some debugging crap + which used to be on by default.. +- Changed the /whois reply: In the server section you now see the + connection this user belongs to. +- Added some root/permission checks. +- configure script works correctly when the terminating / is forgotten for + a directory. +- Fixed format string bug in protocols/oscar/meta.c (Hmm, what's the use of + that file?) +- Added '#include "crypting.h"' to commands.c to get rid of stupid warnings +- Fixed crash-bug (SIGSEGV when adding an @-less contact to MSN/Jabber) +- Added to_char setting +- Fixed bug in set.c: It ignored the new value returned by the evaluator + :-( +- Removed protocol tag from 'hostname' in user hostmask because this info + is in /whois' server section now +- Added the GPL. Somehow 0.7 released without a COPYING file.. :-/ +- Enhanced the root_command() parser, you can 'quote' "arguments" now so + arguments can be strings with spaces +- Debugging versions have True as the default value for set debug +- NICKSERV is now an alternative for PRIVMSG root. This does not affect + functionality of current NICKSERV commands, but does allow people to just + do identify <pass> in channel. +- NICKSERV REGISTER now doesn't try to log you in (to check if the user + exists) but checks for the existence of the user-configuration files. +- NICKSERV SET password now works (as does set password in channel). This + makes changing your password possible. +- NICKSERV password now stored in irc_t. +- ./configure now only bugs you about possible problems with strip if it's + actually going to strip (wooohoooo! _sexy_ :) +- Fixed a load of warnings in oscar.c, irc.c, nick.c and set.c +- Split up root_command() into a version which eats raw strings and one + which eats split strings +- New help system: Help available for most (all?) commands, all read from + an external help-file. +- Changed the maximum message length in irc_usermsg() from IRC_MAX_LINE to + 1024 (for loooong help messages..). +- Only allow user to set supported umodes. +- Fixed a memory leak in crypting.c (Thanks to Erik Hensema.) +- Added a send_handler callback to user_t. Needed for the following entry: +- Added the NickServ user as a root-clone. +- Disabled tcpd by default because it's just a PITA for a lot of systems + and because you can use /usr/sbin/tcpd as well. +- The root user can be renamed now. + +Finished 16 Sep 2002 diff --git a/doc/CREDITS b/doc/CREDITS new file mode 100644 index 00000000..83a19f51 --- /dev/null +++ b/doc/CREDITS @@ -0,0 +1,61 @@ +The authors thank the following people: + +- The Gaim team, for letting us steal their code. +- Sander van Schouwenburg, for his testing. +- Marten Klencke, for his testing. +- Lennart Kats, for putting up with Sjoerd, who bothered him many times to + test things. +- Ralph Slooten, for creating the RPM packages and testing the program. +- Erik Hensema, for creating SuSE RPM packages and some patching. +- Tony Vroon, for being a happy user and patch-submitter. +- Lots of Twente University students (and of course all the other users, + it's just that BitlBee seems to be some sort of hype over there ;-), + for spreading the word of the Bee. +- Han Boetes, for testing on and porting to OpenBSD. +- Paul Foote for some hints on running BitlBee on FreeBSD. +- Floris Kruisselbrink, for submitting the "help set ..." patch. +- Jan-Willem Lenting, for putting up with Wilmer, who wanted to test the + MSN away messages in the middle of the night. +- Jan Sabbe, for the hints about running BitlBee on Mac OS X. +- Kenny Gryp, for thoroughly testing the groupchat code and submitting + bug reports. +- Bryan Williams, for the help in getting BitlBee to run on Cygwin. +- Peter van Dijk for discovering a security leak in BitlBee. +- Christian Häggeström, for the fix for the Jabber barf on high ASCII + characters in away messages. +- James Ray, for some testing, development and patching. +- Yuri Pimenov, for writing the charset/iconv code, requested by a + lot of people. +- Wouter Paesen, for the MSN friendlyname code and the MSNP8 fix. +- Tony Perrie, for the RPM's and the Yahoo! patch. +- Andrej Kacian/Ticho for some patches. +- Jochem Kossen, for giving an account on his OpenBSD box to do some + portability testing. +- Geert Hauwaerts, for maintaining quite a big public BitlBee server + (msn.irssi.org, down for now) and reporting some very nice bugs. +- Robert C Lorentz and other AIM users, for all the reports on bugs (and + providing test accounts) about the stupid AIM spaces-in-screenname + handling. +- Scott Cruzen, for patching up strip_html() and more. +- Samuel Tardieu, for random patches. +- Tibor Csoegoer, for adding support for receiving URL messages to the + ICQ module. +- Jonathan/rise, for reporting and fixing a problem with the Yahoo! servers + and supporting BitlBee in other ways. +- Philip S Tellis, for libyahoo2. +- Simon Schubert, for providing code to read the names of ICQ contacts. +- NETRIC (www.netric.org) for auditting the BitlBee code security (and + finding some small problems). +- Elizabeth Krumbach, for her help on the docs. +- Frank Thieme, for the info-command enhancements and other patches. +- Marcus Dennis, for some bitlbeed enhancements. +- 1nfamus, for security auditing BitlBee code. +- Tijmen Ruizendaal, for some useful BitlBee-related irssi scripts. +- Ed Schouten, for reporting bugs. + +- And all other users who help us by sending useful bug reports, positive + feedback, nice patches and cool addons. Mentioning you all would make + this list fill up the whole source tree, so please don't be offended + by not seeing your name here. + +- All the people who run public BitlBee servers. diff --git a/doc/FAQ b/doc/FAQ new file mode 100644 index 00000000..8b6108f9 --- /dev/null +++ b/doc/FAQ @@ -0,0 +1,103 @@ +Frequently Asked Questions about BitlBee +======================================== + +Well, maybe not exactly "Frequently", but definitely "Asked" ... mostly by +the developers :-) + +Q: WTH were you guys on when you thought of that _weird_ name? +A: Though we live in The Netherlands and one of us even lives in Amsterdam, + we're not on drugs ... most of the time. + +Q: Okay, so the cops are so evil there, you can't even admit the truth, but + WTH does BitlBee mean then? +A: There are a few explanations. But the most symbolical goes like: the two + colors of the bee symbolize the two worlds betwee which the Bee flies. On + the one hand there's the IM-networks, on the other is IRC. + + Truth be told, it's absolute nonsense. The biggest nutcase in the + development team just played around with words for half an hour or so. + BitlBee was the result. We liked it, we kept it. We lovingly shorten it + to "the Bee" or even "het Bijtje" (Dutch for "the little Bee") sometimes. + +Q: What is 'root' doing in my control channel? I didn't start the Bee as + root. +A: 'root' is just the name for the most powerful user in BitlBee. Just like + in the system, it is root who is the ... eh ... root of the + functionality. Luckily, in BitlBee, root follows your orders (mostly), so + no BOFHs there. + + We get some complaints from time to time that 'root' is a confusing name. + Because of that name, some package maintainers have renamed root to, for + example, BitlBee. We recognize that some people see that need. If the + package maintainer hasn't renamed root, you can do this yourself with the + 'rename' command. + + The name root is not likely to change in the 'official' releases, though. + We find the metaphor of root correct and feel that there is no important + (security threatening) reason to change this non-creative piece of + artistic creativity. + +Q: Why is there no mailing list/CVS/<insert your favourite development tool + here>? +A: Short answer: we don't need it. + + Longer answer: and we're not completely convinced of their merits. + + Long answer: we currently use some shell scripts which make sure all + developers' copies are in sync with Wilmer's master copy. These shell + scripts also produce development "releases" and packages, as well as + stick them on a http-server. Patches are sent to Wilmer who decides + whether or not a patch should be applied and if it may need some + additional changes. This has the consistency advantage of a one-person + project while having the capacity of more people available. The system + works and we are kind of attached to it. + +Q: When is $random_feature going to be implemented? +A: Please do consult doc/TODO (preferably in a development snapshot, which + is more up-to-date than a TODO in a release version) before asking. + Please also check the documentation. You'd not be the first one to request + a feature which already exists! + + If your fabulous feature seems not to be requested before, just join + #bitlbee on irc.oftc.net and tell us the news. + + If your feature request is already in the TODO list, of course you can + still request it again/make us know that you'd like to see the feature as + well. But when the feature is in the "post-1.0" list, it's probably not + going to help. Most of the features in this list are low-priority because + we (the developers) don't need (or even want) them. (File transfers are a + good example here.) + Hence, they'll only be implemented when we really got too much spare + time. Obviously, if you're willing to help (i.e. submit a patch), you're + always welcome. + +Q: The messages I send and/or receive look weird. I see weird characters and + annoying HTML codes. Or, BitlBee does evil things when I send messages with + non-ASCII characters! +A: You probably have to change some settings. To get rid of HTML in messages, + see "help set html". If you seem to have problems with your charset, see + "help set charset". + +Q: Is BitlBee forked from Gaim? +A: BitlBee 0.7 was, sort-of. It contained a lot of code from Gaim 0.58 + (mainly the IM-code), although heavily modified, to make it work better + with BitlBee. We were planning to keep BitlBee up-to-date with later Gaim + versions, but this turned out to be very time-consuming because the API + changed a lot, and we don't have the time to keep up with those changes + all the time. + + These days, we replaced the Yahoo! code with libyahoo2 (which is a + separate Yahoo! module. It's derived from Gaim, but separately + maintained) and wrote our own MSN module. More modules are probably going + to be changed, so in the near future, the API might be the only thing + left from Gaim. + +Q: What's that Gaim doing in BitlBee error messages and my Jabber resource? +A: Ah, well, as you probably know we use some of Gaim's IM-modules, and we + don't think it's worth our time to do a search-and-replace over the whole + source to get rid of every reference to Gaim. In fact, we don't want to, + since we don't want to pretend we wrote all that code. + + About Jabber: If you want a different resource string, you can set it + when logging in by appending it to your Jabber ID, like: + lintux@jabber.com/BitlBee diff --git a/doc/INSTALL b/doc/INSTALL new file mode 100644 index 00000000..2ce92e20 --- /dev/null +++ b/doc/INSTALL @@ -0,0 +1 @@ +See the README file for installation instructions. diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 00000000..f6a80b21 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,14 @@ +-include ../Makefile.settings + +install: + mkdir -p $(DESTDIR)$(MANDIR)/man8/ $(DESTDIR)$(MANDIR)/man5/ + install -m 0644 bitlbee.8 $(DESTDIR)$(MANDIR)/man8/ + install -m 0644 bitlbee.conf.5 $(DESTDIR)$(MANDIR)/man5/ + make -C user-guide $@ + +uninstall: + rm -f $(DESTDIR)$(MANDIR)/man8/bitlbee.8* + rm -f $(DESTDIR)$(MANDIR)/man5/bitlbee.conf.5* + make -C user-guide $@ + +.PHONY: install uninstall diff --git a/doc/README b/doc/README new file mode 100644 index 00000000..7a1309fb --- /dev/null +++ b/doc/README @@ -0,0 +1,172 @@ +INSTALLATION +============ + +If you installed BitlBee from a .deb or .rpm you probably don't have to do +anything anymore for installation. Just skip this section. + +If you want to compile BitlBee yourself, that's fine. Just run ./configure +to set up the build system. If configure succeeds, run make to build BitlBee. +make install will move all the files to the right places. + +After installation you have to set up inetd (you got that one running, +right? If not, just take a look at utils/bitlbeed.c) to start BitlBee. You +need to add BitlBee to inetd.conf, like this: + +6667 stream tcp nowait nobody /usr/sbin/tcpd /usr/local/sbin/bitlbee + +Creating a special BitlBee user and running BitlBee with that UID (instead +of just 'nobody') might be a good idea. + +Also, don't forget to create the configuration directory (/var/lib/bitlbee/ +by default) and chown it to the UID BitlBee is running as. Make sure this +directory is read-/writable by this user only. + +(For xinetd users a xinetd configuration file is included: doc/bitlbee.xinetd) + + +DEPENDENCIES +============ + +BitlBee's only real dependency is GLib. This is available on virtually every +platform. Any recent version of GLib (including 1.x versions) will work. + +These days, MSN Messenger clients have to connect to the MS Passport servers +through HTTPS. BitlBee can use serveral SSL libraries for this: GnuTLS, NSS +(which comes with Mozilla) and OpenSSL. OpenSSL is not GPL-compatible in some +situations, so using GnuTLS or NSS is preferred. However, especially on *BSD, +OpenSSL can be considered part of the operating system, which eliminates the +GPL incompatibility. + +The incompatibility is also the reason why the SSL library detection code +doesn't attempt to use OpenSSL. If you want to use OpenSSL, you have to +force configure to use it using the --ssl=openssl parameter. For more +information about this problem, see the URL's configure will write to stdout +when you attempt to use OpenSSL. + + +PORTABILITY ISSUES +================== + +FreeBSD NOTE: It looks like FreeBSD does allow port numbers instead of service +names in inetd.conf, as long as the service for this port exists in +/etc/services. Linux isn't this strict. If you got problems in FreeBSD, just +add a line for your chosen port number to /etc/services. + +Darwin/Mac OS X is even more strict; you should add a bitlbee service to +/etc/services and use that name in inetd.conf. Not really a problem, since +that's the cleanest way of doing this on any operating system anyway. + +Cygwin NOTE: You'll need a glib installation to run BitlBee. However, Cygwin +doesn't provide a glib package. You can download a binary tar.gz from: +<http://my.dreamwiz.com/jbdoll/>. When you installed it, BitlBee should work +fine. You'll probably like bitlbeed or xinetd to get it running on the +network. + +On some non-Linux systems the program still suffers from some random bugs. +Please do report them, we might be able to fix them if they're not too +mysterious. + + +RUNNING ON SERVERS WITH MANY USERS +================================== + +BitlBee is not yet bug-free. Sometimes a bug causes the program to get into +an infinite loop. Something you really don't want on a public server, +especially when that machine is also used for other (mission-critical) things. +For now we can't do much about it. We haven't seen that happen for a long +time already on our own machines, but some people still manage to get +themselves in nasty situations we haven't seen before. + +For now the best we can offer against this problem is bitlbeed, which allows +you to setrlimit() the child processes to use no more than a specified +number of CPU seconds. Not the best solution (not really a solution anyway), +but certainly trashing one busy daemon process is better than trashing your +whole machine. + +We don't believe adding a limit for bitlbee to /etc/security/limits.conf will +work, because that file is only read by PAM (ie just for real login users, +not daemons). + +See utils/bitlbeed.c for more information about the program. + +Just a little note: We run our public server im.bitlbee.org for a couple of +months now, and so far we haven't experienced this problem yet. The only +BitlBee processes killed because of CPU-time overuse were running for a long +time already, they were usually killed during the MSN login process (which +is quite CPU-time consuming). + + +USAGE +===== + +Not much to say here, it's all documented elsewhere already. Just connect to +the new BitlBee IRC server and the bot (root) will tell you what to do. + + +BACKGROUNDS +=========== + +We are both console lovers. But it is annoying to have a few tty's open with +chat things in them. IRC, ICQ, MSN, AIM, Jabber... For X there is Gaim, which +supports many chatprotocols. Why wasn't there such a thing for the console? + +The idea to port Gaim was easily thought of, of course. But we liked our IRC +clients. And we used it the most, so we used it best. Importing it into the +IRC client was a nice idea. But what if someone liked a different client. +Then (s)he had to duplicate our work. + +That's a shame, we thought. Doing work twice is pointless. So when Wilmer +got the ingenious thought in his mind while farming, to create an IRC to +other chatnetworks gateway, we were both so excited, that we started working +on it almost immediately. And the result is BitlBee. + + +WEBSITE +======= + +You can find new releases of BitlBee at: +http://www.bitlbee.org/ + + +A NOTE ON ENCRYPTION +==================== + +BitlBee stores the accounts and settings (not your contact list though) in +some sort of encrypted/obfuscated format. + +*** THIS IS NOT A SAFE FORMAT! *** + +You should still make sure the rights to the configuration directory and +files are set so that only root and the BitlBee user can read/write them. + +This format is not to prevent malicicous users from running with your +passwords, but to prevent accidental glimpses of the administrators to cause +any harm. You have no choice but to trust root though. + + +LEGAL +===== + +BitlBee is distributed under the GPL (GNU General Public License). See the +file COPYING for this license. + +Unfortunately some parts of the Gaim Jabber plugin (most notably the XML +code) were licensed under the MPL (Mozilla Public License) version 1.1. We +could not relicense this code under the GPL. As such it is still licensed +under the MPL. The parts of the code to which this applies are marked as +such. + +The MPL is provided in the file MPL-1.1.txt. This license is not GPL +compatible. It is however a free software license. + +Another part (the md5 algorithm) is licensed under the Aladdin license. +This license can be found in the files, to which this applies. + +The Yahoo! library used by BitlBee is libyahoo2 <http://libyahoo2.sf.net/>, +also licensed under the GPL. + + + BitlBee - An IRC to other chat networks gateway + <http://www.bitlbee.org/> + Copyright (C) 2002-2004 Wilmer van der Gaast <wilmer@gaast.net> + and others diff --git a/doc/TODO b/doc/TODO new file mode 100644 index 00000000..3bd241ef --- /dev/null +++ b/doc/TODO @@ -0,0 +1,40 @@ +TODO for BitlBee: + +We're trying to keep a better TODO list now. The priorities here are somewhat +random, maybe. Or at least they change from time to time. The "After 1.0" +changes are very low-priority, the "Before 1.0" are "highest" priority, the +others are changes we'll do when we feel like doing them. They're usually not +as critical as the "Before 1.0" changes, but still a bit more important than +"After 1.0". + +KNOWN BUGS TO FIX BEFORE 1.0: +- 100% cpu usage bugs. + -> They're still there... :-( +- Check if the IRC send flood protection is reliable now. + -> Probably not, at least it still causes troubles on logging in for some + people. Maybe the thresholds aren't okay yet. Logins are just floody, + nothing we can do about that. + +Some time: (mainly features) +- Rewrite Jabber module - the current one sucks. +- Test Yahoo! groupchats a bit better, because they still seem to be a bit + flakey. + -> There are bug reports from time to time, but we can't do much about + them, possibly it's more a libyahoo2 problem. +- Groupchats + -> Make them work on other nets than MSN/Yahoo as well. +- Make usernames case-insensitive. (On case-insensitive filesystems this + change isn't necessary. This one is going to suck with backward-compati- + bilty...) + -> We'll probably combine this with the introduction of a better file + format for userdata. +- Remind the user of unanswered questions after some time. +- Maybe a way to send global messages. (for server shutdowns, for example) +- Away-auto-replies. +- Allow nick changes. + +After 1.0: (mainly toys) +- File transfers -> DCC +- SSL support? Persistent connections? Things you can do with a bouncer/proxy. +- Support for buddy groups. +- What else? diff --git a/doc/bitlbee.8 b/doc/bitlbee.8 new file mode 100644 index 00000000..ccce2135 --- /dev/null +++ b/doc/bitlbee.8 @@ -0,0 +1,123 @@ +.\" BitlBee is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with this program; see the file COPYING. If not, write to +.\" the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. +.\" +.TH bitlbee 8 "07 March 2004" +.SH NAME +BitlBee \- IRC gateway to IM chat networks +.SH SYNOPSIS +.PP +.B bitlbee +[-I] +[-c \fIconfiguration file\fP] +[-d \fIconfiguration directory\fP] +.PP +.B bitlbee +-D +[-i \fIaddress\fP] +[-p \fIport number\fP] +[-n] +[-v] +[-c \fIconfiguration file\fP] +[-d \fIconfiguration directory\fP] +.PP +.B bitlbee +-h +.RI +.SH DESCRIPTION +BitlBee is an IRC daemon that can talk to instant messaging +networks and acts as a gateway. Users can connect to the server +with any normal IRC client and see their 'buddy list' in +#bitlbee. BitlBee's protocol support is based on the gaim +protocol plugins. BitlBee currently supports Oscar (aim and icq), +MSN, Jabber and Yahoo. + +\fBbitlbee\fP should be called by +.BR inetd (8). +(Or \fBbitlbeed\fP, +if you can't run and/or configure \fBinetd\fP.) There is an experimental +daemon mode too, in which BitlBee will serve all clients in one process +(and does not require inetd), but this mode is still experimental. +There are still some bugs left in BitlBee, and if they cause a crash, +that would terminate the BitlBee connection for all clients. +.PP +.SH OPTIONS +.PP +.IP "-I" +Run in +.BR inetd (8) +mode. This is the default setting, you usually don't have to specify this +option. +.IP "-D" +Run in daemon mode. In this mode, BitlBee forks to the background and +waits for new connections. All clients will be served from one process. +This is still experimental. See the note above for more information. +.IP "-i \fIaddress\fP" +Only useful when running in daemon mode, to specify the network interface +(identified by IP address) to which the daemon should attach. Use this if +you don't want BitlBee to listen on every interface (which is the default +behaviour). +.IP "-p \fIport number\fP" +Only useful when running in daemon mode, to specify the port number on +which BitlBee should listen for connections. 6667 is the default value. +.IP "-n" +Only useful when running in daemon mode. This option prevents BitlBee from +forking into the background. +.IP "-v" +Be more verbose. This only works together with the \fB-n\fP flag. +.IP "-c \fIpath to other configuration file\fP" +Use a different configuration file. +.IP "-d \fIpath to user settings directory\fP" +BitlBee normally saves every user's settings in \fB/var/lib/bitlbee/\fP. If +you want the settings to be stored somewhere else (for example, if you don't +have write permissions in the default location), use this option. +.IP "-h" +Show help information. +.SH COMMANDS +To get a complete list of commands, please use the \fBhelp commands\fP +command in the #bitlbee channel. +.SH "SEE ALSO" +.BR ircd (8), +.BR inetd (8), +.BR inetd.conf (5), +.BR gaim (1). + +.BR http://www.bitlbee.org/ + +For more information on using BitlBee, once connected, you should use +the on-line help system. +.SH BUGS +Of course there are bugs. If you find some, please report them by e-mail +to \fBwilmer@gaast.net\fP, or join \fB#bitlbee\fP on the OFTC network. +(\fBirc.bitlbee.org\fP) +.SH LICENSE +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. +.PP +This program is distributed in the hope that it will be useful, but +\fBWITHOUT ANY WARRANTY\fR; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. +.PP +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 59 Temple PLace, Suite 330, Boston, MA 02111-1307 USA +.SH AUTHORS +.PP + Wilmer van der Gaast <lintux@lintux.cx> +.BR + Jelmer Vernooij <jelmer@vernstok.nl> +.BR + Maurits Dijkstra <mauritsd@xs4all.nl> diff --git a/doc/bitlbee.conf.5 b/doc/bitlbee.conf.5 new file mode 100644 index 00000000..04b11b9a --- /dev/null +++ b/doc/bitlbee.conf.5 @@ -0,0 +1,19 @@ +.\" Manual page for bitlbee.conf, derived from the modules.conf manpage. +.\" Writing a complete manpage from scratch is just too much work... +.\" +.\" This program is distributed according to the Gnu General Public License. +.\" See the file COPYING in the base distribution directory +.\" +.TH BITLBEE.CONF 5 "07 March 2004" +.UC 4 +.SH NAME +bitlbee.conf \- configuration file for +.BR bitlbee (8) +.SH DESCRIPTION +This file contains system-wide settings for the +.BR bitlbee (8) +program. For more information about the file syntax, please read the +example configuration file which comes with the program. The default +file contains lots of comments which explain all the available options. +.SH SEE ALSO +.BR bitlbee (8) diff --git a/doc/bitlbee.xinetd b/doc/bitlbee.xinetd new file mode 100644 index 00000000..5b2dec3f --- /dev/null +++ b/doc/bitlbee.xinetd @@ -0,0 +1,12 @@ +## xinetd file for BitlBee. Please check this file before using it, the +## user, port and/or binary location might be wrong. + +service 6667 +{ + socket_type = stream + protocol = tcp + wait = no + user = nobody + server = /usr/local/sbin/bitlbee + port = 6667 +} diff --git a/doc/user-guide/Installation.xml b/doc/user-guide/Installation.xml new file mode 100644 index 00000000..6980ba3c --- /dev/null +++ b/doc/user-guide/Installation.xml @@ -0,0 +1,114 @@ +<chapter id="Installation"> + +<title>Installation</title> + +<sect1> +<title>Downloading the package</title> + +<para> +The latest BitlBee release is always available from <ulink +url="http://www.bitlbee.org/">http://www.bitlbee.org/</ulink>. +Download the package with your favorite program and unpack it: <command>tar +xvfz bitlbee-<version>.tar.gz</command> where <version> is to be +replaced by the version number of the BitlBee you downloaded (e.g. 0.91). +</para> + +</sect1> + +<sect1> +<title>Compiling</title> +<para> +BitlBee's build system has to be configured before compiling. The +<filename>configure</filename> script will do this for you. Just run +it, it'll set up with nice and hopefully well-working defaults. If you +want to change some settings, just try +<command>./configure --help</command> and see what you can do. +</para> + +<para>Some variables that might be of interest to the normal user:</para> + +<itemizedlist> +<listitem><para>prefix, bindir, etcdir, mandir, datadir - The place where +all the BitlBee program files will be put. There's usually no reason to +specify them all separately, just specifying prefix (or keeping the default +<filename>/usr/local/</filename>) should be okay.</para></listitem> +<listitem><para>config - The place where BitlBee will save all the per-user +settings and buddy information. <filename>/var/lib/bitlbee/</filename> +is the default value.</para></listitem> +<listitem><para>msn, jabber, oscar, yahoo - By default, support for all +these IM-protocols (OSCAR is the protocol used by both ICQ and AIM) will +be compiled in. To make the binary a bit smaller, you can use these options +to leave out support for protocols you're not planning to use.</para></listitem> +<listitem><para>debug - Generate an unoptimized binary with debugging symbols, +mainly useful if you want to do some debugging or help us to track down a +problem.</para></listitem> +<listitem><para>strip - By default, unnecessary parts of the generated binary +will be stripped out to make it as small as possible. If you don't want this +(because it might cause problems on some platforms), set this to 0. +</para></listitem> +<listitem><para>flood - To secure your BitlBee server against flooding attacks, +you can use this option. It's not compiled in by default because it needs +more testing first.</para></listitem> +<listitem><para>ssl - The MSN and Jabber modules require an SSL library for +some of their tasks. BitlBee can use three different SSL libraries: GnuTLS, +mozilla-nss and OpenSSL. (OpenSSL is, however, a bit troublesome because of +licensing issues, so don't forget to read the information configure will +give you when you try to use OpenSSL!) By default, configure will try to +detect GnuTLS or mozilla-nss. If none of them can be found, it'll give up. +If you want BitlBee to use OpenSSL, you have to explicitly specify that. +</para></listitem> +</itemizedlist> + +<para> +After running <filename>configure</filename>, you should run +<command>make</command>. After that, run <command>make install</command> as +root. +</para> + +</sect1> + +<sect1> +<title>Configuration</title> + +<para> +By default, BitlBee runs as the user nobody. You might want +to run it as a seperate user (some computers run named or apache as nobody). +</para> + +<para> +Since BitlBee uses inetd, you should add the following line to <filename>/etc/inetd.conf</filename>: +</para> + +<para> +<programlisting> +6667 stream tcp nowait nobody /usr/local/sbin/bitlbee bitlbee +</programlisting> +</para> + +<para> +Inetd has to be restarted after changing the configuration. Either +<command>killall -HUP inetd</command> or +<command>/etc/init.d/inetd restart</command> should do the job on most systems. +</para> + +<para> +You might be one of the.. ehr, lucky people running an xinetd-powered distro. +<command>xinetd</command> is quite different and they seem to be proud of that.. ;-) +Anyway, if you want BitlBee to work with <command>xinetd</command>, just copy the +bitlbee.xinetd file to your /etc/xinetd.d/ directory (and probably edit it to suit +your needs). +</para> + +<para> +You should create a directory where BitlBee can store it's data files. This +should be the directory named after the value 'CONFIG' in Makefile.settings. +The default is <filename>/var/lib/bitlbee</filename>, which can be created +with the command <command>mkdir -p /var/lib/bitlbee</command>. This +directory has to be owned by the user that runs bitlbee. To make +'nobody' owner of this directory, run <command>chown nobody /var/lib/bitlbee</command>. +Because things like passwords are saved in this directory, it's probably +a good idea to make this directory owner-read-/writable only. +</para> +</sect1> + +</chapter> diff --git a/doc/user-guide/Makefile b/doc/user-guide/Makefile new file mode 100644 index 00000000..98c4e99f --- /dev/null +++ b/doc/user-guide/Makefile @@ -0,0 +1,46 @@ +-include ../../Makefile.settings +EXTRAPARANEWLINE = 1 +# EXTRAPARANEWLINE = 0 + +all: user-guide.txt user-guide.html help.txt # user-guide.pdf user-guide.ps user-guide.rtf + +%.tex: %.db.xml + xsltproc --stringparam l10n.gentext.default.language "en" --stringparam latex.documentclass.common "" --stringparam latex.babel.language "" --output $@ http://db2latex.sourceforge.net/xsl/docbook.xsl $< + +%.txt: %.db.xml + xmlto --skip-validation txt $< + mv $*.db.txt $@ + +%.html: %.db.xml + xsltproc --output $@ http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl $< + +%.pdf: %.db.xml + xmlto --skip-validation pdf $< + mv $*.db.pdf $@ + +%.ps: %.db.xml + xmlto --skip-validation ps $< + mv $*.db.ps $@ + +help.xml: commands.xml + +%.db.xml: %.xml docbook.xsl + xsltproc --xinclude --output $@ docbook.xsl $< + +help.txt: help.xml help.xsl + xsltproc --stringparam extraparanewline "$(EXTRAPARANEWLINE)" --xinclude help.xsl $< | perl -0077 -pe 's/\n\n%/\n%/s; s/_b_/\002/g;' > $@ + +clean: + rm -f *.html *.pdf *.ps *.rtf *.txt *.db.xml + +install: + mkdir -p $(DESTDIR)$(DATADIR) + chmod 0755 $(DESTDIR)$(DATADIR) + rm -f $(DESTDIR)$(DATADIR)/help.txt # Prevent help function from breaking in running sessions + install -m 0644 help.txt $(DESTDIR)$(DATADIR)/help.txt + +uninstall: + rm -f $(DESTDIR)$(DATADIR)/help.txt + -rmdir $(DESTDIR)$(DATADIR) + +.PHONY: clean install uninstall diff --git a/doc/user-guide/Support.xml b/doc/user-guide/Support.xml new file mode 100644 index 00000000..401a4295 --- /dev/null +++ b/doc/user-guide/Support.xml @@ -0,0 +1,48 @@ +<chapter id="Support"> + +<title>Support</title> + +<sect1> +<title>BitlBee is beta software</title> + +<para> +Although BitlBee has quite some functionality it is still beta. That means it +can crash at any time, corrupt your data or whatever. Don't use it in +any production environment and don't rely on it. +</para> + +</sect1> + +<sect1> +<title>Support channels</title> + +<sect2> +<title>The World Wide Web</title> + +<para> +<ulink url="http://www.bitlbee.org/">http://www.bitlbee.org/</ulink> +is the homepage of bitlbee and contains the most recent news on bitlbee and +the latest releases. +</para> + +</sect2> + +<sect2> +<title>IRC</title> +<para> +BitlBee is discussed on #bitlbee on the OFTC IRC network (server: irc.oftc.net). +</para> + +</sect2> + +<sect2> +<title>Mailinglists</title> +<para> +BitlBee doesn't have any mailinglists. +</para> + +</sect2> + +</sect1> + +</chapter> diff --git a/doc/user-guide/Usage.xml b/doc/user-guide/Usage.xml new file mode 100644 index 00000000..5d87e32b --- /dev/null +++ b/doc/user-guide/Usage.xml @@ -0,0 +1,47 @@ +<chapter id="Usage"> + +<title>Usage</title> + +<sect1> +<title>Connecting to the server</title> +<para> +Since BitlBee acts just like any other irc daemon, you can connect to +it with your favorite irc client. Launch it and connect to localhost port 6667 +(or whatever host/port you are running bitlbee on). +</para> + +</sect1> + +<sect1> +<title>The #bitlbee control channel</title> + +<para> +Once you are connected to the BitlBee server, you are automatically joined +to #bitlbee on that server. This channel acts like the 'buddy list' you have +on the various other chat networks. +</para> + +<para> +The user 'root' always hangs around in #bitlbee and acts as your interface +to bitlbee. All commands you give on #bitlbee are 'answered' by root. +</para> + +</sect1> + +<sect1> +<title>Talking to people</title> + +<para> +You can talk to by starting a query with them. In most irc clients, +this can be done with either <command>/msg <nick> <text></command> +or <command>/query <nick></command>. +</para> + +<para> +To keep the number of open query windows limited, you can also talk to people +in the control channel, like <command><nick>: <text></command>. +</para> + +</sect1> + +</chapter> diff --git a/doc/user-guide/commands.xml b/doc/user-guide/commands.xml new file mode 100644 index 00000000..1fc30e6d --- /dev/null +++ b/doc/user-guide/commands.xml @@ -0,0 +1,690 @@ +<chapter id="commands"> + <title>Bitlbee commands</title> + + <command-list/> + + <bitlbee-command name="account"> + <short-description>IM-account list maintenance</short-description> + <syntax>account <action> [<arguments>]</syntax> + + <description> + + <para> + Available actions: add, del, list, on, off. See <emphasis>help account <action></emphasis> for more information. + </para> + + </description> + + <bitlbee-command name="add"> + <syntax>account add <protocol> <username> <password> [<server>]</syntax> + + <description> + <para> + Adds an account on the given server with the specified protocol, username and password to the account list. Supported protocols right now are: Jabber, MSN, OSCAR (AIM/ICQ) and Yahoo. For more information about adding an account, see <emphasis>help account add <protocol></emphasis>. + </para> + </description> + + <bitlbee-command name="jabber"> + <syntax>account add jabber <handle> <password> [<servertag>]</syntax> + + <description> + <para> + Note that the servertag argument is optional. You only have to use it if the part after the @ in your handle isn't the hostname of your Jabber server, or if you want to use SSL/connect to a non-standard port number. The format is simple: [<servername>[:<portnumber>][:ssl]]. For example, this is how you can connect to Google Talk: + </para> + </description> + + <ircexample> + <ircline nick="wilmer">account add jabber example@gmail.com hobbelmeeuw talk.google.com:5223:ssl</ircline> + <ircline nick="root">Account successfully added</ircline> + </ircexample> + + <description> + <para> + Note that Google talk is SSL-only, but officially reachable over both port 5222 and 5223. However, for some people only port 5222 works, for some people only 5223. This is something you'll have to try out. + </para> + </description> + </bitlbee-command> + + <bitlbee-command name="msn"> + <syntax>account add msn <handle> <password></syntax> + + <description> + <para> + For MSN connections there are no special arguments. + </para> + </description> + </bitlbee-command> + + <bitlbee-command name="oscar"> + <syntax>account add oscar <handle> <password> [<servername>]</syntax> + + <description> + <para> + Specifying a server is required for OSCAR, since OSCAR can be used for both ICQ- and AIM-connections. Although these days it's supposed to be possible to connect to ICQ via AIM-servers and vice versa, we like to stick with this separation for now. For ICQ connections, the servername is <emphasis>login.icq.com</emphasis>, for AIM connections it's <emphasis>login.oscar.aol.com</emphasis>. + </para> + </description> + + <ircexample> + <ircline nick="wilmer">account add oscar 72696705 hobbelmeeuw login.icq.com</ircline> + <ircline nick="root">Account successfully added</ircline> + </ircexample> + </bitlbee-command> + + <bitlbee-command name="yahoo"> + <syntax>account add yahoo <handle> <password></syntax> + + <description> + <para> + For Yahoo! connections there are no special arguments. + </para> + </description> + </bitlbee-command> + + </bitlbee-command> + + <bitlbee-command name="del"> + <syntax>account del <account id></syntax> + + <description> + <para> + This commands deletes an account from your account list. You should signoff the account before deleting it. + </para> + + + <para> + The account ID can be a number (see <emphasis>account list</emphasis>), the protocol name or (part of) the screenname, as long as it matches only one connection. + </para> + </description> + </bitlbee-command> + + <bitlbee-command name="on"> + <syntax>account on [<account id>]</syntax> + + <description> + <para> + This command will try to log into the specified account. If no account is specified, BitlBee will log into all the accounts. (Including accounts awaiting a reconnection) + </para> + + <para> + The account ID can be a number (see <emphasis>account list</emphasis>), the protocol name or (part of) the screenname, as long as it matches only one connection. + </para> + </description> + + </bitlbee-command> + + <bitlbee-command name="off"> + <syntax>account off [<account id>]</syntax> + + <description> + <para> + This command disconnects the connection for the specified account. If no account is specified, BitlBee will deactivate all active accounts. (Including accounts awaiting a reconnection) + </para> + + <para> + The account ID can be a number (see <emphasis>account list</emphasis>), the protocol name or (part of) the screenname, as long as it matches only one connection. + </para> + </description> + </bitlbee-command> + + <bitlbee-command name="list"> + <syntax>account list</syntax> + + <description> + <para> + This command gives you a list of all the accounts known by BitlBee, including the numbers you'll need for most account commands. + </para> + </description> + </bitlbee-command> + </bitlbee-command> + + <bitlbee-command name="add"> + <short-description>Add a buddy to your contact list</short-description> + <syntax>add <connection> <handle> [<nick>]</syntax> + + <description> + <para> + Adds the given buddy at the specified connection to your buddy list. The account ID can be a number (see <emphasis>account list</emphasis>), the protocol name or (part of) the screenname, as long as it matches only one connection. + </para> + + <para> + If you want, you can also tell BitlBee what nick to give the new contact. Of course you can also use the <emphasis>rename</emphasis> command for that, but sometimes this might be more convenient. + </para> + </description> + + <ircexample> + <ircline nick="ctrlsoft">add 3 gryp@jabber.org grijp</ircline> + <ircaction nick="grijp" hostmask="gryp@jabber.org">has joined <emphasis>#bitlbee</emphasis></ircaction> + </ircexample> + </bitlbee-command> + + <bitlbee-command name="info"> + <short-description>Request user information</short-description> + <syntax>info <connection> <handle></syntax> + <syntax>info <nick></syntax> + + <description> + <para> + Requests IM-network-specific information about the specified user. The amount of information you'll get differs per protocol. For some protocols (ATM Yahoo! and MSN) it'll give you an URL which you can visit with a normal web browser to get the information. + </para> + </description> + + <ircexample> + <ircline nick="ctrlsoft">info 0 72696705</ircline> + <ircline nick="root">User info - UIN: 72696705 Nick: Lintux First/Last name: Wilmer van der Gaast E-mail: lintux@lintux.cx</ircline> + </ircexample> + + </bitlbee-command> + + <bitlbee-command name="remove"> + <short-description>Remove a buddy from your contact list</short-description> + <syntax>remove <nick></syntax> + + <description> + <para> + Removes the specified nick from your buddy list. + </para> + </description> + + <ircexample> + <ircline nick="ctrlsoft">remove gryp</ircline> + <ircaction nick="gryp" hostmask="gryp@jabber.jabber.org">has quit <emphasis>[Leaving...]</emphasis></ircaction> + </ircexample> + + </bitlbee-command> + + <bitlbee-command name="block"> + <short-description>Block someone</short-description> + <syntax>block <nick></syntax> + <syntax>block <connection> <handle></syntax> + + <description> + <para> + Puts the specified user on your ignore list. Either specify the user's nick when you have him/her in your contact list or a connection number and a user handle. + </para> + </description> + </bitlbee-command> + + <bitlbee-command name="allow"> + <short-description>Unblock someone</short-description> + <syntax>allow <nick></syntax> + <syntax>allow <connection> <handle></syntax> + + <description> + <para> + Reverse of block. Unignores the specified user or user handle on specified connection. + </para> + </description> + </bitlbee-command> + + <bitlbee-command name="set"> + <short-description>Miscellaneous settings</short-description> + <syntax>set [<variable> [<value>]]</syntax> + + <description> + + <para> + Without any arguments, this command lists all the set variables. You can also specify a single argument, a variable name, to get that variable's value. To change this value, specify the new value as the second argument. + </para> + + <para> + To get more help information about a setting, try: + </para> + + </description> + + <ircexample> + <ircline nick="ctrlsoft">help set private</ircline> + </ircexample> + + </bitlbee-command> + + <bitlbee-command name="help"> + <short-description>BitlBee help system</short-description> + + <syntax>help [subject]</syntax> + + <description> + <para> + This command gives you the help information you're reading right now. If you don't give any arguments, it'll give a short help index. + </para> + </description> + </bitlbee-command> + + <bitlbee-command name="save"> + <short-description>Save your account data</short-description> + <syntax>save</syntax> + + <description> + <para> + This command saves all your nicks and accounts immediately. Handy if you have the autosave functionality disabled, or if you don't trust the program's stability... ;-) + </para> + </description> + </bitlbee-command> + + <bitlbee-setting name="charset" type="string"> + <default>iso8859-1</default> + <possible-values>you can get a list of all possible values by doing 'iconv -l' in a shell</possible-values> + + <description> + <para> + The charset setting enables you to use different character sets in BitlBee. These get converted to UTF-8 before sending and from UTF-8 when receiving. + </para> + + <para> + If you don't know what's the best value for this, at least iso8859-1 is the best choice for most Western countries. You can try to find what works best for you on http://czyborra.com/charsets/iso8859.html + </para> + </description> + + </bitlbee-setting> + + <bitlbee-setting name="private" type="boolean"> + <default>True</default> + + <description> + + <para> + If value is true, messages from users will appear in separate query windows. If false, messages from users will appear in the control channel. + </para> + + <para> + This setting is remembered (during one session) per-user, this setting only changes the default state. This option takes effect as soon as you reconnect. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="save_on_quit" type="boolean"> + <default>True</default> + + <description> + <para> + If enabled causes BitlBee to save all current settings and account details when user disconnects. This is enabled by default, and these days there's not really a reason to have it disabled anymore. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="html" type="string"> + <default>nostrip</default> + <possible-values>strip, nostrip</possible-values> + + <description> + <para> + Determines what BitlBee should do with HTML in messages. If set to nostrip, HTML in messages will not be touched. If set to strip, all HTML will be stripped from messages. Unfortunately this sometimes strips too much. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="debug" type="boolean"> + <default>False</default> + + <description> + <para> + Some debugging messages can be sent to the control channel if you wish. They're probably not really useful for you, unless you're doing some development on BitlBee. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="to_char" type="string"> + <default>": "</default> + + <description> + + <para> + It's customary that messages meant for one specific person on an IRC channel are prepended by his/her alias followed by a colon ':'. BitlBee does this by default. If you prefer a different character, you can set it using <emphasis>set to_char</emphasis>. + </para> + + <para> + Please note that this setting is only used for incoming messages. For outgoing messages you can use ':' (colon) or ',' to separate the destination nick from the message, and this is not configurable. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="typing_notice" type="boolean"> + <default>False</default> + + <description> + <para> + Sends you a /notice when a user starts typing a message (if the protocol supports it, MSN for example). This is a bug, not a feature. (But please don't report it.. ;-) You don't want to use it. Really. In fact the typing-notification is just one of the least useful 'innovations' ever. It's just there because some guy will probably ask me about it anyway. ;-) + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="ops" type="string"> + <default>both</default> + <possible-values>both, root, user, none</possible-values> + + <description> + <para> + Some people prefer themself and root to have operator status in #bitlbee, other people don't. You can change these states using this setting. + </para> + + <para> + The value "both" means both user and root get ops. "root" means, well, just root. "user" means just the user. "none" means nobody will get operator status. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="away_devoice" type="boolean"> + <default>True</default> + + <description> + <para> + With this option enabled, the root user devoices people when they go away (just away, not offline) and gives the voice back when they come back. You might dislike the voice-floods you'll get if your contact list is huge, so this option can be disabled. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="handle_unknown" type="string"> + <default>root</default> + <possible-values>root, add, add_private, add_channel, ignore</possible-values> + + <description> + <para> + Messages from unknown users are echoed like this by default: + </para> + + <ircexample> + <ircline nick="root">Unknown message from handle 3137137:</ircline> + <ircline nick="root">j0000! 1 4m l33t h4x0r! kill me!</ircline> + </ircexample> + + <para> + If you want this lame user to be added automatically, you can set this setting to "add". If you prefer to ignore messages from people you don't know, you can set this one to "ignore". "add_private" and "add_channel" are like add, but you can use them to make messages from unknown buddies appear in the channel instead of a query window. + </para> + + <note> + <para> + Auto-added users aren't added to your real contact list. This is because you don't want the user to get authorization requests. So when you restart BitlBee, the auto-added user will be gone. If you want to keep the person in your buddy-list, you have to fixate the add using the <emphasis>add</emphasis> command. + </para> + </note> + </description> + + </bitlbee-setting> + + <bitlbee-setting name="auto_connect" type="boolean"> + <default>True</default> + + <description> + <para> + With this option enabled, when you identify BitlBee will automatically connect to your accounts, with this disabled it will not do this. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="auto_reconnect" type="boolean"> + <default>False</default> + + <description> + <para> + If an IM-connections breaks, you're supposed to bring it back up yourself. Having BitlBee do this automatically might not always be a good idea, for several reasons. If you want the connections to be restored automatically, you can enable this setting. + </para> + + <para> + See also the <emphasis>auto_reconnect_delay</emphasis> setting. + </para> + </description> + + </bitlbee-setting> + + <bitlbee-setting name="auto_reconnect_delay" type="integer"> + <default>300</default> + + <description> + + <para> + Tell BitlBee after how many seconds it should attempt to bring an IM-connection back up after a crash. It's not a good idea to set this value very low, it will cause too much useless traffic when an IM-server is down for a few hours. + </para> + + <para> + See also the <emphasis>auto_reconnect</emphasis> setting. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="buddy_sendbuffer" type="boolean"> + <default>False</default> + + <description> + + <para> + By default, when you send a message to someone, BitlBee forwards this message to the user immediately. When you paste a large number of lines, the lines will be sent in separate messages, which might not be very nice to read. If you enable this setting, BitlBee will buffer your messages and wait for more data. + </para> + + <para> + Using the <emphasis>buddy_sendbuffer_delay</emphasis> setting you can specify the number of seconds BitlBee should wait for more data before the complete message is sent. + </para> + + <para> + Please note that if you remove a buddy from your list (or if the connection to that user drops) and there's still data in the buffer, this data will be lost. BitlBee will not try to send the message to the user in those cases. + </para> + </description> + + </bitlbee-setting> + + <bitlbee-setting name="buddy_sendbuffer_delay" type="integer"> + <description> + + <para> + Tell BitlBee after how many seconds a buffered message should be sent. + </para> + + <para> + See also the <emphasis>buddy_sendbuffer</emphasis> setting. + </para> + </description> + + </bitlbee-setting> + + <bitlbee-setting name="default_target" type="string"> + <default>root</default> + <possible-values>root, last</possible-values> + + <description> + <para> + With this value set to <emphasis>root</emphasis>, lines written in the control channel without any nickname in front of them will be interpreted as commands. If you want BitlBee to send those lines to the last person you addressed in the control channel, set this to <emphasis>last</emphasis>. + </para> + </description> + + </bitlbee-setting> + + <bitlbee-setting name="display_namechanges" type="boolean"> + <default>False</default> + + <para> + With this option enabled, root will inform you when someone in your buddy list changes his/her "friendly name". + </para> + </bitlbee-setting> + + <bitlbee-setting name="password" type="string"> + <description> + <para> + Use this setting to change your "NickServ" password. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="query_order" type="string"> + <default>lifo</default> + <possible-values>lifo, fifo</possible-values> + + <description> + <para> + This changes the order in which the questions from root (usually authorization requests from buddies) should be answered. When set to <emphasis>lifo</emphasis>, BitlBee immediately displays all new questions and they should be answered in reverse order. When this is set to <emphasis>fifo</emphasis>, BitlBee displays the first question which comes in and caches all the others until you answer the first one. + </para> + + <para> + Although the <emphasis>fifo</emphasis> setting might sound more logical (and used to be the default behaviour in older BitlBee versions), it turned out not to be very convenient for many users when they missed the first question (and never received the next ones). + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="lcnicks" type="boolean"> + <default>True</default> + + <description> + <para> + Hereby you can change whether you want all lower case nick names or leave the case as it intended by your peer. + </para> + </description> + + </bitlbee-setting> + + <bitlbee-command name="rename"> + <short-description>Rename (renick) a buddy</short-description> + <syntax>rename <oldnick> <newnick></syntax> + + <description> + <para> + Renick a user in your buddy list. Very useful, in fact just very important, if you got a lot of people with stupid account names (or hard ICQ numbers). + </para> + </description> + + <ircexample> + <ircline nick="itsme">rename itsme_ you</ircline> + <ircaction nick="itsme_">is now known as <emphasis>you</emphasis></ircaction> + </ircexample> + + </bitlbee-command> + + <bitlbee-command name="yes"> + <short-description>Accept a request</short-description> + <syntax>yes [<number>]</syntax> + + <description> + <para> + Sometimes an IM-module might want to ask you a question. (Accept this user as your buddy or not?) To accept a question, use the <emphasis>yes</emphasis> command. + </para> + + <para> + By default, this answers the first unanswered question. You can also specify a different question as an argument. You can use the <emphasis>qlist</emphasis> command for a list of questions. + </para> + </description> + + </bitlbee-command> + + <bitlbee-command name="no"> + <short-description>Deny a request</short-description> + <syntax>no [<number>]</syntax> + + <description> + <para> + Sometimes an IM-module might want to ask you a question. (Accept this user as your buddy or not?) To reject a question, use the <emphasis>no</emphasis> command. + </para> + + <para> + By default, this answers the first unanswered question. You can also specify a different question as an argument. You can use the <emphasis>qlist</emphasis> command for a list of questions. + </para> + </description> + </bitlbee-command> + + <bitlbee-command name="qlist"> + <short-description>List all the unanswered questions root asked</short-description> + <syntax>qlist</syntax> + + <description> + <para> + This gives you a list of all the unanswered questions from root. + </para> + </description> + + </bitlbee-command> + + <bitlbee-command name="register"> + <short-description>Register yourself</short-description> + <syntax>register <password></syntax> + + <description> + <para> + BitlBee can save your settings so you won't have to enter all your IM passwords every time you log in. If you want the Bee to save your settings, use the <emphasis>register</emphasis> command. + </para> + + <para> + Please do pick a secure password, don't just use your nick as your password. Please note that IRC is not an encrypted protocol, so the passwords still go over the network in plaintext. Evil people with evil sniffers will read it all. (So don't use your root password.. ;-) + </para> + + <para> + To identify yourself in later sessions, you can use the <emphasis>identify</emphasis> command. + </para> + </description> + + </bitlbee-command> + + <bitlbee-command name="identify"> + <syntax>identify <password></syntax> + <short-description>Identify yourself with your password</short-description> + + <description> + <para> + BitlBee saves all your settings (contacts, accounts, passwords) on-server. To prevent other users from just logging in as you and getting this information, you'll have to identify yourself with your password. You can register this password using the <emphasis>register</emphasis> command. + </para> + + <para> + Once you're registered, you can change your password using <emphasis>set password <password></emphasis>. + </para> + </description> + </bitlbee-command> + + <bitlbee-command name="drop"> + <syntax>drop <password></syntax> + <short-description>Drop your account</short-description> + + <description> + <para> + Drop your BitlBee registration. Your account files will be removed and your password will be forgotten. For obvious security reasons, you have to specify your NickServ password to make this command work. + </para> + </description> + </bitlbee-command> + + <bitlbee-command name="blist"> + <syntax>blist [all|online|offline|away]</syntax> + <short-description>List all the buddies in your contact list</short-description> + + <description> + <para> + You can get a better readable buddy list using the <emphasis>blist</emphasis> command. If you want a complete list (including the offline users) you can use the <emphasis>all</emphasis> argument. + </para> + </description> + + </bitlbee-command> + + <bitlbee-command name="nick"> + <short-description>Change friendly name, nick</short-description> + <syntax>nick <connection> [<new nick>]</syntax> + <syntax>nick</syntax> + + <description> + <para> + This command allows to set the friendly name of an im account. If no new name is specified the command will report the current name. When the name contains spaces, don't forget to quote the whole nick in double quotes. Currently this command is only supported by the MSN protocol. + </para> + </description> + + <ircexample> + <ircline nick="wouter">nick 1 "Wouter Paesen"</ircline> + <ircline nick="root">Setting your name on connection 1 to `Wouter Paesen'</ircline> + </ircexample> + + </bitlbee-command> + + <bitlbee-command name="import_buddies"> + <short-description>Copy local buddy list to server (normally only needed when upgrading)</short-description> + <syntax>import_buddies <connection> [clear]</syntax> + + <description> + <para> + This command copies the locally stored buddy list to the server. This command exists for upgrading purposes. Previous versions of BitlBee didn't support server-side buddy lists for ICQ, so the list was stored locally. + </para> + + <para> + Since version 0.91 however, server-side contact lists are supported for all protocols, so the local list is now ignored. When upgrading from an older BitlBee to version 0.91, you might need this command to get your buddy list back. + </para> + + <para> + The only argument this command needs is your ICQ account identification. If your serverside buddy list contains some old buddies you don't want anymore, you can pass <emphasis>clear</emphasis> as a second argument. + </para> + + <para> + After giving this command, you have to wait for a while before all the adds are handled, because of ICQ's rate limiting. If your buddy list is very large and the ICQ server starts complaining, you might have to reconnect and enter this command again. + </para> + </description> + + </bitlbee-command> +</chapter> diff --git a/doc/user-guide/docbook.xsl b/doc/user-guide/docbook.xsl new file mode 100644 index 00000000..cfb27702 --- /dev/null +++ b/doc/user-guide/docbook.xsl @@ -0,0 +1,136 @@ +<?xml version='1.0'?> +<!-- + Convert BitlBee XML documentation to DocBook + (C) 2004 Jelmer Vernooij +--> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:exsl="http://exslt.org/common" + version="1.1" + extension-element-prefixes="exsl"> + + <xsl:output method="xml" encoding="UTF-8" doctype-public="-//OASIS//DTD DocBook XML V4.2//EN" indent="yes" doctype-system="http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"/> + + <xsl:strip-space elements="*"/> + + <xsl:template match="ircline"> + <xsl:element name="prompt"><xsl:text>< </xsl:text><xsl:value-of select="@nick"/><xsl:text>> </xsl:text></xsl:element> + <xsl:element name="userinput"><xsl:value-of select="normalize-space(.)"/></xsl:element><xsl:text> </xsl:text> + </xsl:template> + + <xsl:template match="ircaction"> + <xsl:text> * </xsl:text><xsl:value-of select="@nick"/><xsl:value-of select="normalize-space(.)"/><xsl:text> </xsl:text> + </xsl:template> + + <xsl:template match="ircexample"> + <xsl:element name="screen"> + <xsl:for-each select="ircline|ircaction"> + <xsl:apply-templates select="."/> + </xsl:for-each> + </xsl:element> + </xsl:template> + + + <!-- This is needed to copy content unchanged --> + <xsl:template match="@*|node()"> + <xsl:copy> + <xsl:apply-templates select="@*|node()"/> + </xsl:copy> + </xsl:template> + + <xsl:template name="subcmd-list"> + <xsl:if test="bitlbee-command != ''"> + <xsl:element name="variablelist"> + <xsl:for-each select="bitlbee-command"> + <xsl:element name="varlistentry"> + <xsl:element name="term"> + <xsl:value-of select="@name"/> + </xsl:element> + <xsl:element name="listitem"> + <xsl:element name="para"> + <xsl:value-of select="short-description"/> + </xsl:element> + </xsl:element> + </xsl:element> + </xsl:for-each> + </xsl:element> + </xsl:if> + </xsl:template> + + <xsl:template match="command-list"> + <xsl:call-template name="subcmd-list"/> + </xsl:template> + + <xsl:template match="bitlbee-setting"> + <xsl:element name="sect1"> + <xsl:attribute name="id"> + <xsl:text>set_</xsl:text> + <xsl:value-of select="@name"/> + </xsl:attribute> + <xsl:element name="title"><xsl:value-of select="@name"/></xsl:element> + + <xsl:element name="simplelist"> + <xsl:element name="member"> + <xsl:text>Type: </xsl:text><xsl:value-of select="@type"/> + </xsl:element> + </xsl:element> + + <xsl:for-each select="description/para"> + <xsl:apply-templates select="."/> + </xsl:for-each> + + </xsl:element> + </xsl:template> + + <xsl:template name="cmd"> + <xsl:variable name="thiscmd"><xsl:value-of select="$prefix"/><xsl:value-of select="@name"/></xsl:variable> + <xsl:attribute name="id"> + <xsl:text>cmd_</xsl:text> + <xsl:value-of select="translate($thiscmd,' ','_')"/> + </xsl:attribute> + <xsl:element name="title"><xsl:value-of select="$thiscmd"/> + <xsl:if test="short-description"> + <xsl:text> - </xsl:text> + <xsl:value-of select="short-description"/> + </xsl:if> + </xsl:element> + + <xsl:element name="formalpara"> + <xsl:element name="title"><xsl:text>Syntax:</xsl:text></xsl:element> + <xsl:element name="para"> + <xsl:element name="programlisting"> + <xsl:for-each select="syntax"> + <xsl:value-of select="normalize-space(.)"/><xsl:text> </xsl:text> + </xsl:for-each> + </xsl:element> + </xsl:element> + </xsl:element> + + <xsl:for-each select="description/para"> + <xsl:apply-templates select="."/> + </xsl:for-each> + + <xsl:for-each select="ircexample"> + <xsl:apply-templates select="."/> + </xsl:for-each> + + <!--<xsl:call-template name="subcmd-list"/>--> + + <xsl:for-each select="bitlbee-command"> + <xsl:element name="sect2"> + <xsl:call-template name="cmd"> + <xsl:with-param name="prefix"><xsl:value-of select="$thiscmd"/><xsl:text> </xsl:text> + </xsl:with-param> + </xsl:call-template> + </xsl:element> + </xsl:for-each> + </xsl:template> + + <xsl:template match="bitlbee-command"> + <xsl:element name="sect1"> + <xsl:call-template name="cmd"> + <xsl:with-param name="prefix" select="''"/> + </xsl:call-template> + </xsl:element> + </xsl:template> + + </xsl:stylesheet> diff --git a/doc/user-guide/help.txt b/doc/user-guide/help.txt new file mode 100644 index 00000000..a14e3a99 --- /dev/null +++ b/doc/user-guide/help.txt @@ -0,0 +1,554 @@ +? +These are the available help subjects: + + quickstart - A short introduction into BitlBee + commands - All available commands and settings + away - About setting away states + smileys - A summary of some non-standard smileys you might find and fail to understand + groupchats - How to work with groupchats on BitlBee + +You can read more about them with help <subject> + +BitlBee is written by Wilmer van der Gaast together with Jelmer Vernooij, Maurits Dijkstra and others. Bug reports and other kinds of feedback can be sent by e-mail to wilmer@gaast.net. (There is no BitlBee mailing list) + +Or just join #BitlBee on OFTC (irc.oftc.net) (OFTC, *not* FreeNode! Some people accidentally joined #BitlBee on FreeNode already, which is just an empty channel) and flame us right in the face. :-) +% +?index +These are the available help subjects: + + quickstart - A short introduction into BitlBee + commands - All available commands and settings + away - About setting away states + smileys - A summary of some non-standard smileys you might find and fail to understand + groupchats - How to work with groupchats on BitlBee + +You can read more about them with help <subject> +% +?quickstart +Welcome to BitlBee, your IRC gateway to ICQ, MSN, AOL, Jabber and Yahoo Instant Messaging Systems. + +The center of BitlBee is the control channel, #bitlbee. Two users will always be there, you (where "you" is the nickname you are using) and the system user, root. + +You need register so that all your IM settings (passwords, contacts, etc) can be saved on the BitlBee server. It's important that you pick a good password so no one else can access your account. Register with this password using the register command: register <password> (without the brackets!). + +Be sure to remember your password. The next time you connect to the BitlBee server you will need to identify <password> so that you will be recognised and logged in to all the IM services automatically. + +When finished, type help quickstart2 to continue. +% +?quickstart2 +Step Two: Add and Connect To your IM Account(s). + +To add an account to the account list you will need to use the account add command: account add <protocol> <username> <password> [<server>]. + +For instance, suppose you have an ICQ account with UIN 72696705 with password QuickStart, you would: + +<you> account add oscar 72696705 QuickStart login.icq.com +<root> Account successfully added + +Other available IM protocols are jabber, msn, and yahoo. Oscar is the protocol used by ICQ and AOL. For oscar, you need to specify the IM-server as a fourth argument (for msn and yahoo there is no fourth argument). For AOL Instant Messenger, the server name is login.oscar.aol.com. For ICQ, the server name is login.icq.com. + +When you are finished adding your account(s) use the account on command to enable all your accounts, type help quickstart3 to continue. +% +?quickstart3 +Step Three: Managing Contact Lists: Rename + +For most protocols (currently MSN, Jabber, Yahoo and AOL) BitlBee can download the contact list automatically from the IM server and all the on-line users should appear in the control channel when you log in. + +BitlBee will convert names into irc-friendly form (for instance: tux@example.com will be given the nickname tux). If you have more than one person who would have the same name by this logic (for instance: tux@example.com and tux@bitlbee.org) the second one to log on will be tux_. The same is true if you have a tux log on to AOL and a tux log on from Yahoo. + +It would be easy to get these two mixed up, so BitlBee has a rename command to change the nickname into something more suitable: rename <oldnick> <newnick> + +<you> rename tux_ bitlbeetux +* tux_ is now known as bitlbeetux +<root> Nick successfully changed + +When finished, type help quickstart4 to continue. +% +?quickstart4 +Step Four: Managing Contact Lists: Add and Remove. + +Now you might want to add some contacts, to do this we will use the add command. It needs two arguments: a connection ID (which can be a number (try account list), protocol name or (part of) the screenname) and the user's handle. It is used in the following way: add <connection> <handle> + +<you> add 0 r2d2@example.com +* r2d2 has joined #bitlbee + +In this case r2d2 is online, since he/she joins the channel immediately. If the user is not online you will not see them join until they log on. + +Lets say you accidentally added r2d3@example.com rather than r2d2@example.com, or maybe you just want to remove a user from your list because you never talk to them. To remove a name you will want to use the remove command: remove <nick> + +When finished, type help quickstart5 to continue. +% +?quickstart5 +Step Five: Chatting. + +First of all, a person must be on your contact list for you to chat with them (unless it's a group chat, help groupchats for more). If someone not on your contact list sends you a message, simply add them to the proper account with the add command. Once they are on your list and online, you can chat with them in #bitlbee: + +<you> tux: hey, how's the weather down there? +<tux> you: a bit chilly! + +If you'd rather chat with them in a separate window use the /msg or /query command, just like you would for a private message in IRC. If you want to have messages automatically come up in private messages rather than in the #bitlbee channel, use the set private command: set private true (set private false to change back). + +You know the basics. If you want to get to know more about BitlBee, please type help quickstart6. +% +?quickstart6 +So you want more than just chatting? Or maybe you're just looking for a feature? + +You can type help set to learn more about the possible BitlBee user settings. Among these user settings you will find options for common issues, such as changing the charset, HTML stripping and automatic connecting (simply type set to see current user settings). + +For more subjects (like groupchats and away states), please type help index. + +If you're still looking for something, please visit us in #bitlbee on the OFTC network (you can connect via irc.bitlbee.org), or mail us your problem/suggestion. Good luck and enjoy the Bee! +% +?commands + * account - IM-account list maintenance + * add - Add a buddy to your contact list + * info - Request user information + * remove - Remove a buddy from your contact list + * block - Block someone + * allow - Unblock someone + * set - Miscellaneous settings + * help - BitlBee help system + * save - Save your account data + * rename - Rename (renick) a buddy + * yes - Accept a request + * no - Deny a request + * qlist - List all the unanswered questions root asked + * register - Register yourself + * identify - Identify yourself with your password + * drop - Drop your account + * blist - List all the buddies in your contact list + * nick - Change friendly name, nick + * import_buddies - Copy local buddy list to server (normally only needed when upgrading) +% +?account +Syntax: account <action> [<arguments>] + +Available actions: add, del, list, on, off. See help account <action> for more information. +% +?account add +Syntax: account add <protocol> <username> <password> [<server>] + +Adds an account on the given server with the specified protocol, username and password to the account list. Supported protocols right now are: Jabber, MSN, OSCAR (AIM/ICQ) and Yahoo. For more information about adding an account, see help account add <protocol>. +% +?account add jabber +Syntax: account add jabber <handle> <password> [<servertag>] + +Note that the servertag argument is optional. You only have to use it if the part after the @ in your handle isn't the hostname of your Jabber server, or if you want to use SSL/connect to a non-standard port number. The format is simple: [<servername>[:<portnumber>][:ssl]]. For example, this is how you can connect to Google Talk: + +Note that Google talk is SSL-only, but officially reachable over both port 5222 and 5223. However, for some people only port 5222 works, for some people only 5223. This is something you'll have to try out. + +Example: +<wilmer> account add jabber example@gmail.com hobbelmeeuw talk.google.com:5223:ssl +<root> Account successfully added +% +?account add msn +Syntax: account add msn <handle> <password> + +For MSN connections there are no special arguments. +% +?account add oscar +Syntax: account add oscar <handle> <password> [<servername>] + +Specifying a server is required for OSCAR, since OSCAR can be used for both ICQ- and AIM-connections. Although these days it's supposed to be possible to connect to ICQ via AIM-servers and vice versa, we like to stick with this separation for now. For ICQ connections, the servername is login.icq.com, for AIM connections it's login.oscar.aol.com. + +Example: +<wilmer> account add oscar 72696705 hobbelmeeuw login.icq.com +<root> Account successfully added +% +?account add yahoo +Syntax: account add yahoo <handle> <password> + +For Yahoo! connections there are no special arguments. +% +?account del +Syntax: account del <account id> + +This commands deletes an account from your account list. You should signoff the account before deleting it. + +The account ID can be a number (see account list), the protocol name or (part of) the screenname, as long as it matches only one connection. +% +?account on +Syntax: account on [<account id>] + +This command will try to log into the specified account. If no account is specified, BitlBee will log into all the accounts. (Including accounts awaiting a reconnection) + +The account ID can be a number (see account list), the protocol name or (part of) the screenname, as long as it matches only one connection. +% +?account off +Syntax: account off [<account id>] + +This command disconnects the connection for the specified account. If no account is specified, BitlBee will deactivate all active accounts. (Including accounts awaiting a reconnection) + +The account ID can be a number (see account list), the protocol name or (part of) the screenname, as long as it matches only one connection. +% +?account list +Syntax: account list + +This command gives you a list of all the accounts known by BitlBee, including the numbers you'll need for most account commands. +% +?add +Syntax: add <connection> <handle> [<nick>] + +Adds the given buddy at the specified connection to your buddy list. The account ID can be a number (see account list), the protocol name or (part of) the screenname, as long as it matches only one connection. + +If you want, you can also tell BitlBee what nick to give the new contact. Of course you can also use the rename command for that, but sometimes this might be more convenient. + +Example: +<ctrlsoft> add 3 gryp@jabber.org grijp +* grijp has joined #bitlbee +% +?info +Syntax: info <connection> <handle> +Syntax: info <nick> + +Requests IM-network-specific information about the specified user. The amount of information you'll get differs per protocol. For some protocols (ATM Yahoo! and MSN) it'll give you an URL which you can visit with a normal web browser to get the information. + +Example: +<ctrlsoft> info 0 72696705 +<root> User info - UIN: 72696705 Nick: Lintux First/Last name: Wilmer van der Gaast E-mail: lintux@lintux.cx +% +?remove +Syntax: remove <nick> + +Removes the specified nick from your buddy list. + +Example: +<ctrlsoft> remove gryp +* gryp has quit [Leaving...] +% +?block +Syntax: block <nick> +Syntax: block <connection> <handle> + +Puts the specified user on your ignore list. Either specify the user's nick when you have him/her in your contact list or a connection number and a user handle. +% +?allow +Syntax: allow <nick> +Syntax: allow <connection> <handle> + +Reverse of block. Unignores the specified user or user handle on specified connection. +% +?set +Syntax: set [<variable> [<value>]] + +Without any arguments, this command lists all the set variables. You can also specify a single argument, a variable name, to get that variable's value. To change this value, specify the new value as the second argument. + +To get more help information about a setting, try: + +Example: +<ctrlsoft> help set private +% +?help +Syntax: help [subject] + +This command gives you the help information you're reading right now. If you don't give any arguments, it'll give a short help index. +% +?save +Syntax: save + +This command saves all your nicks and accounts immediately. Handy if you have the autosave functionality disabled, or if you don't trust the program's stability... ;-) +% +?rename +Syntax: rename <oldnick> <newnick> + +Renick a user in your buddy list. Very useful, in fact just very important, if you got a lot of people with stupid account names (or hard ICQ numbers). + +Example: +<itsme> rename itsme_ you +* itsme_ is now known as you +% +?yes +Syntax: yes [<number>] + +Sometimes an IM-module might want to ask you a question. (Accept this user as your buddy or not?) To accept a question, use the yes command. + +By default, this answers the first unanswered question. You can also specify a different question as an argument. You can use the qlist command for a list of questions. +% +?no +Syntax: no [<number>] + +Sometimes an IM-module might want to ask you a question. (Accept this user as your buddy or not?) To reject a question, use the no command. + +By default, this answers the first unanswered question. You can also specify a different question as an argument. You can use the qlist command for a list of questions. +% +?qlist +Syntax: qlist + +This gives you a list of all the unanswered questions from root. +% +?register +Syntax: register <password> + +BitlBee can save your settings so you won't have to enter all your IM passwords every time you log in. If you want the Bee to save your settings, use the register command. + +Please do pick a secure password, don't just use your nick as your password. Please note that IRC is not an encrypted protocol, so the passwords still go over the network in plaintext. Evil people with evil sniffers will read it all. (So don't use your root password.. ;-) + +To identify yourself in later sessions, you can use the identify command. +% +?identify +Syntax: identify <password> + +BitlBee saves all your settings (contacts, accounts, passwords) on-server. To prevent other users from just logging in as you and getting this information, you'll have to identify yourself with your password. You can register this password using the register command. + +Once you're registered, you can change your password using set password <password>. +% +?drop +Syntax: drop <password> + +Drop your BitlBee registration. Your account files will be removed and your password will be forgotten. For obvious security reasons, you have to specify your NickServ password to make this command work. +% +?blist +Syntax: blist [all|online|offline|away] + +You can get a better readable buddy list using the blist command. If you want a complete list (including the offline users) you can use the all argument. +% +?nick +Syntax: nick <connection> [<new nick>] +Syntax: nick + +This command allows to set the friendly name of an im account. If no new name is specified the command will report the current name. When the name contains spaces, don't forget to quote the whole nick in double quotes. Currently this command is only supported by the MSN protocol. + +Example: +<wouter> nick 1 "Wouter Paesen" +<root> Setting your name on connection 1 to `Wouter Paesen' +% +?import_buddies +Syntax: import_buddies <connection> [clear] + +This command copies the locally stored buddy list to the server. This command exists for upgrading purposes. Previous versions of BitlBee didn't support server-side buddy lists for ICQ, so the list was stored locally. + +Since version 0.91 however, server-side contact lists are supported for all protocols, so the local list is now ignored. When upgrading from an older BitlBee to version 0.91, you might need this command to get your buddy list back. + +The only argument this command needs is your ICQ account identification. If your serverside buddy list contains some old buddies you don't want anymore, you can pass clear as a second argument. + +After giving this command, you have to wait for a while before all the adds are handled, because of ICQ's rate limiting. If your buddy list is very large and the ICQ server starts complaining, you might have to reconnect and enter this command again. +% +?set charset +Type: string +Default: iso8859-1 +Possible Values: you can get a list of all possible values by doing 'iconv -l' in a shell + +The charset setting enables you to use different character sets in BitlBee. These get converted to UTF-8 before sending and from UTF-8 when receiving. + +If you don't know what's the best value for this, at least iso8859-1 is the best choice for most Western countries. You can try to find what works best for you on http://czyborra.com/charsets/iso8859.html +% +?set private +Type: boolean +Default: True + +If value is true, messages from users will appear in separate query windows. If false, messages from users will appear in the control channel. + +This setting is remembered (during one session) per-user, this setting only changes the default state. This option takes effect as soon as you reconnect. +% +?set save_on_quit +Type: boolean +Default: True + +If enabled causes BitlBee to save all current settings and account details when user disconnects. This is enabled by default, and these days there's not really a reason to have it disabled anymore. +% +?set html +Type: string +Default: nostrip +Possible Values: strip, nostrip + +Determines what BitlBee should do with HTML in messages. If set to nostrip, HTML in messages will not be touched. If set to strip, all HTML will be stripped from messages. Unfortunately this sometimes strips too much. +% +?set debug +Type: boolean +Default: False + +Some debugging messages can be sent to the control channel if you wish. They're probably not really useful for you, unless you're doing some development on BitlBee. +% +?set to_char +Type: string +Default: ": " + +It's customary that messages meant for one specific person on an IRC channel are prepended by his/her alias followed by a colon ':'. BitlBee does this by default. If you prefer a different character, you can set it using set to_char. + +Please note that this setting is only used for incoming messages. For outgoing messages you can use ':' (colon) or ',' to separate the destination nick from the message, and this is not configurable. +% +?set typing_notice +Type: boolean +Default: False + +Sends you a /notice when a user starts typing a message (if the protocol supports it, MSN for example). This is a bug, not a feature. (But please don't report it.. ;-) You don't want to use it. Really. In fact the typing-notification is just one of the least useful 'innovations' ever. It's just there because some guy will probably ask me about it anyway. ;-) +% +?set ops +Type: string +Default: both +Possible Values: both, root, user, none + +Some people prefer themself and root to have operator status in #bitlbee, other people don't. You can change these states using this setting. + +The value "both" means both user and root get ops. "root" means, well, just root. "user" means just the user. "none" means nobody will get operator status. +% +?set away_devoice +Type: boolean +Default: True + +With this option enabled, the root user devoices people when they go away (just away, not offline) and gives the voice back when they come back. You might dislike the voice-floods you'll get if your contact list is huge, so this option can be disabled. +% +?set handle_unknown +Type: string +Default: root +Possible Values: root, add, add_private, add_channel, ignore + +Messages from unknown users are echoed like this by default: + +<root> Unknown message from handle 3137137: +<root> j0000! 1 4m l33t h4x0r! kill me! + +If you want this lame user to be added automatically, you can set this setting to "add". If you prefer to ignore messages from people you don't know, you can set this one to "ignore". "add_private" and "add_channel" are like add, but you can use them to make messages from unknown buddies appear in the channel instead of a query window. + +Auto-added users aren't added to your real contact list. This is because you don't want the user to get authorization requests. So when you restart BitlBee, the auto-added user will be gone. If you want to keep the person in your buddy-list, you have to fixate the add using the add command. +% +?set auto_connect +Type: boolean +Default: True + +With this option enabled, when you identify BitlBee will automatically connect to your accounts, with this disabled it will not do this. +% +?set auto_reconnect +Type: boolean +Default: False + +If an IM-connections breaks, you're supposed to bring it back up yourself. Having BitlBee do this automatically might not always be a good idea, for several reasons. If you want the connections to be restored automatically, you can enable this setting. + +See also the auto_reconnect_delay setting. +% +?set auto_reconnect_delay +Type: integer +Default: 300 + +Tell BitlBee after how many seconds it should attempt to bring an IM-connection back up after a crash. It's not a good idea to set this value very low, it will cause too much useless traffic when an IM-server is down for a few hours. + +See also the auto_reconnect setting. +% +?set buddy_sendbuffer +Type: boolean +Default: False + +By default, when you send a message to someone, BitlBee forwards this message to the user immediately. When you paste a large number of lines, the lines will be sent in separate messages, which might not be very nice to read. If you enable this setting, BitlBee will buffer your messages and wait for more data. + +Using the buddy_sendbuffer_delay setting you can specify the number of seconds BitlBee should wait for more data before the complete message is sent. + +Please note that if you remove a buddy from your list (or if the connection to that user drops) and there's still data in the buffer, this data will be lost. BitlBee will not try to send the message to the user in those cases. +% +?set buddy_sendbuffer_delay +Type: integer +Default: + +Tell BitlBee after how many seconds a buffered message should be sent. + +See also the buddy_sendbuffer setting. +% +?set default_target +Type: string +Default: root +Possible Values: root, last + +With this value set to root, lines written in the control channel without any nickname in front of them will be interpreted as commands. If you want BitlBee to send those lines to the last person you addressed in the control channel, set this to last. +% +?set display_namechanges +Type: boolean +Default: False +% +?set password +Type: string +Default: + +Use this setting to change your "NickServ" password. +% +?set query_order +Type: string +Default: lifo +Possible Values: lifo, fifo + +This changes the order in which the questions from root (usually authorization requests from buddies) should be answered. When set to lifo, BitlBee immediately displays all new questions and they should be answered in reverse order. When this is set to fifo, BitlBee displays the first question which comes in and caches all the others until you answer the first one. + +Although the fifo setting might sound more logical (and used to be the default behaviour in older BitlBee versions), it turned out not to be very convenient for many users when they missed the first question (and never received the next ones). +% +?set lcnicks +Type: boolean +Default: True + +Hereby you can change whether you want all lower case nick names or leave the case as it intended by your peer. +% +?misc +% +?smileys +All MSN smileys (except one) are case insensitive and work without the nose too. + + (Y) - Thumbs up + (N) - Thumbs down + (B) - Beer mug + (D) - Martini glass + (X) - Girl + (Z) - Boy + (6) - Devil smiley + :-[ - Vampire bat + (}) - Right hug + ({) - Left hug + (M) - MSN Messenger or Windows Messenger icon (think a BitlBee logo here ;) + :-S - Crooked smiley (Confused smiley) + :-$ - Embarrassed smiley + (H) - Smiley with sunglasses + :-@ - Angry smiley + (A) - Angel smiley + (L) - Red heart (Love) + (U) - Broken heart + (K) - Red lips (Kiss) + (G) - Gift with bow + (F) - Red rose + (W) - Wilted rose + (P) - Camera + (~) - Film strip + (T) - Telephone receiver + (@) - Cat face + (&) - Dog's head + (C) - Coffee cup + (I) - Light bulb + (S) - Half-moon (Case sensitive!) + (*) - Star + (8) - Musical eighth note + (E) - Envelope + (^) - Birthday cake + (O) - Clock + +This list was extracted from http://help.msn.com/!data/en_us/data/messengerv50.its51/$content$/EMOTICONS.HTM?H_APP=. +% +?groupchats +Since version 0.8x, BitlBee supports groupchats on the MSN and Yahoo! networks. This text will try to explain you how they work. + +As soon as someone invites you into a groupchat, you will be force-joined or invited (depending on the protocol) into a new virtual channel with all the people in there. You can leave the channel at any time, just like you would close the window in regular IM clients. Please note that root-commands don't work in groupchat channels, they only work in the control channel (or to root directly). + +Of course you can also create your own groupchats. Type help groupchats2 to see how. +% +?groupchats2 +If you want to start a groupchat with the person jim_msn in it, just join the channel #jim_msn. BitlBee will refuse to join you to the channel with that name, but it will create a new virtual channel with root, you and jim_msn in it. + +Of course a channel with only two people isn't really exciting yet. So the next step is to invite some other people to the channel. For this, you can use the /invite command of your IRC client. Please do keep in mind that all the people have to be on the same network and contact list! You can't invite Yahoo! buddies into an MSN groupchat. + +This is all you'll probably need to know. If you have any problems, please read help groupchats3. +% +?groupchats3 +Obviously the (numbered) channel names don't make a lot of sense. Problem is that groupchats usually don't have names at all in the IM-world, while IRC insists on a name. So BitlBee just generates something random, just don't pay attention to it. :-) + +Please also note that BitlBee doesn't support groupchats for all protocols yet. BitlBee will tell you so. Support for other protocols will hopefully come later. +% +?away +As you might've expected, you can just use the /away command in your IRC client to set an away-state. BitlBee supports most away-states supported by the protocols. + +Not all away states are supported by all protocols, and some protocols have different names for them. BitlBee will try to pick the best available alias from this list for every connection: + + - Away from computer, Away, Extended away + - NA, N/A, Not available + - Busy, Do not disturb, DND, Occupied + - Be right back, BRB + - On the phone, Phone, On phone + - Out to lunch, Lunch, Food + +So /away Food will set your state to "Out to lunch" on your MSN connection, and for most other connections the default, "Away" or "Away from computer" will be chosen. + +You can also add more information to your away message. Setting it to "Busy - Fixing BitlBee bugs" will set your IM-away-states to Busy, but your away message will be more descriptive for people on IRC. Protocols like Yahoo! and Jabber will also show this complete away message to your buddies. +% diff --git a/doc/user-guide/help.xml b/doc/user-guide/help.xml new file mode 100644 index 00000000..9de4fbad --- /dev/null +++ b/doc/user-guide/help.xml @@ -0,0 +1,60 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<book id="BitlBee-Help" xmlns:xi="http://www.w3.org/2003/XInclude"> + +<preface id=""> +<title>BitlBee help system</title> + +<para> +These are the available help subjects: +</para> + +<variablelist> + <varlistentry><term>quickstart</term><listitem><para>A short introduction into BitlBee</para></listitem></varlistentry> + <varlistentry><term>commands</term><listitem><para>All available commands and settings</para></listitem></varlistentry> + <varlistentry><term>away</term><listitem><para>About setting away states</para></listitem></varlistentry> + <varlistentry><term>smileys</term><listitem><para>A summary of some non-standard smileys you might find and fail to understand</para></listitem></varlistentry> + <varlistentry><term>groupchats</term><listitem><para>How to work with groupchats on BitlBee</para></listitem></varlistentry> +</variablelist> + +<para> +You can read more about them with <emphasis>help <subject></emphasis> +</para> + +<para> +BitlBee is written by Wilmer van der Gaast together with Jelmer Vernooij, Maurits Dijkstra and others. Bug reports and other kinds of feedback can be sent by e-mail to <emphasis>wilmer@gaast.net</emphasis>. (There is no BitlBee mailing list) +</para> + +<para> +Or just join <emphasis>#BitlBee</emphasis> on OFTC (<emphasis>irc.oftc.net</emphasis>) (OFTC, *not* FreeNode! Some people accidentally joined #BitlBee on FreeNode already, which is just an empty channel) and flame us right in the face. :-) +</para> + +</preface> + +<chapter id="index"> +<title>Index</title> + +<para> +These are the available help subjects: +</para> + +<variablelist> + <varlistentry><term>quickstart</term><listitem><para>A short introduction into BitlBee</para></listitem></varlistentry> + <varlistentry><term>commands</term><listitem><para>All available commands and settings</para></listitem></varlistentry> + <varlistentry><term>away</term><listitem><para>About setting away states</para></listitem></varlistentry> + <varlistentry><term>smileys</term><listitem><para>A summary of some non-standard smileys you might find and fail to understand</para></listitem></varlistentry> + <varlistentry><term>groupchats</term><listitem><para>How to work with groupchats on BitlBee</para></listitem></varlistentry> +</variablelist> + +<para> +You can read more about them with <emphasis>help <subject></emphasis> +</para> + +</chapter> + +<xi:include href="quickstart.xml"/> +<xi:include href="commands.xml"/> +<xi:include href="misc.xml"/> + +</book> diff --git a/doc/user-guide/help.xsl b/doc/user-guide/help.xsl new file mode 100644 index 00000000..0eb1a88b --- /dev/null +++ b/doc/user-guide/help.xsl @@ -0,0 +1,156 @@ +<?xml version='1.0'?> +<!-- + Convert DocBook documentation to help.txt file used by bitlbee + (C) 2004 Jelmer Vernooij +--> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.1"> + + <xsl:output method="text" encoding="iso-8859-1" standalone="yes"/> + <xsl:strip-space elements="*"/> + + <xsl:template match="text()"> + <xsl:if test="starts-with(.,' ') and preceding-sibling::* and + not(preceding-sibling::*[1]/node()[1][self::text() and contains(concat(.,'^$%'),' ^$%')])"> + <xsl:text> </xsl:text> + </xsl:if> + + <xsl:value-of select="normalize-space(.)"/> + <xsl:if test="contains(concat(.,'^$%'),' ^$%') and following-sibling::* and + not(following-sibling::*[1]/node()[1][self::text() and starts-with(.,' ')])"> + <xsl:text> </xsl:text> + </xsl:if> + </xsl:template> + + <xsl:template match="para"> + <xsl:apply-templates/><xsl:text> </xsl:text> + <xsl:if test="$extraparanewline = '1'"> + <xsl:text> </xsl:text> + </xsl:if> + </xsl:template> + + <xsl:template name="subject"> + <xsl:message><xsl:text>Processing: </xsl:text><xsl:value-of select="$id"/></xsl:message> + <xsl:text>?</xsl:text><xsl:value-of select="$id"/><xsl:text> </xsl:text> + + <xsl:for-each select="para|variablelist|simplelist|command-list|ircexample"> + <xsl:if test="title != ''"> + <xsl:value-of select="title"/><xsl:text> </xsl:text> + </xsl:if> + <xsl:apply-templates select="."/> + </xsl:for-each> + <xsl:text>% </xsl:text> + + <xsl:for-each select="sect1|sect2"> + <xsl:call-template name="subject"> + <xsl:with-param name="id" select="@id"/> + </xsl:call-template> + </xsl:for-each> + + <xsl:for-each select="bitlbee-command"> + <xsl:call-template name="cmd"> + <xsl:with-param name="prefix" select="''"/> + </xsl:call-template> + </xsl:for-each> + + <xsl:for-each select="bitlbee-setting"> + <xsl:message><xsl:text>Processing setting '</xsl:text><xsl:value-of select="@name"/><xsl:text>'</xsl:text></xsl:message> + <xsl:text>?set </xsl:text><xsl:value-of select="@name"/><xsl:text> </xsl:text> + <xsl:text>_b_Type:_b_ </xsl:text><xsl:value-of select="@type"/><xsl:text> </xsl:text> + <xsl:text>_b_Default:_b_ </xsl:text><xsl:value-of select="default"/><xsl:text> </xsl:text> + <xsl:if test="possible-values"> + <xsl:text>_b_Possible Values:_b_ </xsl:text><xsl:value-of select="possible-values"/><xsl:text> </xsl:text> + </xsl:if> + <xsl:text> </xsl:text> + <xsl:apply-templates select="description"/> + <xsl:text>% </xsl:text> + </xsl:for-each> + </xsl:template> + + <xsl:template match="command-list"> + <xsl:for-each select="../bitlbee-command"> + <xsl:text> * _b_</xsl:text><xsl:value-of select="@name"/><xsl:text>_b_ - </xsl:text><xsl:value-of select="short-description"/><xsl:text> </xsl:text> + </xsl:for-each> + <xsl:text> </xsl:text> + </xsl:template> + + <xsl:template match="preface|chapter|sect1|sect2"> + <xsl:call-template name="subject"> + <xsl:with-param name="id" select="@id"/> + </xsl:call-template> + </xsl:template> + + <xsl:template match="emphasis"> + <xsl:text>_b_</xsl:text> + <xsl:apply-templates/> + <xsl:text>_b_</xsl:text> + </xsl:template> + + <xsl:template match="book"> + <xsl:apply-templates/> + </xsl:template> + + <xsl:template match="variablelist"> + <xsl:for-each select="varlistentry"> + <xsl:text> _b_</xsl:text><xsl:value-of select="term"/><xsl:text>_b_ - </xsl:text><xsl:value-of select="listitem/para"/><xsl:text> </xsl:text> + </xsl:for-each> + <xsl:text> </xsl:text> + </xsl:template> + + <xsl:template match="simplelist"> + <xsl:for-each select="member"> + <xsl:text> - </xsl:text><xsl:apply-templates/><xsl:text> </xsl:text> + </xsl:for-each> + <xsl:text> </xsl:text> + </xsl:template> + + <xsl:template match="ircline"> + <xsl:text>_b_<</xsl:text><xsl:value-of select="@nick"/><xsl:text>>_b_ </xsl:text><xsl:value-of select="."/><xsl:text> </xsl:text> + </xsl:template> + + <xsl:template match="ircaction"> + <xsl:text>_b_* </xsl:text><xsl:value-of select="@nick"/><xsl:text>_b_ </xsl:text><xsl:value-of select="."/><xsl:text> </xsl:text> + </xsl:template> + + <xsl:template match="ircexample"> + <xsl:apply-templates/> + <xsl:text> </xsl:text> + </xsl:template> + + <xsl:template name="cmd"> + <xsl:variable name="thiscmd"><xsl:value-of select="$prefix"/><xsl:value-of select="@name"/></xsl:variable> + <xsl:message><xsl:text>Processing command '</xsl:text><xsl:value-of select="$thiscmd"/><xsl:text>'</xsl:text></xsl:message> + <xsl:text>?</xsl:text><xsl:value-of select="$thiscmd"/><xsl:text> </xsl:text> + <xsl:for-each select="syntax"> + <xsl:text>_b_Syntax:_b_ </xsl:text><xsl:value-of select="."/><xsl:text> </xsl:text> + </xsl:for-each> + <xsl:text> </xsl:text> + + <xsl:apply-templates select="description"/> + + <xsl:for-each select="ircexample"> + <xsl:text>_b_Example:_b_ </xsl:text> + <xsl:apply-templates select="."/> + </xsl:for-each> + + <!-- + <xsl:if test="bitlbee-command != ''"> + <xsl:text>Subcommands: </xsl:text> + <xsl:for-each select="bitlbee-command"> + <xsl:value-of select="@name"/><xsl:text>, </xsl:text> + </xsl:for-each> + <xsl:text> </xsl:text> + </xsl:if> + --> + + <xsl:text>% </xsl:text> + + <xsl:for-each select="bitlbee-command"> + <xsl:call-template name="cmd"> + <xsl:with-param name="prefix"><xsl:value-of select="$thiscmd"/><xsl:text> </xsl:text></xsl:with-param> + </xsl:call-template> + </xsl:for-each> + + </xsl:template> + +</xsl:stylesheet> diff --git a/doc/user-guide/misc.xml b/doc/user-guide/misc.xml new file mode 100644 index 00000000..f90ce538 --- /dev/null +++ b/doc/user-guide/misc.xml @@ -0,0 +1,131 @@ +<chapter id="misc"> +<title>Misc Stuff</title> + +<sect1 id="smileys"> +<title>Smileys</title> + +<para> +All MSN smileys (except one) are case insensitive and work without the nose too. +</para> + +<variablelist> + <varlistentry><term>(Y)</term><listitem><para>Thumbs up</para></listitem></varlistentry> + <varlistentry><term>(N)</term><listitem><para>Thumbs down</para></listitem></varlistentry> + <varlistentry><term>(B)</term><listitem><para>Beer mug</para></listitem></varlistentry> + <varlistentry><term>(D)</term><listitem><para>Martini glass</para></listitem></varlistentry> + <varlistentry><term>(X)</term><listitem><para>Girl</para></listitem></varlistentry> + <varlistentry><term>(Z)</term><listitem><para>Boy</para></listitem></varlistentry> + <varlistentry><term>(6)</term><listitem><para>Devil smiley</para></listitem></varlistentry> + <varlistentry><term>:-[</term><listitem><para>Vampire bat</para></listitem></varlistentry> + <varlistentry><term>(})</term><listitem><para>Right hug</para></listitem></varlistentry> + <varlistentry><term>({)</term><listitem><para>Left hug</para></listitem></varlistentry> + <varlistentry><term>(M)</term><listitem><para>MSN Messenger or Windows Messenger icon (think a BitlBee logo here ;)</para></listitem></varlistentry> + <varlistentry><term>:-S</term><listitem><para>Crooked smiley (Confused smiley)</para></listitem></varlistentry> + <varlistentry><term>:-$</term><listitem><para>Embarrassed smiley</para></listitem></varlistentry> + <varlistentry><term>(H)</term><listitem><para>Smiley with sunglasses</para></listitem></varlistentry> + <varlistentry><term>:-@</term><listitem><para>Angry smiley</para></listitem></varlistentry> + <varlistentry><term>(A)</term><listitem><para>Angel smiley</para></listitem></varlistentry> + <varlistentry><term>(L)</term><listitem><para>Red heart (Love)</para></listitem></varlistentry> + <varlistentry><term>(U)</term><listitem><para>Broken heart</para></listitem></varlistentry> + <varlistentry><term>(K)</term><listitem><para>Red lips (Kiss)</para></listitem></varlistentry> + <varlistentry><term>(G)</term><listitem><para>Gift with bow</para></listitem></varlistentry> + <varlistentry><term>(F)</term><listitem><para>Red rose</para></listitem></varlistentry> + <varlistentry><term>(W)</term><listitem><para>Wilted rose</para></listitem></varlistentry> + <varlistentry><term>(P)</term><listitem><para>Camera</para></listitem></varlistentry> + <varlistentry><term>(~)</term><listitem><para>Film strip</para></listitem></varlistentry> + <varlistentry><term>(T)</term><listitem><para>Telephone receiver</para></listitem></varlistentry> + <varlistentry><term>(@)</term><listitem><para>Cat face</para></listitem></varlistentry> + <varlistentry><term>(&)</term><listitem><para>Dog's head</para></listitem></varlistentry> + <varlistentry><term>(C)</term><listitem><para>Coffee cup</para></listitem></varlistentry> + <varlistentry><term>(I)</term><listitem><para>Light bulb</para></listitem></varlistentry> + <varlistentry><term>(S)</term><listitem><para>Half-moon (Case sensitive!)</para></listitem></varlistentry> + <varlistentry><term>(*)</term><listitem><para>Star</para></listitem></varlistentry> + <varlistentry><term>(8)</term><listitem><para>Musical eighth note</para></listitem></varlistentry> + <varlistentry><term>(E)</term><listitem><para>Envelope</para></listitem></varlistentry> + <varlistentry><term>(^)</term><listitem><para>Birthday cake</para></listitem></varlistentry> + <varlistentry><term>(O)</term><listitem><para>Clock</para></listitem></varlistentry> +</variablelist> + +<para> +This list was extracted from <ulink url="http://help.msn.com/!data/en_us/data/messengerv50.its51/$content$/EMOTICONS.HTM?H_APP=">http://help.msn.com/!data/en_us/data/messengerv50.its51/$content$/EMOTICONS.HTM?H_APP=</ulink>. +</para> + +</sect1> + +<sect1 id="groupchats"> +<title>Groupchats</title> +<para> +Since version 0.8x, BitlBee supports groupchats on the MSN and Yahoo! networks. This text will try to explain you how they work. +</para> + +<para> +As soon as someone invites you into a groupchat, you will be force-joined or invited (depending on the protocol) into a new virtual channel with all the people in there. You can leave the channel at any time, just like you would close the window in regular IM clients. Please note that root-commands don't work in groupchat channels, they only work in the control channel (or to root directly). +</para> + +<para> +Of course you can also create your own groupchats. Type <emphasis>help groupchats2</emphasis> to see how. +</para> + +</sect1> + +<sect1 id="groupchats2"> +<title>Creating groupchats</title> + +<para> +If you want to start a groupchat with the person <emphasis>jim_msn</emphasis> in it, just join the channel <emphasis>#jim_msn</emphasis>. BitlBee will refuse to join you to the channel with that name, but it will create a new virtual channel with root, you and jim_msn in it. +</para> + +<para> +Of course a channel with only two people isn't really exciting yet. So the next step is to invite some other people to the channel. For this, you can use the <emphasis>/invite</emphasis> command of your IRC client. Please do keep in mind that all the people have to be on the same network and contact list! You can't invite Yahoo! buddies into an MSN groupchat. +</para> + +<para> +This is all you'll probably need to know. If you have any problems, please read <emphasis>help groupchats3</emphasis>. +</para> + +</sect1> + +<sect1 id="groupchats3"> +<title>Groupchat channel names</title> + +<para> +Obviously the (numbered) channel names don't make a lot of sense. Problem is that groupchats usually don't have names at all in the IM-world, while IRC insists on a name. So BitlBee just generates something random, just don't pay attention to it. :-) +</para> + +<para> +Please also note that BitlBee doesn't support groupchats for all protocols yet. BitlBee will tell you so. Support for other protocols will hopefully come later. +</para> + +</sect1> + +<sect1 id="away"> +<title>Away states</title> + +<para> +As you might've expected, you can just use the <emphasis>/away</emphasis> command in your IRC client to set an away-state. BitlBee supports most away-states supported by the protocols. +</para> + +<para> +Not all away states are supported by all protocols, and some protocols have different names for them. BitlBee will try to pick the best available alias from this list for every connection: +</para> + +<simplelist> + <member>Away from computer, Away, Extended away</member> + <member>NA, N/A, Not available</member> + <member>Busy, Do not disturb, DND, Occupied</member> + <member>Be right back, BRB</member> + <member>On the phone, Phone, On phone</member> + <member>Out to lunch, Lunch, Food</member> +</simplelist> + +<para> +So <emphasis>/away Food</emphasis> will set your state to "Out to lunch" on your MSN connection, and for most other connections the default, "Away" or "Away from computer" will be chosen. +</para> + +<para> +You can also add more information to your away message. Setting it to "Busy - Fixing BitlBee bugs" will set your IM-away-states to Busy, but your away message will be more descriptive for people on IRC. Protocols like Yahoo! and Jabber will also show this complete away message to your buddies. +</para> + +</sect1> + +</chapter> diff --git a/doc/user-guide/quickstart.xml b/doc/user-guide/quickstart.xml new file mode 100644 index 00000000..9a8b8770 --- /dev/null +++ b/doc/user-guide/quickstart.xml @@ -0,0 +1,163 @@ +<chapter id="quickstart"> +<title>Quickstart</title> + +<para> +Welcome to BitlBee, your IRC gateway to ICQ, MSN, AOL, Jabber and Yahoo Instant Messaging Systems. +</para> + +<para> +The center of BitlBee is the control channel, <emphasis>#bitlbee</emphasis>. Two users will always be there, <emphasis>you</emphasis> (where "you" is the nickname you are using) and the system user, <emphasis>root</emphasis>. +</para> + +<para> +You need register so that all your IM settings (passwords, contacts, etc) can be saved on the BitlBee server. It's important that you pick a good password so no one else can access your account. Register with this password using the <emphasis>register</emphasis> command: <emphasis>register <password></emphasis> (without the brackets!). +</para> + +<para> +Be sure to remember your password. The next time you connect to the BitlBee server you will need to <emphasis>identify <password></emphasis> so that you will be recognised and logged in to all the IM services automatically. +</para> + +<para> +When finished, type <emphasis>help quickstart2</emphasis> to continue. +</para> + +<sect1 id="quickstart2"> +<title>Add and Connect To your IM Account(s)</title> +<!-- quickstart2 --> +<para> +<emphasis>Step Two: Add and Connect To your IM Account(s).</emphasis> +</para> + +<para> +To add an account to the account list you will need to use the <emphasis>account add</emphasis> command: <emphasis>account add <protocol> <username> <password> [<server>]</emphasis>. +</para> + +<para> +For instance, suppose you have an ICQ account with UIN <emphasis>72696705</emphasis> with password <emphasis>QuickStart</emphasis>, you would: +</para> + +<ircexample> + <ircline nick="you">account add oscar 72696705 QuickStart login.icq.com</ircline> + <ircline nick="root">Account successfully added</ircline> +</ircexample> + +<para> +Other available IM protocols are jabber, msn, and yahoo. Oscar is the protocol used by ICQ and AOL. For oscar, you need to specify the IM-server as a fourth argument (for msn and yahoo there is no fourth argument). For AOL Instant Messenger, the server name is <emphasis>login.oscar.aol.com</emphasis>. For ICQ, the server name is <emphasis>login.icq.com</emphasis>. +</para> + +<para> +When you are finished adding your account(s) use the <emphasis>account on</emphasis> command to enable all your accounts, type <emphasis>help quickstart3</emphasis> to continue. +</para> + +</sect1> + +<sect1 id="quickstart3"> +<title>Managing Contact Lists: Rename</title> + +<!--quickstart3--> +<para> +<emphasis>Step Three: Managing Contact Lists: Rename</emphasis> +</para> + +<para> +For most protocols (currently MSN, Jabber, Yahoo and AOL) BitlBee can download the contact list automatically from the IM server and all the on-line users should appear in the control channel when you log in. +</para> + +<para> +BitlBee will convert names into irc-friendly form (for instance: tux@example.com will be given the nickname tux). If you have more than one person who would have the same name by this logic (for instance: tux@example.com and tux@bitlbee.org) the second one to log on will be tux_. The same is true if you have a tux log on to AOL and a tux log on from Yahoo. +</para> + +<para> +It would be easy to get these two mixed up, so BitlBee has a <emphasis>rename</emphasis> command to change the nickname into something more suitable: <emphasis>rename <oldnick> <newnick></emphasis> +</para> + +<ircexample> + <ircline nick="you">rename tux_ bitlbeetux</ircline> + <ircaction nick="tux_">is now known as <emphasis>bitlbeetux</emphasis></ircaction> + <ircline nick="root">Nick successfully changed</ircline> +</ircexample> + +<para> +When finished, type <emphasis>help quickstart4</emphasis> to continue. +</para> + +</sect1> + +<sect1 id="quickstart4"> +<title>Step Four: Managing Contact Lists: Add and Remove.</title> + +<para> +<emphasis>Step Four: Managing Contact Lists: Add and Remove.</emphasis> +</para> + +<para> +Now you might want to add some contacts, to do this we will use the <emphasis>add</emphasis> command. It needs two arguments: a connection ID (which can be a number (try <emphasis>account list</emphasis>), protocol name or (part of) the screenname) and the user's handle. It is used in the following way: <emphasis>add <connection> <handle></emphasis> +</para> + +<ircexample> + <ircline nick="you">add 0 r2d2@example.com</ircline> + <ircaction nick="r2d2"> has joined <emphasis>#bitlbee</emphasis></ircaction> +</ircexample> + +<para> +In this case r2d2 is online, since he/she joins the channel immediately. If the user is not online you will not see them join until they log on. +</para> + +<para> +Lets say you accidentally added r2d3@example.com rather than r2d2@example.com, or maybe you just want to remove a user from your list because you never talk to them. To remove a name you will want to use the <emphasis>remove</emphasis> command: <emphasis>remove <nick></emphasis> +</para> + +<para> +When finished, type <emphasis>help quickstart5</emphasis> to continue. +</para> + +</sect1> + +<sect1 id="quickstart5"> +<title>Chatting</title> + +<para> +<emphasis>Step Five: Chatting.</emphasis> +</para> + +<para> +First of all, a person must be on your contact list for you to chat with them (unless it's a group chat, <emphasis>help groupchats</emphasis> for more). If someone not on your contact list sends you a message, simply add them to the proper account with the <emphasis>add</emphasis> command. Once they are on your list and online, you can chat with them in #bitlbee: +</para> + +<ircexample> + <ircline nick="you">tux: hey, how's the weather down there?</ircline> + <ircline nick="tux"> you: a bit chilly!</ircline> +</ircexample> + +<para> +If you'd rather chat with them in a separate window use the <emphasis>/msg</emphasis> or <emphasis>/query</emphasis> command, just like you would for a private message in IRC. If you want to have messages automatically come up in private messages rather than in the #bitlbee channel, use the <emphasis>set private</emphasis> command: <emphasis>set private true</emphasis> (<emphasis>set private false</emphasis> to change back). +</para> + +<para> +You know the basics. If you want to get to know more about BitlBee, please type <emphasis>help quickstart6</emphasis>. +</para> + +</sect1> + +<sect1 id="quickstart6"> +<title>Further Resources</title> + +<para> +<emphasis>So you want more than just chatting? Or maybe you're just looking for a feature?</emphasis> +</para> + +<para> +You can type <emphasis>help set</emphasis> to learn more about the possible BitlBee user settings. Among these user settings you will find options for common issues, such as changing the charset, HTML stripping and automatic connecting (simply type <emphasis>set</emphasis> to see current user settings). +</para> + +<para> +For more subjects (like groupchats and away states), please type <emphasis>help index</emphasis>. +</para> + +<para> +If you're still looking for something, please visit us in #bitlbee on the OFTC network (you can connect via irc.bitlbee.org), or mail us your problem/suggestion. Good luck and enjoy the Bee! +</para> + +</sect1> + +</chapter> diff --git a/doc/user-guide/user-guide.html b/doc/user-guide/user-guide.html new file mode 100644 index 00000000..5d1fb46a --- /dev/null +++ b/doc/user-guide/user-guide.html @@ -0,0 +1,446 @@ +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>BitlBee User Guide</title><meta name="generator" content="DocBook XSL Stylesheets V1.68.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="BitlBee-User-Guide"></a>BitlBee User Guide</h1></div><div><div class="author"><h3 class="author"><span class="firstname">Jelmer</span> <span class="surname">Vernooij</span></h3></div></div><div><div class="author"><h3 class="author"><span class="firstname">Wilmer</span> <span class="surname">van der Gaast</span></h3></div></div><div><div class="author"><h3 class="author"><span class="firstname">Sjoerd</span> <span class="surname">Hemminga</span></h3></div></div><div><p class="releaseinfo"> + This is the initial release of the BitlBee User Guide. + </p></div><div><div class="legalnotice"><a name="legalnotice"></a><p> + Permission is granted to copy, distribute and/or modify this + document under the terms of the <a href="gnome-help:fdl" target="_top"><em class="citetitle">GNU Free Documentation + License</em></a>, Version 1.1 or any later version + published by the Free Software Foundation with no Invariant + Sections, no Front-Cover Texts, and no Back-Cover Texts. You + may obtain a copy of the <em class="citetitle">GNU Free Documentation + License</em> from the Free Software Foundation by + visiting <a href="http://www.fsf.org" target="_top">their + Web site</a> or by writing to: Free Software Foundation, + Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, + USA. + </p></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="#Installation">1. Installation</a></span></dt><dd><dl><dt><span class="sect1"><a href="#id4683446">Downloading the package</a></span></dt><dt><span class="sect1"><a href="#id4683474">Compiling</a></span></dt><dt><span class="sect1"><a href="#id4683726">Configuration</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Usage">2. Usage</a></span></dt><dd><dl><dt><span class="sect1"><a href="#id4683835">Connecting to the server</a></span></dt><dt><span class="sect1"><a href="#id4683848">The #bitlbee control channel</a></span></dt><dt><span class="sect1"><a href="#id4683867">Talking to people</a></span></dt></dl></dd><dt><span class="chapter"><a href="#Support">3. Support</a></span></dt><dd><dl><dt><span class="sect1"><a href="#id4683912">BitlBee is beta software</a></span></dt><dt><span class="sect1"><a href="#id4683926">Support channels</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id4683931">The World Wide Web</a></span></dt><dt><span class="sect2"><a href="#id4683948">IRC</a></span></dt><dt><span class="sect2"><a href="#id4683960">Mailinglists</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#quickstart">4. Quickstart</a></span></dt><dd><dl><dt><span class="sect1"><a href="#quickstart2">Add and Connect To your IM Account(s)</a></span></dt><dt><span class="sect1"><a href="#quickstart3">Managing Contact Lists: Rename</a></span></dt><dt><span class="sect1"><a href="#quickstart4">Step Four: Managing Contact Lists: Add and Remove.</a></span></dt><dt><span class="sect1"><a href="#quickstart5">Chatting</a></span></dt><dt><span class="sect1"><a href="#quickstart6">Further Resources</a></span></dt></dl></dd><dt><span class="chapter"><a href="#commands">5. Bitlbee commands</a></span></dt><dd><dl><dt><span class="sect1"><a href="#cmd_account">account - IM-account list maintenance</a></span></dt><dd><dl><dt><span class="sect2"><a href="#cmd_account_add">account add</a></span></dt><dt><span class="sect2"><a href="#cmd_account_del">account del</a></span></dt><dt><span class="sect2"><a href="#cmd_account_on">account on</a></span></dt><dt><span class="sect2"><a href="#cmd_account_off">account off</a></span></dt><dt><span class="sect2"><a href="#cmd_account_list">account list</a></span></dt></dl></dd><dt><span class="sect1"><a href="#cmd_add">add - Add a buddy to your contact list</a></span></dt><dt><span class="sect1"><a href="#cmd_info">info - Request user information</a></span></dt><dt><span class="sect1"><a href="#cmd_remove">remove - Remove a buddy from your contact list</a></span></dt><dt><span class="sect1"><a href="#cmd_block">block - Block someone</a></span></dt><dt><span class="sect1"><a href="#cmd_allow">allow - Unblock someone</a></span></dt><dt><span class="sect1"><a href="#cmd_set">set - Miscellaneous settings</a></span></dt><dt><span class="sect1"><a href="#cmd_help">help - BitlBee help system</a></span></dt><dt><span class="sect1"><a href="#cmd_save">save - Save your account data</a></span></dt><dt><span class="sect1"><a href="#set_charset">charset</a></span></dt><dt><span class="sect1"><a href="#set_private">private</a></span></dt><dt><span class="sect1"><a href="#set_save_on_quit">save_on_quit</a></span></dt><dt><span class="sect1"><a href="#set_html">html</a></span></dt><dt><span class="sect1"><a href="#set_debug">debug</a></span></dt><dt><span class="sect1"><a href="#set_to_char">to_char</a></span></dt><dt><span class="sect1"><a href="#set_typing_notice">typing_notice</a></span></dt><dt><span class="sect1"><a href="#set_ops">ops</a></span></dt><dt><span class="sect1"><a href="#set_away_devoice">away_devoice</a></span></dt><dt><span class="sect1"><a href="#set_handle_unknown">handle_unknown</a></span></dt><dt><span class="sect1"><a href="#set_auto_connect">auto_connect</a></span></dt><dt><span class="sect1"><a href="#set_auto_reconnect">auto_reconnect</a></span></dt><dt><span class="sect1"><a href="#set_auto_reconnect_delay">auto_reconnect_delay</a></span></dt><dt><span class="sect1"><a href="#set_buddy_sendbuffer">buddy_sendbuffer</a></span></dt><dt><span class="sect1"><a href="#set_buddy_sendbuffer_delay">buddy_sendbuffer_delay</a></span></dt><dt><span class="sect1"><a href="#set_default_target">default_target</a></span></dt><dt><span class="sect1"><a href="#set_display_namechanges">display_namechanges</a></span></dt><dt><span class="sect1"><a href="#set_password">password</a></span></dt><dt><span class="sect1"><a href="#set_query_order">query_order</a></span></dt><dt><span class="sect1"><a href="#set_lcnicks">lcnicks</a></span></dt><dt><span class="sect1"><a href="#cmd_rename">rename - Rename (renick) a buddy</a></span></dt><dt><span class="sect1"><a href="#cmd_yes">yes - Accept a request</a></span></dt><dt><span class="sect1"><a href="#cmd_no">no - Deny a request</a></span></dt><dt><span class="sect1"><a href="#cmd_qlist">qlist - List all the unanswered questions root asked</a></span></dt><dt><span class="sect1"><a href="#cmd_register">register - Register yourself</a></span></dt><dt><span class="sect1"><a href="#cmd_identify">identify - Identify yourself with your password</a></span></dt><dt><span class="sect1"><a href="#cmd_drop">drop - Drop your account</a></span></dt><dt><span class="sect1"><a href="#cmd_blist">blist - List all the buddies in your contact list</a></span></dt><dt><span class="sect1"><a href="#cmd_nick">nick - Change friendly name, nick</a></span></dt><dt><span class="sect1"><a href="#cmd_import_buddies">import_buddies - Copy local buddy list to server (normally only needed when upgrading)</a></span></dt></dl></dd><dt><span class="chapter"><a href="#misc">6. Misc Stuff</a></span></dt><dd><dl><dt><span class="sect1"><a href="#smileys">Smileys</a></span></dt><dt><span class="sect1"><a href="#groupchats">Groupchats</a></span></dt><dt><span class="sect1"><a href="#groupchats2">Creating groupchats</a></span></dt><dt><span class="sect1"><a href="#groupchats3">Groupchat channel names</a></span></dt><dt><span class="sect1"><a href="#away">Away states</a></span></dt></dl></dd></dl></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="Installation"></a>Chapter 1. Installation</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#id4683446">Downloading the package</a></span></dt><dt><span class="sect1"><a href="#id4683474">Compiling</a></span></dt><dt><span class="sect1"><a href="#id4683726">Configuration</a></span></dt></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id4683446"></a>Downloading the package</h2></div></div></div><p> +The latest BitlBee release is always available from <a href="http://www.bitlbee.org/" target="_top">http://www.bitlbee.org/</a>. +Download the package with your favorite program and unpack it: <span><strong class="command">tar +xvfz bitlbee-<version>.tar.gz</strong></span> where <version> is to be +replaced by the version number of the BitlBee you downloaded (e.g. 0.91). +</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id4683474"></a>Compiling</h2></div></div></div><p> +BitlBee's build system has to be configured before compiling. The +<code class="filename">configure</code> script will do this for you. Just run +it, it'll set up with nice and hopefully well-working defaults. If you +want to change some settings, just try +<span><strong class="command">./configure --help</strong></span> and see what you can do. +</p><p>Some variables that might be of interest to the normal user:</p><div class="itemizedlist"><ul type="disc"><li><p>prefix, bindir, etcdir, mandir, datadir - The place where +all the BitlBee program files will be put. There's usually no reason to +specify them all separately, just specifying prefix (or keeping the default +<code class="filename">/usr/local/</code>) should be okay.</p></li><li><p>config - The place where BitlBee will save all the per-user +settings and buddy information. <code class="filename">/var/lib/bitlbee/</code> +is the default value.</p></li><li><p>msn, jabber, oscar, yahoo - By default, support for all +these IM-protocols (OSCAR is the protocol used by both ICQ and AIM) will +be compiled in. To make the binary a bit smaller, you can use these options +to leave out support for protocols you're not planning to use.</p></li><li><p>debug - Generate an unoptimized binary with debugging symbols, +mainly useful if you want to do some debugging or help us to track down a +problem.</p></li><li><p>strip - By default, unnecessary parts of the generated binary +will be stripped out to make it as small as possible. If you don't want this +(because it might cause problems on some platforms), set this to 0. +</p></li><li><p>flood - To secure your BitlBee server against flooding attacks, +you can use this option. It's not compiled in by default because it needs +more testing first.</p></li><li><p>ssl - The MSN and Jabber modules require an SSL library for +some of their tasks. BitlBee can use three different SSL libraries: GnuTLS, +mozilla-nss and OpenSSL. (OpenSSL is, however, a bit troublesome because of +licensing issues, so don't forget to read the information configure will +give you when you try to use OpenSSL!) By default, configure will try to +detect GnuTLS or mozilla-nss. If none of them can be found, it'll give up. +If you want BitlBee to use OpenSSL, you have to explicitly specify that. +</p></li></ul></div><p> +After running <code class="filename">configure</code>, you should run +<span><strong class="command">make</strong></span>. After that, run <span><strong class="command">make install</strong></span> as +root. +</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id4683726"></a>Configuration</h2></div></div></div><p> +By default, BitlBee runs as the user nobody. You might want +to run it as a seperate user (some computers run named or apache as nobody). +</p><p> +Since BitlBee uses inetd, you should add the following line to <code class="filename">/etc/inetd.conf</code>: +</p><p> + </p><pre class="programlisting"> +6667 stream tcp nowait nobody /usr/local/sbin/bitlbee bitlbee +</pre><p> + </p><p> +Inetd has to be restarted after changing the configuration. Either +<span><strong class="command">killall -HUP inetd</strong></span> or +<span><strong class="command">/etc/init.d/inetd restart</strong></span> should do the job on most systems. +</p><p> +You might be one of the.. ehr, lucky people running an xinetd-powered distro. +<span><strong class="command">xinetd</strong></span> is quite different and they seem to be proud of that.. ;-) +Anyway, if you want BitlBee to work with <span><strong class="command">xinetd</strong></span>, just copy the +bitlbee.xinetd file to your /etc/xinetd.d/ directory (and probably edit it to suit +your needs). +</p><p> +You should create a directory where BitlBee can store it's data files. This +should be the directory named after the value 'CONFIG' in Makefile.settings. +The default is <code class="filename">/var/lib/bitlbee</code>, which can be created +with the command <span><strong class="command">mkdir -p /var/lib/bitlbee</strong></span>. This +directory has to be owned by the user that runs bitlbee. To make +'nobody' owner of this directory, run <span><strong class="command">chown nobody /var/lib/bitlbee</strong></span>. +Because things like passwords are saved in this directory, it's probably +a good idea to make this directory owner-read-/writable only. +</p></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="Usage"></a>Chapter 2. Usage</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#id4683835">Connecting to the server</a></span></dt><dt><span class="sect1"><a href="#id4683848">The #bitlbee control channel</a></span></dt><dt><span class="sect1"><a href="#id4683867">Talking to people</a></span></dt></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id4683835"></a>Connecting to the server</h2></div></div></div><p> +Since BitlBee acts just like any other irc daemon, you can connect to +it with your favorite irc client. Launch it and connect to localhost port 6667 +(or whatever host/port you are running bitlbee on). +</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id4683848"></a>The #bitlbee control channel</h2></div></div></div><p> +Once you are connected to the BitlBee server, you are automatically joined +to #bitlbee on that server. This channel acts like the 'buddy list' you have +on the various other chat networks. +</p><p> +The user 'root' always hangs around in #bitlbee and acts as your interface +to bitlbee. All commands you give on #bitlbee are 'answered' by root. +</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id4683867"></a>Talking to people</h2></div></div></div><p> +You can talk to by starting a query with them. In most irc clients, +this can be done with either <span><strong class="command">/msg <nick> <text></strong></span> +or <span><strong class="command">/query <nick></strong></span>. +</p><p> +To keep the number of open query windows limited, you can also talk to people +in the control channel, like <span><strong class="command"><nick>: <text></strong></span>. +</p></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="Support"></a>Chapter 3. Support</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#id4683912">BitlBee is beta software</a></span></dt><dt><span class="sect1"><a href="#id4683926">Support channels</a></span></dt><dd><dl><dt><span class="sect2"><a href="#id4683931">The World Wide Web</a></span></dt><dt><span class="sect2"><a href="#id4683948">IRC</a></span></dt><dt><span class="sect2"><a href="#id4683960">Mailinglists</a></span></dt></dl></dd></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id4683912"></a>BitlBee is beta software</h2></div></div></div><p> +Although BitlBee has quite some functionality it is still beta. That means it +can crash at any time, corrupt your data or whatever. Don't use it in +any production environment and don't rely on it. +</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id4683926"></a>Support channels</h2></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id4683931"></a>The World Wide Web</h3></div></div></div><p><a href="http://www.bitlbee.org/" target="_top">http://www.bitlbee.org/</a> +is the homepage of bitlbee and contains the most recent news on bitlbee and +the latest releases. +</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id4683948"></a>IRC</h3></div></div></div><p> +BitlBee is discussed on #bitlbee on the OFTC IRC network (server: irc.oftc.net). +</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id4683960"></a>Mailinglists</h3></div></div></div><p> +BitlBee doesn't have any mailinglists. +</p></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="quickstart"></a>Chapter 4. Quickstart</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#quickstart2">Add and Connect To your IM Account(s)</a></span></dt><dt><span class="sect1"><a href="#quickstart3">Managing Contact Lists: Rename</a></span></dt><dt><span class="sect1"><a href="#quickstart4">Step Four: Managing Contact Lists: Add and Remove.</a></span></dt><dt><span class="sect1"><a href="#quickstart5">Chatting</a></span></dt><dt><span class="sect1"><a href="#quickstart6">Further Resources</a></span></dt></dl></div><p> +Welcome to BitlBee, your IRC gateway to ICQ, MSN, AOL, Jabber and Yahoo Instant Messaging Systems. +</p><p> +The center of BitlBee is the control channel, <span class="emphasis"><em>#bitlbee</em></span>. Two users will always be there, <span class="emphasis"><em>you</em></span> (where "you" is the nickname you are using) and the system user, <span class="emphasis"><em>root</em></span>. +</p><p> +You need register so that all your IM settings (passwords, contacts, etc) can be saved on the BitlBee server. It's important that you pick a good password so no one else can access your account. Register with this password using the <span class="emphasis"><em>register</em></span> command: <span class="emphasis"><em>register <password></em></span> (without the brackets!). +</p><p> +Be sure to remember your password. The next time you connect to the BitlBee server you will need to <span class="emphasis"><em>identify <password></em></span> so that you will be recognised and logged in to all the IM services automatically. +</p><p> +When finished, type <span class="emphasis"><em>help quickstart2</em></span> to continue. +</p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="quickstart2"></a>Add and Connect To your IM Account(s)</h2></div></div></div><p> + <span class="emphasis"><em>Step Two: Add and Connect To your IM Account(s).</em></span> + </p><p> +To add an account to the account list you will need to use the <span class="emphasis"><em>account add</em></span> command: <span class="emphasis"><em>account add <protocol> <username> <password> [<server>]</em></span>. +</p><p> +For instance, suppose you have an ICQ account with UIN <span class="emphasis"><em>72696705</em></span> with password <span class="emphasis"><em>QuickStart</em></span>, you would: +</p><pre class="screen"><code class="prompt">< you> </code><strong class="userinput"><code>account add oscar 72696705 QuickStart login.icq.com</code></strong> +<code class="prompt">< root> </code><strong class="userinput"><code>Account successfully added</code></strong> +</pre><p> +Other available IM protocols are jabber, msn, and yahoo. Oscar is the protocol used by ICQ and AOL. For oscar, you need to specify the IM-server as a fourth argument (for msn and yahoo there is no fourth argument). For AOL Instant Messenger, the server name is <span class="emphasis"><em>login.oscar.aol.com</em></span>. For ICQ, the server name is <span class="emphasis"><em>login.icq.com</em></span>. +</p><p> +When you are finished adding your account(s) use the <span class="emphasis"><em>account on</em></span> command to enable all your accounts, type <span class="emphasis"><em>help quickstart3</em></span> to continue. +</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="quickstart3"></a>Managing Contact Lists: Rename</h2></div></div></div><p> + <span class="emphasis"><em>Step Three: Managing Contact Lists: Rename</em></span> + </p><p> +For most protocols (currently MSN, Jabber, Yahoo and AOL) BitlBee can download the contact list automatically from the IM server and all the on-line users should appear in the control channel when you log in. +</p><p> +BitlBee will convert names into irc-friendly form (for instance: tux@example.com will be given the nickname tux). If you have more than one person who would have the same name by this logic (for instance: tux@example.com and tux@bitlbee.org) the second one to log on will be tux_. The same is true if you have a tux log on to AOL and a tux log on from Yahoo. +</p><p> +It would be easy to get these two mixed up, so BitlBee has a <span class="emphasis"><em>rename</em></span> command to change the nickname into something more suitable: <span class="emphasis"><em>rename <oldnick> <newnick></em></span></p><pre class="screen"><code class="prompt">< you> </code><strong class="userinput"><code>rename tux_ bitlbeetux</code></strong> + * tux_is now known as bitlbeetux +<code class="prompt">< root> </code><strong class="userinput"><code>Nick successfully changed</code></strong> +</pre><p> +When finished, type <span class="emphasis"><em>help quickstart4</em></span> to continue. +</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="quickstart4"></a>Step Four: Managing Contact Lists: Add and Remove.</h2></div></div></div><p> + <span class="emphasis"><em>Step Four: Managing Contact Lists: Add and Remove.</em></span> + </p><p> +Now you might want to add some contacts, to do this we will use the <span class="emphasis"><em>add</em></span> command. It needs two arguments: a connection ID (which can be a number (try <span class="emphasis"><em>account list</em></span>), protocol name or (part of) the screenname) and the user's handle. It is used in the following way: <span class="emphasis"><em>add <connection> <handle></em></span></p><pre class="screen"><code class="prompt">< you> </code><strong class="userinput"><code>add 0 r2d2@example.com</code></strong> + * r2d2has joined #bitlbee +</pre><p> +In this case r2d2 is online, since he/she joins the channel immediately. If the user is not online you will not see them join until they log on. +</p><p> +Lets say you accidentally added r2d3@example.com rather than r2d2@example.com, or maybe you just want to remove a user from your list because you never talk to them. To remove a name you will want to use the <span class="emphasis"><em>remove</em></span> command: <span class="emphasis"><em>remove <nick></em></span></p><p> +When finished, type <span class="emphasis"><em>help quickstart5</em></span> to continue. +</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="quickstart5"></a>Chatting</h2></div></div></div><p> + <span class="emphasis"><em>Step Five: Chatting.</em></span> + </p><p> +First of all, a person must be on your contact list for you to chat with them (unless it's a group chat, <span class="emphasis"><em>help groupchats</em></span> for more). If someone not on your contact list sends you a message, simply add them to the proper account with the <span class="emphasis"><em>add</em></span> command. Once they are on your list and online, you can chat with them in #bitlbee: +</p><pre class="screen"><code class="prompt">< you> </code><strong class="userinput"><code>tux: hey, how's the weather down there?</code></strong> +<code class="prompt">< tux> </code><strong class="userinput"><code>you: a bit chilly!</code></strong> +</pre><p> +If you'd rather chat with them in a separate window use the <span class="emphasis"><em>/msg</em></span> or <span class="emphasis"><em>/query</em></span> command, just like you would for a private message in IRC. If you want to have messages automatically come up in private messages rather than in the #bitlbee channel, use the <span class="emphasis"><em>set private</em></span> command: <span class="emphasis"><em>set private true</em></span> (<span class="emphasis"><em>set private false</em></span> to change back). +</p><p> +You know the basics. If you want to get to know more about BitlBee, please type <span class="emphasis"><em>help quickstart6</em></span>. +</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="quickstart6"></a>Further Resources</h2></div></div></div><p> + <span class="emphasis"><em>So you want more than just chatting? Or maybe you're just looking for a feature?</em></span> + </p><p> +You can type <span class="emphasis"><em>help set</em></span> to learn more about the possible BitlBee user settings. Among these user settings you will find options for common issues, such as changing the charset, HTML stripping and automatic connecting (simply type <span class="emphasis"><em>set</em></span> to see current user settings). +</p><p> +For more subjects (like groupchats and away states), please type <span class="emphasis"><em>help index</em></span>. +</p><p> +If you're still looking for something, please visit us in #bitlbee on the OFTC network (you can connect via irc.bitlbee.org), or mail us your problem/suggestion. Good luck and enjoy the Bee! +</p></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="commands"></a>Chapter 5. Bitlbee commands</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#cmd_account">account - IM-account list maintenance</a></span></dt><dd><dl><dt><span class="sect2"><a href="#cmd_account_add">account add</a></span></dt><dt><span class="sect2"><a href="#cmd_account_del">account del</a></span></dt><dt><span class="sect2"><a href="#cmd_account_on">account on</a></span></dt><dt><span class="sect2"><a href="#cmd_account_off">account off</a></span></dt><dt><span class="sect2"><a href="#cmd_account_list">account list</a></span></dt></dl></dd><dt><span class="sect1"><a href="#cmd_add">add - Add a buddy to your contact list</a></span></dt><dt><span class="sect1"><a href="#cmd_info">info - Request user information</a></span></dt><dt><span class="sect1"><a href="#cmd_remove">remove - Remove a buddy from your contact list</a></span></dt><dt><span class="sect1"><a href="#cmd_block">block - Block someone</a></span></dt><dt><span class="sect1"><a href="#cmd_allow">allow - Unblock someone</a></span></dt><dt><span class="sect1"><a href="#cmd_set">set - Miscellaneous settings</a></span></dt><dt><span class="sect1"><a href="#cmd_help">help - BitlBee help system</a></span></dt><dt><span class="sect1"><a href="#cmd_save">save - Save your account data</a></span></dt><dt><span class="sect1"><a href="#set_charset">charset</a></span></dt><dt><span class="sect1"><a href="#set_private">private</a></span></dt><dt><span class="sect1"><a href="#set_save_on_quit">save_on_quit</a></span></dt><dt><span class="sect1"><a href="#set_html">html</a></span></dt><dt><span class="sect1"><a href="#set_debug">debug</a></span></dt><dt><span class="sect1"><a href="#set_to_char">to_char</a></span></dt><dt><span class="sect1"><a href="#set_typing_notice">typing_notice</a></span></dt><dt><span class="sect1"><a href="#set_ops">ops</a></span></dt><dt><span class="sect1"><a href="#set_away_devoice">away_devoice</a></span></dt><dt><span class="sect1"><a href="#set_handle_unknown">handle_unknown</a></span></dt><dt><span class="sect1"><a href="#set_auto_connect">auto_connect</a></span></dt><dt><span class="sect1"><a href="#set_auto_reconnect">auto_reconnect</a></span></dt><dt><span class="sect1"><a href="#set_auto_reconnect_delay">auto_reconnect_delay</a></span></dt><dt><span class="sect1"><a href="#set_buddy_sendbuffer">buddy_sendbuffer</a></span></dt><dt><span class="sect1"><a href="#set_buddy_sendbuffer_delay">buddy_sendbuffer_delay</a></span></dt><dt><span class="sect1"><a href="#set_default_target">default_target</a></span></dt><dt><span class="sect1"><a href="#set_display_namechanges">display_namechanges</a></span></dt><dt><span class="sect1"><a href="#set_password">password</a></span></dt><dt><span class="sect1"><a href="#set_query_order">query_order</a></span></dt><dt><span class="sect1"><a href="#set_lcnicks">lcnicks</a></span></dt><dt><span class="sect1"><a href="#cmd_rename">rename - Rename (renick) a buddy</a></span></dt><dt><span class="sect1"><a href="#cmd_yes">yes - Accept a request</a></span></dt><dt><span class="sect1"><a href="#cmd_no">no - Deny a request</a></span></dt><dt><span class="sect1"><a href="#cmd_qlist">qlist - List all the unanswered questions root asked</a></span></dt><dt><span class="sect1"><a href="#cmd_register">register - Register yourself</a></span></dt><dt><span class="sect1"><a href="#cmd_identify">identify - Identify yourself with your password</a></span></dt><dt><span class="sect1"><a href="#cmd_drop">drop - Drop your account</a></span></dt><dt><span class="sect1"><a href="#cmd_blist">blist - List all the buddies in your contact list</a></span></dt><dt><span class="sect1"><a href="#cmd_nick">nick - Change friendly name, nick</a></span></dt><dt><span class="sect1"><a href="#cmd_import_buddies">import_buddies - Copy local buddy list to server (normally only needed when upgrading)</a></span></dt></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cmd_account"></a>account - IM-account list maintenance</h2></div></div></div><p><b>Syntax: </b> + </p><pre class="programlisting">account <action> [<arguments>] +</pre><p> + </p><p> + Available actions: add, del, list, on, off. See <span class="emphasis"><em>help account <action></em></span> for more information. + </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="cmd_account_add"></a>account add</h3></div></div></div><p><b>Syntax: </b> + </p><pre class="programlisting">account add <protocol> <username> <password> [<server>] +</pre><p> + </p><p> + Adds an account on the given server with the specified protocol, username and password to the account list. Supported protocols right now are: Jabber, MSN, OSCAR (AIM/ICQ) and Yahoo. For more information about adding an account, see <span class="emphasis"><em>help account add <protocol></em></span>. + </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="cmd_account_add_jabber"></a>account add jabber</h3></div></div></div><p><b>Syntax: </b> + </p><pre class="programlisting">account add jabber <handle> <password> [<servertag>] +</pre><p> + </p><p> + Note that the servertag argument is optional. You only have to use it if the part after the @ in your handle isn't the hostname of your Jabber server, or if you want to use SSL/connect to a non-standard port number. The format is simple: [<servername>[:<portnumber>][:ssl]]. For example, this is how you can connect to Google Talk: + </p><p> + Note that Google talk is SSL-only, but officially reachable over both port 5222 and 5223. However, for some people only port 5222 works, for some people only 5223. This is something you'll have to try out. + </p><pre class="screen"><code class="prompt">< wilmer> </code><strong class="userinput"><code>account add jabber example@gmail.com hobbelmeeuw talk.google.com:5223:ssl</code></strong> +<code class="prompt">< root> </code><strong class="userinput"><code>Account successfully added</code></strong> +</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="cmd_account_add_msn"></a>account add msn</h3></div></div></div><p><b>Syntax: </b> + </p><pre class="programlisting">account add msn <handle> <password> +</pre><p> + </p><p> + For MSN connections there are no special arguments. + </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="cmd_account_add_oscar"></a>account add oscar</h3></div></div></div><p><b>Syntax: </b> + </p><pre class="programlisting">account add oscar <handle> <password> [<servername>] +</pre><p> + </p><p> + Specifying a server is required for OSCAR, since OSCAR can be used for both ICQ- and AIM-connections. Although these days it's supposed to be possible to connect to ICQ via AIM-servers and vice versa, we like to stick with this separation for now. For ICQ connections, the servername is <span class="emphasis"><em>login.icq.com</em></span>, for AIM connections it's <span class="emphasis"><em>login.oscar.aol.com</em></span>. + </p><pre class="screen"><code class="prompt">< wilmer> </code><strong class="userinput"><code>account add oscar 72696705 hobbelmeeuw login.icq.com</code></strong> +<code class="prompt">< root> </code><strong class="userinput"><code>Account successfully added</code></strong> +</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="cmd_account_add_yahoo"></a>account add yahoo</h3></div></div></div><p><b>Syntax: </b> + </p><pre class="programlisting">account add yahoo <handle> <password> +</pre><p> + </p><p> + For Yahoo! connections there are no special arguments. + </p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="cmd_account_del"></a>account del</h3></div></div></div><p><b>Syntax: </b> + </p><pre class="programlisting">account del <account id> +</pre><p> + </p><p> + This commands deletes an account from your account list. You should signoff the account before deleting it. + </p><p> + The account ID can be a number (see <span class="emphasis"><em>account list</em></span>), the protocol name or (part of) the screenname, as long as it matches only one connection. + </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="cmd_account_on"></a>account on</h3></div></div></div><p><b>Syntax: </b> + </p><pre class="programlisting">account on [<account id>] +</pre><p> + </p><p> + This command will try to log into the specified account. If no account is specified, BitlBee will log into all the accounts. (Including accounts awaiting a reconnection) + </p><p> + The account ID can be a number (see <span class="emphasis"><em>account list</em></span>), the protocol name or (part of) the screenname, as long as it matches only one connection. + </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="cmd_account_off"></a>account off</h3></div></div></div><p><b>Syntax: </b> + </p><pre class="programlisting">account off [<account id>] +</pre><p> + </p><p> + This command disconnects the connection for the specified account. If no account is specified, BitlBee will deactivate all active accounts. (Including accounts awaiting a reconnection) + </p><p> + The account ID can be a number (see <span class="emphasis"><em>account list</em></span>), the protocol name or (part of) the screenname, as long as it matches only one connection. + </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="cmd_account_list"></a>account list</h3></div></div></div><p><b>Syntax: </b> + </p><pre class="programlisting">account list +</pre><p> + </p><p> + This command gives you a list of all the accounts known by BitlBee, including the numbers you'll need for most account commands. + </p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cmd_add"></a>add - Add a buddy to your contact list</h2></div></div></div><p><b>Syntax: </b> + </p><pre class="programlisting">add <connection> <handle> [<nick>] +</pre><p> + </p><p> + Adds the given buddy at the specified connection to your buddy list. The account ID can be a number (see <span class="emphasis"><em>account list</em></span>), the protocol name or (part of) the screenname, as long as it matches only one connection. + </p><p> + If you want, you can also tell BitlBee what nick to give the new contact. Of course you can also use the <span class="emphasis"><em>rename</em></span> command for that, but sometimes this might be more convenient. + </p><pre class="screen"><code class="prompt">< ctrlsoft> </code><strong class="userinput"><code>add 3 gryp@jabber.org grijp</code></strong> + * grijphas joined #bitlbee +</pre></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cmd_info"></a>info - Request user information</h2></div></div></div><p><b>Syntax: </b> + </p><pre class="programlisting">info <connection> <handle> +info <nick> +</pre><p> + </p><p> + Requests IM-network-specific information about the specified user. The amount of information you'll get differs per protocol. For some protocols (ATM Yahoo! and MSN) it'll give you an URL which you can visit with a normal web browser to get the information. + </p><pre class="screen"><code class="prompt">< ctrlsoft> </code><strong class="userinput"><code>info 0 72696705</code></strong> +<code class="prompt">< root> </code><strong class="userinput"><code>User info - UIN: 72696705 Nick: Lintux First/Last name: Wilmer van der Gaast E-mail: lintux@lintux.cx</code></strong> +</pre></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cmd_remove"></a>remove - Remove a buddy from your contact list</h2></div></div></div><p><b>Syntax: </b> + </p><pre class="programlisting">remove <nick> +</pre><p> + </p><p> + Removes the specified nick from your buddy list. + </p><pre class="screen"><code class="prompt">< ctrlsoft> </code><strong class="userinput"><code>remove gryp</code></strong> + * gryphas quit [Leaving...] +</pre></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cmd_block"></a>block - Block someone</h2></div></div></div><p><b>Syntax: </b> + </p><pre class="programlisting">block <nick> +block <connection> <handle> +</pre><p> + </p><p> + Puts the specified user on your ignore list. Either specify the user's nick when you have him/her in your contact list or a connection number and a user handle. + </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cmd_allow"></a>allow - Unblock someone</h2></div></div></div><p><b>Syntax: </b> + </p><pre class="programlisting">allow <nick> +allow <connection> <handle> +</pre><p> + </p><p> + Reverse of block. Unignores the specified user or user handle on specified connection. + </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cmd_set"></a>set - Miscellaneous settings</h2></div></div></div><p><b>Syntax: </b> + </p><pre class="programlisting">set [<variable> [<value>]] +</pre><p> + </p><p> + Without any arguments, this command lists all the set variables. You can also specify a single argument, a variable name, to get that variable's value. To change this value, specify the new value as the second argument. + </p><p> + To get more help information about a setting, try: + </p><pre class="screen"><code class="prompt">< ctrlsoft> </code><strong class="userinput"><code>help set private</code></strong> +</pre></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cmd_help"></a>help - BitlBee help system</h2></div></div></div><p><b>Syntax: </b> + </p><pre class="programlisting">help [subject] +</pre><p> + </p><p> + This command gives you the help information you're reading right now. If you don't give any arguments, it'll give a short help index. + </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cmd_save"></a>save - Save your account data</h2></div></div></div><p><b>Syntax: </b> + </p><pre class="programlisting">save +</pre><p> + </p><p> + This command saves all your nicks and accounts immediately. Handy if you have the autosave functionality disabled, or if you don't trust the program's stability... ;-) + </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="set_charset"></a>charset</h2></div></div></div><table class="simplelist" border="0" summary="Simple list"><tr><td>Type: string</td></tr></table><p> + The charset setting enables you to use different character sets in BitlBee. These get converted to UTF-8 before sending and from UTF-8 when receiving. + </p><p> + If you don't know what's the best value for this, at least iso8859-1 is the best choice for most Western countries. You can try to find what works best for you on http://czyborra.com/charsets/iso8859.html + </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="set_private"></a>private</h2></div></div></div><table class="simplelist" border="0" summary="Simple list"><tr><td>Type: boolean</td></tr></table><p> + If value is true, messages from users will appear in separate query windows. If false, messages from users will appear in the control channel. + </p><p> + This setting is remembered (during one session) per-user, this setting only changes the default state. This option takes effect as soon as you reconnect. + </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="set_save_on_quit"></a>save_on_quit</h2></div></div></div><table class="simplelist" border="0" summary="Simple list"><tr><td>Type: boolean</td></tr></table><p> + If enabled causes BitlBee to save all current settings and account details when user disconnects. This is enabled by default, and these days there's not really a reason to have it disabled anymore. + </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="set_html"></a>html</h2></div></div></div><table class="simplelist" border="0" summary="Simple list"><tr><td>Type: string</td></tr></table><p> + Determines what BitlBee should do with HTML in messages. If set to nostrip, HTML in messages will not be touched. If set to strip, all HTML will be stripped from messages. Unfortunately this sometimes strips too much. + </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="set_debug"></a>debug</h2></div></div></div><table class="simplelist" border="0" summary="Simple list"><tr><td>Type: boolean</td></tr></table><p> + Some debugging messages can be sent to the control channel if you wish. They're probably not really useful for you, unless you're doing some development on BitlBee. + </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="set_to_char"></a>to_char</h2></div></div></div><table class="simplelist" border="0" summary="Simple list"><tr><td>Type: string</td></tr></table><p> + It's customary that messages meant for one specific person on an IRC channel are prepended by his/her alias followed by a colon ':'. BitlBee does this by default. If you prefer a different character, you can set it using <span class="emphasis"><em>set to_char</em></span>. + </p><p> + Please note that this setting is only used for incoming messages. For outgoing messages you can use ':' (colon) or ',' to separate the destination nick from the message, and this is not configurable. + </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="set_typing_notice"></a>typing_notice</h2></div></div></div><table class="simplelist" border="0" summary="Simple list"><tr><td>Type: boolean</td></tr></table><p> + Sends you a /notice when a user starts typing a message (if the protocol supports it, MSN for example). This is a bug, not a feature. (But please don't report it.. ;-) You don't want to use it. Really. In fact the typing-notification is just one of the least useful 'innovations' ever. It's just there because some guy will probably ask me about it anyway. ;-) + </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="set_ops"></a>ops</h2></div></div></div><table class="simplelist" border="0" summary="Simple list"><tr><td>Type: string</td></tr></table><p> + Some people prefer themself and root to have operator status in #bitlbee, other people don't. You can change these states using this setting. + </p><p> + The value "both" means both user and root get ops. "root" means, well, just root. "user" means just the user. "none" means nobody will get operator status. + </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="set_away_devoice"></a>away_devoice</h2></div></div></div><table class="simplelist" border="0" summary="Simple list"><tr><td>Type: boolean</td></tr></table><p> + With this option enabled, the root user devoices people when they go away (just away, not offline) and gives the voice back when they come back. You might dislike the voice-floods you'll get if your contact list is huge, so this option can be disabled. + </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="set_handle_unknown"></a>handle_unknown</h2></div></div></div><table class="simplelist" border="0" summary="Simple list"><tr><td>Type: string</td></tr></table><p> + Messages from unknown users are echoed like this by default: + </p><p> + If you want this lame user to be added automatically, you can set this setting to "add". If you prefer to ignore messages from people you don't know, you can set this one to "ignore". "add_private" and "add_channel" are like add, but you can use them to make messages from unknown buddies appear in the channel instead of a query window. + </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="set_auto_connect"></a>auto_connect</h2></div></div></div><table class="simplelist" border="0" summary="Simple list"><tr><td>Type: boolean</td></tr></table><p> + With this option enabled, when you identify BitlBee will automatically connect to your accounts, with this disabled it will not do this. + </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="set_auto_reconnect"></a>auto_reconnect</h2></div></div></div><table class="simplelist" border="0" summary="Simple list"><tr><td>Type: boolean</td></tr></table><p> + If an IM-connections breaks, you're supposed to bring it back up yourself. Having BitlBee do this automatically might not always be a good idea, for several reasons. If you want the connections to be restored automatically, you can enable this setting. + </p><p> + See also the <span class="emphasis"><em>auto_reconnect_delay</em></span> setting. + </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="set_auto_reconnect_delay"></a>auto_reconnect_delay</h2></div></div></div><table class="simplelist" border="0" summary="Simple list"><tr><td>Type: integer</td></tr></table><p> + Tell BitlBee after how many seconds it should attempt to bring an IM-connection back up after a crash. It's not a good idea to set this value very low, it will cause too much useless traffic when an IM-server is down for a few hours. + </p><p> + See also the <span class="emphasis"><em>auto_reconnect</em></span> setting. + </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="set_buddy_sendbuffer"></a>buddy_sendbuffer</h2></div></div></div><table class="simplelist" border="0" summary="Simple list"><tr><td>Type: boolean</td></tr></table><p> + By default, when you send a message to someone, BitlBee forwards this message to the user immediately. When you paste a large number of lines, the lines will be sent in separate messages, which might not be very nice to read. If you enable this setting, BitlBee will buffer your messages and wait for more data. + </p><p> + Using the <span class="emphasis"><em>buddy_sendbuffer_delay</em></span> setting you can specify the number of seconds BitlBee should wait for more data before the complete message is sent. + </p><p> + Please note that if you remove a buddy from your list (or if the connection to that user drops) and there's still data in the buffer, this data will be lost. BitlBee will not try to send the message to the user in those cases. + </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="set_buddy_sendbuffer_delay"></a>buddy_sendbuffer_delay</h2></div></div></div><table class="simplelist" border="0" summary="Simple list"><tr><td>Type: integer</td></tr></table><p> + Tell BitlBee after how many seconds a buffered message should be sent. + </p><p> + See also the <span class="emphasis"><em>buddy_sendbuffer</em></span> setting. + </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="set_default_target"></a>default_target</h2></div></div></div><table class="simplelist" border="0" summary="Simple list"><tr><td>Type: string</td></tr></table><p> + With this value set to <span class="emphasis"><em>root</em></span>, lines written in the control channel without any nickname in front of them will be interpreted as commands. If you want BitlBee to send those lines to the last person you addressed in the control channel, set this to <span class="emphasis"><em>last</em></span>. + </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="set_display_namechanges"></a>display_namechanges</h2></div></div></div><table class="simplelist" border="0" summary="Simple list"><tr><td>Type: boolean</td></tr></table></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="set_password"></a>password</h2></div></div></div><table class="simplelist" border="0" summary="Simple list"><tr><td>Type: string</td></tr></table><p> + Use this setting to change your "NickServ" password. + </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="set_query_order"></a>query_order</h2></div></div></div><table class="simplelist" border="0" summary="Simple list"><tr><td>Type: string</td></tr></table><p> + This changes the order in which the questions from root (usually authorization requests from buddies) should be answered. When set to <span class="emphasis"><em>lifo</em></span>, BitlBee immediately displays all new questions and they should be answered in reverse order. When this is set to <span class="emphasis"><em>fifo</em></span>, BitlBee displays the first question which comes in and caches all the others until you answer the first one. + </p><p> + Although the <span class="emphasis"><em>fifo</em></span> setting might sound more logical (and used to be the default behaviour in older BitlBee versions), it turned out not to be very convenient for many users when they missed the first question (and never received the next ones). + </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="set_lcnicks"></a>lcnicks</h2></div></div></div><table class="simplelist" border="0" summary="Simple list"><tr><td>Type: boolean</td></tr></table><p> + Hereby you can change whether you want all lower case nick names or leave the case as it intended by your peer. + </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cmd_rename"></a>rename - Rename (renick) a buddy</h2></div></div></div><p><b>Syntax: </b> + </p><pre class="programlisting">rename <oldnick> <newnick> +</pre><p> + </p><p> + Renick a user in your buddy list. Very useful, in fact just very important, if you got a lot of people with stupid account names (or hard ICQ numbers). + </p><pre class="screen"><code class="prompt">< itsme> </code><strong class="userinput"><code>rename itsme_ you</code></strong> + * itsme_is now known as you +</pre></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cmd_yes"></a>yes - Accept a request</h2></div></div></div><p><b>Syntax: </b> + </p><pre class="programlisting">yes [<number>] +</pre><p> + </p><p> + Sometimes an IM-module might want to ask you a question. (Accept this user as your buddy or not?) To accept a question, use the <span class="emphasis"><em>yes</em></span> command. + </p><p> + By default, this answers the first unanswered question. You can also specify a different question as an argument. You can use the <span class="emphasis"><em>qlist</em></span> command for a list of questions. + </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cmd_no"></a>no - Deny a request</h2></div></div></div><p><b>Syntax: </b> + </p><pre class="programlisting">no [<number>] +</pre><p> + </p><p> + Sometimes an IM-module might want to ask you a question. (Accept this user as your buddy or not?) To reject a question, use the <span class="emphasis"><em>no</em></span> command. + </p><p> + By default, this answers the first unanswered question. You can also specify a different question as an argument. You can use the <span class="emphasis"><em>qlist</em></span> command for a list of questions. + </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cmd_qlist"></a>qlist - List all the unanswered questions root asked</h2></div></div></div><p><b>Syntax: </b> + </p><pre class="programlisting">qlist +</pre><p> + </p><p> + This gives you a list of all the unanswered questions from root. + </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cmd_register"></a>register - Register yourself</h2></div></div></div><p><b>Syntax: </b> + </p><pre class="programlisting">register <password> +</pre><p> + </p><p> + BitlBee can save your settings so you won't have to enter all your IM passwords every time you log in. If you want the Bee to save your settings, use the <span class="emphasis"><em>register</em></span> command. + </p><p> + Please do pick a secure password, don't just use your nick as your password. Please note that IRC is not an encrypted protocol, so the passwords still go over the network in plaintext. Evil people with evil sniffers will read it all. (So don't use your root password.. ;-) + </p><p> + To identify yourself in later sessions, you can use the <span class="emphasis"><em>identify</em></span> command. + </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cmd_identify"></a>identify - Identify yourself with your password</h2></div></div></div><p><b>Syntax: </b> + </p><pre class="programlisting">identify <password> +</pre><p> + </p><p> + BitlBee saves all your settings (contacts, accounts, passwords) on-server. To prevent other users from just logging in as you and getting this information, you'll have to identify yourself with your password. You can register this password using the <span class="emphasis"><em>register</em></span> command. + </p><p> + Once you're registered, you can change your password using <span class="emphasis"><em>set password <password></em></span>. + </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cmd_drop"></a>drop - Drop your account</h2></div></div></div><p><b>Syntax: </b> + </p><pre class="programlisting">drop <password> +</pre><p> + </p><p> + Drop your BitlBee registration. Your account files will be removed and your password will be forgotten. For obvious security reasons, you have to specify your NickServ password to make this command work. + </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cmd_blist"></a>blist - List all the buddies in your contact list</h2></div></div></div><p><b>Syntax: </b> + </p><pre class="programlisting">blist [all|online|offline|away] +</pre><p> + </p><p> + You can get a better readable buddy list using the <span class="emphasis"><em>blist</em></span> command. If you want a complete list (including the offline users) you can use the <span class="emphasis"><em>all</em></span> argument. + </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cmd_nick"></a>nick - Change friendly name, nick</h2></div></div></div><p><b>Syntax: </b> + </p><pre class="programlisting">nick <connection> [<new nick>] +nick +</pre><p> + </p><p> + This command allows to set the friendly name of an im account. If no new name is specified the command will report the current name. When the name contains spaces, don't forget to quote the whole nick in double quotes. Currently this command is only supported by the MSN protocol. + </p><pre class="screen"><code class="prompt">< wouter> </code><strong class="userinput"><code>nick 1 "Wouter Paesen"</code></strong> +<code class="prompt">< root> </code><strong class="userinput"><code>Setting your name on connection 1 to `Wouter Paesen'</code></strong> +</pre></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cmd_import_buddies"></a>import_buddies - Copy local buddy list to server (normally only needed when upgrading)</h2></div></div></div><p><b>Syntax: </b> + </p><pre class="programlisting">import_buddies <connection> [clear] +</pre><p> + </p><p> + This command copies the locally stored buddy list to the server. This command exists for upgrading purposes. Previous versions of BitlBee didn't support server-side buddy lists for ICQ, so the list was stored locally. + </p><p> + Since version 0.91 however, server-side contact lists are supported for all protocols, so the local list is now ignored. When upgrading from an older BitlBee to version 0.91, you might need this command to get your buddy list back. + </p><p> + The only argument this command needs is your ICQ account identification. If your serverside buddy list contains some old buddies you don't want anymore, you can pass <span class="emphasis"><em>clear</em></span> as a second argument. + </p><p> + After giving this command, you have to wait for a while before all the adds are handled, because of ICQ's rate limiting. If your buddy list is very large and the ICQ server starts complaining, you might have to reconnect and enter this command again. + </p></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="misc"></a>Chapter 6. Misc Stuff</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#smileys">Smileys</a></span></dt><dt><span class="sect1"><a href="#groupchats">Groupchats</a></span></dt><dt><span class="sect1"><a href="#groupchats2">Creating groupchats</a></span></dt><dt><span class="sect1"><a href="#groupchats3">Groupchat channel names</a></span></dt><dt><span class="sect1"><a href="#away">Away states</a></span></dt></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="smileys"></a>Smileys</h2></div></div></div><p> +All MSN smileys (except one) are case insensitive and work without the nose too. +</p><div class="variablelist"><dl><dt><span class="term">(Y)</span></dt><dd><p>Thumbs up</p></dd><dt><span class="term">(N)</span></dt><dd><p>Thumbs down</p></dd><dt><span class="term">(B)</span></dt><dd><p>Beer mug</p></dd><dt><span class="term">(D)</span></dt><dd><p>Martini glass</p></dd><dt><span class="term">(X)</span></dt><dd><p>Girl</p></dd><dt><span class="term">(Z)</span></dt><dd><p>Boy</p></dd><dt><span class="term">(6)</span></dt><dd><p>Devil smiley</p></dd><dt><span class="term">:-[</span></dt><dd><p>Vampire bat</p></dd><dt><span class="term">(})</span></dt><dd><p>Right hug</p></dd><dt><span class="term">({)</span></dt><dd><p>Left hug</p></dd><dt><span class="term">(M)</span></dt><dd><p>MSN Messenger or Windows Messenger icon (think a BitlBee logo here ;)</p></dd><dt><span class="term">:-S</span></dt><dd><p>Crooked smiley (Confused smiley)</p></dd><dt><span class="term">:-$</span></dt><dd><p>Embarrassed smiley</p></dd><dt><span class="term">(H)</span></dt><dd><p>Smiley with sunglasses</p></dd><dt><span class="term">:-@</span></dt><dd><p>Angry smiley</p></dd><dt><span class="term">(A)</span></dt><dd><p>Angel smiley</p></dd><dt><span class="term">(L)</span></dt><dd><p>Red heart (Love)</p></dd><dt><span class="term">(U)</span></dt><dd><p>Broken heart</p></dd><dt><span class="term">(K)</span></dt><dd><p>Red lips (Kiss)</p></dd><dt><span class="term">(G)</span></dt><dd><p>Gift with bow</p></dd><dt><span class="term">(F)</span></dt><dd><p>Red rose</p></dd><dt><span class="term">(W)</span></dt><dd><p>Wilted rose</p></dd><dt><span class="term">(P)</span></dt><dd><p>Camera</p></dd><dt><span class="term">(~)</span></dt><dd><p>Film strip</p></dd><dt><span class="term">(T)</span></dt><dd><p>Telephone receiver</p></dd><dt><span class="term">(@)</span></dt><dd><p>Cat face</p></dd><dt><span class="term">(&)</span></dt><dd><p>Dog's head</p></dd><dt><span class="term">(C)</span></dt><dd><p>Coffee cup</p></dd><dt><span class="term">(I)</span></dt><dd><p>Light bulb</p></dd><dt><span class="term">(S)</span></dt><dd><p>Half-moon (Case sensitive!)</p></dd><dt><span class="term">(*)</span></dt><dd><p>Star</p></dd><dt><span class="term">(8)</span></dt><dd><p>Musical eighth note</p></dd><dt><span class="term">(E)</span></dt><dd><p>Envelope</p></dd><dt><span class="term">(^)</span></dt><dd><p>Birthday cake</p></dd><dt><span class="term">(O)</span></dt><dd><p>Clock</p></dd></dl></div><p> +This list was extracted from <a href="http://help.msn.com/!data/en_us/data/messengerv50.its51/%24content%24/EMOTICONS.HTM?H_APP=" target="_top">http://help.msn.com/!data/en_us/data/messengerv50.its51/$content$/EMOTICONS.HTM?H_APP=</a>. +</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="groupchats"></a>Groupchats</h2></div></div></div><p> +Since version 0.8x, BitlBee supports groupchats on the MSN and Yahoo! networks. This text will try to explain you how they work. +</p><p> +As soon as someone invites you into a groupchat, you will be force-joined or invited (depending on the protocol) into a new virtual channel with all the people in there. You can leave the channel at any time, just like you would close the window in regular IM clients. Please note that root-commands don't work in groupchat channels, they only work in the control channel (or to root directly). +</p><p> +Of course you can also create your own groupchats. Type <span class="emphasis"><em>help groupchats2</em></span> to see how. +</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="groupchats2"></a>Creating groupchats</h2></div></div></div><p> +If you want to start a groupchat with the person <span class="emphasis"><em>jim_msn</em></span> in it, just join the channel <span class="emphasis"><em>#jim_msn</em></span>. BitlBee will refuse to join you to the channel with that name, but it will create a new virtual channel with root, you and jim_msn in it. +</p><p> +Of course a channel with only two people isn't really exciting yet. So the next step is to invite some other people to the channel. For this, you can use the <span class="emphasis"><em>/invite</em></span> command of your IRC client. Please do keep in mind that all the people have to be on the same network and contact list! You can't invite Yahoo! buddies into an MSN groupchat. +</p><p> +This is all you'll probably need to know. If you have any problems, please read <span class="emphasis"><em>help groupchats3</em></span>. +</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="groupchats3"></a>Groupchat channel names</h2></div></div></div><p> +Obviously the (numbered) channel names don't make a lot of sense. Problem is that groupchats usually don't have names at all in the IM-world, while IRC insists on a name. So BitlBee just generates something random, just don't pay attention to it. :-) +</p><p> +Please also note that BitlBee doesn't support groupchats for all protocols yet. BitlBee will tell you so. Support for other protocols will hopefully come later. +</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="away"></a>Away states</h2></div></div></div><p> +As you might've expected, you can just use the <span class="emphasis"><em>/away</em></span> command in your IRC client to set an away-state. BitlBee supports most away-states supported by the protocols. +</p><p> +Not all away states are supported by all protocols, and some protocols have different names for them. BitlBee will try to pick the best available alias from this list for every connection: +</p><table class="simplelist" border="0" summary="Simple list"><tr><td>Away from computer, Away, Extended away</td></tr><tr><td>NA, N/A, Not available</td></tr><tr><td>Busy, Do not disturb, DND, Occupied</td></tr><tr><td>Be right back, BRB</td></tr><tr><td>On the phone, Phone, On phone</td></tr><tr><td>Out to lunch, Lunch, Food</td></tr></table><p> +So <span class="emphasis"><em>/away Food</em></span> will set your state to "Out to lunch" on your MSN connection, and for most other connections the default, "Away" or "Away from computer" will be chosen. +</p><p> +You can also add more information to your away message. Setting it to "Busy - Fixing BitlBee bugs" will set your IM-away-states to Busy, but your away message will be more descriptive for people on IRC. Protocols like Yahoo! and Jabber will also show this complete away message to your buddies. +</p></div></div></div></body></html> diff --git a/doc/user-guide/user-guide.txt b/doc/user-guide/user-guide.txt new file mode 100644 index 00000000..b8854f7a --- /dev/null +++ b/doc/user-guide/user-guide.txt @@ -0,0 +1,1209 @@ +BitlBee User Guide + +Jelmer Vernooij + +Wilmer van der Gaast + +Sjoerd Hemminga + +This is the initial release of the BitlBee User Guide. + +Permission is granted to copy, distribute and/or modify this document under the +terms of the GNU Free Documentation License, Version 1.1 or any later version +published by the Free Software Foundation with no Invariant Sections, no +Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy of the GNU +Free Documentation License from the Free Software Foundation by visiting their +Web site or by writing to: Free Software Foundation, Inc., 59 Temple Place - +Suite 330, Boston, MA 02111-1307, USA. + +------------------------------------------------------------------------------- + +Table of Contents + +1. Installation + + Downloading the package + Compiling + Configuration + +2. Usage + + Connecting to the server + The #bitlbee control channel + Talking to people + +3. Support + + BitlBee is beta software + Support channels + + The World Wide Web + IRC + Mailinglists + +4. Quickstart + + Add and Connect To your IM Account(s) + Managing Contact Lists: Rename + Step Four: Managing Contact Lists: Add and Remove. + Chatting + Further Resources + +5. Bitlbee commands + + account - IM-account list maintenance + + account add + account del + account on + account off + account list + + add - Add a buddy to your contact list + info - Request user information + remove - Remove a buddy from your contact list + block - Block someone + allow - Unblock someone + set - Miscellaneous settings + help - BitlBee help system + save - Save your account data + charset + private + save_on_quit + html + debug + to_char + typing_notice + ops + away_devoice + handle_unknown + auto_connect + auto_reconnect + auto_reconnect_delay + buddy_sendbuffer + buddy_sendbuffer_delay + default_target + display_namechanges + password + query_order + lcnicks + rename - Rename (renick) a buddy + yes - Accept a request + no - Deny a request + qlist - List all the unanswered questions root asked + register - Register yourself + identify - Identify yourself with your password + drop - Drop your account + blist - List all the buddies in your contact list + nick - Change friendly name, nick + import_buddies - Copy local buddy list to server (normally only needed when + upgrading) + +6. Misc Stuff + + Smileys + Groupchats + Creating groupchats + Groupchat channel names + Away states + +Chapter 1. Installation + +Table of Contents + +Downloading the package +Compiling +Configuration + +Downloading the package + +The latest BitlBee release is always available from http://www.bitlbee.org/. +Download the package with your favorite program and unpack it: tar xvfz +bitlbee-<version>.tar.gz where <version> is to be replaced by the version +number of the BitlBee you downloaded (e.g. 0.91). + +Compiling + +BitlBee's build system has to be configured before compiling. The configure +script will do this for you. Just run it, it'll set up with nice and hopefully +well-working defaults. If you want to change some settings, just try ./ +configure --help and see what you can do. + +Some variables that might be of interest to the normal user: + + * prefix, bindir, etcdir, mandir, datadir - The place where all the BitlBee + program files will be put. There's usually no reason to specify them all + separately, just specifying prefix (or keeping the default /usr/local/) + should be okay. + + * config - The place where BitlBee will save all the per-user settings and + buddy information. /var/lib/bitlbee/ is the default value. + + * msn, jabber, oscar, yahoo - By default, support for all these IM-protocols + (OSCAR is the protocol used by both ICQ and AIM) will be compiled in. To + make the binary a bit smaller, you can use these options to leave out + support for protocols you're not planning to use. + + * debug - Generate an unoptimized binary with debugging symbols, mainly + useful if you want to do some debugging or help us to track down a problem. + + * strip - By default, unnecessary parts of the generated binary will be + stripped out to make it as small as possible. If you don't want this + (because it might cause problems on some platforms), set this to 0. + + * flood - To secure your BitlBee server against flooding attacks, you can use + this option. It's not compiled in by default because it needs more testing + first. + + * ssl - The MSN and Jabber modules require an SSL library for some of their + tasks. BitlBee can use three different SSL libraries: GnuTLS, mozilla-nss + and OpenSSL. (OpenSSL is, however, a bit troublesome because of licensing + issues, so don't forget to read the information configure will give you + when you try to use OpenSSL!) By default, configure will try to detect + GnuTLS or mozilla-nss. If none of them can be found, it'll give up. If you + want BitlBee to use OpenSSL, you have to explicitly specify that. + +After running configure, you should run make. After that, run make install as +root. + +Configuration + +By default, BitlBee runs as the user nobody. You might want to run it as a +seperate user (some computers run named or apache as nobody). + +Since BitlBee uses inetd, you should add the following line to /etc/inetd.conf: + +6667 stream tcp nowait nobody /usr/local/sbin/bitlbee bitlbee + +Inetd has to be restarted after changing the configuration. Either killall -HUP +inetd or /etc/init.d/inetd restart should do the job on most systems. + +You might be one of the.. ehr, lucky people running an xinetd-powered distro. +xinetd is quite different and they seem to be proud of that.. ;-) Anyway, if +you want BitlBee to work with xinetd, just copy the bitlbee.xinetd file to your +/etc/xinetd.d/ directory (and probably edit it to suit your needs). + +You should create a directory where BitlBee can store it's data files. This +should be the directory named after the value 'CONFIG' in Makefile.settings. +The default is /var/lib/bitlbee, which can be created with the command mkdir -p +/var/lib/bitlbee. This directory has to be owned by the user that runs bitlbee. +To make 'nobody' owner of this directory, run chown nobody /var/lib/bitlbee. +Because things like passwords are saved in this directory, it's probably a good +idea to make this directory owner-read-/writable only. + +Chapter 2. Usage + +Table of Contents + +Connecting to the server +The #bitlbee control channel +Talking to people + +Connecting to the server + +Since BitlBee acts just like any other irc daemon, you can connect to it with +your favorite irc client. Launch it and connect to localhost port 6667 (or +whatever host/port you are running bitlbee on). + +The #bitlbee control channel + +Once you are connected to the BitlBee server, you are automatically joined to # +bitlbee on that server. This channel acts like the 'buddy list' you have on the +various other chat networks. + +The user 'root' always hangs around in #bitlbee and acts as your interface to +bitlbee. All commands you give on #bitlbee are 'answered' by root. + +Talking to people + +You can talk to by starting a query with them. In most irc clients, this can be +done with either /msg <nick> <text> or /query <nick>. + +To keep the number of open query windows limited, you can also talk to people +in the control channel, like <nick>: <text>. + +Chapter 3. Support + +Table of Contents + +BitlBee is beta software +Support channels + + The World Wide Web + IRC + Mailinglists + +BitlBee is beta software + +Although BitlBee has quite some functionality it is still beta. That means it +can crash at any time, corrupt your data or whatever. Don't use it in any +production environment and don't rely on it. + +Support channels + +The World Wide Web + +http://www.bitlbee.org/ is the homepage of bitlbee and contains the most recent +news on bitlbee and the latest releases. + +IRC + +BitlBee is discussed on #bitlbee on the OFTC IRC network (server: +irc.oftc.net). + +Mailinglists + +BitlBee doesn't have any mailinglists. + +Chapter 4. Quickstart + +Table of Contents + +Add and Connect To your IM Account(s) +Managing Contact Lists: Rename +Step Four: Managing Contact Lists: Add and Remove. +Chatting +Further Resources + +Welcome to BitlBee, your IRC gateway to ICQ, MSN, AOL, Jabber and Yahoo Instant +Messaging Systems. + +The center of BitlBee is the control channel, #bitlbee. Two users will always +be there, you (where "you" is the nickname you are using) and the system user, +root. + +You need register so that all your IM settings (passwords, contacts, etc) can +be saved on the BitlBee server. It's important that you pick a good password so +no one else can access your account. Register with this password using the +register command: register <password> (without the brackets!). + +Be sure to remember your password. The next time you connect to the BitlBee +server you will need to identify <password> so that you will be recognised and +logged in to all the IM services automatically. + +When finished, type help quickstart2 to continue. + +Add and Connect To your IM Account(s) + +Step Two: Add and Connect To your IM Account(s). + +To add an account to the account list you will need to use the account add +command: account add <protocol> <username> <password> [<server>]. + +For instance, suppose you have an ICQ account with UIN 72696705 with password +QuickStart, you would: + +< you> account add oscar 72696705 QuickStart login.icq.com +< root> Account successfully added + +Other available IM protocols are jabber, msn, and yahoo. Oscar is the protocol +used by ICQ and AOL. For oscar, you need to specify the IM-server as a fourth +argument (for msn and yahoo there is no fourth argument). For AOL Instant +Messenger, the server name is login.oscar.aol.com. For ICQ, the server name is +login.icq.com. + +When you are finished adding your account(s) use the account on command to +enable all your accounts, type help quickstart3 to continue. + +Managing Contact Lists: Rename + +Step Three: Managing Contact Lists: Rename + +For most protocols (currently MSN, Jabber, Yahoo and AOL) BitlBee can download +the contact list automatically from the IM server and all the on-line users +should appear in the control channel when you log in. + +BitlBee will convert names into irc-friendly form (for instance: +tux@example.com will be given the nickname tux). If you have more than one +person who would have the same name by this logic (for instance: +tux@example.com and tux@bitlbee.org) the second one to log on will be tux_. The +same is true if you have a tux log on to AOL and a tux log on from Yahoo. + +It would be easy to get these two mixed up, so BitlBee has a rename command to +change the nickname into something more suitable: rename <oldnick> <newnick> + +< you> rename tux_ bitlbeetux + * tux_is now known as bitlbeetux +< root> Nick successfully changed + +When finished, type help quickstart4 to continue. + +Step Four: Managing Contact Lists: Add and Remove. + +Step Four: Managing Contact Lists: Add and Remove. + +Now you might want to add some contacts, to do this we will use the add +command. It needs two arguments: a connection ID (which can be a number (try +account list), protocol name or (part of) the screenname) and the user's +handle. It is used in the following way: add <connection> <handle> + +< you> add 0 r2d2@example.com + * r2d2has joined #bitlbee + +In this case r2d2 is online, since he/she joins the channel immediately. If the +user is not online you will not see them join until they log on. + +Lets say you accidentally added r2d3@example.com rather than r2d2@example.com, +or maybe you just want to remove a user from your list because you never talk +to them. To remove a name you will want to use the remove command: remove +<nick> + +When finished, type help quickstart5 to continue. + +Chatting + +Step Five: Chatting. + +First of all, a person must be on your contact list for you to chat with them +(unless it's a group chat, help groupchats for more). If someone not on your +contact list sends you a message, simply add them to the proper account with +the add command. Once they are on your list and online, you can chat with them +in #bitlbee: + +< you> tux: hey, how's the weather down there? +< tux> you: a bit chilly! + +If you'd rather chat with them in a separate window use the /msg or /query +command, just like you would for a private message in IRC. If you want to have +messages automatically come up in private messages rather than in the #bitlbee +channel, use the set private command: set private true (set private false to +change back). + +You know the basics. If you want to get to know more about BitlBee, please type +help quickstart6. + +Further Resources + +So you want more than just chatting? Or maybe you're just looking for a +feature? + +You can type help set to learn more about the possible BitlBee user settings. +Among these user settings you will find options for common issues, such as +changing the charset, HTML stripping and automatic connecting (simply type set +to see current user settings). + +For more subjects (like groupchats and away states), please type help index. + +If you're still looking for something, please visit us in #bitlbee on the OFTC +network (you can connect via irc.bitlbee.org), or mail us your problem/ +suggestion. Good luck and enjoy the Bee! + +Chapter 5. Bitlbee commands + +Table of Contents + +account - IM-account list maintenance + + account add + account del + account on + account off + account list + +add - Add a buddy to your contact list +info - Request user information +remove - Remove a buddy from your contact list +block - Block someone +allow - Unblock someone +set - Miscellaneous settings +help - BitlBee help system +save - Save your account data +charset +private +save_on_quit +html +debug +to_char +typing_notice +ops +away_devoice +handle_unknown +auto_connect +auto_reconnect +auto_reconnect_delay +buddy_sendbuffer +buddy_sendbuffer_delay +default_target +display_namechanges +password +query_order +lcnicks +rename - Rename (renick) a buddy +yes - Accept a request +no - Deny a request +qlist - List all the unanswered questions root asked +register - Register yourself +identify - Identify yourself with your password +drop - Drop your account +blist - List all the buddies in your contact list +nick - Change friendly name, nick +import_buddies - Copy local buddy list to server (normally only needed when + upgrading) + +account - IM-account list maintenance + +Syntax: + +account <action> [<arguments>] + +Available actions: add, del, list, on, off. See help account <action> for more +information. + +account add + +Syntax: + +account add <protocol> <username> <password> [<server>] + +Adds an account on the given server with the specified protocol, username and +password to the account list. Supported protocols right now are: Jabber, MSN, +OSCAR (AIM/ICQ) and Yahoo. For more information about adding an account, see +help account add <protocol>. + +account add jabber + +Syntax: + +account add jabber <handle> <password> [<servertag>] + +Note that the servertag argument is optional. You only have to use it if the +part after the @ in your handle isn't the hostname of your Jabber server, or if +you want to use SSL/connect to a non-standard port number. The format is +simple: [<servername>[:<portnumber>][:ssl]]. For example, this is how you can +connect to Google Talk: + +Note that Google talk is SSL-only, but officially reachable over both port 5222 +and 5223. However, for some people only port 5222 works, for some people only +5223. This is something you'll have to try out. + +< wilmer> account add jabber example@gmail.com hobbelmeeuw talk.google.com:5223:ssl +< root> Account successfully added + +account add msn + +Syntax: + +account add msn <handle> <password> + +For MSN connections there are no special arguments. + +account add oscar + +Syntax: + +account add oscar <handle> <password> [<servername>] + +Specifying a server is required for OSCAR, since OSCAR can be used for both +ICQ- and AIM-connections. Although these days it's supposed to be possible to +connect to ICQ via AIM-servers and vice versa, we like to stick with this +separation for now. For ICQ connections, the servername is login.icq.com, for +AIM connections it's login.oscar.aol.com. + +< wilmer> account add oscar 72696705 hobbelmeeuw login.icq.com +< root> Account successfully added + +account add yahoo + +Syntax: + +account add yahoo <handle> <password> + +For Yahoo! connections there are no special arguments. + +account del + +Syntax: + +account del <account id> + +This commands deletes an account from your account list. You should signoff the +account before deleting it. + +The account ID can be a number (see account list), the protocol name or (part +of) the screenname, as long as it matches only one connection. + +account on + +Syntax: + +account on [<account id>] + +This command will try to log into the specified account. If no account is +specified, BitlBee will log into all the accounts. (Including accounts awaiting +a reconnection) + +The account ID can be a number (see account list), the protocol name or (part +of) the screenname, as long as it matches only one connection. + +account off + +Syntax: + +account off [<account id>] + +This command disconnects the connection for the specified account. If no +account is specified, BitlBee will deactivate all active accounts. (Including +accounts awaiting a reconnection) + +The account ID can be a number (see account list), the protocol name or (part +of) the screenname, as long as it matches only one connection. + +account list + +Syntax: + +account list + +This command gives you a list of all the accounts known by BitlBee, including +the numbers you'll need for most account commands. + +add - Add a buddy to your contact list + +Syntax: + +add <connection> <handle> [<nick>] + +Adds the given buddy at the specified connection to your buddy list. The +account ID can be a number (see account list), the protocol name or (part of) +the screenname, as long as it matches only one connection. + +If you want, you can also tell BitlBee what nick to give the new contact. Of +course you can also use the rename command for that, but sometimes this might +be more convenient. + +< ctrlsoft> add 3 gryp@jabber.org grijp + * grijphas joined #bitlbee + +info - Request user information + +Syntax: + +info <connection> <handle> +info <nick> + +Requests IM-network-specific information about the specified user. The amount +of information you'll get differs per protocol. For some protocols (ATM Yahoo! +and MSN) it'll give you an URL which you can visit with a normal web browser to +get the information. + +< ctrlsoft> info 0 72696705 +< root> User info - UIN: 72696705 Nick: Lintux First/Last name: Wilmer van der Gaast E-mail: lintux@lintux.cx + +remove - Remove a buddy from your contact list + +Syntax: + +remove <nick> + +Removes the specified nick from your buddy list. + +< ctrlsoft> remove gryp + * gryphas quit [Leaving...] + +block - Block someone + +Syntax: + +block <nick> +block <connection> <handle> + +Puts the specified user on your ignore list. Either specify the user's nick +when you have him/her in your contact list or a connection number and a user +handle. + +allow - Unblock someone + +Syntax: + +allow <nick> +allow <connection> <handle> + +Reverse of block. Unignores the specified user or user handle on specified +connection. + +set - Miscellaneous settings + +Syntax: + +set [<variable> [<value>]] + +Without any arguments, this command lists all the set variables. You can also +specify a single argument, a variable name, to get that variable's value. To +change this value, specify the new value as the second argument. + +To get more help information about a setting, try: + +< ctrlsoft> help set private + +help - BitlBee help system + +Syntax: + +help [subject] + +This command gives you the help information you're reading right now. If you +don't give any arguments, it'll give a short help index. + +save - Save your account data + +Syntax: + +save + +This command saves all your nicks and accounts immediately. Handy if you have +the autosave functionality disabled, or if you don't trust the program's +stability... ;-) + +charset + +Type: string + +The charset setting enables you to use different character sets in BitlBee. +These get converted to UTF-8 before sending and from UTF-8 when receiving. + +If you don't know what's the best value for this, at least iso8859-1 is the +best choice for most Western countries. You can try to find what works best for +you on http://czyborra.com/charsets/iso8859.html + +private + +Type: boolean + +If value is true, messages from users will appear in separate query windows. If +false, messages from users will appear in the control channel. + +This setting is remembered (during one session) per-user, this setting only +changes the default state. This option takes effect as soon as you reconnect. + +save_on_quit + +Type: boolean + +If enabled causes BitlBee to save all current settings and account details when +user disconnects. This is enabled by default, and these days there's not really +a reason to have it disabled anymore. + +html + +Type: string + +Determines what BitlBee should do with HTML in messages. If set to nostrip, +HTML in messages will not be touched. If set to strip, all HTML will be +stripped from messages. Unfortunately this sometimes strips too much. + +debug + +Type: boolean + +Some debugging messages can be sent to the control channel if you wish. They're +probably not really useful for you, unless you're doing some development on +BitlBee. + +to_char + +Type: string + +It's customary that messages meant for one specific person on an IRC channel +are prepended by his/her alias followed by a colon ':'. BitlBee does this by +default. If you prefer a different character, you can set it using set to_char. + +Please note that this setting is only used for incoming messages. For outgoing +messages you can use ':' (colon) or ',' to separate the destination nick from +the message, and this is not configurable. + +typing_notice + +Type: boolean + +Sends you a /notice when a user starts typing a message (if the protocol +supports it, MSN for example). This is a bug, not a feature. (But please don't +report it.. ;-) You don't want to use it. Really. In fact the +typing-notification is just one of the least useful 'innovations' ever. It's +just there because some guy will probably ask me about it anyway. ;-) + +ops + +Type: string + +Some people prefer themself and root to have operator status in #bitlbee, other +people don't. You can change these states using this setting. + +The value "both" means both user and root get ops. "root" means, well, just +root. "user" means just the user. "none" means nobody will get operator status. + +away_devoice + +Type: boolean + +With this option enabled, the root user devoices people when they go away (just +away, not offline) and gives the voice back when they come back. You might +dislike the voice-floods you'll get if your contact list is huge, so this +option can be disabled. + +handle_unknown + +Type: string + +Messages from unknown users are echoed like this by default: + +If you want this lame user to be added automatically, you can set this setting +to "add". If you prefer to ignore messages from people you don't know, you can +set this one to "ignore". "add_private" and "add_channel" are like add, but you +can use them to make messages from unknown buddies appear in the channel +instead of a query window. + +auto_connect + +Type: boolean + +With this option enabled, when you identify BitlBee will automatically connect +to your accounts, with this disabled it will not do this. + +auto_reconnect + +Type: boolean + +If an IM-connections breaks, you're supposed to bring it back up yourself. +Having BitlBee do this automatically might not always be a good idea, for +several reasons. If you want the connections to be restored automatically, you +can enable this setting. + +See also the auto_reconnect_delay setting. + +auto_reconnect_delay + +Type: integer + +Tell BitlBee after how many seconds it should attempt to bring an IM-connection +back up after a crash. It's not a good idea to set this value very low, it will +cause too much useless traffic when an IM-server is down for a few hours. + +See also the auto_reconnect setting. + +buddy_sendbuffer + +Type: boolean + +By default, when you send a message to someone, BitlBee forwards this message +to the user immediately. When you paste a large number of lines, the lines will +be sent in separate messages, which might not be very nice to read. If you +enable this setting, BitlBee will buffer your messages and wait for more data. + +Using the buddy_sendbuffer_delay setting you can specify the number of seconds +BitlBee should wait for more data before the complete message is sent. + +Please note that if you remove a buddy from your list (or if the connection to +that user drops) and there's still data in the buffer, this data will be lost. +BitlBee will not try to send the message to the user in those cases. + +buddy_sendbuffer_delay + +Type: integer + +Tell BitlBee after how many seconds a buffered message should be sent. + +See also the buddy_sendbuffer setting. + +default_target + +Type: string + +With this value set to root, lines written in the control channel without any +nickname in front of them will be interpreted as commands. If you want BitlBee +to send those lines to the last person you addressed in the control channel, +set this to last. + +display_namechanges + +Type: boolean + +password + +Type: string + +Use this setting to change your "NickServ" password. + +query_order + +Type: string + +This changes the order in which the questions from root (usually authorization +requests from buddies) should be answered. When set to lifo, BitlBee +immediately displays all new questions and they should be answered in reverse +order. When this is set to fifo, BitlBee displays the first question which +comes in and caches all the others until you answer the first one. + +Although the fifo setting might sound more logical (and used to be the default +behaviour in older BitlBee versions), it turned out not to be very convenient +for many users when they missed the first question (and never received the next +ones). + +lcnicks + +Type: boolean + +Hereby you can change whether you want all lower case nick names or leave the +case as it intended by your peer. + +rename - Rename (renick) a buddy + +Syntax: + +rename <oldnick> <newnick> + +Renick a user in your buddy list. Very useful, in fact just very important, if +you got a lot of people with stupid account names (or hard ICQ numbers). + +< itsme> rename itsme_ you + * itsme_is now known as you + +yes - Accept a request + +Syntax: + +yes [<number>] + +Sometimes an IM-module might want to ask you a question. (Accept this user as +your buddy or not?) To accept a question, use the yes command. + +By default, this answers the first unanswered question. You can also specify a +different question as an argument. You can use the qlist command for a list of +questions. + +no - Deny a request + +Syntax: + +no [<number>] + +Sometimes an IM-module might want to ask you a question. (Accept this user as +your buddy or not?) To reject a question, use the no command. + +By default, this answers the first unanswered question. You can also specify a +different question as an argument. You can use the qlist command for a list of +questions. + +qlist - List all the unanswered questions root asked + +Syntax: + +qlist + +This gives you a list of all the unanswered questions from root. + +register - Register yourself + +Syntax: + +register <password> + +BitlBee can save your settings so you won't have to enter all your IM passwords +every time you log in. If you want the Bee to save your settings, use the +register command. + +Please do pick a secure password, don't just use your nick as your password. +Please note that IRC is not an encrypted protocol, so the passwords still go +over the network in plaintext. Evil people with evil sniffers will read it all. +(So don't use your root password.. ;-) + +To identify yourself in later sessions, you can use the identify command. + +identify - Identify yourself with your password + +Syntax: + +identify <password> + +BitlBee saves all your settings (contacts, accounts, passwords) on-server. To +prevent other users from just logging in as you and getting this information, +you'll have to identify yourself with your password. You can register this +password using the register command. + +Once you're registered, you can change your password using set password +<password>. + +drop - Drop your account + +Syntax: + +drop <password> + +Drop your BitlBee registration. Your account files will be removed and your +password will be forgotten. For obvious security reasons, you have to specify +your NickServ password to make this command work. + +blist - List all the buddies in your contact list + +Syntax: + +blist [all|online|offline|away] + +You can get a better readable buddy list using the blist command. If you want a +complete list (including the offline users) you can use the all argument. + +nick - Change friendly name, nick + +Syntax: + +nick <connection> [<new nick>] +nick + +This command allows to set the friendly name of an im account. If no new name +is specified the command will report the current name. When the name contains +spaces, don't forget to quote the whole nick in double quotes. Currently this +command is only supported by the MSN protocol. + +< wouter> nick 1 "Wouter Paesen" +< root> Setting your name on connection 1 to `Wouter Paesen' + +import_buddies - Copy local buddy list to server (normally only needed when +upgrading) + +Syntax: + +import_buddies <connection> [clear] + +This command copies the locally stored buddy list to the server. This command +exists for upgrading purposes. Previous versions of BitlBee didn't support +server-side buddy lists for ICQ, so the list was stored locally. + +Since version 0.91 however, server-side contact lists are supported for all +protocols, so the local list is now ignored. When upgrading from an older +BitlBee to version 0.91, you might need this command to get your buddy list +back. + +The only argument this command needs is your ICQ account identification. If +your serverside buddy list contains some old buddies you don't want anymore, +you can pass clear as a second argument. + +After giving this command, you have to wait for a while before all the adds are +handled, because of ICQ's rate limiting. If your buddy list is very large and +the ICQ server starts complaining, you might have to reconnect and enter this +command again. + +Chapter 6. Misc Stuff + +Table of Contents + +Smileys +Groupchats +Creating groupchats +Groupchat channel names +Away states + +Smileys + +All MSN smileys (except one) are case insensitive and work without the nose +too. + +(Y) + + Thumbs up + +(N) + + Thumbs down + +(B) + + Beer mug + +(D) + + Martini glass + +(X) + + Girl + +(Z) + + Boy + +(6) + + Devil smiley + +:-[ + + Vampire bat + +(}) + + Right hug + +({) + + Left hug + +(M) + + MSN Messenger or Windows Messenger icon (think a BitlBee logo here ;) + +:-S + + Crooked smiley (Confused smiley) + +:-$ + + Embarrassed smiley + +(H) + + Smiley with sunglasses + +:-@ + + Angry smiley + +(A) + + Angel smiley + +(L) + + Red heart (Love) + +(U) + + Broken heart + +(K) + + Red lips (Kiss) + +(G) + + Gift with bow + +(F) + + Red rose + +(W) + + Wilted rose + +(P) + + Camera + +(~) + + Film strip + +(T) + + Telephone receiver + +(@) + + Cat face + +(&) + + Dog's head + +(C) + + Coffee cup + +(I) + + Light bulb + +(S) + + Half-moon (Case sensitive!) + +(*) + + Star + +(8) + + Musical eighth note + +(E) + + Envelope + +(^) + + Birthday cake + +(O) + + Clock + +This list was extracted from http://help.msn.com/!data/en_us/data/ +messengerv50.its51/$content$/EMOTICONS.HTM?H_APP=. + +Groupchats + +Since version 0.8x, BitlBee supports groupchats on the MSN and Yahoo! networks. +This text will try to explain you how they work. + +As soon as someone invites you into a groupchat, you will be force-joined or +invited (depending on the protocol) into a new virtual channel with all the +people in there. You can leave the channel at any time, just like you would +close the window in regular IM clients. Please note that root-commands don't +work in groupchat channels, they only work in the control channel (or to root +directly). + +Of course you can also create your own groupchats. Type help groupchats2 to see +how. + +Creating groupchats + +If you want to start a groupchat with the person jim_msn in it, just join the +channel #jim_msn. BitlBee will refuse to join you to the channel with that +name, but it will create a new virtual channel with root, you and jim_msn in +it. + +Of course a channel with only two people isn't really exciting yet. So the next +step is to invite some other people to the channel. For this, you can use the / +invite command of your IRC client. Please do keep in mind that all the people +have to be on the same network and contact list! You can't invite Yahoo! +buddies into an MSN groupchat. + +This is all you'll probably need to know. If you have any problems, please read +help groupchats3. + +Groupchat channel names + +Obviously the (numbered) channel names don't make a lot of sense. Problem is +that groupchats usually don't have names at all in the IM-world, while IRC +insists on a name. So BitlBee just generates something random, just don't pay +attention to it. :-) + +Please also note that BitlBee doesn't support groupchats for all protocols yet. +BitlBee will tell you so. Support for other protocols will hopefully come +later. + +Away states + +As you might've expected, you can just use the /away command in your IRC client +to set an away-state. BitlBee supports most away-states supported by the +protocols. + +Not all away states are supported by all protocols, and some protocols have +different names for them. BitlBee will try to pick the best available alias +from this list for every connection: + +Away from computer, Away, Extended away +NA, N/A, Not available +Busy, Do not disturb, DND, Occupied +Be right back, BRB +On the phone, Phone, On phone +Out to lunch, Lunch, Food + +So /away Food will set your state to "Out to lunch" on your MSN connection, and +for most other connections the default, "Away" or "Away from computer" will be +chosen. + +You can also add more information to your away message. Setting it to "Busy - +Fixing BitlBee bugs" will set your IM-away-states to Busy, but your away +message will be more descriptive for people on IRC. Protocols like Yahoo! and +Jabber will also show this complete away message to your buddies. + diff --git a/doc/user-guide/user-guide.xml b/doc/user-guide/user-guide.xml new file mode 100644 index 00000000..eff5998e --- /dev/null +++ b/doc/user-guide/user-guide.xml @@ -0,0 +1,52 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<book id="BitlBee-User-Guide" xmlns:xi="http://www.w3.org/2003/XInclude"> +<bookinfo> + <title>BitlBee User Guide</title> + <author> + <firstname>Jelmer</firstname><surname>Vernooij</surname> + <address><email>jelmer@samba.org</email></address> + </author> + + <author> + <firstname>Wilmer</firstname><surname>van der Gaast</surname> + <address><email>wilmer@gaast.net</email></address> + </author> + + <author> + <firstname>Sjoerd</firstname><surname>Hemminga</surname> + <address><email>sjoerd@huiswerkservice.nl</email></address> + </author> + + <legalnotice id="legalnotice"> + <para> + Permission is granted to copy, distribute and/or modify this + document under the terms of the <ulink type="help" + url="gnome-help:fdl"><citetitle>GNU Free Documentation + License</citetitle></ulink>, Version 1.1 or any later version + published by the Free Software Foundation with no Invariant + Sections, no Front-Cover Texts, and no Back-Cover Texts. You + may obtain a copy of the <citetitle>GNU Free Documentation + License</citetitle> from the Free Software Foundation by + visiting <ulink type="http" url="http://www.fsf.org">their + Web site</ulink> or by writing to: Free Software Foundation, + Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, + USA. + </para> + </legalnotice> + + <releaseinfo> + This is the initial release of the BitlBee User Guide. + </releaseinfo> + + </bookinfo> + + <xi:include href="Installation.xml"/> + <xi:include href="Usage.xml"/> + <xi:include href="Support.xml"/> + <xi:include href="quickstart.xml"/> + <xi:include href="commands.xml"/> + <xi:include href="misc.xml"/> + +</book> |