Pass intermediate conseq. as arg. to ext. rules

[bspwm.git] / doc / bspwm.1.asciidoc

diff --git a/doc/bspwm.1.asciidoc b/doc/bspwm.1.asciidoc
index ff8031e476b29d4d78f4705cb69c4336e76bddb6..bd0605f8f998e698cdf1736bdacd942768dcd11e 100644 (file)
--- a/doc/bspwm.1.asciidoc
+++ b/doc/bspwm.1.asciidoc
@@ -64,13 +64,21 @@ default reference value is *focused*).
 An exclamation mark can be prepended to any modifier in order to reverse its
 meaning.
 
+The following characters cannot be used in monitor or desktop names: *#*, *:*, *.*.
+
+The special selector *%<name>* can be used to select a monitor or a desktop with an invalid name.
+
 Node
 ~~~~
 
 Select a node.
 
 ----
-NODE_SEL := [NODE_SEL#](DIR|CYCLE_DIR|PATH|last|older|newer|focused|pointed|biggest|<node_id>)[.[!]focused][.[!]automatic][.[!]local][.[!]active][.[!]leaf][.[!]window][.[!]STATE][.[!]FLAG][.[!]LAYER][.[!]same_class][.[!]descendant_of][.[!]ancestor_of]
+NODE_SEL := [NODE_SEL#](DIR|CYCLE_DIR|PATH|last|
+                        older|newer|focused|pointed|
+                        biggest|<node_id>)[.[!]focused][.[!]automatic][.[!]local][.[!]active]
+                                          [.[!]leaf][.[!]window][.[!]STATE][.[!]FLAG][.[!]LAYER]
+                                          [.[!]same_class][.[!]descendant_of][.[!]ancestor_of]
 
 STATE := tiled|pseudo_tiled|floating|fullscreen
 
@@ -181,7 +189,9 @@ Desktop
 Select a desktop.
 
 ----
-DESKTOP_SEL := [DESKTOP_SEL#](CYCLE_DIR|last|older|newer|[MONITOR_SEL:](focused|^<n>)|<desktop_id>|<desktop_name>)[.[!]occupied][.[!]focused][.[!]urgent][.[!]local]
+DESKTOP_SEL := [DESKTOP_SEL#](CYCLE_DIR|last|older|newer|
+                              [MONITOR_SEL:](focused|^<n>)|
+                              <desktop_id>|<desktop_name>)[.[!]occupied][.[!]focused][.[!]urgent][.[!]local]
 ----
 
 Descriptors
@@ -203,7 +213,7 @@ focused::
        Selects the currently focused desktop.
 
 ^<n>::
-       Selects the nth desktop.
+       Selects the nth desktop. If *MONITOR_SEL* is given, selects the nth desktop on the selected monitor.
 
 <desktop_id>::
        Selects the desktop with the given ID.
@@ -232,7 +242,9 @@ Monitor
 Select a monitor.
 
 ----
-MONITOR_SEL := [MONITOR_SEL#](DIR|CYCLE_DIR|last|older|newer|focused|primary|^<n>|<monitor_id>|<monitor_name>)[.[!]occupied][.[!]focused]
+MONITOR_SEL := [MONITOR_SEL#](DIR|CYCLE_DIR|last|older|newer|
+                              focused|pointed|primary|^<n>|
+                              <monitor_id>|<monitor_name>)[.[!]occupied][.[!]focused]
 ----
 
 Descriptors
@@ -256,6 +268,9 @@ newer::
 focused::
        Selects the currently focused monitor.
 
+pointed::
+       Selects the monitor under the pointer.
+
 primary::
        Selects the primary monitor.
 
@@ -509,7 +524,7 @@ Options
        Constrain matches to the selected monitor, desktop or node. The descriptor can be omitted for '-M', '-D' and '-N'.
 
 *--names*::
-       Print names instead of IDs.
+       Print names instead of IDs. Can only be used with '-M' and '-D'.
 
 Wm
 ~~
@@ -531,6 +546,9 @@ Commands
 *-a*, *--add-monitor* <name> WxH+X+Y::
        Add a monitor for the given name and rectangle.
 
+*-O*, *--reorder-monitors* <name>...::
+       Reorder the list of monitors to match the given order.
+
 *-o*, *--adopt-orphans*::
        Manage all the unmanaged windows remaining from a previous session.
 
@@ -574,8 +592,17 @@ Subscribe
 
 General Syntax
 ^^^^^^^^^^^^^^
-subscribe (all|report|monitor|desktop|node|...)*::
-       Continuously print status information. See the *EVENTS* section for the detailed description of each event.
+subscribe ['OPTIONS'] (all|report|monitor|desktop|node|...)*::
+       Continuously print events. See the *EVENTS* section for the description of each event.
+
+Options
+^^^^^^^
+
+*-f*, *--fifo*::
+       Print a path to a FIFO from which events can be read and return.
+
+*-c*, *--count* 'COUNT'::
+       Stop the corresponding *bspc* process after having received 'COUNT' events.
 
 Quit
 ~~~~
@@ -619,7 +646,7 @@ Global Settings
        Prefix prepended to each of the status lines.
 
 'external_rules_command'::
-       External command used to retrieve rule consequences. The command will receive the following arguments: window ID, class and instance names, monitor, desktop and node selectors. The output of that command must have the following format: *key1=value1 key2=value2 ...* (the valid key/value pairs are given in the description of the 'rule' command).
+       External command used to retrieve rule consequences. The command will receive the following arguments: window ID, class name, instance name, and intermediate consequences. The output of that command must have the following format: *key1=value1 key2=value2 ...* (the valid key/value pairs are given in the description of the 'rule' command).
 
 'initial_polarity'::
        On which child should a new window be attached when adding a window on a single window tree in automatic mode. Accept the following values: *first_child*, *second_child*.
@@ -769,11 +796,11 @@ Events
 'desktop_layout <monitor_id> <desktop_id> tiled|monocle'::
        The layout of a desktop changed.
 
-'node_manage <monitor_id> <desktop_id> <node_id> <ip_id>'::
-       A window is managed.
+'node_add <monitor_id> <desktop_id> <ip_id> <node_id>'::
+       A node is added.
 
-'node_unmanage <monitor_id> <desktop_id> <node_id>'::
-       A window is unmanaged.
+'node_remove <monitor_id> <desktop_id> <node_id>'::
+       A node is removed.
 
 'node_swap <src_monitor_id> <src_desktop_id> <src_node_id> <dst_monitor_id> <dst_desktop_id> <dst_node_id>'::
        A node is swapped.