From 35bf46766ebe8d702cb4440545c8b7e8f7e13363 Mon Sep 17 00:00:00 2001
From: Joe Wreschnig <joe.wreschnig@gmail.com>
Date: Mon, 24 Aug 2015 22:31:49 +0200
Subject: [PATCH] Updates for new hosting.

---
 .gitignore              |  3 +++
 README.txt => README.md | 59 ++++++++++++++++++++++++++++-------------
 2 files changed, 44 insertions(+), 18 deletions(-)
 create mode 100644 .gitignore
 rename README.txt => README.md (63%)

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..1db1631
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,3 @@
+build
+*.pyc
+collate/icu/_icu.c
diff --git a/README.txt b/README.md
similarity index 63%
rename from README.txt
rename to README.md
index eeb68b0..9b7adef 100644
--- a/README.txt
+++ b/README.md
@@ -1,12 +1,12 @@
-pycollate - Collation algorithms for Python
+# Collation algorithms for Python
 -------------------------------------------
 
 pycollate is an interface to various collation algorithms for Python.
 
 Supported backends:
-- icu - Based on the IBM ICU toolkit and Jim Fulton's zope.ucol.
-- syslocale - Native OS collation routines.
-- codepoint - Raw Unicode codepoint comparison
+- `icu` - Based on the IBM ICU toolkit and Jim Fulton's zope.ucol.
+- `syslocale` - Native OS collation routines.
+- `codepoint` - Raw Unicode codepoint comparison
 
 If available, you'll probably want to use the ICU backend. If it's not
 available, syslocale should work on most Python installations. A
@@ -17,22 +17,45 @@ pycollate also provides tools to perform word-wise and numeric sorts.
 
 pycollate, as with all Unicode collation tools, is a work in progress.
 
-Installing
-----------
-$ sudo apt-get install python-pyrex libicu-dev
-$ ./setup.py build
-$ sudo ./setup.py install
+## Installing
 
-Example
--------
-import collate
-strings = open("contents.txt").read().decode("utf-8").splitlines()
-strings.sort(key=collate.key)
+    $ sudo apt-get install python-pyrex libicu-dev
+    $ ./setup.py build
+    $ sudo ./setup.py install
 
-License
--------
+## Example
 
-icu/_icu.pyx:
+    import collate
+    strings = open("contents.txt").read().decode("utf-8").splitlines()
+    strings.sort(key=collate.key)
+
+## FAQ
+
+### What's collation?
+
+Collation is the process of sorting information in a useful way. In
+particular, this module sorts strings in a way that humans might
+expect to read them.
+
+### What's so hard about that?
+
+Nothing, if your strings are all in one language and you speak English
+yourself.
+
+On the other hand, if that's not the case you need to make sure "ss"
+and "ß" sort similarly, "å" sorts like "A" (unless you're Swedish),
+and "21 Monkeys" comes after "3 Monkeys".
+
+### How fast is the library?
+
+Slow enough that you will probably want to cache sort keys. On a
+mid-range system at the time of its writing, it takes about half a
+second to sort 10000 song titles.
+
+
+## License
+
+### icu/_icu.pyx
 
 Copyright (c) 2004 Zope Corporation and Contributors.
 All Rights Reserved.
@@ -44,7 +67,7 @@ WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
 FOR A PARTICULAR PURPOSE.
 
-All else:
+### All else
 
 Copyright 2010 Joe Wreschnig
 
-- 
2.20.1