doc: Add example sequences for the tags.

lib/awful/tag.lua

@@ -143,6 +143,8 @@ end
 
 --- The tag index.
 --
+-- @DOC_sequences_tag_index_EXAMPLE@
+--
 -- The index is the position as shown in the `awful.widget.taglist`.
 --
 -- **Signal:**
@@ -219,6 +221,9 @@ function tag.move(new_index, target_tag)
 end
 
 --- Swap 2 tags.
+--
+-- @DOC_sequences_tag_swap_EXAMPLE@
+--
 -- @method swap
 -- @param tag2 The second tag
 -- @see client.swap
@@ -296,11 +301,20 @@ function tag.add(name, props)
 end
 
 --- Create a set of tags and attach it to a screen.
+--
+-- This is what's performed by the default config:
+--
+-- @DOC_sequences_tag_default_config_EXAMPLE@
+--
+-- It is also possible to set multiple layouts:
+--
+-- @DOC_sequences_tag_new_with_layouts_EXAMPLE@
+--
 -- @staticfct awful.tag.new
--- @param names The tag name, in a table
--- @param screen The tag screen, or 1 if not set.
--- @param layout The layout or layout table to set for this tags by default.
--- @return A table with all created tags.
+-- @tparam table names The tag name, in a table
+-- @tparam screen|nil screen The tag screen, or 1 if not set.
+-- @tparam table layout The layout or layout table to set for this tags by default.
+-- @treturn table A table with all created tags.
 function tag.new(names, screen, layout)
     screen = get_screen(screen or 1)
     -- True if `layout` should be used as the layout of each created tag
@@ -338,7 +352,7 @@ end
 --
 -- To delete the current tag:
 --
---    mouse.screen.selected_tag:delete()
+-- @DOC_sequences_tag_delete_EXAMPLE@
 --
 -- @method delete
 -- @see awful.tag.add
@@ -893,16 +907,33 @@ end
 --- Define if the tag must be deleted when the last client is untagged.
 --
 -- This is useful to create "throw-away" tags for operation like 50/50
