diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/AUTHORS | 19 | ||||
| -rw-r--r-- | doc/BUILD.win32 | 10 | ||||
| -rw-r--r-- | doc/CHANGES | 957 | ||||
| -rw-r--r-- | doc/CREDITS | 64 | ||||
| -rw-r--r-- | doc/FAQ | 71 | ||||
| -rw-r--r-- | doc/HACKING | 125 | ||||
| -rw-r--r-- | doc/INSTALL | 1 | ||||
| -rw-r--r-- | doc/Makefile | 21 | ||||
| -rw-r--r-- | doc/README | 196 | ||||
| -rw-r--r-- | doc/bitlbee.8 | 119 | ||||
| -rw-r--r-- | doc/bitlbee.conf.5 | 19 | ||||
| -rw-r--r-- | doc/bitlbee.schema | 62 | ||||
| -rw-r--r-- | doc/bitlbee.xinetd | 24 | ||||
| -rw-r--r-- | doc/comic_3.0.png | bin | 0 -> 24638 bytes | |||
| -rw-r--r-- | doc/example_plugin.c | 14 | ||||
| -rw-r--r-- | doc/user-guide/Installation.xml | 114 | ||||
| -rw-r--r-- | doc/user-guide/Makefile | 50 | ||||
| -rw-r--r-- | doc/user-guide/Support.xml | 49 | ||||
| -rw-r--r-- | doc/user-guide/Usage.xml | 58 | ||||
| -rw-r--r-- | doc/user-guide/commands.xml | 1749 | ||||
| -rw-r--r-- | doc/user-guide/docbook.xsl | 137 | ||||
| -rw-r--r-- | doc/user-guide/help.xml | 64 | ||||
| -rw-r--r-- | doc/user-guide/help.xsl | 161 | ||||
| -rw-r--r-- | doc/user-guide/misc.xml | 368 | ||||
| -rw-r--r-- | doc/user-guide/quickstart.xml | 167 | ||||
| -rw-r--r-- | doc/user-guide/user-guide.xml | 41 |
26 files changed, 4660 insertions, 0 deletions
diff --git a/doc/AUTHORS b/doc/AUTHORS new file mode 100644 index 00000000..6dab1040 --- /dev/null +++ b/doc/AUTHORS @@ -0,0 +1,19 @@ +Current developers: + +Wilmer van der Gaast <wilmer@gaast.net> + Main developer + +Jelmer 'ctrlsoft' Vernooij <jelmer@samba.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/BUILD.win32 b/doc/BUILD.win32 new file mode 100644 index 00000000..e1afe600 --- /dev/null +++ b/doc/BUILD.win32 @@ -0,0 +1,10 @@ +Instructions for building BitlBee for Windows
+=============================================
+
+1) Install the mingw32 compiler
+
+2) Compile GLib2 for the target i586-mingw32msvc
+
+3) Cross-compile BitlBee:
+
+$ ./configure --target=i586-mingw32msvc --ssl=bogus --arch=Windows
diff --git a/doc/CHANGES b/doc/CHANGES new file mode 100644 index 00000000..38e4054d --- /dev/null +++ b/doc/CHANGES @@ -0,0 +1,957 @@ +This ChangeLog mostly lists changes relevant to users. A full log can be +found in the bzr commit logs, for example you can try: + +http://bugs.bitlbee.org/bitlbee/timeline?daysback=90&changeset=on + +Version 3.0.2: +- Fixed MSN login issues with @msn.com accounts. +- /CTCP support: You can CTCP VERSION Jabber contacts, and CTCP NUDGE MSN + contacts. More may come later, ideas are welcome. +- By default, leave Twitter turned on for libpurple builds. +- Allow using /OPER to identify/register as well. (Password security hack.) +- Fixed proxy support with libpurple. +- Some minor changes/fixes. + +Finished 7 Mar 2011 + +Version 3.0.1: +- Fixed some bugs that were found only after releasing 3.0, including + Jabber contacts never going offline, MSN login issues, compilation + issues on some non-Linux systems, a fairly big memory leak in the MSN + SOAP code, etc... +- Better handling of multiple control channels and set private=false. +- Using login.icq.com for ICQ logins again since AOL sold ICQ so it + doesn't live on the AIM servers anymore. +- Fixed ability to join password-protected Jabber rooms. +- Time out if logging into an account takes too long. +- Fixed NSS SSL module. +- Support for server-side Gadu-Gadu contact lists (via libpurple, there's + still no native gg support). +- Allow omitting password when using "account add", the password can be + entered using /OPER to prevent echoing to screen and logs. + +Finished 24 Nov 2010 + +Version 3.0: +- Important: This version drops backward compatibility with the file format + used for user settings in versions before 1.2. If you're upgrading from + very old BitlBee versions (like 1.0.x), you'll have to recreate your + BitlBee account - or use an 1.2.x BitlBee once to do the conversion. +- Rewrote the IRC core, which brings: + * Support for multiple (control) channels, so you can have one channel per + buddy group, per IM account/protocol, or for example a &offline with all + offline contacts. See "help channels" for information on how to use this. + * You can also leave and rejoin all channels. Being in &bitlbee is no + longer required. + * Now you can start groupchats by just joining a new channel and inviting + contacts. (The "chat with" command still works as well.) + * You can change your nickname, whenever you want. + * Root commands: + + To hopefully resolve confusion about the "account set" syntax, the + ordering was changed slightly: "account set acc/setting value" + becomes "account acc set setting value". Obviously the same order + should now be used for other account subcommands. + + Shortcuts: Instead of "account list" you can say "acc li". + * /whois shows idle/login times of your contacts when available. + * paste_buffer (previously known as buddy_sendbuffer) now works for chats + as well. + * The nick_source setting was replaced with a nick_format setting, which + looks more or less like a format string, and lets you tweak how nicknames + for contacts are generated in more detail. It also tries to convert non- + ASCII characters (i.e. accents) properly. + * A per-channel show_users setting lets you configure exactly which kinds + of contacts (online/away/offline) should show up in a channel and what + modes (none/voice/etc) they should have. Like show_offline, but together + with other new features it can for example create an &offline channel + with just offline contacts. + * If you connect (and identify) to a BitlBee server you're already + connected to, you can take over the existing session instead of starting + a new one. + * More correct validation of channel names: They can contain pretty much + any character, unlike nicknames. +- Support for using libpurple instead of BitlBee's built-in IM protocol + modules. This can be enabled by passing --purple=1 to the configure script. + * This adds support for many more IM protocols to BitlBee. + * And new functionality to existing protocols. + * This is and will always be optional and using it on public servers is + *not* recommended. It should be pretty stable, but costs more RAM/etc. + * Switching to libpurple should be pretty transparent. See "help purple" + for a list of supported protocols (works only in libpurple-enabled + binaries). +- Rewritten MSN module, implementing MSNP15 instead of the old MSNP8: + * MSNP8 support from MSN was getting pretty unreliable. There were issues + with remembering display names and adding contacts/auth requests (or + even contacts silently getting blocked!). This upgrade should fix all + of that. + * Support for sending offline messages. + * Support for setting and reading status messages. +- Integrated the bitlbee-otr branch in a mostly non-intrusive way. Since + this is not end-to-end it should *not* be enabled on public servers. + Distro packagers are requested to offer OTR as a separately installable + plugin. (Compile with --otr=plugin) Please do not enable it by default as + there is no easy way to disable OTR once the plugin is loaded/built in. +- Support for file transfers, in and out. /DCC SEND a file to a contact and + it becomes a file transfer, and incoming file transfers become /DCC SENDs + to you. Note that this is mostly useful when combined with libpurple, as + only the Jabber native protocol module currently supports file transfers. +- Updated Yahoo! module to be in sync again with libyahoo2. This mostly + fixes issues with authorization requests. +- Show if a contact is mobile or not. See "help set mobile_is_away". +- Easier handling of XMPP chatroom invitations. +- The chatroom mode of the Twitter module is now enabled by default, since + this was by far the most popular. To disable it, see "help set mode". +- Added some Twitter-specific commands that can only be used in the Twitter + window. Most important addition: Retweets. See "help set commands". +- Removed some ancient account/nick migration scripts and added one for + easier switching from Pidgin and other libpurple-based clients to BitlBee. +- Many bug fixes in both the core and IM modules, small feature enhancements + and other minor changes. + +Finished 22 Oct 2010 + +Version 1.2.8: +- Now always using the AIM-style authentication method for OSCAR connections, + even when connecting to ICQ. This solves login issues some people were + having. (If you have problems, try changing the old_icq_auth setting.) +- Twitter: + * Allow changing the Twitter API base URL so the module can also be used + for identi.ca or any other compatible network. + * Fetch the full list of Twitter contacts instead of slowly adding all + contacts as they post a message. + * Fixed message length counting. + * Allow following/unfollowing people using the usual add/remove commands. + * Better error reporting. +- Added a user_agent setting to the Jabber module to get around artificial + client restrictions. +- Allow nick changes (although only before register/identify). +- Some more minor bugfixes/etc. + +Finished 4 Jul 2010 + +Version 1.2.7: +- Fixed problems with MSN Messenger authentication. ("Could not parse + Passport server response") +- Fixed broken typing notifications when talking to GTalk contacts. +- Fixed an issue with non-anonymous Jabber chatrooms polluting the nick + namespace, sometimes generating odd warning messages. +- Restored ability to start groupchats on ICQ. +- Added show_offline setting that will also show offline contacts in the + control channel. +- OAuth support for Twitter: This means the module will keep working after + June (this also changes "via API" under your tweets into "via BitlBee"). + +Finished 15 May 2010 + +Version 1.2.6a: +- Fixed a typo that renders the Twitter groupchat mode unusable. A last- + minute change that came a few minutes late. + +Finished 19 Apr 2010 + +Version 1.2.6: +- Native (very basic) support for Twitter, implemented by Geert Mulders. + Currently supported are posting tweets, reading the ones of people you + follow, and sending (not yet receiving!) direct messages. +- Fixed format of status messages in /WHOIS to improve IRC client + compatibility. +- Show timestamps of offline messages/channel backlogs. +- Allow saving MSN display names locally since sometimes this stuff breaks + server-side. (Use the local_display_name per-account setting.) +- Suppress empty "Headline:" messages for certain new XMPP broadcast + messages. +- Better handling of XMPP contacts with multiple resources on-line. Default + behaviour now is to write to wherever the last message came from, or to + the bare JID (usually becomes a broadcast) if there wasn't any recent msg. +- Added a switchboard_keepalives setting which should solve some issues with + talking to offline MSN contacts. (Although full support for offline + messages is not ready yet!) +- The usual misc. bug fixes. + +Finished 19 Apr 2010 + +Version 1.2.5: +- Many bug fixes, including a fix for MSN login issues, Jabber login timing + issues, Yahoo! crashes at login time with huge contact lists, +- Avoid linking in a static version of libresolv now that glibc has all + relevant functions available in the dynamic version. +- Improved away state code and added the ability to set (non-away) status + messages using "set status" (also possible per account) and see them in + blist and /whois output. +- Added a post-1.2 equivalent of encode/decode to quickly encrypt/decrypt + passwords in a way that BitlBee can read them. +- Allow using the full name for generating nicknames, instead of just the + handle. This is especially useful when using the Facebook XMPP server. +- Auto reconnect is now enabled by default since all protocols can properly + detect cases where auto reconnect should be avoided (i.e. concurrent + logins). +- Changed the default resource_select setting which should reduce message + routing issues on Jabber (i.e. messages going someone's phone instead of + the main client). + +Finished 17 Mar 2010 + +Version 1.2.4: +- Most important change (and main reason for releasing now): Upgraded Yahoo! + module to a newer version to get it working again. +- join_chat command replaced with the much better chat command: + * Similar to how account replaced login/slist/logout. Add a chatroom once, + then just /join it like any other room. Also automatic joining at login + time is now possible. + * Note that the old way of starting groupchats (/join #nickname) is now + also deprecated, use "chat with" instead. + * See "help chat" and "help chat add" for more information. +- Rewrote bitlbee.conf parser to be less dumb. +- Fixed compatibility (hopefully) with AIM mobile messages, certain kinds + of Google Talk chatrooms. +- Fixed numerous stability/reliability bugs over the last year. + +Finished 17 Oct 2009 + +Version 1.2.3: +- Fixed one more flaw similar to the previous hijacking bug, caused by incon- + sistent handling of the USTATUS_IDENTIFIED state. All code touching these + variables was reviewed and should be correct now. + +Finished 7 Sep 2008 + +Version 1.2.2: +- Security bugfix: It was possible to hijack accounts (without gaining access + to the old account, it's simply an overwrite) +- Some more stability improvements. +- Fixed bug where people with non-lowercase nicks couldn't drop their account. +- Easier upgrades of non-forking daemon mode servers (using the DEAF + command). +- Can be cross-compiled for Win32 now! (No support for SSL yet though, which + makes it less useful for now.) +- Exponential backoff on auto-reconnect. +- Changing passwords gives less confusing feedback ("password is empty") now. + +Finished 26 Aug 2008 + +Version 1.2.1: +- Fixed proxy support. +- Fixed stalling issues while connecting to Jabber when using the OpenSSL + module. +- Fixed problem with GLib and ForkDaemon where processes didn't die when + the client disconnects. +- Fixed handling of "set charset none". (Which pretty much breaks the account + completely in 1.2.) +- You can now automatically identify yourself to BitlBee by setting a server + password in your IRC client. +- Compatible with all crazy kinds of line endings that clients can send. +- Changed root nicknames are now saved. +- Added ClientInterface setting to bind() outgoing connections to a specific + network interface. +- Support for receiving Jabber chatroom invitations. +- Relaxed port restriction of the Jabber module: added ports 80 and 443. +- Preserving case in Jabber resources of buddies, since these should + officially be treated as case sensitive. +- Fully stripping spaces from AIM screennames, this didn't happen completely + which severly breaks the IRC protocol. +- Removed all the yellow tape around daemon mode, it's pretty mature by now: + testing.bitlbee.org serves all (~30) SSL users from one daemon mode + process without any serious stability issues. +- Fixed GLib <2.6 compatibility issue. +- Misc. memory leak/crash fixes. + +Finished 24 Jun 2008 + +Version 1.2: +- Added ForkDaemon mode next to the existing Daemon- and inetd modes. With + ForkDaemon you can run BitlBee as a stand-alone daemon and every connection + will run in its own process. No more need to configure inetd, and still you + don't get the stability problems BitlBee unfortunately still has in ordinary + (one-process) daemon mode. +- Added inter-process/connection communication. This made it possible to + implement some IRC operator features like WALLOPs, KILL, DIE, REHASH and + more. +- Added hooks for using libevent instead of GLib for event handling. This + should improve scalability, although this won't really be useful yet because + the one-process daemon mode is not reliable enough. +- BitlBee now makes the buddy quits when doing "account off" look like a + netsplit. Modern IRC clients show this in a different, more compact way. + (This can be disabled if your client doesn't support this.) +- GLib 1.x compatibility was dropped. BitlBee now requires GLib 2.4 or newer. + This allows us to use more GLib features (like the XML parser). By now GLib + 1.x is so old that supporting it really isn't necessary anymore. +- Many, many, MANY little changes, improvements, fixes. Using non-blocking + I/O as much as possible, replaced the Gaim (0.59, IOW heavily outdated) + API, fixed lots of little bugs (including bugs that affected daemon mode + stability). See the bzr logs for more information. +- One of the user-visible changes from the API change: You can finally see + all away states/messages properly. +- Added units tests. Test coverage is very minimal for now. +- Better charset handling: Everything is just converted from/to UTF-8 right + in the IRC core, and charset mismatches are detected (if possible) and the + user is asked to resolve this before continuing. Also, UTF-8 is the default + setting now, since that's how the world seems to work these days. +- One can now keep hashed passwords in bitlbee.conf instead of the cleartext + version. +- Most important change: New file format for user data (accounts, nicks and + settings). Migration to the new format should happen transparently, + BitlBee will read the old files and once you quit/save it will save in the + new format. It is recommended to delete the old files (BitlBee doesn't do + this automatically, it will just ignore them) since they won't be used + anymore (and since the old file format is a security risk). Some advantages + of this file format switch: + * Safer format, since the identify-password is now salted before generating + a checksum. This way one can't use MD5 reverse lookup databases to crack + passwords. Also, the IM-account passwords are encrypted using RC4 instead + of the simple obfuscation scheme which BitlBee used so far. + * Easier to extend than the previous format (at least the .nicks format was + horribly limited). + * Nicknames for buddies are now saved per-account instead of per-protocol. + So far having one buddy on multiple accounts of the same protocol was a + problem because the nicks generated for the two "instances" of this buddy + were very unpredictable. + NOTE: This also means that "account del" removes not just the account, + BUT ALSO ALL NICKNAMES! If you're changing IM accounts and don't want to + lose the nicknames, you can now use "account set" to change the username + and password for the existing connection. + * Per-account settings (see the new "account set" command). +- A brand new Jabber module. Besides the major code cleanup, it also has + has these new features: + * Pretty complete XMPP support: RFC3920, RFC3921 plus a number of XEPs + including XEP45, XEP73 and XEP85. (See http://www.xmpp.org/ for what all + these things mean exactly.) Privacy lists are not supported for obvious + reasons. + * This complete support also includes TLS and SASL support and SRV record + lookup. This means that specifying a server tag for connections should + (almost) never be necessary anymore, BitlBee can find the server and can + automatically convert plaintext connections to TLS-encrypted ones. + * XEP45: Jabber chatroom support! + * XEP85 means typing notifications. The older XEP22 (still used by some + clients including Gaim <2.0) is not supported. + * Better handling of buddies who have more than one resource on-line. As + long as one resource is on-line (and visible), BitlBee will show this. + (The previous module didn't keep track of resources and sent an offline + event as soon as any resource disappears.) + * You can now set your resource priority. + * The info command now gives away state/message information for all + resources available for that buddy. (Of course this only works if the + buddy is in your contact list.) + * An XML console (add xmlconsole to your contact list or see "help set + xmlconsole" if you want it permanently). +- The Yahoo! module now says it supports YMSG protocol version 12, which will + hopefully keep the Yahoo module working after 2008-04-02 (when Yahoo! is + dropping support for version 6.x of their client). +- MSN switchboard handling changes. Hopefully less messages will get lost now, + although things are still not perfect. + +Finished 17 Mar 2008 + +Version 1.0.4: +- Removed sethostent(), which causes problems for many people, especially on + *BSD. This is basically the reason for this release. +- "allow" command actually displays the allow list, not the block list. +- Yahoo away state/msg fix. +- Don't display "Gender: Male" by default if nothing's filled in (OSCAR + "info" command) +- Fixed account cleanup (possible infinite loop) in irc_free(). +- Fixed configdir error message to not always display the compile-time + setting. + +Finished 20 Aug 2007 + +Version 1.0.3: +- Fixed ugliness in block/allow list commands (still not perfect though, the + list is empty or not up-to-date for most protocols). +- OSCAR module doesn't send the ICQ web-aware flag anymore, which seems to + get rid of a lot of ICQ spam. +- added show_got_added(), BitlBee asks you, after authorizing someone, if you + want to add him/her to your list too. +- add -tmp, mainly convenient if you want to talk to people who are not in + your list. +- Fixed ISON command, should work better with irssi now. +- Fixed compilation with tcc. +- Fixed xinetd-file. +- Misc. (crash)bug fixes, including one in the root command parsing that + caused mysterious error messages sometimes. + +Finished 24 Jun 2006 (Happy 4th birthday, BitlBee!) + +Version 1.0.2: +- Pieces of code cleanup, fixes for possible problems in error checking. +- Fixed an auto-reconnect cleanup problem that caused crashes in daemon mode. +- /AWAY in daemon mode now doesn't set the away state for every connection + anymore. +- Fixed a crash-bug on empty help subjects. +- Jabber now correctly sets the current away state when connecting. +- Added Invisible and Hidden to the away state alias list, invisible mode + should be pretty usable now. +- Fixed handling of iconv(): It's now done for everything that goes between + BitlBee and the IRC client, instead of doing it (almost) every time + something goes to or come from the IM-modules. Should've thought about + that before. :-) +- When cleaning up MSN switchboards with unsent msgs, it now also says which + contact those messages were meant for. +- You can now use the block and allow commands to see your current block/ + allow list. + +Finished 1 Apr 2006 + +Version 1.0.1: +- Support for AIM groupchats. +- Improved typing notification support for at least AIM. +- BitlBee sends a 005 reply when logging in, this informs modern IRC clients + of some of BitlBee's capabilities. This might also solve problems some + people were having with the new control channel name. +- MSN switchboards are now properly reset when talking to a person who is + offline. This fixes problems with messages to MSN people that sometimes + didn't arrive. +- Fixed one of the problems that made BitlBee show online Jabber people as + offline. +- Fixed problems with commas in MSN passwords. +- Added some consts for read-only data, which should make the BitlBee per- + process memory footprint a bit smaller. +- Other bits of code cleanup. + +Finished 14 Jan 2006 + +Version 1.0: +- Removed some crashy debugging code. +- QUIT command now works before logging in. (Mainly an RFC-compliancy fix.) +- Hopefully slightly clearer handling of buddy add requests. +- set buddy_sendbuffer_delay now also supports milisecond precision. +- Renamed #bitlbee to &bitlbee to avoid confusion with the channel on OFTC. +- Reviewed the xinetd file and installation instructions. +- HTML stripping is configurable again. +- Quit messages (at least on crashes) should appear again. +- Cleaned up some unnecessary code in the Jabber module, and implemented + handlers for headline messages (which allows you to use RSS-to-Jabber + gateways). +- Lowered the line splitting limit a bit to fix data loss issues. +- The $proto($handle) format used for messages specific to one IM-connection + now only include the ($handle) part when there's more than one $proto- + connection. +- Fix for a crash-bug on broken Jabber/SSL connections. +- Incoming typing notifications now also come in as CTCP TYPING messages, for + better consistency. Don't forget to update your scripts! +- AIM typing notifications are supported now. +- Jabber module only accepts ports 5220-5229 now, to prevent people from + abusing it as a port scanner. We aren't aware of any Jabber server that + runs on other ports than those. If you are, please warn us. +- Send flood protection can't be enabled anymore. It was disabled by default + for a good reason for some time already, but some package maintainers + turned it back on while it's way too unreliable and trigger-happy to be + used. +- Removed TODO file, the current to-do list is always in the on-line bug + tracking system. +- Fixed a potential DoS bug in input handling. + +Finished 4 Dec 2005 + +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..d53f6de0 --- /dev/null +++ b/doc/CREDITS @@ -0,0 +1,64 @@ +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. +- infamous41md, for security auditing BitlBee code. +- Tijmen Ruizendaal, for some useful BitlBee-related irssi scripts. +- Ed Schouten, for reporting bugs. +- Greg (gropeep.org), for updating the Yahoo! module to fix some issues + that were there for quite some time already. +- misc@mandriva.org for lots of Jabber contributions. + +- 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..e4fdcaed --- /dev/null +++ b/doc/FAQ @@ -0,0 +1,71 @@ +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: When is $random_feature going to be implemented? +A: It depends on the feature. We keep a list of all wishlist "bugs" in our + Bug Tracking system at http://bugs.bitlbee.org/ + +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 strip_html". If you seem to have problems with your charset, + see "help set charset". + + Although actually most of these problems should be gone by now. So if you + can't get things to work well, you might have found a bug. + +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, Jabber and Twitter modules from + scratch. Most of the API has also been changed, so by now the only traces + of Gaim left are in the "nogaim" filename. + + There is good news for Gaim (or now Pidgin, of course) fans though: + BitlBee can now be compiled to use libpurple for all IM interactions. + This makes BitlBee a bit more resource-hungry, but adds support for many + IM protocols/networks that couldn't be used from BitlBee so far. diff --git a/doc/HACKING b/doc/HACKING new file mode 100644 index 00000000..9d064d58 --- /dev/null +++ b/doc/HACKING @@ -0,0 +1,125 @@ +BitlBee post-1.x "architecture" + +DISCLAIMER: The messy architecture is being cleaned up. Although lots of +progress was made already, this is still a work in progress, and possibly +parts of this document aren't entirely accurate anymore by the time you +read this. + +It's been a while since BitlBee started, as a semi-fork of Gaim (version +0.58 at the time). Some people believe nothing changed, but fortunately, +many things have. + +The API is gone for a while already - which wasn't incredibly intrusive, +just a few functions renamed for slightly better consistency, added some +calls and arguments where that seemed useful, etc. + +However, up to late in the 1.2 series, the IRC core was still spread accross +several files, mostly irc.c + irc_commands.c and pieces and bits in +nogaim.c. If you're looking for a textbook example of layer violation, start +there. + +This was all finally redone. Most of the IRC protocol code was rewritten, +as was most of the glue between that and the IM modules. + +The core of BitlBee is now protocols/bee*. Some pieces are still left in +protocols/nogaim*. Most stuff in the "root" directory belongs to the IRC +UI, which should be considered "a" frontend (although currently, and +possibly forever, the only one). Every subdirectory of protocols/ is another +IM protocol backend (including purple/ which uses libpurple to define +many different protocols). + + +/ + +The IRC core has code to show an IRC interface to a user, with contacts, +channels, etc. To make channels and contacts do something, you add event +handlers (that translate a message sent to a nick into an instant message +to an IM contact, or translates joining a channel into joining an IM +chatroom). + +To get events back from the BitlBee core, the bee_t object has a bunch of +functions (struct bee_ui_funcs) that catch them and convert them back to +IRC. + +Short description of what all irc*.c files (and some related ones) do: + +bitlbee.c: BitlBee bootstrap code, doing bits of I/O as well. +ipc.c: For inter-process communication - communication between BitlBee + sessions. Also used in daemon mode (in which it's not so much inter- + process). +irc.c: The main core, with bits of I/O handling, parsing, etc. +irc_channel.c: Most things related to standard channels (also defines some + of the control channel behaviour). +irc_commands.c: Defines all IRC commands (JOIN, NICK, PRIVMSG, etc.). +irc_im.c: Most of the glue between IRC and the IM core live here. This is + where instant messages are converted to IRC and vice versa, contacts + coming online is translated to one or more joins and/or mode changes. +irc_send.c: Simple functions that send pieces of IRC output. Somewhat + random, but if an IRC response is slightly more complicated than just a + simple line, make it a function here. +irc_user.c: Defines all IRC user details. Mostly defines the user "object". +irc_util.c: Misc. stuff. Not much ATM. +nick.c: Handling of nicknames: compare, ucase/lcase, generating and storing + nicks for IM contacts. +set.c: Settings management, used for user-changeable global/account/channel + settings. Should really be considered part of the core. +storage*.c: Storing user accounts. (The stuff you normally find in + /var/lib/bitlbee) + + +/protocols + +The IM core lives in protocols/. Whenever you write code there, try to avoid +using any IRCisms there. + +Most header files in there have some of their details explained in comments. +bee*.c and nogaim.c are the layer between the IM modules and the IRC +frontend. They keep track of IM accounts, contacts and their status, +groupchats, etc. + +You can control them by calling functions in there if available, and +otherwise by just calling the functions exported via the prpl struct. Most +of these functions are briefly explained in the header files, otherwise the +best documentation is sadly in irc_im.c and root_commands.c. + +Events from the IM module go back to the core + frontend via imcb_* +functions defined in bee*.c and nogaim.c. They're all described in the +header files. + + +/lib + +BitlBee uses GLib, which is a pretty nifty library adding a bunch of things +that make life of a C coder better. Please try to not use features from +recent GLib versions as whenever this happens, some people get cranky. :> + +There's also a whole bunch of nice stuff in lib/ that you can use: + +arc.c: ARC4 encryption, mostly used for encrypting IM passwords in the XML + storage module. +base64.c +events_*.c: Event handling, using either GLib (default) or libevent (may + make non-forking daemon mode with many users a little bit more efficient). +ftutil.c: Some small utility functions currently just used for file transfers. +http_client.c: A simple (but asynchronous) HTTP(S) client, used by the MSN, + Yahoo! and Twitter module by now. +ini.c: Simple INI file parser, used to parse bitlbee.conf. +md5.c +misc.c: What the name says, really. +oauth.c: What the name says. If you don't know what OAuth is, ask Google. + Currently only used by the Twitter module. Implements just version 1a ATM. +proxy.c: Used together with events_*.c for asynchronous I/O directly or via + proxies. +sha1.c +ssl_*.c: SSL client stuff, using GnuTLS (preferred) or OpenSSL. Other modules + aren't working well ATM. +url.c: URL parser. +xmltree.c: Uses the GLib stream parser to build XML parse trees from a stream + and convert the same structs back into XML. Good enough to do Jabber but + not very aware of stuff like XML namespaces. Used for Jabber and Twitter. + +This, together with the headerfile comments, is most of the documentation we +have right now. If you're trying to make some changes to BitlBee, do feel +free to join #bitlbee on irc.oftc.net to ask any question you have. +Suggestions for specific parts to document a little bit more are also +welcome. 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..5f59879e --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,21 @@ +-include ../Makefile.settings +ifdef SRCDIR +SRCDIR := $(SRCDIR)doc/ +endif + +all: + # Only build the docs if this is a bzr checkout + test ! -d ../.bzr || $(MAKE) -C user-guide + +install: + mkdir -p $(DESTDIR)$(MANDIR)/man8/ $(DESTDIR)$(MANDIR)/man5/ + install -m 0644 $(SRCDIR)bitlbee.8 $(DESTDIR)$(MANDIR)/man8/ + install -m 0644 $(SRCDIR)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..5a3bb66e --- /dev/null +++ b/doc/README @@ -0,0 +1,196 @@ +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. + +--- (Fork)Daemon mode + +These days ForkDaemon mode is the recommended way of running BitlBee. The +difference between Daemon and ForkDaemon mode is that in the latter, a +separate process is spawned for every user. This costs a little bit more +memory, but means that if one user hits a bug in the code, not all other +users get disconnected with him/her. + +To use BitlBee in any daemon mode, just start it with the right flags or +enable it in bitlbee.conf (see the RunMode option). You probably want to +write an init script to start BitlBee automatically after a reboot. (This +is where you realise using a package from your distro would've been a better +idea. :-P) + +Please do make sure that the user BitlBee runs as (not root, please!) is +able to read from and write to the /var/lib/bitlbee directory to save your +settings! + +--- inetd installation (more or less deprecated) + +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. + +*BSD/Darwin/OSX NOTE: Most *BSD inetds are more scrict than the one that +comes with Linux systems. Possibly all non-Linux inetds are like this. They +don't allow you to specify a port number in the inetd.conf entry, instead +you have to put a service name there (one that is also mentioned in +/etc/services). So if there's no line in /services for 6667/tcp (or whatever +you choose), add it and use that name in the inetd.conf entry. + +-- xinetd installation (equally deprecated) + +Most machines use xinetd instead of inetd these days. If your machine runs +xinetd, you can copy the bitlbee.xinetd file from the doc/ directory to your +xinetd.d/ directory. Most likely you'll have to change a thing or two before +it'll work. + +After configuring your (x)inetd, send the daemon a SIGHUP and things should +work. If not, see your syslogs, since both daemons will complain there when +something's wrong. + +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. + + +DEPENDENCIES +============ + +BitlBee's only real dependency is GLib. This is available on virtually every +platform. Any recent version of GLib (2.4 or higher) will work. + +Off-the-Record encryption support can be included if libotr is available on +your machine. Pass --otr=1 to configure to build it into BitlBee, or +--otr=plugin to build it as a separate loadable plugin (mostly meant for +distro packages). + +These days, many IM protocols use SSL/TLS connections (for authentication +or for the whole session). BitlBee can use several SSL libraries for this: +GnuTLS, NSS (which comes with Mozilla) and OpenSSL. OpenSSL is not GPL- +compatible in some situations, so using GnuTLS 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 +================== + +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. + +Also, the configure script is known to not work very well with non-Bash +shells, so if you experience problems, make sure you use bash to run the +script. Same for the Makefile, it only works well with GNU make. (gmake on +most BSD systems) + +If someone can tell us how to write Makefiles that work with both/all +versions of make, we'd love to hear it, but it seems this just isn't +possible. + + +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/ + +The bug tracking system: +http://bugs.bitlbee.org/ + +Our version control system is Bazaar. Our repository is at: +http://code.bitlbee.org/ + +More documentation on the Wiki: +http://wiki.bitlbee.org/ + + +A NOTE ON PASSWORD ENCRYPTION +============================= + +There used to be a note here about the simple obfuscation method used to +make the passwords in the configuration files unreadable. However, BitlBee +now uses a better format (and real encryption (salted MD5 and RC4)) to store +the passwords. This means that people who somehow get their hands on your +configuration files can't easily extract your passwords from them anymore. + +However, once you log into the BitlBee server and send your password, an +intruder with tcpdump can still read your passwords. This can't really be +avoided, of course. The new format is a lot more reliable (because it can't +be cracked with just very basic crypto analysis anymore), but you still have +to be careful. The main extra protection offered by the new format is that +the files can only be cracked with some help from the user (by sending the +password at login time). + +So if you run a public server, it's most important that you don't give root +access to people who like to play with tcpdump. Also, it's a good idea to +delete all *.nicks/*.accounts files as soon as BitlBee converted them to the +new format (which happens as soon as the user logs in, it can't be done +automatically because it needs the password for that account). You won't +need them anymore (unless you want to switch back to an older BitlBee +version) and they only make it easier for others to crack your passwords. + + +LEGAL +===== + +BitlBee is distributed under the GPL (GNU General Public License). See the +file COPYING for this license. + +The MD5 algorithm code is licensed under the Aladdin license. This license +can be found in the files, to which this applies. The SHA1 algorithm code +is licensed under the Mozilla Public License, see http://www.mozilla.org/MPL/ +for details. + +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-2010 Wilmer van der Gaast <wilmer@gaast.net> + and others diff --git a/doc/bitlbee.8 b/doc/bitlbee.8 new file mode 100644 index 00000000..d01ec39e --- /dev/null +++ b/doc/bitlbee.8 @@ -0,0 +1,119 @@ +.\" 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. It currently supports Oscar (AIM and ICQ), +MSN, Jabber, Yahoo! and Twitter. + +\fBbitlbee\fP should be called by +.BR inetd (8), +or you can run it as a stand-alone daemon. +.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. +.IP "-F" +Run in ForkDaemon mode. This is similar to ordinary daemon mode, but every +client gets its own process. Easier to set up than inetd mode, and without +the possible stability issues. +.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 at +\fBhttp://bugs.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 <wilmer@gaast.net> +.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.schema b/doc/bitlbee.schema new file mode 100644 index 00000000..3322e057 --- /dev/null +++ b/doc/bitlbee.schema @@ -0,0 +1,62 @@ +## LDAP Schema file for BitlBee +## Copyright (C) 2006 Jelmer Vernooij <jelmer@samba.org> +## +## We need the following object classes and related attributes: +## +## bitlBeeBuddy: +## - nick +## - handle + +## each bitlBeeNick has zero or more bitlBeeAccount subentries +## and bitlBeeAccount entries contain zero or more bitlBeeBuddy entries + +## The admin needs to setup the LDAP server to: +## - allow anonymous users to auth against bitlBeeNick objects on the +## password field +## - allow anonymous users to create new objects that start with nick= +## - allow read/write for a user that is authenticated only to his/her own +## object and subentries + +## - userid +## - userPassword +## - setting (multiple values) +## depends: top, account + +attributetype ( 1.3.6.1.4.1.25873.2.1.1 NAME 'bitlBeeAutoConnect' + DESC 'Autoconnect setting' + EQUALITY booleanMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 SINGLE-VALUE ) + +attributetype ( 1.3.6.1.4.1.25873.2.1.2 NAME 'bitlBeeAccountNo' + DESC 'Account number' + EQUALITY integerMatch + SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) + +objectclass ( 1.3.6.1.4.1.25873.2.2.3 NAME 'bitlBeeAccount' SUP account STRUCTURAL + DESC 'BitlBee User Account ' + MUST ( userid, userPassword ) + MAY ( ) ) + +## bitlBeeAccount: +## - accountNo 1.3.6.1.4.1.1466.115.121.1.27 +## - protocol (msn, oscar, jabber, yahoo, ...) +## - username +## - password +## - server name +## - autoconnect (true/false) 1.3.6.1.4.1.1466.115.121.1.7 +## depends: top + +objectclass ( 1.3.6.1.4.1.25873.2.2.1 NAME 'bitlBeeIMAccount' SUP account STRUCTURAL + DESC 'BitlBee IM Account ' + MUST ( bitlBeeAccountNo, userid, userPassword ) + MAY ( host, bitlBeeAutoconnect ) ) + +objectclass ( 1.3.6.1.4.1.25873.2.2.2 NAME 'bitlBeeSetting' SUP top STRUCTURAL + DESC 'BitlBee Configuration Setting' + MUST ( bitlBeeSettingName ) + MAY ( bitlBeeSettingValue ) ) + +objectclass ( 1.3.6.1.4.1.25873.2.2.3 NAME 'bitlBeeBuddy' SUP top STRUCTURAL + DESC 'BitlBee Nick Mapping' + MUST ( bitlBeeBuddyHandle ) + MAY ( ircNick ) ) diff --git a/doc/bitlbee.xinetd b/doc/bitlbee.xinetd new file mode 100644 index 00000000..88d02013 --- /dev/null +++ b/doc/bitlbee.xinetd @@ -0,0 +1,24 @@ +## xinetd file for BitlBee. Please check this file before using it, the +## user, port and/or binary location might be wrong. + +## This file assumes you have ircd somewhere in your /etc/services, if things +## don't work, check that file first. +service ircd +{ + socket_type = stream + protocol = tcp + wait = no + + ## You most likely want to change these two + user = nobody + server = /usr/local/sbin/bitlbee + + ## You might want to limit access to localhost only: + # bind = 127.0.0.1 + + ## Thanks a lot to friedman@splode.com for telling us about the type + ## argument, so now this file can be used without having to edit + ## /etc/services too. + type = UNLISTED + port = 6667 +} diff --git a/doc/comic_3.0.png b/doc/comic_3.0.png Binary files differnew file mode 100644 index 00000000..f0fbc3ee --- /dev/null +++ b/doc/comic_3.0.png diff --git a/doc/example_plugin.c b/doc/example_plugin.c new file mode 100644 index 00000000..a33907a8 --- /dev/null +++ b/doc/example_plugin.c @@ -0,0 +1,14 @@ +/* + * This is the most simple possible BitlBee plugin. To use, compile it as + * a shared library and place it in the plugin directory: + * + * gcc -o example.so -shared example.c `pkg-config --cflags bitlbee` + * cp example.so /usr/local/lib/bitlbee + */ +#include <stdio.h> +#include <bitlbee.h> + +void init_plugin(void) +{ + printf("I am a BitlBee plugin!\n"); +} 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..2a80ea6c --- /dev/null +++ b/doc/user-guide/Makefile @@ -0,0 +1,50 @@ +-include ../../Makefile.settings +ifdef SRCDIR +SRCDIR := $(SRCDIR)doc/user-guide/ +endif + +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/xhtml/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 commands.xml misc.xml quickstart.xml + 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 $(SRCDIR)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..c9f50a5f --- /dev/null +++ b/doc/user-guide/Support.xml @@ -0,0 +1,49 @@ +<chapter id="Support"> + +<title>Support</title> + +<sect1> +<title>Disclaimer</title> + +<para> +BitlBee doesn't come with a warranty and is still (and will probably always +be) under development. 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, or at least don't blame us if things blow up. :-) +</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..167a74e0 --- /dev/null +++ b/doc/user-guide/Usage.xml @@ -0,0 +1,58 @@ +<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> + +<para> +You might be slightly confused by the & in the channel name. This is, +however, completely allowed by the IRC standards. Just try it on a regular +IRC server, it should work. The difference between the standard #channels +and &channels is that the #channels are distributed over all the servers +on the IRC network, while &channels are local to one server. Because +the BitlBee control channel is local to one server (and in fact, to one person), +this name seems more suitable. Also, with this name, it's harder to confuse +the control channel with the #bitlbee channel on OFTC. +</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..85003f24 --- /dev/null +++ b/doc/user-guide/commands.xml @@ -0,0 +1,1749 @@ +<chapter id="commands"> + <title>Bitlbee commands</title> + + <command-list/> + + <bitlbee-command name="account"> + <short-description>IM-account list maintenance</short-description> + <syntax>account [<account id>] <action> [<arguments>]</syntax> + + <description> + + <para> + Available actions: add, del, list, on, off and set. See <emphasis>help account <action></emphasis> for more information. + </para> + + </description> + + <bitlbee-command name="add"> + <syntax>account add <protocol> <username> [<password>]</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), Yahoo and Twitter. For more information about adding an account, see <emphasis>help account add <protocol></emphasis>. + </para> + + <para> + You can omit the password and enter it separately using the IRC /OPER command. This lets you enter your password without your IRC client echoing it on screen or recording it in logs. + </para> + </description> + + <bitlbee-command name="jabber"> + <syntax>account add jabber <handle@server.tld> [<password>]</syntax> + + <description> + <para> + The handle should be a full handle, including the domain name. You can specify a servername if necessary. Normally BitlBee doesn't need this though, since it's able to find out the server by doing DNS SRV lookups. + </para> + + <para> + In previous versions it was also possible to specify port numbers and/or SSL in the server tag. This is deprecated and should now be done using the <emphasis>account set</emphasis> command. This also applies to specifying a resource in the handle (like <emphasis>wilmer@bitlbee.org/work</emphasis>). + </para> + </description> + </bitlbee-command> + + <bitlbee-command name="msn"> + <syntax>account add msn <handle@server.tld> [<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>]</syntax> + + <description> + <para> + OSCAR is the protocol used to connect to AIM and/or ICQ. The servers will automatically detect if you're using a numeric or non-numeric username so there's no need to tell which network you want to connect to. + </para> + </description> + + <ircexample> + <ircline nick="wilmer">account add oscar 72696705 hobbelmeeuw</ircline> + <ircline nick="root">Account successfully added</ircline> + </ircexample> + </bitlbee-command> + + <bitlbee-command name="twitter"> + <syntax>account add twitter <handle> [<password>]</syntax> + + <description> + <para> + This module gives you simple access to Twitter and Twitter API compatible services. + </para> + + <para> + By default all your Twitter contacts will appear in a new channel called #twitter_yourusername. You can change this behaviour using the <emphasis>mode</emphasis> setting (see <emphasis>help set mode</emphasis>). + </para> + + <para> + To send tweets yourself, send them to the twitter_(yourusername) contact, or just write in the groupchat channel if you enabled that option. + </para> + + <para> + Since Twitter now requires OAuth authentication, you should not enter your Twitter password into BitlBee. Just type a bogus password. The first time you log in, BitlBee will start OAuth authentication. (See <emphasis>help set oauth</emphasis>.) + </para> + + <para> + To use a non-Twitter service, change the <emphasis>base_url</emphasis> setting. For identi.ca, you can simply use <emphasis>account add identica</emphasis>. + </para> + </description> + </bitlbee-command> + + <bitlbee-command name="identica"> + <syntax>account add identica <handle> [<password>]</syntax> + + <description> + <para> + Same protocol as <emphasis>twitter</emphasis>, but defaults to a <emphasis>base_url</emphasis> pointing at identi.ca, and with OAuth disabled. + </para> + </description> + </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 <account id> del</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/tag (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 [<account id>] on</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 that have the auto_connect flag set. + </para> + + <para> + The account ID can be a number/tag (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 [<account id>] off</syntax> + + <description> + <para> + This command disconnects the connection for the specified account. If no account is specified, BitlBee will deactivate all active accounts and cancel all pending reconnects. + </para> + + <para> + The account ID can be a number/tag (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. + </para> + </description> + </bitlbee-command> + + <bitlbee-command name="set"> + <syntax>account <account id> set</syntax> + <syntax>account <account id> set <setting></syntax> + <syntax>account <account id> set <setting> <value></syntax> + <syntax>account <account id> set -del <setting></syntax> + + <description> + <para> + This command can be used to change various settings for IM accounts. For all protocols, this command can be used to change the handle or the password BitlBee uses to log in and if it should be logged in automatically. Some protocols have additional settings. You can see the settings available for a connection by typing <emphasis>account <account id> set</emphasis>. + </para> + + <para> + For more infomation about a setting, see <emphasis>help set <setting></emphasis>. + </para> + + <para> + The account ID can be a number/tag (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> + + <bitlbee-command name="channel"> + <short-description>Channel list maintenance</short-description> + <syntax>channel [<account id>] <action> [<arguments>]</syntax> + + <description> + <para> + Available actions: del, list, set. See <emphasis>help channel <action></emphasis> for more information. + </para> + + <para> + There is no <emphasis>channel add</emphasis> command. To create a new channel, just use the IRC <emphasis>/join</emphasis> command. See also <emphasis>help channels</emphasis> and <emphasis>help groupchats</emphasis>. + </para> + </description> + + <bitlbee-command name="del"> + <syntax>channel <channel id> del</syntax> + + <description> + <para> + Remove a channel and forget all its settings. You can only remove channels you're not currently in, and can't remove the main control channel. (You can, however, leave it.) + </para> + </description> + + </bitlbee-command> + + <bitlbee-command name="list"> + <syntax>channel list</syntax> + + <description> + <para> + This command gives you a list of all the channels you configured. + </para> + </description> + + </bitlbee-command> + + <bitlbee-command name="set"> + <syntax>channel [<channel id>] set</syntax> + <syntax>channel [<channel id>] set <setting></syntax> + <syntax>channel [<channel id>] set <setting> <value></syntax> + <syntax>channel [<channel id>] set -del <setting></syntax> + + <description> + <para> + This command can be used to change various settings for channels. Different channel types support different settings. You can see the settings available for a channel by typing <emphasis>channel <channel id> set</emphasis>. + </para> + + <para> + For more infomation about a setting, see <emphasis>help set <setting></emphasis>. + </para> + + <para> + The channel ID can be a number (see <emphasis>channel list</emphasis>), or (part of) its name, as long as it matches only one channel. If you want to change settings of the current channel, you can omit the channel ID. + </para> + </description> + </bitlbee-command> + + </bitlbee-command> + + <bitlbee-command name="chat"> + <short-description>Chatroom list maintenance</short-description> + <syntax>chat <action> [<arguments>]</syntax> + + <description> + + <para> + Available actions: add, with. See <emphasis>help chat <action></emphasis> for more information. + </para> + + </description> + + <bitlbee-command name="add"> + <syntax>chat add <account id> <room> [<channel>]</syntax> + + <description> + <para> + Add a chatroom to the list of chatrooms you're interested in. BitlBee needs this list to map room names to a proper IRC channel name. + </para> + + <para> + After adding a room to your list, you can simply use the IRC /join command to enter the room. Also, you can tell BitlBee to automatically join the room when you log in. (See <emphasis>chat set</emphasis>) + </para> + + <para> + Password-protected rooms work exactly like on IRC, by passing the password as an extra argument to /join. + </para> + </description> + + </bitlbee-command> + + <bitlbee-command name="with"> + <syntax>chat with <nickname></syntax> + + <description> + <para> + While most <emphasis>chat</emphasis> subcommands are about named chatrooms, this command can be used to open an unnamed groupchat with one or more persons. This command is what <emphasis>/join #nickname</emphasis> used to do in older BitlBee versions. + </para> + </description> + </bitlbee-command> + </bitlbee-command> + + <bitlbee-command name="add"> + <short-description>Add a buddy to your contact list</short-description> + <syntax>add <account id> <handle> [<nick>]</syntax> + <syntax>add -tmp <account id> <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. The -tmp option adds the buddy to the internal BitlBee structures only, not to the real contact list (like done by <emphasis>set handle_unknown add</emphasis>). This allows you to talk to people who are not in your contact list. This normally won't show you any presence notifications. + </para> + + <para> + If you use this command in a control channel containing people from only one group, the new contact will be added to that group automatically. + </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> + <syntax>block <connection></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> + + <para> + When called with only a connection specification as an argument, the command displays the current block list for that connection. + </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> + + <para> + When called with only a connection specification as an argument, the command displays the current allow list for that connection. + </para> + </description> + </bitlbee-command> + + <bitlbee-command name="otr"> + <short-description>Off-the-Record encryption control</short-description> + <syntax>otr <subcommand> [<arguments>]</syntax> + + <description> + + <para> + Available subcommands: connect, disconnect, smp, smpq, trust, info, keygen, and forget. See <emphasis>help otr <subcommand></emphasis> for more information. + </para> + + </description> + + <bitlbee-command name="connect"> + <syntax>otr connect <nick></syntax> + + <description> + + <para> + Attempts to establish an encrypted connection with the specified user by sending a magic string. + </para> + + </description> + + </bitlbee-command> + + <bitlbee-command name="disconnect"> + <syntax>otr disconnect <nick></syntax> + + <description> + + <para> + Resets the connection with the specified user to cleartext. + </para> + + </description> + + </bitlbee-command> + + <bitlbee-command name="smp"> + <syntax>otr smp <nick> <secret></syntax> + + <description> + + <para> + Attempts to authenticate the given user's active fingerprint via the Socialist Millionaires' Protocol. + </para> + + <para> + If an SMP challenge has been received from the given user, responds with the specified secret/answer. Otherwise, sends a challenge for the given secret. + </para> + + <para> + Note that there are two flavors of SMP challenges: "shared-secret" and "question & answer". This command is used to respond to both of them, or to initiate a shared-secret style exchange. Use the <emphasis>otr smpq</emphasis> command to initiate a "Q&A" session. + </para> + + <para> + When responding to a "Q&A" challenge, the local trust value is not altered. Only the <emphasis>asking party</emphasis> sets trust in the case of success. Use <emphasis>otr smpq</emphasis> to pose your challenge. In a shared-secret exchange, both parties set their trust according to the outcome. + </para> + + </description> + + </bitlbee-command> + + <bitlbee-command name="smpq"> + <syntax>otr smpq <nick> <question> <answer></syntax> + + <description> + + <para> + Attempts to authenticate the given user's active fingerprint via the Socialist Millionaires' Protocol, Q&A style. + </para> + + <para> + Initiates an SMP session in "question & answer" style. The question is transmitted with the initial SMP packet and used to prompt the other party. You must be confident that only they know the answer. If the protocol succeeds (i.e. they answer correctly), the fingerprint will be trusted. Note that the answer must be entered exactly, case and punctuation count! + </para> + + <para> + Note that this style of SMP only affects the trust setting on your side. Expect your opponent to send you their own challenge. Alternatively, if you and the other party have a shared secret, use the <emphasis>otr smp</emphasis> command. + </para> + + </description> + + </bitlbee-command> + + <bitlbee-command name="trust"> + <syntax>otr trust <nick> <fp1> <fp2> <fp3> <fp4> <fp5></syntax> + + <description> + + <para> + Manually affirms trust in the specified fingerprint, given as five blocks of precisely eight (hexadecimal) digits each. + </para> + + </description> + + </bitlbee-command> + + <bitlbee-command name="info"> + <syntax>otr info</syntax> + <syntax>otr info <nick></syntax> + + <description> + + <para> + Shows information about the OTR state. The first form lists our private keys and current OTR contexts. The second form displays information about the connection with a given user, including the list of their known fingerprints. + </para> + + </description> + + </bitlbee-command> + + <bitlbee-command name="keygen"> + <syntax>otr keygen <account-no></syntax> + + <description> + + <para> + Generates a new OTR private key for the given account. + </para> + + </description> + + </bitlbee-command> + + <bitlbee-command name="forget"> + <syntax>otr forget <thing> <arguments></syntax> + + <description> + + <para> + Forgets some part of our OTR userstate. Available things: fingerprint, context, and key. See <emphasis>help otr forget <thing></emphasis> for more information. + </para> + + </description> + + <bitlbee-command name="fingerprint"> + <syntax>otr forget fingerprint <nick> <fingerprint></syntax> + + <description> + + <para> + Drops the specified fingerprint from the given user's OTR connection context. It is allowed to specify only a (unique) prefix of the desired fingerprint. + </para> + + </description> + + </bitlbee-command> + + <bitlbee-command name="context"> + <syntax>otr forget context <nick></syntax> + + <description> + + <para> + Forgets the entire OTR context associated with the given user. This includes current message and protocol states, as well as any fingerprints for that user. + </para> + + </description> + + </bitlbee-command> + + <bitlbee-command name="key"> + <syntax>otr forget key <fingerprint></syntax> + + <description> + + <para> + Forgets an OTR private key matching the specified fingerprint. It is allowed to specify only a (unique) prefix of the fingerprint. + </para> + + </description> + + </bitlbee-command> + + </bitlbee-command> + + </bitlbee-command> + + <bitlbee-command name="set"> + <short-description>Miscellaneous settings</short-description> + <syntax>set</syntax> + <syntax>set <variable></syntax> + <syntax>set <variable> <value></syntax> + <syntax>set -del <variable></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. With <emphasis>-del</emphasis> you can reset a setting to its default value. + </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="account" type="string" scope="channel"> + + <description> + <para> + For control channels with <emphasis>fill_by</emphasis> set to <emphasis>account</emphasis>: Set this setting to the account id (numeric, or part of the username) of the account containing the contacts you want to see in this channel. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="allow_takeover" type="boolean" scope="global"> + <default>true</default> + + <description> + <para> + When you're already connected to a BitlBee server and you connect (and identify) again, BitlBee will offer to migrate your existing session to the new connection. If for whatever reason you don't want this, you can disable this setting. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="auto_connect" type="boolean" scope="both"> + <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> + + <para> + This setting can also be changed for specific accounts using the <emphasis>account set</emphasis> command. (However, these values will be ignored if the global <emphasis>auto_connect</emphasis> setting is disabled!) + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="auto_join" type="boolean" scope="channel"> + <default>false</default> + + <description> + <para> + With this option enabled, BitlBee will automatically join this channel when you log in. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="auto_reconnect" type="boolean" scope="both"> + <default>true</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> + + <para> + This setting can also be changed for specific accounts using the <emphasis>account set</emphasis> command. (However, these values will be ignored if the global <emphasis>auto_reconnect</emphasis> setting is disabled!) + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="auto_reconnect_delay" type="string" scope="global"> + <default>5*3<900</default> + + <description> + <para> + Tell BitlBee after how many seconds it should attempt to bring a broken IM-connection back up. + </para> + + <para> + This can be one integer, for a constant delay. One can also set it to something like "10*10", which means wait for ten seconds on the first reconnect, multiply it by ten on every failure. Once successfully connected, this delay is re-set to the initial value. With < you can give a maximum delay. + </para> + + <para> + See also the <emphasis>auto_reconnect</emphasis> setting. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="auto_reply_timeout" type="integer" scope="account"> + <default>10800</default> + + <description> + <para> + For Twitter accounts: If you respond to Tweets IRC-style (like "nickname: reply"), this will automatically be converted to the usual Twitter format ("@screenname reply"). + </para> + + <para> + By default, BitlBee will then also add a reference to that person's most recent Tweet, unless that message is older than the value of this setting in seconds. + </para> + + <para> + If you want to disable this feature, just set this to 0. Alternatively, if you want to write a message once that is <emphasis>not</emphasis> a reply, use the Twitter reply syntax (@screenname). + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="away" type="string" scope="both"> + <description> + <para> + To mark yourself as away, it is recommended to just use <emphasis>/away</emphasis>, like on normal IRC networks. If you want to mark yourself as away on only one IM network, you can use this per-account setting. + </para> + + <para> + You can set it to any value and BitlBee will try to map it to the most appropriate away state for every open IM connection, or set it as a free-form away message where possible. + </para> + + <para> + Any per-account away setting will override globally set away states. To un-set the setting, use <emphasis>set -del away</emphasis>. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="away_devoice" type="boolean" scope="global"> + <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> + + <para> + Replaced with the <emphasis>show_users</emphasis> setting. See <emphasis>help show_users</emphasis>. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="away_reply_timeout" type="integer" scope="global"> + <default>3600</default> + + <description> + <para> + Most IRC servers send a user's away message every time s/he gets a private message, to inform the sender that they may not get a response immediately. With this setting set to 0, BitlBee will also behave like this. + </para> + + <para> + Since not all IRC clients do an excellent job at suppressing these messages, this setting lets BitlBee do it instead. BitlBee will wait this many seconds (or until the away state/message changes) before re-informing you that the person's away. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="base_url" type="string" scope="account"> + <default>http://twitter.com</default> + + <description> + <para> + There are more services that understand the Twitter API than just Twitter.com. BitlBee can connect to all Twitter API implementations. + </para> + + <para> + For example, set this setting to <emphasis>http://identi.ca/api</emphasis> to use Identi.ca. + </para> + + <para> + Keep two things in mind: When not using Twitter, you <emphasis>must</emphasis> also disable the <emphasis>oauth</emphasis> setting as it currently only works with Twitter. If you're still having issues, make sure there is <emphasis>no</emphasis> slash at the end of the URL you enter here. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="charset" type="string" scope="global"> + <default>utf-8</default> + <possible-values>you can get a list of all possible values by doing 'iconv -l' in a shell</possible-values> + + <description> + <para> + This setting tells BitlBee what your IRC client sends and expects. It should be equal to the charset setting of your IRC client if you want to be able to send and receive non-ASCII text properly. + </para> + + <para> + Most systems use UTF-8 these days. On older systems, an iso8859 charset may work better. For example, iso8859-1 is the best choice for most Western countries. You can try to find what works best for you on http://www.unicodecharacter.com/charsets/iso8859.html + </para> + </description> + + </bitlbee-setting> + + <bitlbee-setting name="color_encrypted" type="boolean" scope="global"> + <default>true</default> + + <description> + <para> + If set to true, BitlBee will color incoming encrypted messages according to their fingerprint trust level: untrusted=red, trusted=green. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="control_channel" type="string" scope="global"> + <default>&bitlbee</default> + + <description> + <para> + Normally the control channel where you can see all your contacts is called "&bitlbee". If you don't like this name, you can rename it to anything else using the <emphasis>rename</emphasis> command, or by changing this setting. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="chat_type" type="string" scope="channel"> + <default>groupchat</default> + <possible-values>groupchat, room</possible-values> + + <description> + <para> + There are two kinds of chat channels: simple groupchats (basically normal IM chats with more than two participants) and names chatrooms, more similar to IRC channels. + </para> + + <para> + BitlBee supports both types. With this setting set to <emphasis>groupchat</emphasis> (the default), you can just invite people into the room and start talking. + </para> + + <para> + For setting up named chatrooms, it's currently easier to just use the <emphasis>chat add</emphasis> command. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="commands" type="boolean" scope="account"> + <default>true</default> + + <description> + <para> + With this setting enabled, you can use some commands in your Twitter channel/query. The commands are simple and not documented in too much detail: + </para> + + <variablelist> + <varlistentry><term>undo [<id>]</term><listitem><para>Delete your last Tweet (or one with the given ID)</para></listitem></varlistentry> + <varlistentry><term>rt <screenname|id></term><listitem><para>Retweet someone's last Tweet (or one with the given ID)</para></listitem></varlistentry> + <varlistentry><term>follow <screenname></term><listitem><para>Start following a person</para></listitem></varlistentry> + <varlistentry><term>unfollow <screenname></term><listitem><para>Stop following a person</para></listitem></varlistentry> + <varlistentry><term>post <message></term><listitem><para>Post a tweet</para></listitem></varlistentry> + </variablelist> + + <para> + Anything that doesn't look like a command will be treated as a tweet. Watch out for typos! :-) + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="debug" type="boolean" scope="global"> + <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="default_target" type="string" scope="global"> + <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_name" type="string" scope="account"> + <description> + <para> + Currently only available for MSN connections. This setting allows you to read and change your "friendly name" for this connection. Since this is a server-side setting, it can't be changed when the account is off-line. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="display_namechanges" type="boolean" scope="global"> + <default>false</default> + + <description> + <para> + With this option enabled, root will inform you when someone in your buddy list changes his/her "friendly name". + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="display_timestamps" type="boolean" scope="global"> + <default>true</default> + + <description> + <para> + When incoming messages are old (i.e. offline messages and channel backlogs), BitlBee will prepend them with a timestamp. If you find them ugly or useless, you can use this setting to hide them. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="fill_by" type="string" scope="channel"> + <default>all</default> + <possible-values>all, group, account, protocol</possible-values> + + <description> + <para> + For control channels only: This setting determines which contacts the channel gets populated with. + </para> + + <para> + By default, control channels will contain all your contacts. You instead select contacts by buddy group, IM account or IM protocol. + </para> + + <para> + Change this setting and the corresponding <emphasis>account</emphasis>/<emphasis>group</emphasis>/<emphasis>protocol</emphasis> setting to set up this selection. + </para> + + <para> + Note that, when creating a new channel, BitlBee will try to preconfigure the channel for you, based on the channel name. See <emphasis>help channels</emphasis>. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="group" type="string" scope="channel"> + + <description> + <para> + For control channels with <emphasis>fill_by</emphasis> set to <emphasis>group</emphasis>: Set this setting to the name of the group containing the contacts you want to see in this channel. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="handle_unknown" type="string" scope="global"> + <default>add_channel</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="ignore_auth_requests" type="boolean" scope="account"> + <default>false</default> + + <description> + <para> + Only supported by OSCAR so far, you can use this setting to ignore ICQ authorization requests, which are hardly used for legitimate (i.e. non-spam) reasons anymore. + </para> + </description> + + </bitlbee-setting> + + <bitlbee-setting name="lcnicks" type="boolean" scope="global"> + <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-setting name="local_display_name" type="boolean" scope="account"> + <default>false</default> + + <description> + <para> + Mostly meant to work around a bug in MSN servers (forgetting the display name set by the user), this setting tells BitlBee to store your display name locally and set this name on the MSN servers when connecting. + </para> + </description> + + </bitlbee-setting> + + <bitlbee-setting name="mail_notifications" type="boolean" scope="account"> + <default>false</default> + + <description> + <para> + Some protocols (MSN, Yahoo!) can notify via IM about new e-mail. Since most people use their Hotmail/Yahoo! addresses as a spam-box, this is disabled default. If you want these notifications, you can enable this setting. + </para> + </description> + + </bitlbee-setting> + + <bitlbee-setting name="message_length" type="integer" scope="account"> + <default>140</default> + + <description> + <para> + Since Twitter rejects messages longer than 140 characters, BitlBee can count message length and emit a warning instead of waiting for Twitter to reject it. + </para> + + <para> + You can change this limit here but this won't disable length checks on Twitter's side. You can also set it to 0 to disable the check in case you believe BitlBee doesn't count the characters correctly. + </para> + </description> + + </bitlbee-setting> + + <bitlbee-setting name="mode" type="string" scope="account"> + <possible-values>one, many, chat</possible-values> + <default>chat</default> + + <description> + <para> + By default, BitlBee will create a separate channel (called #twitter_yourusername) for all your Twitter contacts/messages. + </para> + + <para> + If you don't want an extra channel, you can set this setting to "one" (everything will come from one nick, twitter_yourusername), or to "many" (individual nicks for everyone). + </para> + + <para> + With modes "chat" and "many", you can send direct messages by /msg'ing your contacts directly. Note, however, that incoming DMs are not fetched yet. + </para> + + <para> + With modes "many" and "one", you can post tweets by /msg'ing the twitter_yourusername contact. In mode "chat", messages posted in the Twitter channel will also be posted as tweets. + </para> + </description> + + </bitlbee-setting> + + <bitlbee-setting name="mobile_is_away" type="boolean" scope="global"> + <default>false</default> + + <description> + <para> + Most IM networks have a mobile version of their client. People who use these may not be paying that much attention to messages coming in. By enabling this setting, people using mobile clients will always be shown as away. + </para> + </description> + + </bitlbee-setting> + + <bitlbee-setting name="nick" type="string" scope="chat"> + <description> + <para> + You can use this option to set your nickname in a chatroom. You won't see this nickname yourself, but other people in the room will. By default, BitlBee will use your username as the chatroom nickname. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="nick_format" type="string" scope="both"> + <default>%-@nick</default> + + <description> + <para> + By default, BitlBee tries to derive sensible nicknames for all your contacts from their IM handles. In some cases, IM modules (ICQ for example) will provide a nickname suggestion, which will then be used instead. This setting lets you change this behaviour. + </para> + + <para> + Whenever this setting is set for an account, it will be used for all its contacts. If it's not set, the global value will be used. + </para> + + <para> + It's easier to describe this setting using a few examples: + </para> + + <para> + FB-%full_name will make all nicknames start with "FB-", followed by the person's full name. For example you can set this format for your Facebook account so all Facebook contacts are clearly marked. + </para> + + <para> + [%group]%-@nick will make all nicknames start with the group the contact is in between square brackets, followed by the nickname suggestions from the IM module if available, or otherwise the handle. Because of the "-@" part, everything from the first @ will be stripped. + </para> + + <para> + See <emphasis>help nick_format</emphasis> for more information. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="nick_source" type="string" scope="account"> + <default>handle</default> + <possible-values>handle, full_name, first_name</possible-values> + + <description> + <para> + By default, BitlBee generates a nickname for every contact by taking its handle and chopping off everything after the @. In some cases, this gives very inconvenient nicknames. The Facebook XMPP server is a good example, as all Facebook XMPP handles are numeric. + </para> + + <para> + With this setting set to <emphasis>full_name</emphasis>, the person's full name is used to generate a nickname. Or if you don't like long nicknames, set this setting to <emphasis>first_name</emphasis> instead and only the first word will be used. Note that the full name can be full of non-ASCII characters which will be stripped off. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="oauth" type="boolean" scope="account"> + <default>true</default> + + <description> + <para> + This enables OAuth authentication for Twitter accounts. From June 2010 this will be mandatory. + </para> + + <para> + With OAuth enabled, you shouldn't tell BitlBee your Twitter password. Just add your account with a bogus password and type <emphasis>account on</emphasis>. BitlBee will then give you a URL to authenticate with Twitter. If this succeeds, Twitter will return a PIN code which you can give back to BitlBee to finish the process. + </para> + + <para> + The resulting access token will be saved permanently, so you have to do this only once. + </para> + </description> + + </bitlbee-setting> + + <bitlbee-setting name="ops" type="string" scope="global"> + <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="otr_policy" type="string" scope="global"> + <default>opportunistic</default> + <possible-values>never, opportunistic, manual, always</possible-values> + + <description> + <para> + This setting controls the policy for establishing Off-the-Record connections. + </para> + <para> + A value of "never" effectively disables the OTR subsystem. In "opportunistic" mode, a magic whitespace pattern will be appended to the first message sent to any user. If the peer is also running opportunistic OTR, an encrypted connection will be set up automatically. On "manual", on the other hand, OTR connections must be established explicitly using <emphasis>otr connect</emphasis>. Finally, the setting "always" enforces encrypted communication by causing BitlBee to refuse to send any cleartext messages at all. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="password" type="string" scope="both"> + <description> + <para> + Use this global setting to change your "NickServ" password. + </para> + + <para> + This setting is also available for all IM accounts to change the password BitlBee uses to connect to the service. + </para> + + <para> + Note that BitlBee will always say this setting is empty. This doesn't mean there is no password, it just means that, for security reasons, BitlBee stores passwords somewhere else so they can't just be retrieved in plain text. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="paste_buffer" type="boolean" scope="global"> + <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>paste_buffer_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="paste_buffer_delay" type="integer" scope="global"> + <default>200</default> + + <description> + + <para> + Tell BitlBee after how many (mili)seconds a buffered message should be sent. Values greater than 5 will be interpreted as miliseconds, 5 and lower as seconds. + </para> + + <para> + See also the <emphasis>paste_buffer</emphasis> setting. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="port" type="integer" scope="account"> + <description> + <para> + Currently only available for Jabber connections. Specifies the port number to connect to. Usually this should be set to 5222, or 5223 for SSL-connections. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="priority" type="integer" scope="account"> + <default>0</default> + + <description> + <para> + Can be set for Jabber connections. When connecting to one account from multiple places, this priority value will help the server to determine where to deliver incoming messages (that aren't addressed to a specific resource already). + </para> + + <para> + According to RFC 3921 servers will always deliver messages to the server with the highest priority value. Mmessages will not be delivered to resources with a negative priority setting (and should be saved as an off-line message if all available resources have a negative priority value). + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="private" type="boolean" scope="global"> + <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="protocol" type="string" scope="channel"> + + <description> + <para> + For control channels with <emphasis>fill_by</emphasis> set to <emphasis>protocol</emphasis>: Set this setting to the name of the IM protocol of all contacts you want to see in this channel. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="query_order" type="string" scope="global"> + <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="resource" type="string" scope="account"> + <default>BitlBee</default> + + <description> + <para> + Can be set for Jabber connections. You can use this to connect to your Jabber account from multiple clients at once, with every client using a different resource string. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="resource_select" type="string" scope="account"> + <default>activity</default> + <possible-values>priority, activity</possible-values> + + <description> + <para> + Because the IRC interface makes it pretty hard to specify the resource to talk to (when a buddy is online through different resources), this setting was added. + </para> + + <para> + Normally it's set to <emphasis>priority</emphasis> which means messages will always be delivered to the buddy's resource with the highest priority. If the setting is set to <emphasis>activity</emphasis>, messages will be delivered to the resource that was last used to send you a message (or the resource that most recently connected). + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="root_nick" type="string" scope="global"> + <default>root</default> + + <description> + <para> + Normally the "bot" that takes all your BitlBee commands is called "root". If you don't like this name, you can rename it to anything else using the <emphasis>rename</emphasis> command, or by changing this setting. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="save_on_quit" type="boolean" scope="global"> + <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="server" type="string" scope="account"> + <description> + <para> + Can be set for Jabber- and OSCAR-connections. For Jabber, you might have to set this if the servername isn't equal to the part after the @ in the Jabber handle. For OSCAR this shouldn't be necessary anymore in recent BitlBee versions. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="show_offline" type="boolean" scope="global"> + <default>false</default> + + <description> + <para> + If enabled causes BitlBee to also show offline users in Channel. Online-users will get op, away-users voice and offline users none of both. This option takes effect as soon as you reconnect. + </para> + + <para> + Replaced with the <emphasis>show_users</emphasis> setting. See <emphasis>help show_users</emphasis>. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="show_users" type="string" scope="channel"> + <default>online+,away</default> + + <description> + <para> + Comma-separated list of statuses of users you want in the channel, + and any modes they should have. The following statuses are currently + recognised: <emphasis>online</emphasis> (i.e. available, not + away), <emphasis>away</emphasis>, and <emphasis>offline</emphasis>. + </para> + + <para> + If a status is followed by a valid channel mode character + (@, % or +), it will be given to users with that status. + For example, <emphasis>online@,away+,offline</emphasis> will + show all users in the channel. Online people will + have +o, people who are online but away will have +v, + and others will have no special modes. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="simulate_netsplit" type="boolean" scope="global"> + <default>true</default> + + <description> + <para> + Some IRC clients parse quit messages sent by the IRC server to see if someone really left or just disappeared because of a netsplit. By default, BitlBee tries to simulate netsplit-like quit messages to keep the control channel window clean. If you don't like this (or if your IRC client doesn't support this) you can disable this setting. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="ssl" type="boolean" scope="account"> + <default>false</default> + + <description> + <para> + Currently only available for Jabber connections. Set this to true if the server accepts SSL connections. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="status" type="string" scope="both"> + <description> + <para> + Certain protocols (like Jabber/XMPP) support status messages, similar to away messages. They can be used to indicate things like your location or activity, without showing up as away/busy. + </para> + + <para> + This setting can be used to set such a message. It will be available as a per-account setting for protocols that support it, and also as a global setting (which will then automatically be used for all protocols that support it). + </para> + + <para> + Away states set using <emphasis>/away</emphasis> or the <emphasis>away</emphasis> setting will override this setting. To un-set the setting, use <emphasis>set -del status</emphasis>. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="strip_html" type="boolean" scope="global"> + <default>true</default> + + <description> + <para> + Determines what BitlBee should do with HTML in messages. Normally this is turned on and HTML will be stripped from messages, if BitlBee thinks there is HTML. + </para> + <para> + If BitlBee fails to detect this sometimes (most likely in AIM messages over an ICQ connection), you can set this setting to <emphasis>always</emphasis>, but this might sometimes accidentally strip non-HTML things too. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="switchboard_keepalives" type="boolean" scope="account"> + <default>false</default> + + <description> + <para> + Turn on this flag if you have difficulties talking to offline/invisible contacts. + </para> + + <para> + With this setting enabled, BitlBee will send keepalives to MSN switchboards with offline/invisible contacts every twenty seconds. This should keep the server and client on the other side from shutting it down. + </para> + + <para> + This is useful because BitlBee doesn't support MSN offline messages yet and the MSN servers won't let the user reopen switchboards to offline users. Once offline messaging is supported, this flag might be removed. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="tag" type="string" scope="account"> + <description> + <para> + For every account you have, you can set a tag you can use to uniquely identify that account. This tag can be used instead of the account number (or protocol name, or part of the screenname) when using commands like <emphasis>account</emphasis>, <emphasis>add</emphasis>, etc. You can't have two accounts with one and the same account tag. + </para> + + <para> + By default, it will be set to the name of the IM protocol. Once you add a second account on an IM network, a numeric suffix will be added, starting with 2. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="timezone" type="string" scope="global"> + <default>local</default> + <possible-values>local, utc, gmt, timezone-spec</possible-values> + + <description> + <para> + If message timestamps are available for offline messages or chatroom backlogs, BitlBee will display them as part of the message. By default it will use the local timezone. If you're not in the same timezone as the BitlBee server, you can adjust the timestamps using this setting. + </para> + + <para> + Values local/utc/gmt should be self-explanatory. timezone-spec is a time offset in hours:minutes, for example: -8 for Pacific Standard Time, +2 for Central European Summer Time, +5:30 for Indian Standard Time. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="tls" type="boolean" scope="account"> + <default>try</default> + + <description> + <para> + Newer Jabber servers allow clients to convert a plain-text session to a TLS/SSL-encrypted session. Normally (with this setting set to <emphasis>try</emphasis>) BitlBee will do this, if possible. + </para> + + <para> + If you want to force BitlBee to use TLS sessions only (and to give up if that doesn't seem to be possible) you can set this setting to <emphasis>true</emphasis>. Set it to <emphasis>false</emphasis> if you want the session to remain plain-text. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="to_char" type="string" scope="global"> + <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="translate_to_nicks" type="boolean" scope="channel"> + <default>true</default> + + <description> + <para> + IRC's nickname namespace is quite limited compared to most IM protocols. Not any non-ASCII characters are allowed, in fact nicknames have to be mostly alpha-numeric. Also, BitlBee has to add underscores sometimes to avoid nickname collisions. + </para> + + <para> + While normally the BitlBee user is the only one seeing these names, they may be exposed to other chatroom participants for example when addressing someone in the channel (with or without tab completion). By default BitlBee will translate these stripped nicknames back to the original nick. If you don't want this, disable this setting. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="type" type="string" scope="channel"> + <default>control</default> + <possible-values>control, chat</possible-values> + + <description> + <para> + BitlBee supports two kinds of channels: control channels (usually with a name starting with a &) and chatroom channels (name usually starts with a #). + </para> + + <para> + See <emphasis>help channels</emphasis> for a full description of channel types in BitlBee. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="typing_notice" type="boolean" scope="global"> + <default>false</default> + + <description> + <para> + Sends you a /notice when a user starts typing a message (if supported by the IM protocol and the user's client). To use this, you most likely want to use a script in your IRC client to show this information in a more sensible way. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="user_agent" type="string" scope="account"> + <default>BitlBee</default> + + <description> + <para> + Some Jabber servers are configured to only allow a few (or even just one) kinds of XMPP clients to connect to them. + </para> + + <para> + You can change this setting to make BitlBee present itself as a different client, so that you can still connect to these servers. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="web_aware" type="string" scope="account"> + <default>false</default> + + <description> + <para> + ICQ allows people to see if you're on-line via a CGI-script. (http://status.icq.com/online.gif?icq=UIN) This can be nice to put on your website, but it seems that spammers also use it to see if you're online without having to add you to their contact list. So to prevent ICQ spamming, recent versions of BitlBee disable this feature by default. + </para> + + <para> + Unless you really intend to use this feature somewhere (on forums or maybe a website), it's probably better to keep this setting disabled. + </para> + </description> + </bitlbee-setting> + + <bitlbee-setting name="xmlconsole" type="boolean" scope="account"> + <default>false</default> + + <description> + <para> + The Jabber module allows you to add a buddy <emphasis>xmlconsole</emphasis> to your contact list, which will then show you the raw XMPP stream between you and the server. You can also send XMPP packets to this buddy, which will then be sent to the server. + </para> + <para> + If you want to enable this XML console permanently (and at login time already), you can set this setting. + </para> + </description> + </bitlbee-setting> + + <bitlbee-command name="rename"> + <short-description>Rename (renick) a buddy</short-description> + <syntax>rename <oldnick> <newnick></syntax> + <syntax>rename -del <oldnick></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> + + <para> + <emphasis>rename -del</emphasis> can be used to erase your manually set nickname for a contact and reset it to what was automatically generated. + </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. To change your password later, you can use the <emphasis>set password</emphasis> command. + </para> + + <para> + You can omit the password and enter it separately using the IRC /OPER command. This lets you enter your password without your IRC client echoing it on screen or recording it in logs. + </para> + </description> + + </bitlbee-command> + + <bitlbee-command name="identify"> + <syntax>identify [-noload|-force] [<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> + + <para> + The <emphasis>-noload</emphasis> and <emphasis>-force</emphasis> flags can be used to identify when you're logged into some IM accounts already. <emphasis>-force</emphasis> will let you identify yourself and load all saved accounts (and keep the accounts you're logged into already). + </para> + + <para> + <emphasis>-noload</emphasis> will log you in but not load any accounts and settings saved under your current nickname. These will be overwritten once you save your settings (i.e. when you disconnect). + </para> + + <para> + You can omit the password and enter it separately using the IRC /OPER command. This lets you enter your password without your IRC client echoing it on screen or recording it in logs. + </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 the current channel</short-description> + + <description> + <para> + You can get a more 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="group"> + <short-description>Contact group management</short-description> + <syntax>group list</syntax> + + <description> + <para> + Only the <emphasis>group list</emphasis> command is supported at the moment, which shows a list of all groups defined so far. + </para> + + <para> + If you want to move contacts between groups, you can use the IRC <emphasis>/invite</emphasis> command. Also, if you use the <emphasis>add</emphasis> command in a control channel configured to show just one group, the new contact will automatically be added to that group. + </para> + </description> + </bitlbee-command> + + <bitlbee-command name="transfer"> + <short-description>Monitor, cancel, or reject file transfers</short-description> + <syntax>transfer [<cancel> id | <reject>]</syntax> + + <description> + <para> + Without parameters the currently pending file transfers and their status will be listed. Available actions are <emphasis>cancel</emphasis> and <emphasis>reject</emphasis>. See <emphasis>help transfer <action></emphasis> for more information. + </para> + + <ircexample> + <ircline nick="ulim">transfer</ircline> + </ircexample> + </description> + + <bitlbee-command name="cancel"> + <short-description>Cancels the file transfer with the given id</short-description> + <syntax>transfer <cancel> id</syntax> + + <description> + <para>Cancels the file transfer with the given id</para> + </description> + + <ircexample> + <ircline nick="ulim">transfer cancel 1</ircline> + <ircline nick="root">Canceling file transfer for test</ircline> + </ircexample> + </bitlbee-command> + + <bitlbee-command name="reject"> + <short-description>Rejects all incoming transfers</short-description> + <syntax>transfer <reject></syntax> + + <description> + <para>Rejects all incoming (not already transferring) file transfers. Since you probably have only one incoming transfer at a time, no id is neccessary. Or is it?</para> + </description> + + <ircexample> + <ircline nick="ulim">transfer reject</ircline> + </ircexample> + </bitlbee-command> + </bitlbee-command> + +</chapter> diff --git a/doc/user-guide/docbook.xsl b/doc/user-guide/docbook.xsl new file mode 100644 index 00000000..21d6b08e --- /dev/null +++ b/doc/user-guide/docbook.xsl @@ -0,0 +1,137 @@ +<?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:text> </xsl:text><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:param name="prefix"/> + <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.xml b/doc/user-guide/help.xml new file mode 100644 index 00000000..48ed8a48 --- /dev/null +++ b/doc/user-guide/help.xml @@ -0,0 +1,64 @@ +<?xml version="1.0" encoding="utf-8"?> +<!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>channels</term><listitem><para>About creating and customizing channels</para></listitem></varlistentry> + <varlistentry><term>away</term><listitem><para>About setting away states</para></listitem></varlistentry> + <varlistentry><term>groupchats</term><listitem><para>How to work with groupchats on BitlBee</para></listitem></varlistentry> + <varlistentry><term>nick_changes</term><listitem><para>Changing your nickname without losing any settings</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> +</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. Bugs can be reported at <ulink link="http://bugs.bitlbee.org/">http://bugs.bitlbee.org/</ulink>. +</para> + +<para> +For other things than bug reports, you can join <emphasis>#BitlBee</emphasis> on OFTC (<emphasis>irc.oftc.net</emphasis>) (OFTC, *not* FreeNode!) 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>channels</term><listitem><para>About creating and customizing channels</para></listitem></varlistentry> + <varlistentry><term>away</term><listitem><para>About setting away states</para></listitem></varlistentry> + <varlistentry><term>groupchats</term><listitem><para>How to work with groupchats on BitlBee</para></listitem></varlistentry> + <varlistentry><term>nick_changes</term><listitem><para>Changing your nickname without losing any settings</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> +</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..b7e3c371 --- /dev/null +++ b/doc/user-guide/help.xsl @@ -0,0 +1,161 @@ +<?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="utf-8" 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:param name="id"/> + <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_Scope:_b_ </xsl:text><xsl:value-of select="@scope"/><xsl:text> </xsl:text> + <xsl:if test="default"> + <xsl:text>_b_Default:_b_ </xsl:text><xsl:value-of select="default"/><xsl:text> </xsl:text> + </xsl:if> + <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:param name="prefix"/> + <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..1aceab56 --- /dev/null +++ b/doc/user-guide/misc.xml @@ -0,0 +1,368 @@ +<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> + +</sect1> + +<sect1 id="groupchats"> +<title>Groupchats</title> +<para> +BitlBee now supports groupchats on all IM 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> +To open a groupchat, use the <emphasis>chat with</emphasis> command. For example, to start a groupchat with the person <emphasis>lisa_msn</emphasis> in it, just type <emphasis>chat with lisa_msn</emphasis>. BitlBee will create a new virtual channel with root, you and lisa_msn in it. +</para> + +<para> +Then, just use the ordinary IRC <emphasis>/invite</emphasis> command to invite more people. 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> +Some protocols (like Jabber) also support named groupchats. BitlBee now supports these too. You can use the <emphasis>chat add</emphasis> command to join them. See <emphasis>help chat add</emphasis> for more information. +</para> + +</sect1> + +<sect1 id="away"> +<title>Away states</title> + +<para> +To mark yourself as away, you can just use the <emphasis>/away</emphasis> command in your IRC client. BitlBee supports most away-states supported by the protocols. +</para> + +<para> +Away states have different names accross different protocols. BitlBee will try to pick the best available option for every connection: +</para> + +<simplelist> + <member>Away</member> + <member>NA</member> + <member>Busy, DND</member> + <member>BRB</member> + <member>Phone</member> + <member>Lunch, Food</member> + <member>Invisible, Hidden</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" 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. Most IM-protocols can also show this additional information to your buddies. +</para> + +<para> +If you want to set an away state for only one of your connections, you can use the per-account <emphasis>away</emphasis> setting. See <emphasis>help set away</emphasis>. +</para> + +</sect1> + +<sect1 id="nick_changes"> +<title>Changing your nickname</title> + +<para> +BitlBee now allows you to change your nickname. So far this was not possible because it made managing saved accounts more complicated. +</para> + +<para> +The restriction no longer exists now though. When you change your nick (just using the <emphasis>/nick</emphasis> command), your logged-in status will be reset, which means any changes made to your settings/accounts will not be saved. +</para> + +<para> +To restore your logged-in status, you need to either use the <emphasis>register</emphasis> command to create an account under the new nickname, or use <emphasis>identify -noload</emphasis> to re-identify yourself under the new nickname. The <emphasis>-noload</emphasis> flag tells the command to verify your password and log you in, but not load any new settings. See <emphasis>help identify</emphasis> for more information. +</para> + +</sect1> + +<sect1 id="channels"> +<title>Dealing with channels</title> + +<para> +You can have as many channels in BitlBee as you want. You maintain your channel list using the <emphasis>channel</emphasis> command. You can create new channels by just joining them, like on regular IRC networks. +</para> + +<para> +You can create two kinds of channels. Control channels, and groupchat channels. By default, BitlBee will set up new channels as control channels if their name starts with an &, and as chat channels if it starts with a #. +</para> + +<para> +Control channels are where you see your contacts. By default, you will have one control channel called &bitlbee, containing all your contacts. But you can create more, if you want, and divide your contact list accross several channels. +</para> + +<para> +For example, you can have one channel with all contacts from your MSN Messenger account in it. Or all contacts from the group called "Work". +</para> + +<para> +Type <emphasis>help channels2</emphasis> to read more. +</para> + +</sect1> + +<sect1 id="channels2"> +<title>Creating a channel</title> + +<para> +When you create a new channel, BitlBee will try to guess from its name which contacts to fill it with. For example, if the channel name (excluding the &) matches the name of a group in which you have one or more contacts, the channel will contain all those contacts. +</para> + +<para> +Any valid account ID (so a number, protocol name or part of screenname, as long as it's unique) can also be used as a channel name. So if you just join &msn, it will contain all your MSN contacts. And if you have a Facebook account set up, you can see its contacts by just joining &facebook. +</para> + +<para> +To start a simple group chat, you simply join a channel which a name starting with #, and invite people into it. All people you invite have to be on the same IM network and contact list. +</para> + +<para> +If you want to configure your own channels, you can use the <emphasis>channel set</emphasis> command. See <emphasis>help channels3</emphasis> for more information. +</para> + +</sect1> + +<sect1 id="channels3"> +<title>Configuring a control channel</title> + +<para> +The most important setting for a control channel is <emphasis>fill_by</emphasis>. It +tells BitlBee what information should be used to decide if someone should be shown +in the channel or not. After setting this setting to, for example, <emphasis>account</emphasis>, you +also have to set the <emphasis>account</emphasis> setting. Example: +</para> + +<ircexample> + <ircline nick="wilmer">chan set &wlm fill_by account</ircline> + <ircline nick="root">fill_by = `account'</ircline> + <ircline nick="wilmer">chan set &wlm account msn</ircline> + <ircline nick="root">account = `msn'</ircline> +</ircexample> + +<para> +Also, each channel has a <emphasis>show_users</emphasis> setting which lets you +choose, for example, if you want to see only online contacts in a channel, or +also/just offline contacts. Example: +</para> + +<ircexample> + <ircline nick="wilmer">chan set &offline show_users offline</ircline> + <ircline nick="root">show_users = `offline'</ircline> +</ircexample> + +<para> +See the help information for all these settings for more information. +</para> + +</sect1> + +<sect1 id="nick_format"> +<title>Nickname formatting</title> + +<para> +The <emphasis>nick_format</emphasis> setting can be set globally using +the <emphasis>set</emphasis> command, or per account using <emphasis>account +set</emphasis> (so that you can set a per-account suffix/prefix or have +nicknames generated from full names for certain accounts). +</para> + +<para> +The setting is basically some kind of format string. It can contain normal +text that will be copied to the nick, combined with several variables: +</para> + +<variablelist> + <varlistentry><term>%nick</term><listitem><para>Nickname suggested for this contact by the IM protocol, or just the handle if no nickname was suggested.</para></listitem></varlistentry> + <varlistentry><term>%handle</term><listitem><para>The handle/screenname of the contact.</para></listitem></varlistentry> + <varlistentry><term>%full_name</term><listitem><para>The full name of the contact.</para></listitem></varlistentry> + <varlistentry><term>%first_name</term><listitem><para>The first name of the contact (the full name up to the first space).</para></listitem></varlistentry> + <varlistentry><term>%group</term><listitem><para>The name of the group this contact is a member of</para></listitem></varlistentry> + <varlistentry><term>%account</term><listitem><para>Account tag of the contact</para></listitem></varlistentry> +</variablelist> + +<para> +Invalid characters (like spaces) will always be stripped. Depending on your +locale settings, characters with accents will be converted to ASCII. +</para> + +<para> +See <emphasis>help nick_format2</emphasis> for some more information. +</para> + +</sect1> + +<sect1 id="nick_format2"> +<title>Nickname formatting - modifiers</title> + +<para> +Two modifiers are currently available: You can include only the first few +characters of a variable by putting a number right after the %. For +example, <emphasis>[%3group]%-@nick</emphasis> will include only the first +three characters of the group name in the nick. +</para> + +<para> +Also, you can truncate variables from a certain character using +the <emphasis>-</emphasis> modifier. For example, you may want to leave out +everything after the @. <emphasis>%-@handle</emphasis> will expand to +everything in the handle up to the first @. +</para> + +</sect1> + +<sect1 id="whatsnew010206"> +<title>New stuff in BitlBee 1.2.6</title> + +<para> +Twitter support. See <emphasis>help account add twitter</emphasis>. +</para> +</sect1> + +<sect1 id="whatsnew010300"> +<title>New stuff in BitlBee 1.3dev</title> + +<para> +Support for multiple configurable control channels, each with a subset of +your contact list. See <emphasis>help channels</emphasis> for more +information. +</para> + +<para> +File transfer support for some protocols (more if you use libpurple). Just +/DCC SEND stuff. Incoming files also become DCC transfers. +</para> + +<para> +Only if you run your own BitlBee instance: You can build a BitlBee that uses +libpurple for connecting to IM networks instead of its own code, adding +support for some of the more obscure IM protocols and features. +</para> + +<para> +Many more things, briefly described in <emphasis>help news1.3</emphasis>. +</para> +</sect1> + +<sect1 id="whatsnew030000"> +<title>New stuff in BitlBee 3.0</title> + +<para> +BitlBee can be compiled with support for OTR message encryption (not available +on public servers since encryption should be end-to-end). +</para> + +<para> +The MSN module was heavily updated to support features added to MSN Messenger +over the recent years. You can now see/set status messages, send offline +messages, and many strange issues caused by Microsoft breaking old-protocol +compatibility should now be resolved. +</para> + +<para> +Twitter extended: IRC-style replies ("BitlBee:") now get converted to proper +Twitter replies ("@BitlBee") and get a reference to the original message +(see <emphasis>help set auto_reply_timeout</emphasis>). Retweets and some +other stuff is also supported now (see <emphasis>help set commands</emphasis>). +</para> +</sect1> + +<sect1 id="news1.3"> +<title>New stuff in BitlBee 1.3dev (details)</title> + +<para> +Most of the core of BitlBee was rewritten since the last release. This entry +should sum up the majority of the changes. +</para> + +<para> +First of all, you can now have as many control channels as you want. Or you +can have none, it's finally possible to leave &bitlbee and still talk to +all your contacts. Or you can have a &work with all your work-related +contacts, or a &msn with all your MSN Messenger contacts. See <emphasis>help +channels</emphasis> for more information about this. +</para> + +<para> +Also, you can change how nicknames are generated for your contacts. Like +automatically adding a [fb] tag to the nicks of all your Facebook contacts. +See <emphasis>help nick_format</emphasis>. +</para> + +<para> +When you're already connected to a BitlBee server and you connect from +elsewhere, you can take over the old session. +</para> + +<para> +Instead of account numbers, accounts now also get tags. These are +automatically generated but can be changed (<emphasis>help set +tag</emphasis>). You can now use them instead of accounts numbers. +(Example: <emphasis>acc gtalk on</emphasis>) +</para> + +<para> +Last of all: You can finally change your nickname and +shorten root commands (try <emphasis>acc li</emphasis> instead +of <emphasis>account list</emphasis>). +</para> + +</sect1> + +</chapter> diff --git a/doc/user-guide/quickstart.xml b/doc/user-guide/quickstart.xml new file mode 100644 index 00000000..80c16ffb --- /dev/null +++ b/doc/user-guide/quickstart.xml @@ -0,0 +1,167 @@ +<chapter id="quickstart"> +<title>Quickstart</title> + +<para> +Welcome to BitlBee, your IRC gateway to ICQ, MSN, AOL, Jabber, Yahoo! and Twitter. +</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 a Jabber account at jabber.org with handle <emphasis>bitlbee@jabber.org</emphasis> with password <emphasis>QuickStart</emphasis>, you would: +</para> + +<ircexample> + <ircline nick="you">account add jabber bitlbee@jabber.org QuickStart</ircline> + <ircline nick="root">Account successfully added</ircline> +</ircexample> + +<para> +Other available IM protocols are msn, oscar, yahoo and twitter. OSCAR is the protocol used by ICQ and AOL. For more information about the <emphasis>account add</emphasis> command, see <emphasis>help account add</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> +Now BitlBee logs in and downloads the contact list from the IM server. In a few seconds, all your on-line buddies should show up in the control channel. +</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> +Note that, although all contacts are in the &bitlbee channel, only tux will actually receive this message. The &bitlbee channel shouldn't be confused with a real IRC channel. +</para> + +<para> +If you prefer chatting in a separate window, use the <emphasis>/msg</emphasis> or <emphasis>/query</emphasis> command, just like on real IRC. BitlBee will remember how you talk to someone and show his/her responses the same way. If you want to change the default behaviour (for people you haven't talked to yet), see <emphasis>help set private</emphasis>. +</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.xml b/doc/user-guide/user-guide.xml new file mode 100644 index 00000000..5e1c8fe0 --- /dev/null +++ b/doc/user-guide/user-guide.xml @@ -0,0 +1,41 @@ +<?xml version="1.0" encoding="utf-8"?> +<!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"> + </legalnotice> + + <releaseinfo> + This is the BitlBee User Guide. For now, the on-line help is + the most up-to-date documentation. Although this document shares + some parts with the on-line help system, other parts might be + very outdated. + </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> |
