Release version 0.0.1

Author: thkala

AUTHORS

@@ -0,0 +1 @@
+Theodoros V. Kalamatianos <[email protected]>

COPYING

@@ -0,0 +1,2 @@
+Fri Aug 19 00:48:28 EEST 2005 - Theodoros V. Kalamatianos <[email protected]>
+	* Initial testing release (0.0.1)

ChangeLog

@@ -0,0 +1,82 @@
+* Why yet another keyboard daemon ?
+
+Because I needed a daemon that:
+
+- is small and simple
+- is NOT X Window based, so that it's usable even from the console
+- can execute external programs
+- can handle key combinations
+
+
+* What about the other daemons
+
+I had a look at the following:
+
+- lineakd:
+    pros: modules
+    cons: X-based
+
+- pbbuttonsd:
+    pros: not X-based (IIRC)
+    cons: could not find how to execute external programs, Mac-centric,
+	bloated with PM stuff and other non-keyboard stuff.
+
+- esekeyd
+    pros: not X-based, executes external programs
+    cons: does not support key combinations
+
+    I used a self-modified (i.e. with limited combination support) esekeyd
+    for quite some time, until I decided to write my own daemon.
+
+- keyed
+    pros: not X-based, executes external programs
+    cons: alpha, with fork() issues (according to the author)
+
+- evkeyd
+    pros: not X-based
+    cons: no external program execution, no key combinations
+
+
+* Does it work ?
+
+I have performed some minimal testing and it seems to work fine. I will have
+to receive quite a lot of feedback before I mark it as stable, though.
+
+
+* How does it work ?
+
+To find out read the `Internals' section in the README. Then read the source
+code itself for details.
+
+
+* I found a bug !
+
+Good! Now report it to me at <[email protected]>... or even better fix
+it and send a patch!
+
+
+* How can I help ?
+
+- Test it!
+- Report bugs!
+- Ideas, suggestions e.t.c. are welcome. Patches even more :-D
+- Occasionally you may drop a line to say that it worked for you. Positive
+  feedback is just as important.
+
+
+* I don't like your coding style
+
+I don't like yours either.
+
+
+* Who wrote it ?
+
+Me, Theodoros Kalamatianos, a student at the department of Electric and Computer
+Engineering of the National Technical University of Athens. For purposes related
+to actkbd I may be reached at <[email protected]>.
+
+
+* Under what license is it released ?
+
+Naturally, the GNU General Public License. The full text of the GPL is included
+in the actkbd tarball.

FAQ

@@ -0,0 +1,24 @@
+prefix := /usr/local
+sbindir := $(prefix)/sbin
+
+CFLAGS := -O2 -Wall $(DEBUG)
+
+
+
+all: actkbd
+
+actkbd: actkbd.o mask.o config.o linux.o
+
+actkbd.o : actkbd.h
+mask.o : actkbd.h
+config.o : actkbd.h
+
+linux.o : actkbd.h
+
+actkbd.h: version.h
+
+install: all
+	install -D -m755 actkbd $(sbindir)/actkbd
+
+clean:
+	rm -f actkbd *.o

Makefile

@@ -0,0 +1,2 @@
+0.0.1:
+	* Initial testing release

NEWS

@@ -0,0 +1,136 @@
+actkbd - A keyboard shortcut daemon
+
+
+
+Contents:
+
+    1. Introduction
+    2. Platforms
+    3. Setup
+	3.1. Compilation
+	3.2. Installation
+	3.3. Configuration
+	3.4. Running
+    4. Internals
+    5. License
+    6. Authors
+
+
+1. Introduction
+
+actkbd is a simple daemon that binds actions to keyboard events. It recognises
+key combinations and can handle press, repeat and release events. Currently it
+only supports the linux-2.6 evdev interface, but the platform-specific code is
+well-contained, so that support for additional platforms can be added with no
+or minimal changes to the rest of the code.
+
+It uses a plain-text configuration file which contains all the bindings. Its
+file format has some prediction for command modules, which would allow the user
+to perform some common actions (e.g. eject the CD-ROM or change the volume)
+without having to call external commands. Currently, though, actkbd can only
+execute external commands.
+
+
+
+2. Platforms
+
+Currently only the following platforms are supported:
+
+* Linux 2.6.x
+
+The following platforms will probably never be supported:
+
+* Windows - no POSIX, no support
+* BeOS - unless someone can resurrect it
+
+
+
+3. Setup
+
+3.1. Compilation
+
+A simple call to `make' is normally all you need to compile actkbd:
+
+$ make
+
+You can override the CFLAGS variable to provide optimisation flags e.t.c. The
+DEBUG variable can be used to enable debugging - if you are using gcc, setting
+DEBUG to "-g" would probably do.
+
+
+3.2. Installation
+
+First verify with `make -n install' the installation paths. By default, the
+installation prefix is /usr/local and the actkbd daemon binary is installed in
+$(prefix)/sbin. You can set the prefix and sbindir variables to override these
+defaults. Then run `make install' as root to perform the actual installation:
+
+# make install
+
+
+3.3. Configuration
+
+The default configuration file resides in /etc/actkbd.conf. It is a plain-text
+file with each line being an entry. A proper entry has the following format:
+
+<keys>:<event type>:<command module>:<command>
+
+The <keys> field is a series of numeric keycodes, separated by the `+'
+character. `actkbd -n -s' can be used to find out any keycodes you need.
+
+The <event type> string field is one of `key' (key press event), `rep' (key
+repeat event) or `rel' (key release event). If empty, it defaults to `key'.
+
+The <command module> field is currently ignored.
+
+The <command> field is the executed command that will be passed to system(). Note
+that in order to have non-blocking behaviour, you have to append the `&' character
+to the command, so that /bin/sh will execute it in the background.
+
+Lines starting with '#' are considered comments. Invalid lines are silently
+ignored, unless a high enough verbosity level has been specified.
+
+
+3.4. Running
+
+Run `actkbd --help' to see the various command line options. actkbd is normally
+able to auto-detect your keyboard device, therefore you do not need to specify
+it. For the most common case - a daemon with the default configuration file in
+/etc - the following command should suffice:
+
+# actkbd -D -q
+
+Note that sending HUP to actkbd will cause it to reload the configuration file.
+
+
+4. Internals
+
+The most interesting/messy part of evkey is the code that keeps track of which
+keys are pressed each moment. It uses a bitmask with one bit for each available
+key. When press/repeat events are received, the corresponding bit is set and it
+becomes unset when a release event is received for that key. To match key events
+with the corresponding actions, each valid configuration file entry has its key
+field transformed to a bitmask. After that, whenever a new event is received,
+the status bitmask is matched against all configuration entry bitmasks and the
+first one to match (if any) is used and the corresponding command is executed.
+
+Please note that the platform specific code is contained in <platform>.c (.e.g.
+linux.c). This file implements a generic interface to keyboard events, hiding
+each system's intricacies from the rest of code. It is also the file that has
+to be written/ported to add support for a new platform.
+
+For any additional details the best documentation is probalby the source code
+itself.
+
+
+5. License
+
+actkbd is released under the GNU General Public License version 2. The full
+text of the GPL is in the COPYING file that should be included in the actkbd
+distribution.
+
+
+6. Authors
+
+Original author:
+    Theodoros V. Kalamatianos <[email protected]>