--- side-by-side views.
+-- (Windows "Aero Snap) side-by-side views. This keybinding code for this is:
 --
---    local t = awful.tag.add("Temporary", {
---         screen   = client.focus.screen,
+--    local function aero_tag()
+--        local c = client.focus
+--
+--        if not c then return end
+--
+--        local c2 = awful.client.focus.history.list[2]
+--
+--        if (not c2) or c2 == c then return end
+--
+--        local t = aw_tag.add("Aero", {
+--            screen              = c.screen,
 --            volatile            = true,
---         clients  = {
---             client.focus,
---             awful.client.focus.history.get(client.focus.screen, 1)
---         }
---    }
+--            layout              = awful.layout.suit.tile,
+--            master_width_factor = 0.5
+--        })
+--
+--        t:clients({c, c2})
+--
+--        t:view_only()
+--    end
+--
+-- @DOC_sequences_tag_volatile_EXAMPLE@
+--
+-- As you can see, the "Volatile" tag has been automatically discarded while
+-- the "Non-volatile" tag is still there (but with zero clients).
 --
 -- **Signal:**
 --
@@ -910,6 +941,7 @@ end
 --
 -- @property volatile
 -- @param boolean
+-- @see delete
 
 -- Volatile accessors are implicit
 
@@ -1316,6 +1348,9 @@ function tag.incncol(add, t, sensible)
 end
 
 --- View no tag.
+--
+-- @DOC_sequences_tag_viewnone_EXAMPLE@
+--
 -- @staticfct awful.tag.viewnone
 -- @tparam[opt] int|screen screen The screen.
 function tag.viewnone(screen)
@@ -1326,13 +1361,19 @@ function tag.viewnone(screen)
     end
 end
 
---- View a tag by its taglist index.
+--- Select a tag relative to the currently selected one.
+--
+-- Note that this doesn't work well with multiple selection.
+--
+-- @DOC_sequences_tag_viewidx_EXAMPLE@
 --
 -- This is equivalent to `screen.tags[i]:view_only()`
 -- @staticfct awful.tag.viewidx
 -- @see screen.tags
--- @param i The **relative** index to see.
--- @param[opt] screen The screen.
+-- @tparam number i The **relative** index to see.
+-- @tparam[opt] screen screen The screen.
+-- @see awful.tag.viewnext
+-- @see awful.tag.viewprev
 function tag.viewidx(i, screen)
     screen = get_screen(screen or ascreen.focused())
     local tags = screen.tags
@@ -1363,21 +1404,39 @@ function tag.getidx(query_tag)
     return tag.object.get_index(query_tag or ascreen.focused().selected_tag)
 end
 
---- View next tag. This is the same as tag.viewidx(1).
+
+--- View next tag. This is the same as `tag.viewidx(1)`.
+--
+-- Note that this doesn't work well with multiple selection.
+--
+-- @DOC_sequences_tag_viewnext_EXAMPLE@
+--
 -- @staticfct awful.tag.viewnext
--- @param screen The screen.
+-- @tparam screen screen The screen.
+-- @see awful.tag.viewidx
+-- @see awful.tag.viewprev
 function tag.viewnext(screen)
     return tag.viewidx(1, screen)
 end
 
---- View previous tag. This is the same a tag.viewidx(-1).
+--- View previous tag. This is the same a `tag.viewidx(-1)`.
+--
+-- Note that this doesn't work well with multiple selection.
+--
+-- @DOC_sequences_tag_viewprev_EXAMPLE@
+--
 -- @staticfct awful.tag.viewprev
--- @param screen The screen.
+-- @tparam screen screen The screen.
+-- @see awful.tag.viewidx
+-- @see awful.tag.viewnext
 function tag.viewprev(screen)
     return tag.viewidx(-1, screen)
 end
 
 --- View only a tag.
+--
+-- @DOC_sequences_tag_view_only_EXAMPLE@
+--
 -- @method view_only
 -- @see selected
 function tag.object.view_only(self)
@@ -1398,7 +1457,7 @@ end
 --- View only a tag.
 -- @deprecated awful.tag.viewonly
 -- @see tag.view_only
--- @param t The tag object.
+-- @tparam tag t The tag object.
 function tag.viewonly(t)
     gdebug.deprecate("Use t:view_only() instead of awful.tag.viewonly", {deprecated_in=4})
 
@@ -1412,8 +1471,8 @@ end
 -- more of the tags are already selected, set `maximum` to zero.
 --
 -- @staticfct awful.tag.viewmore
--- @param tags A table with tags to view only.
--- @param[opt] screen The screen of the tags.
+-- @tparam table tags A table with tags to view only.
+-- @tparam[opt] screen screen The screen of the tags.
 -- @tparam[opt=#tags] number maximum The maximum number of tags to select.
 function tag.viewmore(tags, screen, maximum)
     maximum = maximum or #tags

objects/tag.c

@@ -21,12 +21,21 @@
 
 /** awesome tag API
  *
- * Furthermore to the classes described here, one can also use signals as
- * described in @{signals}.
+ * What is a tag?
+ * ==============
+ *
+ * In AwesomeWM, a `tag` is a group of clients. It can either be used as labels
+ * or as more classical workspaces depending on how they are configured.
  *
  * ![Client geometry](../images/tag_props.svg)
  *
- * **Creating tags**:
+ *  * A **tag** can be attached to **multiple clients**
+ *  * A **client** can be attached to **multiple tags**
+ *  * A **tag** can only be in 1 screen *any given time*, but can be moved
+ *  * All **clients** attached to a tag **must be in the same screen as the tag**
+ *
+ * Creating tags
+ * =============
  *
  * The default config initializes tags like this:
  *
@@ -58,7 +67,8 @@
  * Note: the example above sets "First tag" to be selected explicitly,
  * because otherwise you will find yourself without any selected tag.
  *
- * **Accessing tags**:
+ * Accessing tags
+ * ==============
  *
  * To access the "current tags", use
  *
@@ -95,7 +105,8 @@
  *
  *    local t = awful.tag.find_by_name(awful.screen.focused(), "name")
  *
- * **Common shortcuts**:
+ * Common keybindings code
+ * =======================
  *
  * Here is a few useful shortcuts not part of the default `rc.lua`. Add these
  * functions above `-- {{{ Key bindings`:
@@ -209,6 +220,8 @@
 /**
  * Tag name.
  *
+ * @DOC_sequences_tag_name_EXAMPLE@
+ *
  * **Signal:**
  *
  *  * *property::name*
@@ -220,6 +233,8 @@
 /**
  * True if the tag is selected to be viewed.
  *
+ * @DOC_sequences_tag_selected_EXAMPLE@
+ *
  * **Signal:**
  *
  *  * *property::selected*

tests/examples/sequences/tag/default_config.lua

@@ -0,0 +1,19 @@
+ --DOC_GEN_IMAGE --DOC --DOC_NO_USAGE
+local module = ... --DOC_HIDE
+local awful = {tag = require("awful.tag"), layout = require("awful.layout") } --DOC_HIDE
+screen[1]._resize {x = 0, width = 128, height = 96} --DOC_HIDE
+
+module.add_event("Calling awful.tag.new", function() --DOC_HIDE
+    assert(awful.layout.layouts[1]) --DOC_HIDE
+    -- Calling awful.tag.new
+    awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.layouts[1])
+
+    assert(#screen[1].tags == 9) --DOC_HIDE
+    for _, t in ipairs(screen[1].tags) do --DOC_HIDE
+        assert(t.layout) --DOC_HIDE
+    end --DOC_HIDE
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+module.execute() --DOC_HIDE

tests/examples/sequences/tag/delete.lua

@@ -0,0 +1,27 @@
+ --DOC_GEN_IMAGE --DOC --DOC_NO_USAGE
+local module = ... --DOC_HIDE
+local awful = {tag = require("awful.tag"), layout = require("awful.layout") } --DOC_HIDE
+screen[1]._resize {x = 0, width = 128, height = 96} --DOC_HIDE
+
+module.add_event("Calling awful.tag.new", function() --DOC_HIDE
+    assert(awful.layout.layouts[1]) --DOC_HIDE
+    -- Calling awful.tag.new
+    awful.tag({ "one", "two", "three", "four" }, screen[1])
+
+    --DOC_NEWLINE
+
+    screen[1].tags[2]:view_only()
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+--DOC_NEWLINE
+
+module.add_event("Deleting the selected tag", function() --DOC_HIDE
+    -- Delete the selected tag.
+    mouse.screen.selected_tag:delete()
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+module.execute() --DOC_HIDE

tests/examples/sequences/tag/index.lua

@@ -0,0 +1,32 @@
+ --DOC_GEN_IMAGE --DOC --DOC_NO_USAGE
+local module = ... --DOC_HIDE
+local awful = {tag = require("awful.tag"), layout = require("awful.layout") } --DOC_HIDE
+screen[1]._resize {x = 0, width = 128, height = 96} --DOC_HIDE
+
+module.add_event("Calling awful.tag.new", function() --DOC_HIDE
+    assert(awful.layout.layouts[1]) --DOC_HIDE
+    -- Calling awful.tag.new
+    awful.tag({ "one", "two", "three", "four" }, screen[1])
+
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+--DOC_NEWLINE
+
+module.add_event("Send the first tag to index 3", function() --DOC_HIDE
+    -- Send the first tag to index 3.
+    screen[1].tags[1].index = 3
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+--DOC_NEWLINE
+
+module.add_event("Send the fourth tag to index 1", function() --DOC_HIDE
+    -- Send the first tag to index 3.
+    screen[1].tags[4].index = 1
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+module.execute() --DOC_HIDE

tests/examples/sequences/tag/name.lua

@@ -0,0 +1,27 @@
+ --DOC_GEN_IMAGE --DOC --DOC_NO_USAGE --DOC_ASTERISK
+local module = ... --DOC_HIDE
+local awful = {tag = require("awful.tag"), layout = require("awful.layout") } --DOC_HIDE
+screen[1]._resize {x = 0, width = 128, height = 96} --DOC_HIDE
+
+module.add_event("Calling awful.tag.new", function() --DOC_HIDE
+    assert(awful.layout.layouts[1]) --DOC_HIDE
+    -- Calling awful.tag.new
+    awful.tag({ "one", "two", "three", "four" }, screen[1])
+
+    --DOC_NEWLINE
+    screen[1].tags[2]:view_only()
+
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+--DOC_NEWLINE
+
+module.add_event("Change the name to New*tag*name", function() --DOC_HIDE
+    -- Change the name to New*tag*name.
+    screen[1].tags[2].name = "New*tag*name"
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+module.execute() --DOC_HIDE

tests/examples/sequences/tag/new_with_layouts.lua

@@ -0,0 +1,54 @@
+ --DOC_GEN_IMAGE --DOC --DOC_NO_USAGE
+local module = ... --DOC_HIDE
+local awful = {tag = require("awful.tag"), --DOC_HIDE
+    layout = require("awful.layout"), --DOC_HIDE
+} --DOC_HIDE
+screen[1]._resize {x = 0, width = 128, height = 96} --DOC_HIDE
+
+function awful.spawn(_, args) --DOC_HIDE
+    local c = client.gen_fake{} --DOC_HIDE
+    c:tags({args.tag}) --DOC_HIDE
+    assert(#c:tags() == 1) --DOC_HIDE
+    assert(c:tags()[1] == args.tag) --DOC_HIDE
+end --DOC_HIDE
+
+module.add_event("Calling awful.tag.new", function() --DOC_HIDE
+    assert(awful.layout.layouts[1]) --DOC_HIDE
+    local some_layouts = {
+        awful.layout.suit.fair,
+        awful.layout.suit.spiral,
+        awful.layout.suit.spiral.dwindle,
+        awful.layout.suit.magnifier,
+        awful.layout.suit.corner.nw,
+        awful.layout.suit.max.fullscreen,
+    }
+
+    --DOC_NEWLINE
+
+    -- Calling awful.tag.new
+    awful.tag({ "one", "two", "three", "four", "five" }, screen[1], some_layouts)
+
+    assert(#screen[1].tags == 5) --DOC_HIDE
+    for k, t in ipairs(screen[1].tags) do --DOC_HIDE
+        assert(t.layout and t.layout == some_layouts[k]) --DOC_HIDE
+        assert(#t:clients() == 0) --DOC_HIDE
+    end --DOC_HIDE
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+--DOC_NEWLINE
+
+module.add_event("Add some clients", function() --DOC_HIDE
+    -- Add some clients
+    for _, t in ipairs(screen[1].tags) do
+        for _ = 1, 5 do
+            awful.spawn("xterm", {tag = t})
+        end
+        assert(#t:clients() == 5) --DOC_HIDE
+    end
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+module.execute {show_empty = true} --DOC_HIDE

tests/examples/sequences/tag/selected.lua

@@ -0,0 +1,26 @@
+ --DOC_GEN_IMAGE --DOC --DOC_NO_USAGE --DOC_ASTERISK
+local module = ... --DOC_HIDE
+local awful = {tag = require("awful.tag"), layout = require("awful.layout") } --DOC_HIDE
+screen[1]._resize {x = 0, width = 128, height = 96} --DOC_HIDE
+
+module.add_event("Calling awful.tag.new", function() --DOC_HIDE
+    assert(awful.layout.layouts[1]) --DOC_HIDE
+    -- Calling awful.tag.new
+    awful.tag({ "one", "two", "three", "four" }, screen[1])
+
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+--DOC_NEWLINE
+
+module.add_event("Change the selection", function() --DOC_HIDE
+    -- Change the selection.
+    screen[1].tags[1].selected = not screen[1].tags[1].selected
+    screen[1].tags[2].selected = true
+    screen[1].tags[3].selected = true
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+module.execute() --DOC_HIDE

tests/examples/sequences/tag/swap.lua

@@ -0,0 +1,27 @@
+ --DOC_GEN_IMAGE --DOC --DOC_NO_USAGE
+local module = ... --DOC_HIDE
+local awful = {tag = require("awful.tag"), layout = require("awful.layout") } --DOC_HIDE
+screen[1]._resize {x = 0, width = 128, height = 96} --DOC_HIDE
+
+module.add_event("Calling awful.tag.new", function() --DOC_HIDE
+    assert(awful.layout.layouts[1]) --DOC_HIDE
+    -- Calling awful.tag.new
+    awful.tag({ "one", "two", "three", "four" }, screen[1])
+
+    --DOC_NEWLINE
+    screen[1].tags[2]:view_only()
+
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+--DOC_NEWLINE
+
+module.add_event("Swap tag 2 with tag 4", function() --DOC_HIDE
+    -- Swap tag 2 with tag 4.
+    screen[1].tags[2]:swap(screen[1].tags[4])
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+module.execute() --DOC_HIDE

tests/examples/sequences/tag/view_only.lua

@@ -0,0 +1,34 @@
+ --DOC_GEN_IMAGE --DOC --DOC_NO_USAGE
+local module = ... --DOC_HIDE
+local awful = {tag = require("awful.tag"), layout = require("awful.layout") } --DOC_HIDE
+screen[1]._resize {x = 0, width = 128, height = 96} --DOC_HIDE
+
+module.add_event("Calling awful.tag.new", function() --DOC_HIDE
+    assert(awful.layout.layouts[1]) --DOC_HIDE
+    -- Calling awful.tag.new
+    awful.tag({ "one", "two", "three", "four" }, screen[1])
+
+    --DOC_NEWLINE
+
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+module.add_event("Manually select some tags", function() --DOC_HIDE
+    -- Manually select some tags (tag 1 was auto selected).
+    screen[1].tags[3].selected = true
+    screen[1].tags[4].selected = true
+end)--DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+--DOC_NEWLINE
+
+module.add_event("Call :view_only()", function() --DOC_HIDE
+    -- Call :view_only() on the second tag.
+    screen[1].tags[2]:view_only()
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+module.execute() --DOC_HIDE

tests/examples/sequences/tag/viewidx.lua

@@ -0,0 +1,36 @@
+ --DOC_GEN_IMAGE --DOC --DOC_NO_USAGE
+local module = ... --DOC_HIDE
+local awful = {tag = require("awful.tag"), layout = require("awful.layout") } --DOC_HIDE
+screen[1]._resize {x = 0, width = 128, height = 96} --DOC_HIDE
+
+module.add_event("Calling awful.tag.new", function() --DOC_HIDE
+    assert(awful.layout.layouts[1]) --DOC_HIDE
+    -- Calling awful.tag.new
+    awful.tag({ "one", "two", "three", "four" }, screen[1])
+
+    --DOC_NEWLINE
+    screen[1].tags[2]:view_only()
+
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+--DOC_NEWLINE
+
+module.add_event("Select the tag relative to idx 2", function() --DOC_HIDE
+    -- Select the tag relative to idx 2.
+    awful.tag.viewidx(2)
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+--DOC_NEWLINE
+
+module.add_event("Select the tag relative to idx -2", function() --DOC_HIDE
+    -- Select the tag relative to idx -2.
+    awful.tag.viewidx(-2)
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+module.execute() --DOC_HIDE

tests/examples/sequences/tag/viewnext.lua

@@ -0,0 +1,36 @@
+ --DOC_GEN_IMAGE --DOC --DOC_NO_USAGE
+local module = ... --DOC_HIDE
+local awful = {tag = require("awful.tag"), layout = require("awful.layout") } --DOC_HIDE
+screen[1]._resize {x = 0, width = 128, height = 96} --DOC_HIDE
+
+module.add_event("Calling awful.tag.new", function() --DOC_HIDE
+    assert(awful.layout.layouts[1]) --DOC_HIDE
+    -- Calling awful.tag.new
+    awful.tag({ "one", "two", "three", "four" }, screen[1])
+
+    --DOC_NEWLINE
+    screen[1].tags[3]:view_only()
+
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+--DOC_NEWLINE
+
+module.add_event("Select the next tag", function() --DOC_HIDE
+    -- Select the next tag.
+    awful.tag.viewnext()
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+--DOC_NEWLINE
+
+module.add_event("Select the next tag (again)", function() --DOC_HIDE
+    -- Select the next tag (again).
+    awful.tag.viewnext()
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+module.execute() --DOC_HIDE

tests/examples/sequences/tag/viewnone.lua

@@ -0,0 +1,34 @@
+ --DOC_GEN_IMAGE --DOC --DOC_NO_USAGE
+local module = ... --DOC_HIDE
+local awful = {tag = require("awful.tag"), layout = require("awful.layout") } --DOC_HIDE
+screen[1]._resize {x = 0, width = 128, height = 96} --DOC_HIDE
+
+module.add_event("Calling awful.tag.new", function() --DOC_HIDE
+    assert(awful.layout.layouts[1]) --DOC_HIDE
+    -- Calling awful.tag.new
+    awful.tag({ "one", "two", "three", "four" }, screen[1])
+
+    --DOC_NEWLINE
+
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+module.add_event("Manually select some tags", function() --DOC_HIDE
+    -- Manually select some tags (tag 1 was auto selected).
+    screen[1].tags[3].selected = true
+    screen[1].tags[4].selected = true
+end)--DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+--DOC_NEWLINE
+
+module.add_event("Deselect all tags", function() --DOC_HIDE
+    -- Deselect all tags.
+    awful.tag.viewnone()
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+module.execute{show_code_pointer = true} --DOC_HIDE

tests/examples/sequences/tag/viewprev.lua

@@ -0,0 +1,36 @@
+ --DOC_GEN_IMAGE --DOC --DOC_NO_USAGE
+local module = ... --DOC_HIDE
+local awful = {tag = require("awful.tag"), layout = require("awful.layout") } --DOC_HIDE
+screen[1]._resize {x = 0, width = 128, height = 96} --DOC_HIDE
+
+module.add_event("Calling awful.tag.new", function() --DOC_HIDE
+    assert(awful.layout.layouts[1]) --DOC_HIDE
+    -- Calling awful.tag.new
+    awful.tag({ "one", "two", "three", "four" }, screen[1])
+
+    --DOC_NEWLINE
+    screen[1].tags[2]:view_only()
+
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+--DOC_NEWLINE
+
+module.add_event("Select the previous tag", function() --DOC_HIDE
+    -- Select the previous tag.
+    awful.tag.viewprev()
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+--DOC_NEWLINE
+
+module.add_event("Select the previous tag (again)", function() --DOC_HIDE
+    -- Select the previous tag (again).
+    awful.tag.viewprev()
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+module.execute() --DOC_HIDE

tests/examples/sequences/tag/volatile.lua

@@ -0,0 +1,59 @@
+ --DOC_GEN_IMAGE --DOC --DOC_NO_USAGE
+local module = ... --DOC_HIDE
+local awful = {tag = require("awful.tag"), layout = require("awful.layout") } --DOC_HIDE
+screen[1]._resize {x = 0, width = 128, height = 96} --DOC_HIDE
+
+
+function awful.spawn(_, args) --DOC_HIDE
+    local c = client.gen_fake{} --DOC_HIDE
+    c:tags({args.tag}) --DOC_HIDE
+    assert(#c:tags() == 1) --DOC_HIDE
+    assert(c:tags()[1] == args.tag) --DOC_HIDE
+end --DOC_HIDE
+
+module.add_event("Create a non-volatile and a volatile tag", function() --DOC_HIDE
+    -- Create a non-volatile and a volatile tag.
+    awful.tag.add("Non-Volatile", {
+        screen   = screen[1],
+        layout   = awful.layout.suit.corner.nw,
+        volatile = false,
+    })
+
+--DOC_NEWLINE
+
+    awful.tag.add("Volatile", {
+        screen   = screen[1],
+        layout   = awful.layout.suit.corner.nw,
+        volatile = true,
+    })
+
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+--DOC_NEWLINE
+
+module.add_event("Add some clients", function() --DOC_HIDE
+    -- Add some clients.
+    for _, t in ipairs(screen[1].tags) do
+        for _ = 1, 5 do
+            awful.spawn("xterm", {tag = t})
+        end
+        assert(#t:clients() == 5) --DOC_HIDE
+    end
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+--DOC_NEWLINE
+
+module.add_event("Kill all clients", function() --DOC_HIDE
+    -- Kill all clients.
+    while #client.get() ~= 0 do
+        client.get()[1]:kill()
+    end
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+module.execute {show_empty = true} --DOC_HIDE