@@ -60,9 +60,21 @@ Requirements
 
 Nothing except Python itself.
 
-You will need a Python build with "wide" Unicode characters in order for
-unidecode to work correctly with characters outside of Basic Multilingual
-Plane. Surrogate pair encoding of "narrow" builds is not supported.
+You need a Python build with "wide" Unicode characters (also called "UCS-4
+build") in order for unidecode to work correctly with characters outside of
+Basic Multilingual Plane (BMP). Common characters outside BMP are bold, italic,
+script, etc. variants of the Latin alphabet intended for mathematical notation.
+Surrogate pair encoding of "narrow" builds is not supported in unidecode.
+
+If your Python build supports "wide" Unicode the following expression will
+return True::
+
+    >>> import sys
+    >>> sys.maxunicode > 0xffff
+    True
+
+See PEP 261 for details regarding support for "wide" Unicode characters in
+Python.
 
 
 Installation
 
@@ -51,10 +51,51 @@ def showwarning_new(message, category, *args):
 
 	def test_bmp(self):
 		for n in xrange(0,0x10000):
+			# skip over surrogate pairs, which throw a warning
+			if 0xd800 <= n <= 0xdfff:
+				continue
+
 			# Just check that it doesn't throw an exception
 			t = unichr(n)
 			unidecode(t)
 
+	@unittest.skipIf(sys.maxunicode < 0x10000, "narrow build")
+	def test_surrogate_pairs(self):
+		# same character, written as a non-BMP character and a
+		# surrogate pair
+		s = u'\U0001d4e3'
+
+		# Note: this needs to be constructed at run-time, otherwise
+		# a "wide" Python seems to optimize it automatically into a
+		# single character.
+		s_sp_1 = u'\ud835'
+		s_sp_2 = u'\udce3'
+		s_sp = s_sp_1 + s_sp_2
+
+		self.assertEqual(s.encode('utf16'), s_sp.encode('utf16'))
+
+		log = []
+		def showwarning_new(message, category, *args):
+			if ("Surrogate character" in str(message)) and \
+					(category is RuntimeWarning):
+				log.append((message, category))
+			else:
+				showwarning_old(message, category, *args)
+
+		showwarning_old = warnings.showwarning
+		warnings.showwarning = showwarning_new
+		warnings.filterwarnings("always")
+
+		a = unidecode(s)
+		a_sp = unidecode(s_sp)
+
+		self.assertEqual('T', a)
+
+		# Two warnings should have been logged
+		self.assertEqual(2, len(log))
+
+		warnings.showwarning = showwarning_old
+
 	def test_circled_latin(self):
 		# 1 sequence of a-z
 		for n in xrange(0, 26):
 
@@ -11,6 +11,10 @@ def test_ascii(self):
 
 	def test_bmp(self):
 		for n in range(0,0x10000):
+			# skip over surrogate pairs, which throw a warning
+			if 0xd800 <= n <= 0xdfff:
+				continue
+
 			# Just check that it doesn't throw an exception
 			t = chr(n)
 			unidecode(t)
 
@@ -44,6 +44,11 @@ def unidecode(string):
         if codepoint > 0xeffff:
             continue # Characters in Private Use Area and above are ignored
 
+        if 0xd800 <= codepoint <= 0xdfff:
+            warnings.warn(  "Surrogate character %r will be ignored. "
+                            "You might be using a narrow Python build." % (char,),
+                            RuntimeWarning, 2)
+
         section = codepoint >> 8   # Chop off the last two hex digits
         position = codepoint % 256 # Last two hex digits