README

   1 wmiirc-lua copyright (c) 2007 Bart Trojanowski <bart@jukie.net>
   2                               http://www.jukie.net/~bart/blog/wmiirc-in-lua
   3
   4 Abstract
   5 --------
   6 wmii [1], window manager improved-improved, is a dynamic window manager
   7 for X11.  It supports classic and tiled window management with extended
   8 keyboard, mouse, and 9P-based [2] remote control.
   9
  10 wmiirc-lua [3] implements an "event loop" script for the wmii window
  11 manager.  The goals of the project are to
  12
  13  - be fast, small, feature rich, and extensible through plugins,
  14  - avoid threading and polling at all costs, and
  15  - replicate the functionality of wmii+ruby.
  16
  17 As the name suggests the script is written in Lua.  Before writing it I
  18 was a happy user of wmii+ruby.  Happy, until powertop [4] was written.
  19 Powertop told me that ruby was the number 1 reason my battery life
  20 sucked.  I chose lua because it helps me achieve the first and second
  21 goals.
  22
  23
  24 Requirements
  25 ------------
  26 The following are required to build wmiirc-lua project:
  27
  28  - wmii, 3.5+ or whatever is in hg at the moment
  29  - libixp, latest
  30  - lua5.1
  31  - liblua5.1
  32  - liblua5.1-posix0
  33  - patience (no, it's not a package)
  34
  35 Note that as of version 0.2 wmiirc-lua is tracking wmii project closely,
  36 and we don't officially support anything older then wmii from the hg
  37 (mercurial) repository.
  38
  39
  40 Installation
  41 ------------
  42 If you are running Debian (or derivative) these steps may help you:
  43
  44  1) install Debian packages that you need to build
  45
  46     apt-get install mercurial git-core                      \
  47                     build-essential debhelper               \
  48                     libx11-dev libxext-dev libxt-dev        \
  49                     lua5.1 liblua5.1-0-dev liblua5.1-posix0
  50
  51     If you chose to work on plugins, you can install all lua packages
  52     like this:
  53
  54        apt-cache search lua5.1 | awk '/liblua5.1/ { print $1 }' \
  55        | xargs sudo apt-get install -y
  56
  57  2) build libixp and wmii from source:
  58
  59     hg clone http://suckless.org/hg.rc/libixp
  60     cd libixp
  61     make
  62     sudo make install
  63     cd ..
  64
  65     hg clone http://suckless.org/hg.rc/wmii
  66     cd wmii
  67     make
  68     sudo make install
  69     cd ..
  70
  71  3) build wmiirc-lua
  72
  73     # you can skip this step if you already have wmiirc-lua :)
  74     git clone git://repo.or.cz/wmiirc-lua.git/
  75     cd wmiirc-lua
  76
  77     make install
  78
  79
  80 Running wmii
  81 ------------
  82 wmiirc-lua is now ready to run, but you still have to make wmii your
  83 window manager.  You can do this by running the wmii executable from
  84 .initrc or .xsession... your choice.
  85
  86     cat ~/.xinitrc
  87     wmii
  88
  89 or
  90
  91     cat ~/.xsession
  92     exec wmii
  93
  94 Note: the base configuration uses Mod4 -- the windows key on PC
  95 keyboards -- for some of the binding.  If your keyboard, like my
  96 Thinkpad's, does not have a windows key you can "make one" with
  97 xmodmaprc.  See: contrib/remap-caps-ctrl-mod4
  98
  99 Configuration
 100 -------------
 101 All configuration of wmiirc-lua is done by editing the
 102 ~/.wmii-3.5/wmiirc file.  See doc/configuration for more help on configuring
 103 wmiirc-lua.
 104
 105 wmiirc-lua supports all the keyboard shortcuts of wmii's shell wmiirc,
 106 some of the features of wmii+ruby, as well as some additional ones.  See
 107 the doc/key-bindings for information on how to control wmii with the
 108 extended key bindings wmiirc-lua provides.
 109
 110 More advanced users may also write plugins for wmiirc-lua using the
 111 plugin API.  Plugins live in ~/.wmii-3.5/plugins/ directory, and several
 112 come with this package.  See the wmii.3lua man page, and doc/plugin-api
 113 for more information about how to write code for wmiirc-lua.
 114
 115     make man
 116     man ./wmii.3lua
 117
 118
 119 Credits
 120 -------
 121 The following people have contributed especially to wmiirc-lua in
 122 various ways.  They are copyright holders of their respective
 123 contributions.
 124
 125 - Bart Trojanowski <bart@jukie.net>
 126 - Dave O'Neill <dmo@dmo.ca>
 127 - Jean Richard <jean@geemoo.ca>
 128
 129
 130 Credits
 131 -------
 132 wmiirc-lua is licensed under GPLv2.
 133
 134 References
 135 ----------
 136 [1] http://www.suckless.org/
 137 [2] http://www.cs.bell-labs.com/sys/man/5/INDEX.html
 138 [3] http://www.jukie.net/~bart/blog/wmiirc-in-lua
 139 [4] http://www.linuxpowertop.org