Clarify and expand the configuration documentation

README.md

@@ -1,24 +1,26 @@
 ![logo](https://github.com/baskerville/bspwm/raw/master/logo/bspwm-logo.png)
 
+## Synopsis
+
+    bspwm [-v|-s STATUS_FIFO]
+
+    bspc MESSAGE [ARGUMENTS] [OPTIONS]
+
 ## Description
 
-`bspwm` is a tiling window manager based on binary space partitioning.
+`bspwm` is a tiling window manager where each window is represented as the leaf of a binary tree.
 
-The windows are represented as the leaves of a binary tree.
+It is controlled and configured via `bspc`.
 
 ## Configuration
 
 `bspwm` have only two sources of informations: the X events it receives and the messages it reads on a dedicated socket.
 
-Those messages are sent via `bspc`.
-
-If the `BSPWM_SOCKET` environment variable is defined, it will be used as the socket path, otherwise `/tmp/bspwm-socket` is used.
+Its configuration file is `$XDG_CONFIG_HOME/bspwm/autostart`.
 
 The recommended way of defining keyboard shortcuts is to use [sxhkd](https://github.com/baskerville/sxhkd).
 
-The only way to configure `bspwm` is by sending *set* messages via the client, hence `bspwm`'s configuration file is an executable called `autostart` which lives in `$XDG_CONFIG_HOME/bspwm/`.
-
-Example configurations: [autostart](https://github.com/baskerville/bin/blob/master/bspwm_autostart) and [sxhkdrc](https://github.com/baskerville/dotfiles/blob/master/sxhkdrc).
+Example configuration files can be found in the `examples` directory.
 
 ## Splitting Modes
 
@@ -65,12 +67,6 @@ was sent beforehand:
         |            |            |         |            |            |
         +-------------------------+         +-------------------------+
 
-## Synopsis
-
-    bspwm [-v|-s STATUS_FIFO]
-
-    bspc MESSAGE [ARGUMENTS] [OPTIONS]
-
 ## Messages
 
 The syntax for the client is `bspc MESSAGE [ARGUMENTS ...]`.
@@ -221,19 +217,22 @@ Colors are either [X color names](http://en.wikipedia.org/wiki/X11_color_names)
 
 - `apply_shadow_property` — Enable shadows for floating windows via the `_COMPTON_SHADOW` property.
 
+## Environment Variables
+
+- `BSPWM_SOCKET` — The path of the socket used for the communication between `bspc` and `bspwm`.
+
 ## Key Features
 
-- Configured and controlled through messages
-- Multiple monitors support (via *Xinerama*)
-- EWMH support (`tint2` works)
-- Automatic and manual modes
+- Configured and controlled through messages.
+- Multiple monitors support (via *Xinerama*).
+- EWMH support (`tint2` works).
+- Automatic and manual modes.
 
-## Panel
+## Panels
 
-Multiple choices:
-- `dzen2` fed with the output of `ewmhstatus`. Example: [launchpanel](https://github.com/baskerville/bin/blob/master/launchpanel).
-- A custom panel if the `-s` flag is used (have a look at the files in `examples/`).
 - Any EWMH compliant panel (e.g. `tint2`, `bmpanel2`, etc.).
+- A custom panel if the `-s` flag is used (have a look at the files in `examples/panel`).
+- `dzen2` fed with the output of `ewmhstatus`. Example: [launchpanel](https://github.com/baskerville/bin/blob/master/launchpanel).
 
 ## Required Libraries:
 

bspwm.1

@@ -10,7 +10,9 @@ bspwm \- Tiling window manager based on binary space partitioning
 .RI [ OPTIONS ]
 .SH DESCRIPTION
 .B bspwm
-is a tiling window manager where each window is represented as the leaf of a binary tree. It is controlled and configured via
+is a tiling window manager where each window is represented as the leaf of a binary tree.
+.P
+It is controlled and configured via
 .BR bspc .
 .SH CONFIGURATION
 .B bspwm
@@ -18,28 +20,15 @@ have only two sources of informations: the
 .B X
 events it receives and the messages it reads on a dedicated socket.
 .P
-Those messages are sent via
-.BR bspc .
-.P
-If the
-.I BSPWM_SOCKET
-environment variable is defined, it will be used as the socket path, otherwise
-.I /tmp/bspwm-socket
-is used.
+Its configuration file is
+.IR $XDG_CONFIG_HOME/bspwm/autostart .
 .P
 The recommended way of defining keyboard shortcuts is to use
 .BR sxhkd .
 .P
-The only way to configure
-.B bspwm
-is by sending
-.I set
-messages via the client, hence
-.BR bspwm \'s
-configuration file is an executable called
-.I autostart
-which lives in
-.IR $XDG_CONFIG_HOME/bspwm/ .
+Example configuration files can be found in the
+.I examples
+directory.
 .SH SPLITTING MODES
 There is only two splitting modes:
 .IR automatic " and " manual .
@@ -336,6 +325,11 @@ Prevent floating windows from being raised when they might cover other floating
 Enable shadows for floating windows via the
 .B _COMPTON_SHADOW
 property.
+.SH ENVIRONMENT VARIABLES
+.TP
+.I BSPWM_SOCKET
+The path of the socket used for the communication between
+.BR bspc " and " bspwm .
 .SH AUTHOR
 .EX
 Bastien Dejean <baskerville at lavabit.com>

examples/autostart

@@ -0,0 +1,16 @@
+#! /bin/sh
+
+FIRST_DESK=One
+REMAINING_DESKS='Two Three Four Five Six Seven Eight Nine Ten'
+bspc rename Desktop01 $FIRST_DESK
+bspc add $REMAINING_DESKS
+bspc layout monocle $FIRST_DESK $REMAINING_DESKS
+
+bspc rule Gimp Eight floating
+
+bspc set border_width  1
+bspc set window_gap    6
+
+bspc set borderless_monocle  true
+bspc set gapless_monocle     true
+bspc set adaptative_raise    true

examples/panel/autostart

@@ -0,0 +1,3 @@
+#! /bin/sh
+
+panel &

examples/panel/panel

@@ -0,0 +1,5 @@
+#! /bin/sh
+
+xtitle -sf 'T%s' > "$BSPWM_STATUS_FIFO" &
+clock 'S%H:%M' 5 > "$BSPWM_STATUS_FIFO" & 
+cat "$BSPWM_STATUS_FIFO" | panel_bar | bar

examples/panel/panel_bar

@@ -7,6 +7,9 @@ while read -r line ; do
         S*)
             sys_infos="\\r\\f5${line#?}\\fr"
             ;;
+        T*)
+            title="\\c${line#?}"
+            ;;
         *)
             wm_infos=""
             IFS=':'
@@ -35,15 +38,10 @@ while read -r line ; do
                         layout=$(printf "%s" "${item#?}" | sed 's/\(.\).*/\U\1/')
                         wm_infos="$wm_infos \\b4\\f0$layout\\br\\fr"
                         ;;
-                    W*)
-                        # window id
-                        wid=${item#?}
-                        [ $wid != 0 ] && wm_infos="$wm_infos\\c$(xdotool getwindowname 0x$wid)"
-                        ;;
                 esac
                 shift
             done
             ;;
     esac
-    printf "%s\n" "$wm_infos $sys_infos"
+    printf "%s\n" "$wm_infos $title $sys_infos"
 done

examples/panel/profile

@@ -0,0 +1 @@
+export BSPWM_STATUS_FIFO=/tmp/bspwm-fifo

examples/panel/xinitrc

@@ -0,0 +1,3 @@
+[ -e "$BSPWM_STATUS_FIFO" ] && rm "$BSPWM_STATUS_FIFO"
+mkfifo "$BSPWM_STATUS_FIFO"
+exec bspwm -s "$BSPWM_STATUS_FIFO"

examples/sxhkdrc

@@ -0,0 +1,75 @@
+#
+# bspwm hotkeys
+#
+
+super + alt + Escape
+    bspc quit
+
+super + w
+    bspc close
+
+super + t
+    bspc cycle_layout
+
+super + {s,f}
+    bspc toggle_{floating,fullscreen}
+
+super + {grave,Tab}
+    bspc {alternate,alternate_desktop}
+
+super + {h,j,k,l}
+    bspc focus {left,down,up,right}
+
+super + shift + {h,j,k,l}
+    bspc shift {left,down,up,right}
+
+super + {c,shift + c}
+    bspc cycle {next,prev}
+
+super + bracket{left,right}
+    bspc cycle_desktop {prev,next}
+
+super + ctrl + {h,j,k,l}
+    bspc presel {left,down,up,right}
+
+super + alt + {h,j,k,l}
+    bspc push {left,down,up,right}
+
+super + alt + shift + {h,j,k,l}
+    bspc pull {right,up,down,left}
+
+super + ctrl + {1-9}
+    bspc ratio 0.{1-9}
+
+super + {1-9,0}
+    bspc use {One,Two,Three,Four,Five,Six,Seven,Eight,Nine,Ten}
+
+super + shift + {1-9,0}
+    bspc send_to {One,Two,Three,Four,Five,Six,Seven,Eight,Nine,Ten}
+
+super + button{1,2,3}
+    bspc grab_pointer {move,resize_side,resize_corner}
+
+super + !button{1,2,3}
+    bspc {track_pointer,track_pointer,track_pointer} %i %i
+
+super + @button{1,2,3}
+    bspc {ungrab_pointer,ungrab_pointer,ungrab_pointer}
+
+super + alt + button1
+    bspc grab_pointer focus
+
+#
+# wm independent hotkeys
+#
+
+super + Return
+    urxvt
+
+super + space
+    dmenu_run
+
+super + Escape
+    pkill -USR1 -x sxhkd
+
+ vim: set ft=sxhkdrc: