Add utf8.{c,h} for common UTF-8 util functions

We need to validate some UTF-8, so this adds an is_valid_utf8()
function, which is probably pretty slow but should work correctly.

Signed-off-by: Ran Benita <ran234@gmail.com>
state: add xkb_state_key_get_{utf8,utf32}() API functions

These functions generally have the same effect as
xkb_state_key_get_syms() + xkb_keysym_to_utf{8,32}().

So why add them?

- They provide a slightly nicer interface, especially if the string is
  the only interest.

- It makes the handling of multiple-keysyms-to-utf8 transparent. For the
  designated use-case of multiple-keysyms (unicode combining
  characters), this is a must. We also validate the UTF-8, which the
  user might not otherwise do.

- We will need to apply some transformation on the resulting string
  which depend on the xkb_state. This is not possible with the
  xkb_keysym_* functions.

With these functions, the existing xkb_keysym_to_utf{8,32}() are not
expected to be used by a typical user; they are "raw" functions.

Signed-off-by: Ran Benita <ran234@gmail.com>
state: apply control transformation on utf8/utf32 keysym strings

This is required by the specification:
http://www.x.org/releases/current/doc/kbproto/xkbproto.html#Interpreting_the_Control_Modifier
and clients expect this to happen.

https://bugs.freedesktop.org/show_bug.cgi?id=75892

Reported-by: Gatis Paeglis <gatis.paeglis@digia.com>
Signed-off-by: Ran Benita <ran234@gmail.com>
doc: add a quick guide to the library

This is a nice intro to the documentation, and also preferably gently
pushes users to the "proper way" of using the library, which can be
confusing.

See also: http://fooishbar.org/tell-me-about/xkbcommon-intro/

Signed-off-by: Ran Benita <ran234@gmail.com>
Reformat README markdown

So that github displays it as markdown, and correctly.

Signed-off-by: Ran Benita <ran234@gmail.com>
state: fix consumed modifier calculation

The current calculation is in short:
    entry ? (entry->mask & ~entry->preserve) : 0

This changes it be
    type->mask & ~(entry ? entry->preserve : 0)

This is what Xlib does. While less intuitive, it is actually more
correct, if you follow this deduction:

- The key group's type->mask defines which modifiers the key even cares
  about. The others are completely irrelevant (and in fact they are
  masked out from all sided in the level calculation). Example: NumLock
  for an alphabetic key.

- The type->mask, the mods which are not masked out, are *all* relevant
  (and in fact in the level calculation they must match *exactly* to the
  state). These mods affect which level is chosen for the key, whether
  they are active or not.

- Because the type->mask mods are all relevant, they must be considered
  as consumed by the calculation *even if they are not active*.

Therefore we use type->mask instead of entry->mask.

The second change is what happens when no entry is found: return 0 or
just take preserve to be 0? Let's consider an example, the basic type

    type "ALPHABETIC" {
        modifiers = Shift+Lock;
        map[Shift] = Level2;
        map[Lock] = Level2;
        level_name[Level1] = "Base";
        level_name[Level2] = "Caps";
    };

Suppose Shift+Lock is active - it doesn't match any entry, thus it gets
to level 0. The first interpretation would take them both to be
unconsumed, the second (new one) would take them both to be consumed.
This seems much better: Caps is active, and Shift disables it, they both
do something.

This change also fixes a pretty lousy bug (since 0.3.2), where Shift
appears to apparently *not* disable Caps. What actually happens is that
Caps is not consumed (see above) but active, thus the implicit
capitalization in get_one_sym() kicks in and capitalizes it anyway.

Reported-by: Davinder Pal Singh Bhamra
Signed-off-by: Ran Benita <ran234@gmail.com>