diff --git a/docs/05-awesomerc.md.lua b/docs/05-awesomerc.md.lua
index 139dfb817..d21c119c1 100644
--- a/docs/05-awesomerc.md.lua
+++ b/docs/05-awesomerc.md.lua
@@ -113,12 +113,68 @@ sections.DOC_ROOT_BUTTONS = [[
sections.DOC_GLOBAL_KEYBINDINGS = [[
-
+
+ This section stores the global keybindings. A global keybinding is a shortcut
+ that will be executed when the key is pressed. It is different from
+ client keybindings. A client keybinding
+ only works when a client is focused while a global one works all the time.
+
+ Each keybinding is stored in an `awful.key` object. When creating such an
+ object, you need to provide a list of modifiers, a key or keycode, a callback
+ function and extra metadata used for the `awful.hotkeys_popup` widget.
+
+ Common modifiers are:
+
+
+
+
Name
+
Description
+
+
Mod4
Also called Super, Windows and Command ⌘
+
Mod1
Usually called Alt on PCs and Option on Macs
+
Shift
Both left and right shift keys
+
Control
Also called CTRL on some keyboards
+
+
+ Note that both `Mod2` and `Lock` are ignored by default. If you wish to
+ use them, add `awful.key.ignore_modifiers = {}` to your `rc.lua`. `Mod3`,
+ `Mod5` are usually not bound in most leyboard layouts. There is an X11 utility
+ called `xmodmap` to bind them. See
+ [the ARCH Linux Wiki](https://wiki.archlinux.org/index.php/xmodmap) for more
+ information.
+
+ The key or keycode is usually the same as the keyboard key, for example:
+
+ * "a"
+ * "Return"
+ * "Shift_R"
+
+ Each key also has a code. This code depends on the exact keyboard layout. It
+ can be obtained by reading the terminal output of the `xev` command. A keycode
+ based keybinding will look like `#123` where 123 is the keycode.
+
+ The callback has to be a function. Note that a function isn't the same as a
+ function call. If you use, for example, `awful.tag.viewtoggle()` as the
+ callback, you store the **result** of the function. If you wish to use that
+ function as a callback, just use `awful.tag.viewtoggle`. The same applies to
+ methods. If you have to add parameters to the callback, wrap them in another
+ function. For the toggle example, this would be
+ `function() awful.tag.viewtoggle(mouse.screen.tags[1]) end`.
+
+ Note that global keybinding callbacks have no argument. If you wish to act on
+ the current `client`, use the client keybindings
+ table.
]]
sections.DOC_CLIENT_KEYBINDINGS = [[
-
+
+
+ A client keybinding is a shortcut that will get the currently focused client
+ as its first callback argument. For example, to toggle a property, the callback
+ will look like `function(c) c.sticky = not c.sticky end`. For more information
+ about the keybinding syntax, see the
+ global keybindings section.
]]
diff --git a/lib/awful/tag.lua b/lib/awful/tag.lua
index 254c10014..dbf3a6071 100644
--- a/lib/awful/tag.lua
+++ b/lib/awful/tag.lua
@@ -889,7 +889,13 @@ function tag.getgap(t, numclients)
return tag.object.get_gap(t or ascreen.focused().selected_tag)
end
---- The default fill policy
+--- The default fill policy.
+--
+-- ** Possible values**:
+--
+-- * *expand*: Take all the space
+-- * *master_width_factor*: Only take the ratio defined by the
+-- `master_width_factor`
--
-- @beautiful beautiful.master_fill_policy
-- @param string (default: "expand")
@@ -897,6 +903,12 @@ end
--- Set size fill policy for the master client(s).
--
+-- ** Possible values**:
+--
+-- * *expand*: Take all the space
+-- * *master_width_factor*: Only take the ratio defined by the
+-- `master_width_factor`
+--
-- **Signal:**
--
-- * *property::master_fill_policy*
diff --git a/objects/screen.c b/objects/screen.c
index 78112385c..93ce2288f 100644
--- a/objects/screen.c
+++ b/objects/screen.c
@@ -1112,6 +1112,17 @@ luaA_screen_count(lua_State *L)
}
/** Add a fake screen.
+ *
+ * To vertically split the first screen in 2 equal parts, use:
+ *
+ * local geo = screen[1].geometry
+ * local new_width = math.ceil(geo.width/2)
+ * local new_width2 = geo.width - new_width
+ * screen[1]:fake_resize(geo.x, geo.y, new_width, geo.height)
+ * screen.fake_add(geo.x + new_width, geo.y, new_width2, geo.height)
+ *
+ * Both virtual screens will have their own taglist and wibars.
+ *
* @tparam integer x X-coordinate for screen.
* @tparam integer y Y-coordinate for screen.
* @tparam integer width width for screen.
diff --git a/objects/tag.c b/objects/tag.c
index 7fa467b3c..45624d7b0 100644
--- a/objects/tag.c
+++ b/objects/tag.c
@@ -26,6 +26,148 @@
*
* 
*
+ * **Creating tags**:
+ *
+ * The default config initializes tags like this:
+ *
+ * awful.tag(
+ * { "1", "2", "3", "4", "5", "6", "7", "8", "9" },
+ * s,
+ * awful.layout.layouts[1]
+ * )
+ *
+ * If you wish to have tags with different properties, then `awful.tag.add` is
+ * a better choice:
+ *
+ * awful.tag.add("First tag", {
+ * icon = "/path/to/icon1.png",
+ * layout = awful.layout.suit.tile,
+ * master_fill_policy = "master_width_factor",
+ * gap_single_client = true,
+ * gap = 15,
+ * screen = s,
+ * }
+ *
+ * awful.tag.add("Second tag", {
+ * icon = "/path/to/icon2.png",
+ * layout = awful.layout.suit.max,
+ * screen = s,
+ * }
+ *
+ * **Accessing tags**:
+ *
+ * To access the "current tags", use
+ *
+ * local tags = awful.screen.focused().selected_tags
+ *
+ * See: `awful.screen.focused`
+ *
+ * See: `screen.selected_tags`
+ *
+ * To ignore the corner case where multiple tags are selected:
+ *
+ * local t = awful.screen.focused().selected_tag
+ *
+ * See: `screen.selected_tag`
+ *
+ * To get all tags for the focused screen:
+ *
+ * local tags = awful.screen.focused().tags
+ *
+ * See: `screen.tags`
+ *
+ * To get all tags:
+ *
+ * local tags = root.tags()
+ *
+ * To get the current tag of the focused client:
+ *
+ * local t = client.focus and client.focus.first_tag or nil
+ *
+ * See: `client.focus`
+ * See: `client.first_tag`
+ *
+ * To get a tag from its name:
+ *
+ * local t = awful.tag.find_by_name(awful.screen.focused(), "name")
+ *
+ * **Common shortcuts**:
+ *
+ * Here is a few useful shortcuts not part of the default `rc.lua`. Add these
+ * functions above `-- {{{ Key bindings`:
+ *
+ * Delete the current tag
+ *
+ * local function delete_tag()
+ * local t = awful.screen.focused().selected_tag
+ * if not t then return end
+ * t:delete()
+ * end
+ *
+ * Create a new tag at the end of the list
+ *
+ * local function add_tag()
+ * awful.tag.add("NewTag",{screen= awful.screen.focused() }):view_only()
+ * end
+ *
+ * Rename the current tag
+ *
+ * local function rename_tag()
+ * awful.prompt.run {
+ * prompt = "New tag name: ",
+ * textbox = awful.screen.focused().mypromptbox.widget,
+ * exe_callback = function(new_name)
+ * if not new_name or #new_name == 0 then return end
+ *
+ * local t = awful.screen.focused().selected_tag
+ * if t then
+ * t.name = new_name
+ * end
+ * end
+ * }
+ * end
+ *
+ * Move the focused client to a new tag
+ *
+ * local function move_to_new_tag()
+ * local c = client.focus
+ * if not c then return end
+ *
+ * local t = awful.tag.add(c.class,{screen= c.screen })
+ * c:tags({t})
+ * t:view_only()
+ * end
+ *
+ * Copy the current tag at the end of the list
+ *
+ * local function copy_tag()
+ * local t = awful.screen.focused().selected_tag
+ * if not t then return end
+ *
+ * local clients = t:clients()
+ * local t2 = awful.tag.add(t.name, awful.tag.getdata(t))
+ * t2:clients(clients)
+ * t2:view_only()
+ * end
+ *
+ * And, in the `globalkeys` table:
+ *
+ * awful.key({ modkey, }, "a", add_tag,
+ * {description = "add a tag", group = "tag"}),
+ * awful.key({ modkey, "Shift" }, "a", delete_tag,
+ * {description = "delete the current tag", group = "tag"}),
+ * awful.key({ modkey, "Control" }, "a", move_to_new_tag,
+ * {description = "add a tag with the focused client", group = "tag"}),
+ * awful.key({ modkey, "Mod1" }, "a", copy_tag,
+ * {description = "create a copy of the current tag", group = "tag"}),
+ * awful.key({ modkey, "Shift" }, "r", rename_tag,
+ * {description = "rename the current tag", group = "tag"}),
+ *
+ * See the
+ *
+ * global keybindings
+ * for more information about the keybindings.
+ *
* Some signal names are starting with a dot. These dots are artefacts from
* the documentation generation, you get the real signal name by
* removing the starting dot.
diff --git a/tests/test-awful-layout.lua b/tests/test-awful-layout.lua
index bc8ced7d9..cac28935b 100644
--- a/tests/test-awful-layout.lua
+++ b/tests/test-awful-layout.lua
@@ -76,8 +76,8 @@ local common_steps = {
return true
end,
function()
- t.master_fill_policy = t.master_fill_policy == "mwfact" and
- "expand" or "mwfact"
+ t.master_fill_policy = t.master_fill_policy == "master_width_factor" and
+ "expand" or "master_width_factor"
return true
end,