Finally add documentation

README.md

@@ -12,6 +12,71 @@ much the same rule configuration, but without all the dynamic tag code. Note
 that dynamic tagging is now supported directly by awesome. Tyrannical support
 Awesome WM version 3.5 and higher.
 
+#### Tag model
+
+Tyrannical turn awful.rule upside down. Instead of having to define rules for
+specific classes or matches, you define an array of tags, each with their own
+set of properties and rules. When a new client will arrive, it will be matched
+with a set of tags without any client specific configuration.
+
+All tags can have one "current" state:
+
+ * **inclusive:** The default state. All new clients will be allowed
+ * **exclusive:** Clients have be part of the allowed classes to be added
+ * **locked:** No new clients will be allowed in the tag
+ * **fallback:** If a client cannot be added to the current tag, then it will go there
+
+These rules are bypassed by `intrusive` clients. In that case, the client will
+be allowed no matter what. If there is no fallback tag and the client cannot be
+added to an existing tag, then a new one will be created with the client class
+as name. If the tag is set to `volatile`, then it will be destroyed when the
+last client is closed. If set to `init`, it will be present by default even if
+there is nothing in it.
+
+#### Client properties model
+
+Tyrannical offer a bunch of dynamic table for each properties (see below).
+When a class is present in one of those table, clients will be assigned the
+properties from the table name. For example, if you add Firefox to
+`tyrannical.properties.floating`, then it will float by default. Specific values
+can also to other value by using the class name as table key:
+
+```lua
+    tyrannical.properties.maximized = {
+        amarok = false,
+    }
+```
+
+#### Focus model
+
+Tyrannical focus model is very fine tuned. It is possible to add rules on how
+the focus will be attributes to clients and tags.
+
+**block_transient_for_focus_stealing:** 
+This is a fancy X11 name for something very common: modal dialogs and popups.
+If this is set to `true`, then a dialog wont be able to steal the focus from
+whatever your doing. This is useful for some misbehaving apps such as Firefox
+that can decide to show an update popup at the worst possible moment.
+
+**group_children:**
+While not directly related to focus, when using with `no_focus_stealing_out`,
+it allow new "children" clients to silently be added to their "parent" tag.
+A good taglist widgets such as Radical can take care of notifying the user
+without disturbing your workflow.
+
+**no_focus_stealing_in:**
+When a new client is added to a tag with `no_focus_stealing_in` set to true,
+then the tag wont be selected and the current one will be kept.
+
+**no_focus_stealing_out:**
+Similar to `no_focus_stealing_in`. If a tag enable this, then the tag will stay
+selected no matter what event happen. This is useful for video games and video
+players.
+
+**no_autofocus:**
+When a class has this flag, then new clients wont be focused when they are
+launched. This is useful for download managers or background terminals tasks.
+
 ### Installation
 
 This is how to install Tyrannical
@@ -173,7 +238,6 @@ Then edit this section to fit your needs.
 | **mwfact**                | Tiled layout master/slave ratio                      | float(0-1)       |
 | **ncol**                  | Number of columns                                    | number           |
 | **nmaster**               | Number of master clients                             | number           |
-| **no_focus_stealing**     | Do not change focus then a new client is added       | boolean          |
 | **no_focus_stealing_in**  | Do not select this tag when a new client is added    | boolean          |
 | **no_focus_stealing_out** | Do not unselect when a new client is added elsewhere | boolean          |
 | **screen**                | Tag screen(s)                                        | number or array  |
@@ -205,14 +269,15 @@ Then edit this section to fit your needs.
 | **sticky**                | Display in all tags                            | boolean          |
 | **master**                | Open a client as master (bigger)               | boolean          |
 | **slave**                 | Open a client as slave (smaller)               | boolean          |
+| **no_autofocus**          | Do not focus a new instance                    | boolean          |
 
  *Need default rc.lua modifications in the "client.connect_signal('focus')" section
 
 ##### The available global settings are:
 
 | Property                               | Description                                         | Type             |
-| --------------------------------- | --------------------------------------------------- |:----------------:|
+| -------------------------------------- | --------------------------------------------------- |:----------------:|
-| **block_children_focus_stealing** | Prevent popups from stealing focus                  | boolean          |
+| **block_transient_for_focus_stealing** | Prevent popups from stealing focus                  | boolean          |
 | **default_layout**                     | The default layout for tags                         | layout           |
 | **group_children**                     | Add dialogs to the same tags as their parent client | boolean          |
 | **mwfact**                             | The default master/slave ratio                      | float (0-1)      |