Changeset db2cef1 for doc

Timestamp:

2010-07-13T00:09:40Z (14 years ago)

Author:

Wilmer van der Gaast <wilmer@…>

Branches:

master

Children:

06b39f2

Parents:

badd148

Message:

Document this complex new beast.

Location:

doc/user-guide

Files:

• commands.xml (modified) (1 diff)
• misc.xml (modified) (1 diff)

doc/user-guide/commands.xml

@@ -764 +764 @@
 
         <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>

doc/user-guide/misc.xml

@@ -180 +180 @@
 </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>