[gnome-shell/wip/fmuellner/pardon-my-french: 13/22] Add basic documentation

[Florian Müllner <fmuellner src gnome org>]

commit 22eac5c508ac4bdd34a27e1138c6037182b14bab
Author: Alan <alan boum org>
Date:   Wed Aug 2 09:31:50 2017 +0000

    Add basic documentation

 README.mdwn | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)
---
diff --git a/README.mdwn b/README.mdwn
new file mode 100644
index 000000000..0eb54bcae
--- /dev/null
+++ b/README.mdwn
@@ -0,0 +1,40 @@
+cldr2json
+=========
+
+This script converts Unicode CLDR android keyboard layouts to JSON usable by
+GNOME Shell.
+
+CLDR keyboard layouts can be found at
+<http://www.unicode.org/Public/cldr/latest/keyboards.zip>
+
+
+Usage
+=====
+
+    ./cldr2json <input file or directory> <output directory>
+
+example:
+
+    ./cldr2json cldr/keyboards/android/ json_layouts/
+
+
+Keyboard layout mapping
+=======================
+
+Unicode CLDR layout identifiers are language codes, while XKB layout
+identifiers are... something else. The mapping between the two currently uses
+heuristic based on the layout descriptions, in this order:
+
+- if the CLDR layout description matches an XKB layout description, chose its
+  XKB identifier
+- if one word of the CLDR layout description matches an XKB layout
+  description, chose its XKB identifier
+- if the CLDR layout description matches one word of an XKB layout description,
+  chose its XKB identifier
+
+That doesn't always work. For instance it fails for "en" language, that should
+match "us" XKB identifier. For such cases, there is a mapping in
+LOCALE_TO_XKB_OVERRIDES at the top of the script. If you discover a weird
+mapping of if you get a "failed to find XKB mapping for <locale>" warning then
+please consider adding an override there.
+