From db2cef1ab11cc58cc92c16fd9bccd0fe17e413e4 Mon Sep 17 00:00:00 2001
From: Wilmer van der Gaast <wilmer@gaast.net>
Date: Tue, 13 Jul 2010 01:09:40 +0100
Subject: Document this complex new beast.

---
 doc/user-guide/commands.xml | 31 ++++++++++++++++++++++++++++++-
 doc/user-guide/misc.xml     | 34 ++++++++++++++++++++++++++++++++++
 2 files changed, 64 insertions(+), 1 deletion(-)

(limited to 'doc/user-guide')

diff --git a/doc/user-guide/commands.xml b/doc/user-guide/commands.xml
index be61e4db..d0ce485e 100644
--- a/doc/user-guide/commands.xml
+++ b/doc/user-guide/commands.xml
@@ -763,7 +763,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.
@@ -771,6 +770,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>
diff --git a/doc/user-guide/misc.xml b/doc/user-guide/misc.xml
index 175f0cd4..825d80ee 100644
--- a/doc/user-guide/misc.xml
+++ b/doc/user-guide/misc.xml
@@ -179,4 +179,38 @@ If you want to configure your own channels, you can use the <emphasis>channel se
 
 </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>
-- 
cgit v1.2.3