From: luke bonham <dadasignificanulla@gmail.com>
Date: Tue, 21 Jan 2014 15:01:44 +0000 (+0100)
Subject: Merge wiki
X-Git-Url: https://git.madduck.net/etc/awesome.git/commitdiff_plain/6cc550655fad64e784ff87916f3ef439ebaf4c4a?hp=3a387e9f49b3b94c2907fe5e9730a6ae3f6662e1

Merge wiki
---

diff --git a/Home.md b/Home.md
new file mode 100644
index 0000000..5581a9e
--- /dev/null
+++ b/Home.md
@@ -0,0 +1,34 @@
+Welcome to the Lain wiki!
+
+Dependencies
+------------------
+
+Package | Requested by | Reason of choice
+--- | --- | ---
+alsa-utils | [alsa](https://github.com/copycat-killer/lain/wiki/alsa), [alsabar](https://github.com/copycat-killer/lain/wiki/alsabar) | /
+curl | widgets accessing network resources | LuaSocket is not a core library, and still not available for Lua 5.2+. LuaSSL is out of date. 
+imagemagick | album arts in [mpd](https://github.com/copycat-killer/lain/wiki/mpd) notifications | Cairo doesn't do high quality filtering.
+
+Installation
+---------------
+
+### Arch Linux
+
+[AUR package](https://aur.archlinux.org/packages/lain/)
+
+### Other distributions
+
+    git clone https://github.com/copycat-killer/lain.git ~/.config/awesome/lain
+
+Usage
+--------
+
+First, include it into your `rc.lua`:
+
+    local lain = require("lain")
+
+Then check out the submodules you want:
+
+- [Layouts](https://github.com/copycat-killer/lain/wiki/Layouts)
+- [Widgets](https://github.com/copycat-killer/lain/wiki/Widgets)
+- [Utilities](https://github.com/copycat-killer/lain/wiki/Utilities)
\ No newline at end of file
diff --git a/Layouts.md b/Layouts.md
new file mode 100644
index 0000000..045c2c9
--- /dev/null
+++ b/Layouts.md
@@ -0,0 +1,298 @@
+Currently, there are **8** layouts.
+
+    lain/layout
+    .
+    |-- termfair
+    |-- centerfair
+    |-- cascade
+    |-- cascadetile
+    |-- centerwork
+    |-- uselessfair
+    |-- uselesspiral
+    `-- uselesstile
+
+Just add your favourites to ``layouts`` table:
+
+    layouts =
+    {
+        ...
+        lain.layout.termfair,
+        lain.layout.uselesstile,
+        ...
+    }
+
+Or set them on specific tags like this:
+
+	awful.layout.set(lain.layout.uselessfair, tags[1][7])
+
+How do layouts work?
+=========================
+
+termfair
+--------
+
+I do a lot of work on terminals. The common tiling algorithms usually
+maximize windows, so you'll end up with a terminal that has about 200
+columns or more. That's way too much. Have you ever read a manpage in a
+terminal of this size?
+
+This layout restricts the size of each window. Each window will have the
+same width but is variable in height. Furthermore, windows are
+left-aligned. The basic workflow is as follows (the number above the
+screen is the number of open windows, the number in a cell is the fixed
+number of a client):
+
+	     (1)                (2)                (3)
+	+---+---+---+      +---+---+---+      +---+---+---+
+	|   |   |   |      |   |   |   |      |   |   |   |
+	| 1 |   |   |  ->  | 2 | 1 |   |  ->  | 3 | 2 | 1 |  ->
+	|   |   |   |      |   |   |   |      |   |   |   |
+	+---+---+---+      +---+---+---+      +---+---+---+
+
+	     (4)                (5)                (6)
+	+---+---+---+      +---+---+---+      +---+---+---+
+	| 4 |   |   |      | 5 | 4 |   |      | 6 | 5 | 4 |
+	+---+---+---+  ->  +---+---+---+  ->  +---+---+---+
+	| 3 | 2 | 1 |      | 3 | 2 | 1 |      | 3 | 2 | 1 |
+	+---+---+---+      +---+---+---+      +---+---+---+
+
+The first client will be located in the left column. When opening
+another window, this new window will be placed in the left column while
+moving the first window into the middle column. Once a row is full,
+another row above it will be created.
+
+Default number of columns and rows are respectively taken from `nmaster`
+and `ncol` values in `awful.tag`, but you can set your own.
+
+For example, this sets `termfair` to 3 columns and at least 1 row:
+
+    lain.layout.termfair.nmaster = 3
+    lain.layout.termfair.ncol = 1
+
+centerfair
+----------
+
+Similar to `termfair`, but with fixed number of vertical columns. Cols are centerded until there are `nmaster` columns, then windows are stacked as slaves, with possibly `ncol` clients per column at most.
+
+            (1)                (2)                (3)
+       +---+---+---+      +-+---+---+-+      +---+---+---+
+       |   |   |   |      | |   |   | |      |   |   |   |
+       |   | 1 |   |  ->  | | 1 | 2 | | ->   | 1 | 2 | 3 |  ->
+       |   |   |   |      | |   |   | |      |   |   |   |
+       +---+---+---+      +-+---+---+-+      +---+---+---+
+
+            (4)                (5)
+       +---+---+---+      +---+---+---+
+       |   |   | 3 |      |   | 2 | 4 |
+       + 1 + 2 +---+  ->  + 1 +---+---+
+       |   |   | 4 |      |   | 3 | 5 |
+       +---+---+---+      +---+---+---+
+
+Like `termfair`, default number of columns and rows are respectively taken from `nmaster`
+and `ncol` values in `awful.tag`, but you can set your own.
+
+For example:
+
+    lain.layout.centerfair.nmaster = 3
+    lain.layout.centerfair.ncol = 1
+
+cascade
+-------
+
+Cascade all windows of a tag.
+
+You can control the offsets by setting these two variables:
+
+	lain.layout.cascade.cascade_offset_x = 64
+	lain.layout.cascade.cascade_offset_y = 16
+
+The following reserves space for 5 windows:
+
+	lain.layout.cascade.nmaster = 5
+
+That is, no window will get resized upon the creation of a new window,
+unless there's more than 5 windows.
+
+cascadetile
+-----------
+
+Similar to `awful.layout.suit.tile` layout, however, clients in the slave
+column are cascaded instead of tiled.
+
+Left column size can be set, otherwise is controlled by `mwfact` of the
+tag. Additional windows will be opened in another column on the right.
+New windows are placed above old windows.
+
+Whether the slave column is placed on top of the master window or not is
+controlled by the value of `ncol`. A value of 1 means "overlapping slave column"
+and anything else means "don't overlap windows".
+
+Usage example:
+
+	lain.layout.cascadetile.cascade_offset_x = 2
+	lain.layout.cascadetile.cascade_offset_y = 32
+	lain.layout.cascadetile.extra_padding = 5
+    lain.layout.cascadetile.nmaster = 5
+    lain.layout.ncol = 1
+
+`extra_padding` reduces the size of the master window if "overlapping
+slave column" is activated. This allows you to see if there are any
+windows in your slave column.
+
+Setting `cascade_offset_x` to a very small value or even 0 is reccommended to avoid wasting space.
+
+centerwork
+----------
+
+You start with one window, centered horizontally:
+
+	+--------------------------+
+	|       +----------+       |
+	|       |          |       |
+	|       |          |       |
+	|       |          |       |
+	|       |   MAIN   |       |
+	|       |          |       |
+	|       |          |       |
+	|       |          |       |
+	|       |          |       |
+	|       +----------+       |
+	+--------------------------+
+
+This is your main working window. You do most of the work right here.
+Sometimes, you may want to open up additional windows. They're put in
+the following four slots:
+
+	+--------------------------+
+	| +---+ +----------+ +---+ |
+	| |   | |          | |   | |
+	| | 0 | |          | | 1 | |
+	| |   | |          | |   | |
+	| +---+ |   MAIN   | +---+ |
+	| +---+ |          | +---+ |
+	| |   | |          | |   | |
+	| | 2 | |          | | 3 | |
+	| |   | |          | |   | |
+	| +---+ +----------+ +---+ |
+	+--------------------------+
+
+Yes, the number "four" is fixed. In total, you can only have five open
+windows with this layout. Additional windows are not managed and set to
+floating mode. **This is intentional**.
+
+You can set the order of the four auxiliary windows. This is the default
+configuration:
+
+	lain.layout.centerwork.top_left = 0
+	lain.layout.centerwork.top_right = 1
+	lain.layout.centerwork.bottom_left = 2
+	lain.layout.centerwork.bottom_right = 3
+
+This means: The bottom left slot will be occupied by the third window
+(not counting the main window). Suppose you want your windows to appear
+in this order:
+
+	+--------------------------+
+	| +---+ +----------+ +---+ |
+	| |   | |          | |   | |
+	| | 3 | |          | | 0 | |
+	| |   | |          | |   | |
+	| +---+ |   MAIN   | +---+ |
+	| +---+ |          | +---+ |
+	| |   | |          | |   | |
+	| | 2 | |          | | 1 | |
+	| |   | |          | |   | |
+	| +---+ +----------+ +---+ |
+	+--------------------------+
+
+This would require you to use these settings:
+
+	lain.layout.centerwork.top_left = 3
+	lain.layout.centerwork.top_right = 0
+	lain.layout.centerwork.bottom_left = 2
+	lain.layout.centerwork.bottom_right = 1
+
+*Please note:* If you use Awesome's default configuration, navigation in
+this layout may be very confusing. How do you get from the main window
+to satellite ones depends on the order in which the windows are opened.
+Thus, use of `awful.client.focus.bydirection()` is suggested.
+Here's an example:
+
+	globalkeys = awful.util.table.join(
+        ...
+	    awful.key({ modkey }, "j",
+	        function()
+	            awful.client.focus.bydirection("down")
+	            if client.focus then client.focus:raise() end
+	        end),
+	    awful.key({ modkey }, "k",
+	        function()
+	            awful.client.focus.bydirection("up")
+	            if client.focus then client.focus:raise() end
+	        end),
+	    awful.key({ modkey }, "h",
+	        function()
+	            awful.client.focus.bydirection("left")
+	            if client.focus then client.focus:raise() end
+	        end),
+	    awful.key({ modkey }, "l",
+	        function()
+	            awful.client.focus.bydirection("right")
+	            if client.focus then client.focus:raise() end
+	        end),
+	    ...
+	)
+
+uselessfair, uselesspiral & uselesstile
+---------------------------------------
+These are duplicates of the stock `fair`, `spiral` and `tile` layouts.
+
+However, "useless gaps" (see below) have been added.
+
+Useless gaps
+============
+
+Useless gaps are gaps between windows. They are "useless" because they
+serve no special purpose despite increasing overview. I find it easier
+to recognize window boundaries if windows are set apart a little bit.
+
+The `uselessfair` layout, for example, looks like this:
+
+	+================+
+	#                #
+	#  +---+  +---+  #
+	#  | 1 |  |   |  #
+	#  +---+  |   |  #
+	#         | 3 |  #
+	#  +---+  |   |  #
+	#  | 2 |  |   |  #
+	#  +---+  +---+  #
+	#                #
+	+================+
+
+All of lain layouts provide useless gaps. To set the width of the gaps,
+you have to add an item called `useless_gap_width` in your `theme.lua`.
+If it doesn't exist, the width will default to 0.
+Example:
+
+	theme.useless_gap_width = 10
+
+What about layout icons?
+========================
+
+They are located in ``lain/icons/layout``.
+
+To use them, add lines to your ``theme.lua`` like this:
+
+	theme.lain_icons         = os.getenv("HOME") .. "/.config/awesome/lain/icons/layout/default/"
+	theme.layout_termfair    = theme.lain_icons .. "termfairw.png"
+	theme.layout_cascade     = theme.lain_icons .. "cascadew.png"
+	theme.layout_cascadetile = theme.lain_icons .. "cascadetilew.png"
+	theme.layout_centerwork  = theme.lain_icons .. "centerworkw.png"
+
+Credits goes to [Nicolas Estibals](https://github.com/nestibal) for creating
+layout icons for default theme.
+
+You can use them as a template for your custom versions.
+
+[<- home](https://github.com/copycat-killer/lain/wiki)
\ No newline at end of file
diff --git a/Utilities.md b/Utilities.md
new file mode 100644
index 0000000..99588b9
--- /dev/null
+++ b/Utilities.md
@@ -0,0 +1,163 @@
+markup
+------
+
+Made markup easier!
+
+First, require it like this:
+
+    local markup = lain.util.markup
+
+then you can call its functions:
+
+     +-- markup
+     |
+     |`-- bold()        Set bold.
+     |`-- italic()      Set italicized text.
+     |`-- strike()      Set strikethrough text.
+     |`-- underline()   Set underlined text.
+     |`-- monospace()   Set monospaced text.
+     |`-- big()         Set bigger text.
+     |`-- small()       Set smaller text.
+     |`-- font()        Set the font of the text.
+     |
+     |`--+ bg
+     |   |
+     |   |`-- color()   Set background color.
+     |   |`-- focus()   Set focus  background color.
+     |   |`-- normal()  Set normal background color.
+     |    `-- urgent()  Set urgent background color.
+     |
+     |`--+ fg
+     |   |
+     |   |`-- color()   Set foreground color.
+     |   |`-- focus()   Set focus  foreground color.
+     |   |`-- normal()  Set normal foreground color.
+     |    `-- urgent()  Set urgent foreground color.
+     |
+     |`-- focus()       Set both foreground and background focus  colors.
+     |`-- normal()      Set both foreground and background normal colors.
+      `-- urgent()      Set both foreground and background urgent colors.
+
+they all take one argument, which is the text to markup, except `fg.color` and `bg.color`:
+
+    markup.fg.color(text, color)
+    markup.bg.color(text, color)
+
+dynamic tagging
+---------------
+
+That is:
+
+- add a new tag;
+- rename current tag;
+- move current tag;
+- remove current tag.
+
+If you delete a tag, any rule set on it shall be broken, so be careful.
+
+Use it with key bindings like these:
+
+    awful.key({ modkey, "Shift" }, "n", function () lain.util.add_tag(mypromptbox) end),
+    awful.key({ modkey, "Shift" }, "r", function () lain.util.rename_tag(mypromptbox) end),
+    awful.key({ modkey, "Shift" }, "Left", function () lain.util.move_tag(1) end),  -- move to next tag
+    awful.key({ modkey, "Shift" }, "Right", function () lain.util.move_tag(-1) end), -- move to previous tag
+    awful.key({ modkey, "Shift" }, "d", function () lain.util.remove_tag() end),
+
+**Note** that these function won't work properly with [Copland theme](https://github.com/copycat-killer/awesome-copycats) or any other configuration that already uses a dynamic tagging module like [Eminent](https://github.com/copycat-killer/awesome-copycats/tree/master/eminent).
+
+useless\_gaps\_resize
+---------------------
+
+Changes `beautiful.useless_gaps_width` on the fly.
+
+The function takes an integer argument, being the amount of pixel to add/remove to gaps.
+
+You could use it with these keybindings:
+
+    -- On the fly useless gaps change
+    awful.key({ altkey, "Control" }, "+", function () lain.util.useless_gaps_resize(1) end),
+    awful.key({ altkey, "Control" }, "-", function () lain.util.useless_gaps_resize(-1) end),
+
+where `altkey=Mod1`, or you could use it like this:
+
+    mywidget:buttons(awful.util.table.join (
+          awful.button({}, 4, function() lain.util.useless_gaps_resize(-1) end),
+          awful.button({}, 5, function() lain.util.useless_gaps_resize(1) end)
+          end)
+    ))
+
+so when hovering the mouse over `mywidget`, you can adjust useless gaps size by scrolling with the mouse wheel.
+
+tag\_view\_nonempty
+-------------------
+
+This function lets you jump to the next/previous non-empty tag.
+It takes two arguments:
+
+* `direction`: `1` for next non-empty tag, `-1` for previous.
+* `sc`: Screen which the taglist is in. Default is `mouse.screen` or `1`. This
+  argument is optional.
+
+You can use it with key bindings like these:
+
+    -- Non-empty tag browsing
+    awful.key({ altkey }, "Left", function () lain.util.tag_view_nonempty(-1) end),
+    awful.key({ altkey }, "Right", function () lain.util.tag_view_nonempty(1) end),
+
+where `altkey = "Mod1"`.
+
+menu\_clients\_current\_tags
+----------------------------
+
+Similar to `awful.menu.clients`, but this menu only shows the clients
+of currently visible tags. Use it with a key binding like this:
+
+    awful.key({ "Mod1" }, "Tab",
+    function()
+        awful.menu.menu_keys.down = { "Down", "Alt_L", "Tab", "j" }
+        awful.menu.menu_keys.up = { "Up", "k" }
+        lain.util.menu_clients_current_tags({ width = 350 }, { keygrabber = true })
+    end),
+
+magnify\_client
+---------------
+
+Set a client to floating and resize it in the same way the "magnifier"
+layout does it. Place it on the "current" screen (derived from the mouse
+position). This allows you to magnify any client you wish, regardless of
+the currently used layout. Use it with a client keybinding like this:
+
+	clientkeys = awful.util.table.join(
+		...
+		awful.key({ modkey, "Control" }, "m", lain.util.magnify_client),
+		...
+	)
+
+If you want to "de-magnify" it, just retype the keybinding.
+
+niceborder\_{focus, unfocus}
+----------------------------
+
+By default, your `rc.lua` contains something like this:
+
+	client.connect_signal("focus", function(c) c.border_color = beautiful.border_focus end)
+	client.connect_signal("unfocus", function(c) c.border_color = beautiful.border_normal end)
+
+You can change it to this:
+
+	client.connect_signal("focus", lain.util.niceborder_focus(c))
+	client.connect_signal("unfocus", lain.util.niceborder_unfocus(c))
+
+Now, when a client is focused or unfocused, Awesome will look up its
+nice value in `/proc/<pid>/stat`. If it's less than 0, the client is
+classified as "high priority"; if it's greater than 0, the client is
+classified as "low priority". If it's equal to 0, nothing special
+happens.
+
+This requires to define additional colors in your `theme.lua`. For example:
+
+	theme.border_focus_highprio  = "#FF0000"
+	theme.border_normal_highprio = "#A03333"
+
+	theme.border_focus_lowprio   = "#3333FF"
+	theme.border_normal_lowprio  = "#333366"
\ No newline at end of file
diff --git a/Widgets.md b/Widgets.md
new file mode 100644
index 0000000..5917aac
--- /dev/null
+++ b/Widgets.md
@@ -0,0 +1,53 @@
+General usage
+-------------
+
+Every widget is output by a `function`.
+
+For some widgets, `function` returns a `wibox.widget.textbox`, for others a table to be used for notification and update purposes.
+
+Every widget may take either a table or a list of variables as argument.
+
+If it takes a table, you have to define a function variable called `settings` in it, in order to make your customizations.
+
+To markup the textbox, call `widget:set_markup(...)` within `settings`.
+
+You can feed `set_markup` with predefined arguments, see the sections for all the details.
+
+`widget` is a textbox, so you can threat it like any other `wibox.widget.textbox`.
+
+Here follows an example: 
+
+    mycpu = lain.widgets.cpu({
+        timeout = 4,
+        settings = function()
+            widget:set_markup("Cpu " .. cpu_now.usage)
+        end
+    })
+
+If you want to see more complex applications, check [awesome-copycats](https://github.com/copycat-killer/awesome-copycats).
+
+Index
+-----
+
+- [alsa](https://github.com/copycat-killer/lain/wiki/alsa)
+- [alsabar](https://github.com/copycat-killer/lain/wiki/alsabar)
+- [bat](https://github.com/copycat-killer/lain/wiki/bat)
+- [borderbox](https://github.com/copycat-killer/lain/wiki/borderbox)
+- [calendar](https://github.com/copycat-killer/lain/wiki/calendar)
+- [cpu](https://github.com/copycat-killer/lain/wiki/cpu)
+- [fs](https://github.com/copycat-killer/lain/wiki/fs)
+- [imap](https://github.com/copycat-killer/lain/wiki/imap)
+- [maildir](https://github.com/copycat-killer/lain/wiki/maildir)
+- [mem](https://github.com/copycat-killer/lain/wiki/mem)
+- [mpd](https://github.com/copycat-killer/lain/wiki/mpd)
+- [net](https://github.com/copycat-killer/lain/wiki/net)
+- [sysload](https://github.com/copycat-killer/lain/wiki/sysload)
+- [temp](https://github.com/copycat-killer/lain/wiki/temp)
+- [yawn](https://github.com/copycat-killer/lain/wiki/yawn)
+
+Users contributed
+----------------
+
+- [task](https://github.com/copycat-killer/lain/wiki/task)
+- [tpbat](https://github.com/copycat-killer/lain/wiki/tpbat)
+- [brightness](https://github.com/copycat-killer/lain/wiki/brightness)
\ No newline at end of file
diff --git a/alsa.md b/alsa.md
new file mode 100644
index 0000000..daf4016
--- /dev/null
+++ b/alsa.md
@@ -0,0 +1,53 @@
+[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets)
+
+Shows and controls alsa volume with a textbox.
+
+	volumewidget = lain.widgets.alsa()
+
+### input table
+
+Variable | Meaning | Type | Default
+--- | --- | --- | ---
+`timeout` | Refresh timeout seconds | int | 5
+`channel` | Mixer channel | string | "Master" 
+`settings` | User settings | function | empty function
+
+`settings` can use the following variables:
+
+Variable | Meaning | Type | Values
+--- | --- | --- | ---
+`volume_now.level` | Self explained | int | 0-100
+`volume_now.status` | Device status | string | "on", "off"
+
+### output table
+
+Variable | Meaning | Type
+--- | --- | --- 
+`widget` | The widget | `wibox.widget.textbox`
+`update` | Update `widget` | function
+
+You can control the widget with key bindings like these:
+
+    -- Volume control
+    awful.key({ altkey }, "Up",
+    function ()
+        awful.util.spawn("amixer set Master 1%+")
+        volumewidget.update()
+    end),
+    awful.key({ altkey }, "Down",
+    function ()
+        awful.util.spawn("amixer set Master 1%-")
+        volumewidget.update()
+    end),
+    awful.key({ altkey }, "m",
+    function ()
+        awful.util.spawn("amixer set Master playback toggle")
+        volumewidget.update()
+    end),
+    awful.key({ altkey, "Control" }, "m", 
+    function ()
+        awful.util.spawn("amixer set Master playback 100%", false )
+        volumewidget.update()
+    end),
+
+where `altkey = "Mod1"`.
\ No newline at end of file
diff --git a/alsabar.md b/alsabar.md
new file mode 100644
index 0000000..6138f2c
--- /dev/null
+++ b/alsabar.md
@@ -0,0 +1,85 @@
+[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets)
+
+Shows and controls alsa volume with a progressbar; provides tooltips, notifications, and color changes at mute/unmute switch.
+
+	volume = lain.widgets.alsabar()
+
+* Left click: Launch `alsamixer` in your `terminal`.
+* Right click: Mute/unmute.
+* Scroll wheel: Increase/decrase volume.
+
+The function takes a table as optional argument, which can contain:
+
+Variable | Meaning | Type | Default
+--- | --- | --- | ---
+`timeout` | Refresh timeout seconds | int | 4
+`settings` | User settings | function | empty function
+`width` | Bar width | int | 63
+`height` | Bar height | int | 1
+`ticks` | Set bar ticks on | boolean | false
+`ticks_size` | Ticks size | int | 7
+`vertical` | Set the bar vertical | boolean | false
+`channel` | Mixer channel | string | "Master" 
+`step` | Step at which volume is increased/decreased | string | "5%"
+`colors` | Bar colors | table | see **colors**
+`notifications` | Notifications settings | table | see **notifications**
+
+### colors
+
+Variable | Meaning | Type | Default
+--- | --- | --- | ---
+`background` | Bar backgrund color | string | `beautiful.bg_normal`
+`mute` | Bar mute color | string | "#EB8F8F"
+`unmute` | Bar unmute color | string | "#A4CE8A"
+
+### notifications
+
+Variable | Meaning | Type | Default
+--- | --- | --- | ---
+`font` | Notifications font | string | The one defined in `beautiful.font`
+`font_size` | Notifications font size | string | "11"
+`color` | Notifications color | string | `beautiful.fg_normal`
+`bar_size` | Wibox height | int | 18
+
+It's **crucial** to set `notifications.bar_size` to your `mywibox[s]` height.
+
+`settings` can use the following variables:
+
+Variable | Meaning | Type | Values
+--- | --- | --- | ---
+`volume_now.level` | Self explained | int | 0-100
+`volume_now.status` | Device status | string | "on", "off"
+### output table
+
+Variable | Meaning | Type
+--- | --- | ---
+`bar` | The widget | `awful.widget.progressbar`
+`channel` | Alsa channel | string
+`step` | Increase/decrease step | string
+`notify` | The notification | function
+
+You can control the widget with key bindings like these:
+
+    -- ALSA volume control
+    awful.key({ altkey }, "Up",
+        function ()
+            awful.util.spawn("amixer -q set " .. volume.channel .. " " .. volume.step .. "+")
+            volume.notify()
+        end),
+    awful.key({ altkey }, "Down",
+        function ()
+            awful.util.spawn("amixer -q set " .. volume.channel .. " " .. volume.step .. "-")
+            volume.notify()
+        end),
+    awful.key({ altkey }, "m",
+        function ()
+            awful.util.spawn("amixer -q set " .. volume.channel .. " playback toggle")
+            volume.notify()
+        end),
+    awful.key({ altkey, "Control" }, "m",
+        function ()
+            awful.util.spawn("amixer -q set " .. volume.channel .. " playback 100%")
+            volume.notify()
+        end),
+
+where `altkey = "Mod1"`.
\ No newline at end of file
diff --git a/bat.md b/bat.md
new file mode 100644
index 0000000..6bbb21e
--- /dev/null
+++ b/bat.md
@@ -0,0 +1,30 @@
+[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets)
+
+Shows in a textbox the remaining time and percentage capacity of your laptop battery, as well as
+the current wattage.
+
+Displays a notification when battery is low or critical.
+
+	mybattery = lain.widgets.bat()
+
+### input table
+
+Variable | Meaning | Type | Default
+--- | --- | --- | ---
+`timeout` | Refresh timeout seconds | int | 30
+`battery` | Identifier of the battery | string | "BAT0"
+`notify` | Enable notifications | string | "on"
+`settings` | User settings | function | empty function
+
+`settings` can use the `bat_now` table, which contains the following strings:
+
+- `status` ("Not present", "Charging", "Discharging");
+- `perc`;
+- `time`;
+- `watt`.
+
+To disable warning notifications, set `notify` to `"off"`.
+
+### output
+
+A textbox.
\ No newline at end of file
diff --git a/borderbox.md b/borderbox.md
new file mode 100644
index 0000000..a56026a
--- /dev/null
+++ b/borderbox.md
@@ -0,0 +1,49 @@
+[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets)
+
+Creates a thin wibox at a position relative to another wibox.
+
+This allows to create "borders" for your wiboxes.
+
+	lain.widget.borderbox(relbox, s, args)
+
+`relbox` and `s` (an integer being screen number) are required arguments, `args` is an optional table
+which can contain:
+
+Variable | Meaning | Type | Default
+--- | --- | --- | ---
+`position` | Position of the additional box | string | "above"
+`color` | Color of the additional box | string | `#FFFFFF`
+`size` | Size in pixels of the additional box | int | 1
+
+Possible values for `.position`: `top`, `bottom`, `left` and `right`.
+
+### Example usage
+
+Think of this as a wibox:
+
+	[======================]
+
+If `args.position = "above"`, then you'll get an additional wibox below
+the existing one:
+
+	________________________
+	[======================]
+
+It'll match position and size of the existing wibox.
+
+If your main wiboxes are stored in a table called `mywibox` (one wibox
+for each screen) and are located at the bottom of your screen, then this
+adds a borderbox on top of them:
+
+    -- Layout section
+	for s = 1, screen.count() do
+        ...
+
+	    -- Most likely, you'll want to do this as well:
+	    awful.screen.padding(screen[s], "bottom")
+
+	    -- Create the box and place it above the existing box.
+	    lain.widgets.borderbox(mywibox[s], s )
+
+        ...
+	end
\ No newline at end of file
diff --git a/brightness.md b/brightness.md
new file mode 100644
index 0000000..4cd4f8e
--- /dev/null
+++ b/brightness.md
@@ -0,0 +1,40 @@
+[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets)
+
+Shows the current level of screen brightness in a textbox.
+
+	brightnesswidget = lain.widgets.contrib.brightness()
+
+### input table
+
+Variable | Meaning | Type | Default
+--- | --- | --- | ---
+`timeout` | Refresh timeout seconds | int | 5
+`backlight` | Backlight video | string | "acpi_video0" 
+`settings` | User settings | function | empty function
+
+`settings` can use the following variables:
+
+Variable | Meaning | Type | Values
+--- | --- | --- | ---
+`brightness_now` | Brightness level | int | 0-100
+
+### output table
+
+Variable | Meaning | Type
+--- | --- | --- 
+`widget` | The widget | `wibox.widget.textbox`
+`update` | Update `widget` | function
+
+You can control the widget with key bindings like these:
+
+    -- Brightness control
+    awful.key({}, "XF86MonBrightnessUp",
+    function ()
+        awful.util.spawn("xbacklight -inc 1")
+        brightnesswidget.update()
+    end),
+    awful.key({}, "XF86MonBrightnessDown",
+    function ()
+        awful.util.spawn("xbacklight -dec 1")
+        brightnesswidget.update()
+    end),
\ No newline at end of file
diff --git a/calendar.md b/calendar.md
new file mode 100644
index 0000000..b06c453
--- /dev/null
+++ b/calendar.md
@@ -0,0 +1,31 @@
+[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets)
+
+Attaches a calendar notification to a widget.
+
+    lain.widgets.calendar:attach(widget, args)
+
+- Left click: switch to previous month.
+- Right click: switch to next month.
+
+`args` is an optional table which can contain:
+
+Variable | Meaning | Type | Default
+--- | --- | --- | ---
+`icons` | Path to calendar icons | string | [lain/icons/cal/white](https://github.com/copycat-killer/lain/tree/master/icons/cal/white)
+`font_size` | Calendar font size | int | 12
+`fg` | Calendar foreground color | string | `beautiful.fg_normal`
+`bg` | Calendar background color | string | `beautiful.bg_normal`
+`position` | Calendar position | string | "top_right"
+
+`position` possible values are defined [here](http://awesome.naquadah.org/doc/api/modules/naughty.html#notify).
+
+Notification will show an icon displaying current day, and formatted output
+from ``cal`` with current day highlighted.
+
+You can call the notification with a key binding like this:
+
+    awful.key({ altkey }, "c", function () lain.widgets.calendar:show(7) end),
+
+where ``altkey = "Mod1"`` and ``show`` argument is an optional integer, meaning timeout seconds.
+
+**Note that** this widget exploits ``cal`` to do the alignment, in order to avoid more dozens of code lines, but this requires that your system font is monospaced.
\ No newline at end of file
diff --git a/cpu.md b/cpu.md
new file mode 100644
index 0000000..e42180c
--- /dev/null
+++ b/cpu.md
@@ -0,0 +1,18 @@
+[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets)
+
+Shows in a textbox the average CPU usage percent for a given amount of time.
+
+	mycpuusage = lain.widgets.cpu()
+
+### input table
+
+Variable | Meaning | Type | Default
+--- | --- | --- | ---
+`timeout` | Refresh timeout seconds | int | 5
+`settings` | User settings | function | empty function
+
+`settings` can use the string `cpu_now.usage`, which is the cpu use percentage.
+
+### output
+
+A textbox.
\ No newline at end of file
diff --git a/fs.md b/fs.md
new file mode 100644
index 0000000..1e34f86
--- /dev/null
+++ b/fs.md
@@ -0,0 +1,45 @@
+[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets)
+
+Shows disk space usage for a set partition.
+
+Displays a notification when the partition is full or has low space.
+
+    mypartition = lain.widgets.fs()
+
+### input table
+
+Variable | Meaning | Type | Default
+--- | --- | --- | ---
+`timeout` | Refresh timeout seconds -| int | 600
+`partition` | Partition to monitor | string | "/"
+`settings` | User settings | function | empty function
+
+`settings` can use the following `partition` related float values: `fs_now.used`, `fs_now.available`, `fs_now.size_mb`, `fs_now.size_gb`.
+
+It can also use value strings in these formats:
+
+    fs_info[p .. "used_p"]
+    fs_info[p .. "avail_p"]
+    fs_info[p .. "size_mb"]
+    fs_info[p .. "size_gb"]
+
+where `p` is the last column of `df` command ("/", "/home", "/boot", ...).
+
+This means you can set the widget for a certain partition, but you can look up at others too.
+
+Finally, `settings` can modify `fs_notification_preset` table too. This table will be the preset for the naughty notifications. Check [here](http://awesome.naquadah.org/doc/api/modules/naughty.html#notify) for the list of variables it can contain. Default definition:
+
+    fs_notification_preset = { fg = beautiful.fg_normal }
+
+### output table
+
+Variable | Meaning | Type
+--- | --- | ---
+`widget` | The widget | `wibox.widget.textbox`
+`show` | The notification | function
+
+You can display the notification with a key binding like this:
+
+    awful.key({ altkey }, "h", function () mypartition.show(7) end),
+
+where ``altkey = "Mod1"`` and ``show`` argument is an optional integer, meaning timeout seconds.
\ No newline at end of file
diff --git a/imap.md b/imap.md
new file mode 100644
index 0000000..403a61a
--- /dev/null
+++ b/imap.md
@@ -0,0 +1,68 @@
+[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets)
+
+Shows mail count in a textbox fetching over IMAP.
+
+	myimapcheck = lain.widgets.imap(args)
+
+New mails are notified like this:
+
+	+--------------------------------------------+
+	| +---+                                      |
+	| |\ /| donald@disney.org has 3 new messages |
+	| +---+                                      |
+	+--------------------------------------------+
+
+The function takes a table as argument. Required table parameters are:
+
+Variable | Meaning | Type
+--- | --- | ---
+`server` | Mail server | string
+`mail` | User mail | string
+`password` | User password | string
+
+while the optional are:
+
+Variable | Meaning | Type | Default
+--- | --- | --- | ---
+`port` | IMAP port | int | 993
+`timeout` | Refresh timeout seconds | int | 60
+`is_plain` | Define whether `password` is a plain password (true) or a function that retrieves it (false) | boolean | false
+`settings` | User settings | function
+
+Let's focus better on `is_plain`.
+
+The reason why it's false by default is to discourage the habit of storing passwords in plain.
+
+So you can set your password in plain like this:
+
+    myimapcheck = lain.widgets.imap({
+        is_plain = true,
+        password = "myplainpassword",
+        [...]
+    })
+
+and you'll have the same security provided by `~/.netrc`.
+
+**Or** you can use a keyring, like [python keyring](https://pypi.python.org/pypi/keyring):
+
+    myimapcheck = lain.widgets.imap({
+        password = "keyring get mymail",
+        [...]
+    })
+
+When `is_plain == false`, it *executes* `password` before using it, so you can also use whatever password fetching solution you want.
+
+`settings` can use the value `mailcount`, an integer greater or equal to zero, and can modify `mail_notification_preset` table, which will be the preset for the naughty notifications. Check [here](http://awesome.naquadah.org/doc/api/modules/naughty.html#notify) for the list of variables it can contain. 
+
+Default definition:
+
+    mail_notification _preset = {
+       icon = lain/icons/mail.png,
+       position = "top_left"
+    }
+
+Note that `mailcount` is 0 either if there are no new mails or credentials are invalid, so make sure you get the right settings.
+
+### output 
+
+A textbox.
\ No newline at end of file
diff --git a/maildir.md b/maildir.md
new file mode 100644
index 0000000..355ecdd
--- /dev/null
+++ b/maildir.md
@@ -0,0 +1,39 @@
+[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets)
+
+Shows maildirs status in a textbox.
+
+Maildirs are structured as follows:
+
+	~/Mail
+	.
+	|-- arch
+	|   |-- cur
+	|   |-- new
+	|   `-- tmp
+	|-- gmail
+	|   |-- cur
+	|   |-- new
+	|   `-- tmp
+	.
+	.
+	.
+
+therefore the widget checks whether there are files in the `new` directories.
+If there's new mails, the textbox will say something like "mail: bugs(3), system(1)", otherwise it says
+"no mail".
+
+	mymaildir = lain.widgets.maildir("/path/to/my/maildir")
+
+### input table
+
+Variable | Meaning | Type | Default
+--- | --- | --- | ---
+`timeout` | Refresh timeout seconds | int | 60
+`mailpath` | Path to your maildir | string | "~/Mail"
+`settings` | User settings | function | empty function
+
+`settings` can use the string `newmail`, which format will be something like defined above, or "no mail".
+
+### output
+
+A textbox.
\ No newline at end of file
diff --git a/mem.md b/mem.md
new file mode 100644
index 0000000..84b7ad2
--- /dev/null
+++ b/mem.md
@@ -0,0 +1,18 @@
+[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets)
+
+Shows memory status (in MiB) in a textbox.
+
+	mymem = lain.widgets.mem()
+
+### input table
+
+Variable | Meaning | Type | Default
+--- | --- | --- | ---
+`timeout` | Refresh timeout seconds | int | 3
+`settings` | User settings | function | empty function
+
+`settings` can use the strings `mem_now.used` (memory used MB) and `mem_now.swapused` (swap used MB).
+
+### output
+
+A textbox.
\ No newline at end of file
diff --git a/mpd.md b/mpd.md
new file mode 100644
index 0000000..646b690
--- /dev/null
+++ b/mpd.md
@@ -0,0 +1,85 @@
+[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets)
+
+Shows MPD status in a textbox.
+
+	mpdwidget = lain.widgets.mpd()
+
+Now playing songs are notified like this:
+
+	+--------------------------------------------------------+
+	| +-------+                                              |
+	| |/^\_/^\| Now playing                                  |
+    | |\ O O /| Cannibal Corpse (Hammer Smashed Face) - 1993 |
+    | | '.o.' | Hammer Smashed Face (Radio Disney Version)   |
+	| +-------+                                              |
+	+--------------------------------------------------------+
+
+You need a file like this
+
+     (Front|front|Cover|cover|Art|art|Folder|folder)\.(jpg|jpeg|png|gif)
+
+in the album folder in order to show album art too.
+
+### input table
+
+Variable | Meaning | Type | Default
+--- | --- | --- | ---
+`timeout` | Refresh timeout seconds | int | 1
+`password` | MPD password | string | ""
+`host` | MPD server | string | "127.0.0.1"
+`port` | MPD port | string | "6600"
+`music_dir` | Music directory | string | "~/Music"
+`cover_size` | Album art notification size | int | 100
+`default_art` | Default art | string | ""
+`settings` | User settings | function | empty function
+
+`settings` can use `mpd_now` table, which contains the following string values:
+
+- state (possible values: "play", "pause", "stop")
+- file
+- artist
+- title
+- album
+- date
+
+and can modify `mpd_notification_preset` table, which will be the preset for the naughty notifications. Check [here](http://awesome.naquadah.org/doc/api/modules/naughty.html#notify) for the list of variables it can contain. Default definition:
+
+    mpd_notification_preset = {
+       title   = "Now playing",
+       timeout = 6,
+       text    = string.format("%s (%s) - %s\n%s", mpd_now.artist,
+                 mpd_now.album, mpd_now.date, mpd_now.title)
+    }
+
+### output table
+
+Variable | Meaning | Type
+--- | --- | ---
+`widget` | The textbox | `wibox.widget.textbox`
+`update` | The notification | function
+
+You can control the widget with key bindings like these:
+
+    -- MPD control
+    awful.key({ altkey, "Control" }, "Up",
+        function ()
+            awful.util.spawn_with_shell("mpc toggle || ncmpcpp toggle || ncmpc toggle || pms toggle")
+            mpdwidget.update()
+        end),
+    awful.key({ altkey, "Control" }, "Down",
+        function ()
+            awful.util.spawn_with_shell("mpc stop || ncmpcpp stop || ncmpc stop || pms stop")
+            mpdwidget.update()
+        end),
+    awful.key({ altkey, "Control" }, "Left",
+        function ()
+            awful.util.spawn_with_shell("mpc prev || ncmpcpp prev || ncmpc prev || pms prev")
+            mpdwidget.update()
+        end),
+    awful.key({ altkey, "Control" }, "Right",
+        function ()
+            awful.util.spawn_with_shell("mpc next || ncmpcpp next || ncmpc next || pms next")
+            mpdwidget.update()
+        end),
+
+where `altkey = "Mod1"`.
\ No newline at end of file
diff --git a/net.md b/net.md
new file mode 100644
index 0000000..f857239
--- /dev/null
+++ b/net.md
@@ -0,0 +1,26 @@
+[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets)
+
+Monitors network interfaces and shows current traffic in a textbox. 
+
+    mynet = lain.widgets.net()
+
+### input table
+
+Variable | Meaning | Type | Default
+--- | --- | --- | ---
+`timeout` | Refresh timeout seconds | int | 2
+`iface` | Network device | string | autodetected
+`units` | Units | int | 1024 (kilobytes) 
+`settings` | User settings | function | empty function
+
+Possible other values for `units` are 1 (byte) or multiple of 1024: 1024^2 (mb), 1024^3 (gb), and so on.
+
+`settings` can use the following `iface` related strings:
+
+- `net_now.carrier` ("0", "1");
+- `net_now.state` ("up", "down");
+- `net_now.sent` and `net_now.received` (numbers).
+
+### output
+
+A textbox.
\ No newline at end of file
diff --git a/sysload.md b/sysload.md
new file mode 100644
index 0000000..3e53881
--- /dev/null
+++ b/sysload.md
@@ -0,0 +1,18 @@
+[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets)
+
+Shows the current system load.
+
+	mysysload = lain.widgets.sysload()
+
+### input table
+
+Variable | Meaning | Type | Default
+--- | --- | --- | ---
+`timeout` | Refresh timeout seconds | int | 5
+`settings` | User settings | function | empty function
+
+`settings` can use strings `load_1`, `load_5` and `load_15`, which are loadavg over 1, 5, and 15 minutes.
+
+### output
+
+A textbox.
\ No newline at end of file
diff --git a/task.md b/task.md
new file mode 100644
index 0000000..b4bc7f0
--- /dev/null
+++ b/task.md
@@ -0,0 +1,30 @@
+[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets)
+
+Attaches a [taskwarrior](http://taskwarrior.org/projects/show/taskwarrior) notification to a widget, and lets to add/search tasks from the promptbox.
+
+    lain.widgets.contrib.task:attach(widget, args)
+
+`args` is an optional table which can contain:
+
+Variable | Meaning | Type | Default
+--- | --- | --- | ---
+`font_size` | Calendar font size | int | 12
+`fg` | Calendar foreground color | string | `beautiful.fg_normal`
+`bg` | Calendar background color | string | `beautiful.bg_normal`
+`position` | Calendar position | string | "top_right"
+`timeout` | Notification timeout seconds | int | 7
+
+`position` possible values are defined [here](http://awesome.naquadah.org/doc/api/modules/naughty.html#notify).
+
+Notification will show the output of `task` command.
+
+You can call the notification with a key binding like this:
+
+    awful.key({ modkey, altkey }, "t", lain.widgets.contrib.task.show),
+
+where ``altkey = "Mod1"``.
+
+And you can prompt to add/search a task with key bindings like these:
+
+    awful.key({ modkey,         }, "t", lain.widgets.contrib.task.prompt_add),
+    awful.key({ modkey, "Shift" }, "t", lain.widgets.contrib.task.prompt_search),
\ No newline at end of file
diff --git a/temp.md b/temp.md
new file mode 100644
index 0000000..91f3031
--- /dev/null
+++ b/temp.md
@@ -0,0 +1,20 @@
+[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets)
+
+Shows the current core temperature in a textbox.
+
+Reads from `/sys/class/thermal`, so value is expressed in Celsius.
+
+	mytemp = lain.widgets.temp()
+
+### input table
+
+Variable | Meaning | Type | Default
+--- | --- | --- | ---
+`timeout` | Refresh timeout seconds | int | 5
+`settings` | User settings | function | empty function
+
+`settings` can use the string `coretemp_now`, which means current core temperature, expressed in Celsius (linux standard).
+
+### output 
+
+A textbox.
\ No newline at end of file
diff --git a/tpbat.md b/tpbat.md
new file mode 100644
index 0000000..5a7ba0c
--- /dev/null
+++ b/tpbat.md
@@ -0,0 +1,9 @@
+[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets)
+
+A battery widget that works with Lenovo ThinkPad laptops using [tp_smapi](http://www.thinkwiki.org/wiki/Tp_smapi).
+
+Includes hover notification with more details.
+
+    tpbatwidget = lain.widgets.contrib.tpbat()
+
+Configuration is identical to [standard battery widget's](https://github.com/copycat-killer/lain/wiki/bat).
\ No newline at end of file
diff --git a/yawn.md b/yawn.md
new file mode 100644
index 0000000..30d160c
--- /dev/null
+++ b/yawn.md
@@ -0,0 +1,93 @@
+[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets)
+
+(YAhoo! Weather Notification)
+
+Yawn provides brief and compact Yahoo! Weather notification.
+
+Usage
+-----
+
+You can ``register`` Yawn to get a set of widgets, or ``attach`` it to
+an existent widget.
+
+### register
+
+    yawn = lain.widgets.yawn(id, args)
+
+- ``id``
+
+    An integer that defines the WOEID code of your city.
+    To obtain it you can google 'yahoo weather %CITYNAME%' and follow the first link.
+    It will look like:
+
+        http://weather.yahoo.com/united-states/california/san-diego-2487889/
+
+    and the last number in that link will be the ID you need.
+
+- ``args``
+
+    A required table which can contain:
+
+    Variables | Meaning | Type | Possible values | Default value
+    --- | --- | --- | --- | ---
+    `u` | Units | string | "c" (Celsius), "f" (Fahrenheit) | "c"
+    `timeout` | Refresh timeout seconds | int | integers | 600
+    `settings` | User settings | function | function | empty function
+
+    `settings` can use strings `forecast`, `units`, and can modify `yawn_notification_preset` table, which
+     will be the preset for the naughty notifications. Check [here](http://awesome.naquadah.org/doc/api/modules/naughty.html#notify) for the list of variables it can contain.
+
+The function `register` creates an imagebox icon and a textbox widget. Add them to you wibox like this:
+
+    right_layout:add(yawn.icon)
+    right_layout:add(yawn.widget)
+
+Hovering over ``yawn.icon`` will display the notification.
+
+### attach
+
+    lain.widgets.yawn.attach(widget, id, args)
+
+Arguments:
+
+- ``widget``
+ 
+    The widget which you want to attach Yawn to.
+
+- ``id``
+
+    Same as in ``register``.
+
+- ``args``
+ 
+   Same as in ``register``.
+
+Hovering over ``widget`` will display the notification.
+
+Popup shortcut
+--------------
+
+You can also create a keybinding for the weather popup like this:
+
+    awful.key( { "Mod1" }, "w", function () yawn.show(5) end )
+
+where ``show`` argument is an integer defining timeout seconds.
+
+Localization
+------------
+
+Default language is English, but Yawn can be localized.
+
+Move to `localizations` subdirectory and fill `localization_template`.
+
+Once you're done, rename it like your locale id. In my case:
+
+    $ lua
+    Lua 5.2.2  Copyright (C) 1994-2013 Lua.org, PUC-Rio
+    > print(os.getenv("LANG"):match("(%S*$*)[.]"))
+    it_IT
+    >
+
+hence I named my file "it_IT" (Italian localization).
+
+**NOTE:** If you create a localization, feel free to send me! I will add it.
\ No newline at end of file