README

@@ -0,0 +1,33 @@
+* Find out what happens if the keyboard device suddenly disappears - I have
+  to find a USB keyboard to test this. Make sure we handle this gracefully.
+
+* Perform some testing on non-IA32 platforms, especially on 64-bit and
+  big-endian CPUs - some external feedback is welcome.
+
+* Check/Implement support for linux-2.4 kernels. I can't even remember whether
+  those had a proper event interface...
+
+* Implement the module subsystem. Modules to control sound mixers e.t.c could
+  be built.
+
+* Use select() to handle multiple keyboards, instead of just the first one,
+  and get a USB keyboard to test it.
+
+* Dynamically attach to new keyboards - the select() infrastrusture is a
+  prerequisite for this - can we do this without periodically reading the
+  /proc/bus/input/devices file ?
+
+* Per-keyboard configuration - this may never be implemented since it would
+  complicate the code. Perhaps a hotplug script could handle this better.
+
+* Support additional platforms. To do this, alternatives to linux.c must be
+  written and the build system must become smarter (autotools ?). I would
+  also need maintainers for any platform apart from Linux, since I do not
+  see myself installing another OS any time soon.
+
+* Find out if there are any good reasons (security ?) to replace the call
+  to system().
+
+* Add support for symbolic key names in the configuration file. Can we do
+  do this while still keeping the code relatively portable and without using
+  huge fixed keymaps ?