Ready for first release

README.md

@@ -1,21 +1,80 @@
 # KMonad
 
-If you have somehow stumbled into my little remote corner of GitHub and
-encountered this project: welcome! Feel free to try KMonad, it is currently
-extremely experimental. I will be continuing to test and document it over the
-coming weeks, and when I am content it is ready for more widespread testing, I
-will announce it in a number of places.
-
-# Installing KMonad
-
-You can either compile KMonad yourself using haskell. It should be very
-straighforward with stack. Alternatively, once I decide that we're ready to
-start testing at a larger scale, I will provide a release with a statically
-compiled binary, thanks to the lovely people over at
-https://github.com/nh2/static-haskell-nix. 
-
-## Compiling
-Currently KMonad is configured to be compiled by stack. If you do not have stack
+Welcome to the very first release of KMonad! Please bear with us, this is our
+very first release, and our very first open source project of any real scale.
+Let me start by immediately disappointing you if you are running Windows or Mac:
+KMonad has been developed and tested solely on Linux and currently depends on
+the linux `/dev/input` files and the `uinput` subsystem to interface with the
+OS. Trying to get cross-platform support is high on my todo list, and any help
+is greatly appreciated.
+
+## What is KMonad?
+
+KMonad is a keyboard remapping utility written to provide functionality that
+aligns with that provided by the amazing [QMK
+firmware](https://github.com/qmk/qmk_firmware/). The QMK firmware is compiled
+and installed on programmable keyboards and allows your keyboards to transform
+from comfortable clacky ("Wahaay!" for mechanical switches) to amazingly useful,
+by introducing the ability to overlap various maps of keys, have different
+functionality for the same key when held or tapped, or create buttons that can
+be tapped multiple times to have different effects.
+
+However, we can't always have our programmable keyboard with us, and I
+personally don't like using it with my laptop, because it either becomes a
+balancing act, or I have to sit at a table with my laptop uncomfortably far away
+from me. Additionally, there are loads of people who do not have programmable
+keyboards who might enjoy all the bells and whistles that QMK has to offer, and
+so `KMonad` was born.
+
+### What about that name, KMonad?
+
+The name KMonad is a wink at my favorite window manager:
+[XMonad](https://github.com/xmonad/xmonad), but where XMonad manages your
+x-windows in its X-monad, we manage your Keys in our K-monad (actually, we call
+it App, but who's checking).
+
+### What can I do with KMonad?
+
+Well, there are a variety of customizations you can make. For example, this
+duplicates the functionality of another popular Linux utility: XCAPE, which
+allows you to specify mod-buttons that also emit events when you simply tap
+them. 
+
+For example, look at that useless CapsLock key on your keyboard. It is in a
+**great** position, but do we ever use it? Well, what if you could remap
+CapsLock to a button that behaves like a Ctrl key? That's already quite nice.
+What if it could also emit 'Esc' when you tap it? Yep: all of that is possible.
+
+Do you write a lot of Haskell code and define your own operators? Do you want
+your operators to look like this: =>=->->>? That's a lot to type. Why not just
+define a macro that does it for you?
+
+The same technique can be used to create macros that insert a variety of
+accented or umlauted characters, depending on your OS. Why type `AltGr " e` when
+you can put this macro in a layer on a button close to home row? (Note:
+compose behavior depends on your OS, I don't think there is any 1 way to
+implement this). 
+
+Or more practically: do you really like the Dvorak layout, but do you also wish
+you had very simple, left-handed access to the common Control z x c v shortcuts?
+Have a look at <insert-link-here> to see an easy solution. 
+
+For more ideas, check the `example` subdirectory, or the [syntax
+guide](https://github.com/david-janssen/kmonad/blob/master/doc/syntax_guide.md)
+for an overview of different button-types.
+
+## Getting KMonad
+
+KMonad is written in haskell (with a tiny bit of C). You can either compile it
+yourself using the instructions mentioned below. Alternatively, the lovely
+people over at https://github.com/nh2/static-haskell-nix have helped me figure
+how to compile a static binary that should work basically on any standard 64-bit
+linux system. Note that this is almost entirely untested, only on my own
+computer and in a virtualbox running Ubuntu. The binary for the most current
+release can be found <insert-link-here>.
+
+### Compiling
+Probably the easiest way to compile KMonad is using `stack`. If you do not have `stack`
 installed, check https://docs.haskellstack.org/en/stable/README/ for
 instructions on installing it. After compilation, it can be removed again, since
 `kmomad` does not need to be recompiled upon configuration.
@@ -30,7 +89,9 @@ Or call the following:
 ``` shell
 stack haddock --no-haddock-deps
 ```
-to build a KMonad binary and the haddock documentation.
+to build a KMonad binary and the haddock documentation. I have put some effort
+into documenting the code if you want to have a look around. It is nowhere near
+perfect, and I hope to do more in the future.
 
 `stack` will tell you where it saved the compiled binary after which you can
 copy it to somewhere on your path.
@@ -78,3 +139,10 @@ sudo modprobe uinput
 This might have to be repeated whenever you restart your computer. There are
 various techniques for getting the `uinput` subsystem to load automatically, but
 I didn't manage to get any of them to work.
+
+### Figuring out which event-file corresponds to your keyboard 
+Sometimes you can find your keyboard listed under `/dev/input/by-id`. If so,
+this is by far the best solution, since there is no guarantee that a keyboard
+will be assigned the same numbered event-file. If this is not the case, however,
+the easiest way to figure out which event-file corresponds to your keyboard is
+probably to use the `evtest` linux utility. 

example/dvorak_sane_zxcv.kbd

@@ -0,0 +1,67 @@
+/* This example shows how to implement Dvorak, but still provide a solution for
+left-hand only common shortcuts. There are various possible solutions: you could
+implement an entire layer that is simply completely QWERTY, but every key
+modified by Ctrl. However, that might be rough on your brain. The solution here
+is to leave Ctrl unchanged, so all shortcuts are available via Ctrl and the
+normal DVorak layout. In addition, though, we implement a layer with the basic
+C-z, C-x, C-c, C-v shortcuts mapped to asdf, accessible through caps-lock.
+
+Just to make that layer a bit sweeter we put a numpad under the right-hands
+home-row, and add a shift to the left thumb, making it easy to type all numbers
+and shifted-numbers without strechting your hands.
+
+Just in case you still really need caps-lock (I never use it), we hide it at the
+location for right-shift in the `sym` layer.
+
+*/
+
+// IO
+INPUT = LINUX_DEVICE L64 /dev/input/by-id/usb-04d9_daskeyboard-event-kbd
+OUTPUT = UINPUT_SINK
+
+/* Copy this out to create a new layer
+LAYER name
+  _    _    _    _    _    _    _    _    _    _    _    _    _
+  _    _    _    _    _    _    _    _    _    _    _    _    _    _
+  _    _    _    _    _    _    _    _    _    _    _    _    _    _
+  _    _    _    _    _    _    _    _    _    _    _    _         _
+  _    _    _    _    _    _    _    _    _    _    _              _
+  _    _    _                   _                   _    _    _    _
+*/
+
+@sym = LT-sym            // Use this to create a 'switch to sym button'
+@smt = TH 300 esc LT-sym // Use this if you want that button to also double
+                         // as an escape key when tapped
+
+// Different ways of adding accents to letters
+@e1 = CMP-|| " e ||      // I think this is how a Compose key is supposed to work?
+@e2 = CMP-|| ' e ||      // Or do you tap it before the rest of the sequence?
+@e3 = || cmps " e ||     // This is how a tapped compose-key macro would look.
+@e4 = RA-e               // Additionally something RightAlt as a mod can add accents
+
+// Source codes: standard ansi qwerty
+SRC
+  esc  f1   f2   f3   f4   f5   f6   f7   f8   f9   f10  f11  f12
+  grv  1    2    3    4    5    6    7    8    9    0    -    =    bspc
+  tab  q    w    e    r    t    y    u    i    o    p    [    ]    \
+  caps a    s    d    f    g    h    j    k    l    ;    '         ret
+  lsft z    x    c    v    b    n    m    ,    .    /              rsft
+  lctl lmet lalt                spc                 ralt rmet cmps rctl
+
+// Dvorak base:
+LAYER dvorak
+  esc  f1   f2   f3   f4   f5   f6   f7   f8   f9   f10  f11  f12
+  grv  1    2    3    4    5    6    7    8    9    0    [    ]    bspc
+  tab  '    ,    .    p    y    f    g    c    r    l    /    =    \
+  @sym a    o    e    u    i    d    h    t    n    s    -         ret
+  lsft ;    q    j    k    x    b    m    w    v    z              rsft
+  lctl lmet lalt                spc                 ralt rmet cmps rctl
+
+// Symbs, left-handed short-cuts, right hand numpad, thumb-shift for symbols
+LAYER sym
+  _    _    _    _    _    _    _    _    _    _    _    _    _
+  _    _    _    _    _    _    _    _    /    *    _    _    _    _
+  _    _    _    @e1  @e2  _    _    7    8    9    -    _    _    _
+  _    C-z  C-x  C-c  C-v  _    _    4    5    6    +    _         _
+  _    _    _    _    _    _    _    1    2    3    0              caps
+  _    _    lsft                _                   _    _    _    _

src/KMonad/Core/Parser/Parsers/Button.hs

@@ -141,8 +141,9 @@ modded = do
                 , KeyRightCtrl  <$ string "RC-"
                 , KeyRightAlt   <$ string "RA-"
                 , KeyRightMeta  <$ string "RM-"
+                , KeyCompose    <$ string "CMP-"
                 ]
-  rest <- modded <|> emit
+  rest <- modded <|> emit <|> tapMacro
   return $ BModded mod rest
 
 -- | Parse a number of special characters as "the shifted sequence to push

src/KMonad/Core/Parser/Parsers/KeyCode.hs

@@ -83,6 +83,7 @@ specialNames = concatMap (\(k, as) -> map (,k) as) $
   , (KeyBrightnessDown, ["brdown", "brdwn", "brdn"])
   , (KeyLeftAlt,        ["lalt"])
   , (KeyRightAlt,       ["ralt"])
+  , (KeyCompose,        ["comp", "cmps"])
   , (KeyLeftShift,      ["lshift", "lshft", "lsft"])
   , (KeyRightShift,     ["rshift", "rshft", "rsft"])
   , (KeyLeftCtrl,       ["lctrl", "lctl"])