diff options
Diffstat (limited to 'doc/user-guide')
| -rw-r--r-- | doc/user-guide/Makefile | 6 | ||||
| -rw-r--r-- | doc/user-guide/commands.xml | 384 | ||||
| -rw-r--r-- | doc/user-guide/help.xml | 8 | ||||
| -rw-r--r-- | doc/user-guide/misc.xml | 97 |
4 files changed, 408 insertions, 87 deletions
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 0cef37ce..46d12a9c 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> @@ -98,7 +98,7 @@ </bitlbee-command> <bitlbee-command name="del"> - <syntax>account del <account id></syntax> + <syntax>account <account id> del</syntax> <description> <para> @@ -113,7 +113,7 @@ </bitlbee-command> <bitlbee-command name="on"> - <syntax>account on [<account id>]</syntax> + <syntax>account [<account id>] on</syntax> <description> <para> @@ -128,7 +128,7 @@ </bitlbee-command> <bitlbee-command name="off"> - <syntax>account off [<account id>]</syntax> + <syntax>account [<account id>] off</syntax> <description> <para> @@ -152,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> @@ -173,88 +173,102 @@ </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> - The room ID can be a number (see <emphasis>chat list</emphasis>), or (part of) the name of the room/channel. + 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. </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> <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> @@ -397,6 +411,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> @@ -411,12 +444,12 @@ </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> @@ -483,53 +516,34 @@ </description> </bitlbee-setting> - <bitlbee-setting name="base_url" type="string" scope="account"> - <default>http://twitter.com</default> + <bitlbee-setting name="away_reply_timeout" type="integer" scope="global"> + <default>3600</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. + 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> - 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. + 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" type="boolean" scope="global"> - <default>false</default> + <bitlbee-setting name="base_url" type="string" scope="account"> + <default>http://twitter.com</default> <description> <para> - By default, when you send a message to someone, BitlBee forwards this message to the user immediately. When you paste a large number of lines, the lines will be sent in separate messages, which might not be very nice to read. If you enable this setting, BitlBee will buffer your messages and wait for more data. - </para> - - <para> - Using the <emphasis>buddy_sendbuffer_delay</emphasis> setting you can specify the number of seconds BitlBee should wait for more data before the complete message is sent. - </para> - - <para> - Please note that if you remove a buddy from your list (or if the connection to that user drops) and there's still data in the buffer, this data will be lost. BitlBee will not try to send the message to the user in those cases. + There are more services that understand the Twitter API than just Twitter.com. BitlBee can connect to all Twitter API implementations. </para> - </description> - </bitlbee-setting> - - <bitlbee-setting name="buddy_sendbuffer_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. + 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> @@ -560,6 +574,25 @@ </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="debug" type="boolean" scope="global"> <default>false</default> @@ -609,8 +642,40 @@ </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> @@ -716,7 +781,6 @@ </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. @@ -724,6 +788,36 @@ </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> @@ -788,6 +882,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> @@ -825,6 +952,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> @@ -1013,6 +1149,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> @@ -1145,7 +1310,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> @@ -1156,6 +1321,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> @@ -1194,9 +1367,52 @@ </description> <ircexample> - <ircline nick="wouter">account set 1/display_name "The majestik møøse"</ircline> + <ircline nick="wouter">account 1 set display_name "The majestik møøse"</ircline> <ircline nick="root">display_name = `The majestik møøse'</ircline> </ircexample> </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="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..825d80ee 100644 --- a/doc/user-guide/misc.xml +++ b/doc/user-guide/misc.xml @@ -116,4 +116,101 @@ 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> +</variablelist> + +<para> +One modifier is currently available: %-@variable will remove all characters from the first @ in the string. +</para> + +<para> +In all cases, invalid characters (like spaces) will be stripped. Depending +on your locale settings, characters with accents will be converted to ASCII. +</para> + +</sect1> + </chapter> |