[nongnu] elpa/flx e24352a502 074/182: add usage information

[ELPA Syncer]

branch: elpa/flx
commit e24352a502c8ada7cbc59bfb19b97235304267d6
Author: Le Wang <le.wang@agworld.com.au>
Commit: Le Wang <le.wang@agworld.com.au>

    add usage information
    
    fixes #33
---
 README.md | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/README.md b/README.md
index 40942ba47b..541e377b2a 100644
--- a/README.md
+++ b/README.md
@@ -48,6 +48,33 @@ This version will always be up-to-date.
 user - `flx-ido` is already properly configured and ready for
 action.
 
+## Usage
+
+The sorting algorithm is a balance between word beginnings (abbreviation) and
+contiguous matches (substring).
+
+The longer the substring match, the higher it scores.  This maps well to how
+we think about matching.
+
+In general, it's better form queries wiht only **alphanumeric** characters so
+the sorting algorithm can do something smart.
+
+For example, if you have these files:
+
+    projects/clojure-mode/clojure-mode.el
+    projects/prelude/core/prelude-mode.el
+
+If the search term was "pre-mode", you might expect "prelude-mode.el" to be
+ranked higher.  However because the substring match "re-mode" is so long,
+"clojure-mode.el" actually scores higher.
+
+
+Here, using "premode" would give the expected order
+
+### completing file names
+
+Matches within the basepath score higher.
+
 ## ido support
 
 Add this to your init file and *flx* match will be enabled for ido.