diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/CHANGES | 119 | ||||
| -rw-r--r-- | doc/HACKING | 125 | ||||
| -rw-r--r-- | doc/Makefile | 7 | ||||
| -rw-r--r-- | doc/README | 48 | ||||
| -rw-r--r-- | doc/bitlbee.8 | 5 | ||||
| -rw-r--r-- | doc/user-guide/Makefile | 6 | ||||
| -rw-r--r-- | doc/user-guide/commands.xml | 646 | ||||
| -rw-r--r-- | doc/user-guide/help.xml | 8 | ||||
| -rw-r--r-- | doc/user-guide/misc.xml | 117 | ||||
| -rw-r--r-- | doc/user-guide/quickstart.xml | 4 |
10 files changed, 967 insertions, 118 deletions
diff --git a/doc/CHANGES b/doc/CHANGES index 1cac2dc7..d313c5d3 100644 --- a/doc/CHANGES +++ b/doc/CHANGES @@ -3,6 +3,123 @@ found in the bzr commit logs, for example you can try: http://bugs.bitlbee.org/bitlbee/timeline?daysback=90&changeset=on +Version 1.3dev: +- For the first time since 2007, a dev snapshot. Like then, this is pretty + stable already (running on testing.bitlbee.org for weeks by now), but not + all planned features for the next major release are ready yet, and there + may be some rough edges in the interface and documentation. +- Loads of new stuff, mostly ready for a new major release, but starting with + a dev snapshot. A few changes that were planned for a long time already: +- 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). +- 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. + +Finished 6 Aug 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, @@ -22,7 +139,7 @@ Version 1.2.5: routing issues on Jabber (i.e. messages going someone's phone instead of the main client). -Fixed 17 Mar 2010 +Finished 17 Mar 2010 Version 1.2.4: - Most important change (and main reason for releasing now): Upgraded Yahoo! 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/Makefile b/doc/Makefile index 9b473df3..5f59879e 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,4 +1,7 @@ -include ../Makefile.settings +ifdef SRCDIR +SRCDIR := $(SRCDIR)doc/ +endif all: # Only build the docs if this is a bzr checkout @@ -6,8 +9,8 @@ all: install: mkdir -p $(DESTDIR)$(MANDIR)/man8/ $(DESTDIR)$(MANDIR)/man5/ - install -m 0644 bitlbee.8 $(DESTDIR)$(MANDIR)/man8/ - install -m 0644 bitlbee.conf.5 $(DESTDIR)$(MANDIR)/man5/ + install -m 0644 $(SRCDIR)bitlbee.8 $(DESTDIR)$(MANDIR)/man8/ + install -m 0644 $(SRCDIR)bitlbee.conf.5 $(DESTDIR)$(MANDIR)/man5/ $(MAKE) -C user-guide $@ uninstall: @@ -8,7 +8,25 @@ 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. ---- inetd installation +--- (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 @@ -26,7 +44,7 @@ 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 +-- 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 @@ -41,25 +59,6 @@ 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. ---- (Fork)Daemon mode - -If you don't want to run any inetd daemon, you can run BitlBee in Daemon -mode. Right now, daemon mode may be a bad idea on servers with multiple -users, since possible fatal BitlBee bugs will crash the BitlBee process and -disconnect all connected users at once. Instead, you can use ForkDaemon -mode, which serves every user from a separate process, without depending on -an inetd daemon. - -To use BitlBee in daemon mode, just start it with the right flags or enable -it in bitlbee.conf. 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) - -Note that the BitlBee code is getting stable enough for daemon mode to be -useful. Some public servers use it, and it saves a lot of memory by serving -tens of users from a single process. One crash affects all users, but these -are becoming quite rare. - DEPENDENCIES ============ @@ -138,9 +137,12 @@ http://www.bitlbee.org/ The bug tracking system: http://bugs.bitlbee.org/ -Our version control system is Bazaar-NG. Our repository is at: +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 ENCRYPTION ==================== @@ -185,5 +187,5 @@ also licensed under the GPL. BitlBee - An IRC to other chat networks gateway <http://www.bitlbee.org/> - Copyright (C) 2002-2007 Wilmer van der Gaast <wilmer@gaast.net> + Copyright (C) 2002-2010 Wilmer van der Gaast <wilmer@gaast.net> and others diff --git a/doc/bitlbee.8 b/doc/bitlbee.8 index 9e634844..36576e59 100644 --- a/doc/bitlbee.8 +++ b/doc/bitlbee.8 @@ -38,9 +38,8 @@ BitlBee \- IRC gateway to IM chat networks BitlBee is an IRC daemon that can talk to instant messaging networks and acts as a gateway. Users can connect to the server with any normal IRC client and see their 'buddy list' in -&bitlbee. BitlBee's protocol support is based on the gaim -protocol plugins. BitlBee currently supports Oscar (aim and icq), -MSN, Jabber and Yahoo. +&bitlbee. It currently supports Oscar (AIM and ICQ), +MSN, Jabber, Yahoo! and Twitter. \fBbitlbee\fP should be called by .BR inetd (8), diff --git a/doc/user-guide/Makefile b/doc/user-guide/Makefile index 9841de8d..2a80ea6c 100644 --- a/doc/user-guide/Makefile +++ b/doc/user-guide/Makefile @@ -1,4 +1,8 @@ -include ../../Makefile.settings +ifdef SRCDIR +SRCDIR := $(SRCDIR)doc/user-guide/ +endif + EXTRAPARANEWLINE = 1 # EXTRAPARANEWLINE = 0 @@ -37,7 +41,7 @@ install: mkdir -p $(DESTDIR)$(DATADIR) chmod 0755 $(DESTDIR)$(DATADIR) rm -f $(DESTDIR)$(DATADIR)/help.txt # Prevent help function from breaking in running sessions - install -m 0644 help.txt $(DESTDIR)$(DATADIR)/help.txt + install -m 0644 $(SRCDIR)help.txt $(DESTDIR)$(DATADIR)/help.txt uninstall: rm -f $(DESTDIR)$(DATADIR)/help.txt diff --git a/doc/user-guide/commands.xml b/doc/user-guide/commands.xml index f8ae4386..7cedffc3 100644 --- a/doc/user-guide/commands.xml +++ b/doc/user-guide/commands.xml @@ -5,7 +5,7 @@ <bitlbee-command name="account"> <short-description>IM-account list maintenance</short-description> - <syntax>account <action> [<arguments>]</syntax> + <syntax>account [<account id>] <action> [<arguments>]</syntax> <description> @@ -20,7 +20,7 @@ <description> <para> - Adds an account on the given server with the specified protocol, username and password to the account list. Supported protocols right now are: Jabber, MSN, OSCAR (AIM/ICQ) and Yahoo. For more information about adding an account, see <emphasis>help account add <protocol></emphasis>. + 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> </description> @@ -62,6 +62,28 @@ <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. Although it uses the Twitter API, only Twitter itself is supported at the moment. + </para> + + <para> + By default all your Twitter contacts will come from a contact 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> + </description> + </bitlbee-command> <bitlbee-command name="yahoo"> <syntax>account add yahoo <handle> <password></syntax> @@ -76,7 +98,7 @@ </bitlbee-command> <bitlbee-command name="del"> - <syntax>account del <account id></syntax> + <syntax>account <account id> del</syntax> <description> <para> @@ -85,13 +107,13 @@ <para> - The account ID can be a number (see <emphasis>account list</emphasis>), the protocol name or (part of) the screenname, as long as it matches only one connection. + 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 on [<account id>]</syntax> + <syntax>account [<account id>] on</syntax> <description> <para> @@ -99,14 +121,14 @@ </para> <para> - The account ID can be a number (see <emphasis>account list</emphasis>), the protocol name or (part of) the screenname, as long as it matches only one connection. + 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 off [<account id>]</syntax> + <syntax>account [<account id>] off</syntax> <description> <para> @@ -114,7 +136,7 @@ </para> <para> - The account ID can be a number (see <emphasis>account list</emphasis>), the protocol name or (part of) the screenname, as long as it matches only one connection. + 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> @@ -130,14 +152,14 @@ </bitlbee-command> <bitlbee-command name="set"> - <syntax>account set <account id></syntax> - <syntax>account set <account id>/<setting></syntax> - <syntax>account set <account id>/<setting> <value></syntax> - <syntax>account set -del <account id>/<setting></syntax> + <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 set <account id></emphasis>. + 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> @@ -145,94 +167,108 @@ </para> <para> - The account ID can be a number (see <emphasis>account list</emphasis>), the protocol name or (part of) the screenname, as long as it matches only one connection. + 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="chat"> - <short-description>Chatroom list maintenance</short-description> - <syntax>chat <action> [<arguments>]</syntax> + <bitlbee-command name="channel"> + <short-description>Channel list maintenance</short-description> + <syntax>channel [<account id>] <action> [<arguments>]</syntax> <description> - <para> - Available actions: add, del, list, with and set. See <emphasis>help chat <action></emphasis> for more information. + Available actions: del, list, set. See <emphasis>help chat <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="add"> - <syntax>chat add <account> <room> [<channel>]</syntax> + <bitlbee-command name="del"> + <syntax>channel <channel id> del</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. + 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> - <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> + </bitlbee-command> + <bitlbee-command name="list"> + <syntax>channel list</syntax> + + <description> <para> - Password-protected rooms work exactly like on IRC, by passing the password as an extra argument to /join. + This command gives you a list of all the channels you configured. </para> </description> </bitlbee-command> - <bitlbee-command name="del"> - <syntax>chat del <chat id></syntax> + <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 commands deletes an chatroom from your list. + 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 room ID can be a number (see <emphasis>chat list</emphasis>), or (part of) the name of the room/channel. + 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 name="list"> - <syntax>chat list</syntax> + </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> - This command gives you a list of all the chatrooms known by BitlBee. + 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> - </description> - </bitlbee-command> - <bitlbee-command name="with"> - <syntax>chat with <nickname></syntax> + <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> - <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. + 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="set"> - <syntax>chat set <chat id></syntax> - <syntax>chat set <chat id>/<setting></syntax> - <syntax>chat set <chat id>/<setting> <value></syntax> - <syntax>chat set -del <chat id>/<setting></syntax> + <bitlbee-command name="with"> + <syntax>chat with <nickname></syntax> <description> <para> - This command can be used to change various settings for chatrooms. - </para> - - <para> - For more infomation about a setting, see <emphasis>help set <setting></emphasis>. - </para> - - <para> - The room ID can be a number (see <emphasis>chat list</emphasis>), or (part of) the name of the room/channel. + 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> @@ -240,8 +276,8 @@ <bitlbee-command name="add"> <short-description>Add a buddy to your contact list</short-description> - <syntax>add <connection> <handle> [<nick>]</syntax> - <syntax>add -tmp <connection> <handle> [<nick>]</syntax> + <syntax>add <account id> <handle> [<nick>]</syntax> + <syntax>add -tmp <account id> <handle> [<nick>]</syntax> <description> <para> @@ -251,6 +287,10 @@ <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> @@ -375,6 +415,25 @@ </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> @@ -389,18 +448,18 @@ </description> </bitlbee-setting> - <bitlbee-setting name="auto_join" type="boolean" scope="chat"> + <bitlbee-setting name="auto_join" type="boolean" scope="channel"> <default>false</default> <description> <para> - With this option enabled, BitlBee will automatically join this chatroom when you log in. + 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>false</default> + <default>true</default> <description> <para> @@ -435,6 +494,24 @@ </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> @@ -458,38 +535,41 @@ <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="buddy_sendbuffer" type="boolean" scope="global"> - <default>false</default> + <bitlbee-setting name="away_reply_timeout" type="integer" scope="global"> + <default>3600</default> <description> <para> - By default, when you send a message to someone, BitlBee forwards this message to the user immediately. When you paste a large number of lines, the lines will be sent in separate messages, which might not be very nice to read. If you enable this setting, BitlBee will buffer your messages and wait for more data. - </para> - - <para> - Using the <emphasis>buddy_sendbuffer_delay</emphasis> setting you can specify the number of seconds BitlBee should wait for more data before the complete message is sent. + 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> - 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. + 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="buddy_sendbuffer_delay" type="integer" scope="global"> - <default>200</default> + <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> - 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. + For example, set this setting to <emphasis>http://identi.ca/api</emphasis> to use Identi.ca. </para> <para> - See also the <emphasis>buddy_sendbuffer</emphasis> setting. + 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> @@ -520,6 +600,47 @@ </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> @@ -559,8 +680,50 @@ </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>root</default> + <default>add_channel</default> <possible-values>root, add, add_private, add_channel, ignore</possible-values> <description> @@ -586,6 +749,17 @@ </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> @@ -597,6 +771,17 @@ </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> @@ -608,15 +793,79 @@ </bitlbee-setting> - <bitlbee-setting name="nick" type="string" scope="chat"> + <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>one</default> + + <description> + <para> + By default, everything from the Twitter module will come from one nick, twitter_(yourusername). If you prefer to have individual nicks for everyone, you can set this setting to "many" instead. + </para> + + <para> + If you prefer to have all your Twitter things in a separate channel, you can set this setting to "chat". + </para> + + <para> + In the last two modes, you can send direct messages by /msg'ing your contacts directly. Note, however, that incoming DMs are not fetched yet. + </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> @@ -632,6 +881,25 @@ </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> @@ -662,6 +930,39 @@ </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> @@ -699,6 +1000,15 @@ </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> @@ -767,6 +1077,42 @@ </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> @@ -816,6 +1162,51 @@ </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> @@ -844,6 +1235,35 @@ </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> @@ -854,6 +1274,20 @@ </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> @@ -962,7 +1396,7 @@ </bitlbee-command> <bitlbee-command name="identify"> - <syntax>identify <password></syntax> + <syntax>identify [-noload|-force] <password></syntax> <short-description>Identify yourself with your password</short-description> <description> @@ -973,6 +1407,14 @@ <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> </description> </bitlbee-command> @@ -999,21 +1441,57 @@ </bitlbee-command> - <bitlbee-command name="nick"> - <short-description>Change friendly name, nick</short-description> - <syntax>nick <connection> [<new nick>]</syntax> - <syntax>nick <connection></syntax> + <bitlbee-command name="group"> + <short-description>Contact group management</short-description> + <syntax>group list</syntax> <description> <para> - Deprecated: Use the per-account <emphasis>display_name</emphasis> setting to read and change this information. + Only the <emphasis>group list</emphasis> command is supported at the moment, which shows a list of all groups defined so far. </para> </description> + </bitlbee-command> + + <bitlbee-command name="transfers"> + <short-description>Monitor, cancel, or reject file transfers</short-description> + <syntax>transfers [<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 transfers <action></emphasis> for more information. + </para> - <ircexample> - <ircline nick="wouter">account set 1/display_name "The majestik møøse"</ircline> - <ircline nick="root">display_name = `The majestik møøse'</ircline> - </ircexample> + <ircexample> + <ircline nick="ulim">transfers</ircline> + </ircexample> + </description> + + <bitlbee-command name="cancel"> + <short-description>Cancels the file transfer with the given id</short-description> + <syntax>transfers <cancel> id</syntax> + + <description> + <para>Cancels the file transfer with the given id</para> + </description> + <ircexample> + <ircline nick="ulim">transfers 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>transfers <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">transfers reject</ircline> + </ircexample> + </bitlbee-command> </bitlbee-command> + </chapter> diff --git a/doc/user-guide/help.xml b/doc/user-guide/help.xml index 7487a841..48ed8a48 100644 --- a/doc/user-guide/help.xml +++ b/doc/user-guide/help.xml @@ -13,9 +13,11 @@ These are the available help subjects: <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>smileys</term><listitem><para>A summary of some non-standard smileys you might find and fail to understand</para></listitem></varlistentry> <varlistentry><term>groupchats</term><listitem><para>How to work with groupchats on BitlBee</para></listitem></varlistentry> + <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> @@ -42,9 +44,11 @@ These are the available help subjects: <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>smileys</term><listitem><para>A summary of some non-standard smileys you might find and fail to understand</para></listitem></varlistentry> <varlistentry><term>groupchats</term><listitem><para>How to work with groupchats on BitlBee</para></listitem></varlistentry> + <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> diff --git a/doc/user-guide/misc.xml b/doc/user-guide/misc.xml index a926775a..7829a432 100644 --- a/doc/user-guide/misc.xml +++ b/doc/user-guide/misc.xml @@ -116,4 +116,121 @@ If you want to set an away state for only one of your connections, you can use t </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>. +</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>set 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> + </chapter> diff --git a/doc/user-guide/quickstart.xml b/doc/user-guide/quickstart.xml index 0539a7c7..80c16ffb 100644 --- a/doc/user-guide/quickstart.xml +++ b/doc/user-guide/quickstart.xml @@ -2,7 +2,7 @@ <title>Quickstart</title> <para> -Welcome to BitlBee, your IRC gateway to ICQ, MSN, AOL, Jabber and Yahoo Instant Messaging Systems. +Welcome to BitlBee, your IRC gateway to ICQ, MSN, AOL, Jabber, Yahoo! and Twitter. </para> <para> @@ -42,7 +42,7 @@ For instance, suppose you have a Jabber account at jabber.org with handle <empha </ircexample> <para> -Other available IM protocols are msn, oscar, and yahoo. 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>. +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> |