update documentation

2 files changed, 222 insertions, 67 deletions

diff --git a/README.md b/README.md
index 5ad7b74..878ebfc 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@ monsterwm
 
 **monsterwm** is a minimal, lightweight, tiny but monsterous dynamic tiling window manager.
 It will try to stay as small as possible. Currently under 750 lines with the config file included.
-It provides a set of different layout modes (see below), and has partial floating mode support.
+It provides a set of different layout modes (see below), including floating mode support.
 Each virtual desktop has its own properties, unaffected by other desktops' settings.
 For screenshots and ramblings/updates check the [topic on ArchLinux forums][monsterwm].
 
@@ -54,6 +54,9 @@ opening the window at the bottom of the stack (attach\_aside)
     |   |   |   |
     -------------
 
+one can have as many windows he wants.
+`GRID` layout automatically manages the rows and columns.
+
 ---
 
  *Monocle mode* (aka fullscreen)
@@ -65,6 +68,10 @@ opening the window at the bottom of the stack (attach\_aside)
     |           |
     -------------
 
+`MONOCLE` layout presents one window at a time in fullscreen mode.
+Windows have no borders on this layout to save space.
+See the `monocleborders` branch to give those windows borders.
+
 ---
 
  *floating mode*
@@ -80,30 +87,38 @@ opening the window at the bottom of the stack (attach\_aside)
  Changing desktops, adding or removing floating windows, does not affect the
  floating status of the windows. Windows will revert to their tiling mode
  position once the user selects a tiling mode.
- Note, that one cannot "select" the floating mode, but it will be enabled if
- one tries to move or resize a window with the mouse. Once one does that, then
- the window is marked as being in floating mode.
+ To enter the floating mode, either change the layout to `FLOAT`, or
+ enabled it by moving or resizing a window with the mouse, the window
+ is then marked as being in floating mode.
 
 ---
 
-All accessible with keyboard and mouse shortcuts are defined in the config.h file.
+All shortcuts are accessible via the keyboard and the mouse, and defined in `config.h` file.
+
+All desktops store their settings independently.
 
  * The window W at the top of the stack can be resized on a per desktop basis.
  * Changing a tiling mode or window size on one desktop doesn't affect the other desktops.
+ * toggling the panel in one desktop does not affect the state of the panel in other desktops.
 
 
 Panel - Statusbar
 -----------------
 
-The user can define an empty space on the bottom or top of the screen, to be
-used by a panel. The panel is toggleable, but will be visible if no windows are
-on the screen.
+The user can define an empty space (by default 18px) on the bottom or top(default) of the
+screen, to be used by a panel. The panel is toggleable, but will be visible if no windows
+are on the screen.
+
 Monsterwm does not provide a panel and/or statusbar itself. Instead it adheres
 to the [UNIX philosophy][unix] and outputs information about the existent
 desktop, the number of windows on each, the mode of each desktop, the current
 desktop and urgent hints whenever needed. The user can use whatever tool or
 panel suits him best (dzen2, conky, w/e), to process and display that information.
 
+To disable the panel completely set `PANEL_HEIGHT` to zero `0`.
+The `SHOW_PANELL` setting controls whether the panel is visible on startup,
+it does not control whether there is a panel or not.
+
   [unix]: http://en.wikipedia.org/wiki/Unix_philosophy
 
 
@@ -125,24 +140,36 @@ Patches
 -------
 
 Some extensions to the code are supported in the form of patches.
-See other branches for patch and code.
+See other branches for the patch and code.
+Easiest way to apply a patch, is to `git merge` that branch.
 
 Currently:
 
- * [fib]            : adds fibonacci layout
+ * [centerwindow]   : center new floating windows on the screen and  center any window with a shortcut
+ * [fib]            : adds fibonacci layout mode
+ * [initlayouts]    : define initial layouts for every desktop
  * [monocleborders] : adds borders to the monocle layout
+ * [nmaster]        : adds nmaster layout - multiple master windows for BSTACK and TILE layouts
  * [showhide]       : adds a function to show and hide all windows on all desktops
  * [uselessgaps]    : adds gaps around every window on screen
  * [warpcursor]     : cursors follows and is placed in the center of the current window
- * [bloat]          : bloat is merge of all patches with the current master, just for fun
+ * [windowtitles]   : along with the rest desktop info, output the title of the current window
 
+  [centerwindow]:   https://github.com/c00kiemon5ter/monsterwm/tree/centerwindow
   [fib]:            https://github.com/c00kiemon5ter/monsterwm/tree/fib
+  [initlayouts]:    https://github.com/c00kiemon5ter/monsterwm/tree/initlayouts
   [monocleborders]: https://github.com/c00kiemon5ter/monsterwm/tree/monocleborders
+  [nmaster]:        https://github.com/c00kiemon5ter/monsterwm/tree/nmaster
   [showhide]:       https://github.com/c00kiemon5ter/monsterwm/tree/showhide
   [uselessgaps]:    https://github.com/c00kiemon5ter/monsterwm/tree/uselessgaps
   [warpcursor]:     https://github.com/c00kiemon5ter/monsterwm/tree/warpcursor
-  [bloat]:          https://github.com/c00kiemon5ter/monsterwm/tree/bloat
+  [windowtitles]:   https://github.com/c00kiemon5ter/monsterwm/tree/windowtitles
+
+There is also another branch, called [`core`].
+`core` is an even more stripped and minimal version of `monsterwm`,
+on top of which the `master` branch is built and builds.
 
+  [core]: https://github.com/c00kiemon5ter/monsterwm/tree/core
 
 Bugs
 ----
diff --git a/monsterwm.1 b/monsterwm.1
index ce601b0..1ef47c0 100644
--- a/monsterwm.1
+++ b/monsterwm.1
@@ -5,64 +5,84 @@ monsterwm \- minimal and dynamic tiling window manager
 .B monsterwm
 .RB [ \-v ]
 .SH DESCRIPTION
-monsterwm is a very minimal, lightweight, tiny but monsterous, dynamic tiling
-window manager with floating mode support. It will try to stay as small as
-possible.
+.I monsterwm
+is a minimal, lightweight, tiny but monsterous, dynamic tiling window manager.
 .P
 .SH MODES
-It allows the "normal" method of tiling window managers (with the new window as
-the master) and with the new window opened at the bottom of the stack
+.I monsterwm
+comes with four tiling layouts by default plus the floating mode.
+It allows the usual method of tiling window managers, with the new window as
+the master window, but also provides the ability to have the new window opened
+as the last window (at the bottom) of the stack.
 .P
-.B monsterwm
-three other modes available:
-.I Bottom stack
-where the slave clients (the smaller "windows") are tiled beneath the master.
-.I Grid mode
-where, once there are four or more cliens in a workspace, they are all
-equally divided into a grid.
-.I Monocle mode
-or fullscreen mode, where the clients take up the entire workspace, and additional
-clients are hidden behind the current shown window.
-.I Floating mode
-where, windows can move and be resized freely in the screen space. Windows
-retain their floating status until the user switches to a tiling mode.
+the available modes:
+.TP
+.B Tile stack
+the stack clients are tiled on the side of master.
+.TP
+.B Bottom stack
+the stack clients are tiled beneath the master.
+.TP
+.B Grid mode
+clients are tiled in a grid, equaly sharing and dividing the screen space
+.TP
+.B Monocle mode
+also known as fullscreen or max mode, where the clients take up the entire
+screen space. Other clients are hidden behind the current shown window.
+On this layout, fullscreen clients don't need and don't have borders.
+You can change that behavior with the
+.I monocleborders
+patch, in the corresponding branch.
+.TP
+.B Floating mode
+windows can move and be resized freely in the screen space, like on a stacking
+window manager. Windows retain their floating status until the user switches
+to a tiling mode.
 .SH OPTIONS
 .TP
 .B \-v
 prints version information to standard output, then exits.
 .SH USAGE
 .SS Status bar
-monsterwm does not provide a status bar. Consistent with the Unix philosophy,
-monsterwm provides information to the status bar or panel of choice via text.
+.P
+.I monsterwm
+does not provide a status bar. Consistent with the Unix philosophy,
+.I monsterwm
+provides information to the status bar or panel of choice via ouputing
+text with information about the state of the windows.
+.P
+the available settings in
+.I config.h
+for the panel/status bar, are:
+.TP
+.B SHOW_PANEL
+whether the panel should be visible or hidden by default
+.TP
+.B TOP_PANEL
+whether the panel should be on top or bottom of the screen
+.TP
+.B PANEL_HEIGHT
+how much space should be left for use by the panel. Set to
+.B 0
+to disable the panel completely.
 .SS Keyboard and mouse commands
 All of
 .I monsterwm's
 commands can be customized by editing
 .I config.h
-and recompiling. The default key-bindings include:
-.TP
-.B Mod1\-Shift\-Return
-Start
-.BR xterm (1).
-.TP
-.B Mod4\-v
-Start
-.BR dmenu (1).
+and recompiling.
+.P
+The default keyboard-bindings include:
 .TP
 .B Mod1\-b
 Toggles the panel on and off.
 .TP
-.B Mod1\-Shift\-t
-Sets tiled layout.
+.B Mod1\-Backspace
+Focus the window with an urgent hint.
+Focus the appropriate desktop if needed.
 .TP
-.B Mod1\-Shift\-m
-Sets monocle layout.
-.TP
-.B Mod1\-Shift\-b
-Sets bottom stack layout
-.TP
-.B Mod1\-Shift\-g
-Sets grid layout
+.B Mod1\-Shift\-c
+Close focused window.
 .TP
 .B Mod1\-j
 Focus next window.
@@ -70,40 +90,91 @@ Focus next window.
 .B Mod1\-k
 Focus previous window.
 .TP
-.B Mod1\-Shift\-j
-Move the focussed window down the stack
-.TP
-.B Mod1\-Shift\-k
-Move the focussed window up the stack
-.TP
 .B Mod1\-l
 Increase master area size.
 .TP
 .B Mod1\-h
 Decrease master area size.
 .TP
-.B Mod1\-Return
-Swaps the focused window to/from master area (tiled layouts only).
+.B Mod1\-o
+Shrink the size of the first stack window.
 .TP
-.B Mod1\-Shift\-{Left,Right}
-Rotate to the next/previous desktop
+.B Mod1\-p
+Grow the size of the first stack window.
 .TP
-.B Mod1\-Shift\-c
-Close focused window.
+.B Mod1\-Ctrl\-h
+focus the previous desktop.
+.TP
+.B Mod1\-Ctrl\-l
+focus the next desktop.
+.TP
+.B Mod1\-Shift\-h
+focus the previous desktop that has windows open.
+.TP
+.B Mod1\-Shift\-l
+focus the next desktop that has windows open.
 .TP
 .B Mod1\-Tab
 Toggles to the last selected desktop.
 .TP
+.B Mod1\-Return
+Swaps the focused window to/from master area (tiled layouts only).
+.TP
+.B Mod1\-Shift\-j
+Move the focussed window down the stack
+.TP
+.B Mod1\-Shift\-k
+Move the focussed window up the stack
+.TP
+.B Mod1\-Shift\-t
+Sets tiled layout.
+.TP
+.B Mod1\-Shift\-m
+Sets monocle layout.
+.TP
+.B Mod1\-Shift\-b
+Sets bottom stack layout
+.TP
+.B Mod1\-Shift\-g
+Sets grid layout
+.TP
+.B Mod1\-Shift\-f
+Sets float layout
+.TP
+.B Mod1\-Shift\-r
+Quit with exit value 0 (usefull for restarts of the wm).
+.TP
 .B Mod1\-Shift\-q
-Quit monsterwm.
+Quit with exit value 1 (differentiate quit from restart).
+.TP
+.B Mod1\-Shift\-Return
+Start
+.BR xterm (1).
+.TP
+.B Mod4\-v
+Start
+.BR dmenu (1).
+.TP
+.B MOD4\-{Down,Up,Right,Left} Arrow
+move the current window to the corresponding direction.
+.TP
+.B MOD4\-Shift\-{Down,Up,Right,Left} Arrow
+resize the current window to the corresponding direction.
 .TP
 .B Mod1\-F{1..n}
 Move to the nth workspace. By default,
 .I monsterwm
 is configured with four workspaces.
+The setting in
+.I config.h
+.B FOLLOW_WINDOW
+defines whether the focus should change on
+the new desktop, where the window moved to.
 .TP
 .B Mod1\-Shift\-F{1..n}
 Move focused window to nth workspace.
+.P
+The default mouse-bindings include:
 .TP
 .B Mod1\-Button1
 Dragging the mouse will move the selected window
@@ -114,20 +185,77 @@ Dragging the mouse will resize the selected window
 .B Mod4\-Button3
 will bring up
 .I dmenu
-.TP
-.SH CUSTOMIZATION
+.SS Customization
 .I monsterwm
 is customized by copying
 .I config.def.h
 to
 .I config.h
 and (re)compiling the source code.
+.P
+settings among others covered above include:
+.TP
+.B MASTER_SIZE
+set the size of the master area that
+will be used by the master window
+.TP
+.B DEFAULT_MODE
+set the default tiling mode to be active on startup
+.TP
+.B ATTACH_ASIDE
+whether new stack clients should spawn as the master window,
+or the last stack window
+.TP
+.B FOLLOW_MOUSE
+whether to focus the window the mouse just entered
+.TP
+.B FOLLOW_WINDOW
+whether to follow the window to the new desktop where it moved
+.TP
+.B CLICK_TO_FOCUS
+whether an action on a window (eg clicking, or scrolling)
+will give the window focus. Disabling this gives the user
+the ability to, for example, look up things on a web browser
+but not lose focus from the terminal etc.
+.TP
+.B BORDER_WIDTH
+the width of the borders the windows have
+.TP
+.B FOCUS / UNFOCUS
+the colors for the borders of focused and unfocused windows
+.TP
+.B DESKTOPS
+the number of desktops to use
+.TP
+.B DEFAULT_DESKTOP
+which desktop to focus by default
+.TP
+.B MINWSZ
+the minimum window size allowed. Prevents over resizing with
+the mouse or keyboard (eg resizing the master area)
+.P
+users can set
+.B rules
+on applications, by matching their
+.B class
+or
+.B instance
+name. The rules can specify on which
+.B desktop
+the application should start (or
+.B -1
+to signify the current desktop), whether the
+.B focus
+should change to that desktop, when the application starts
+and whether the application should start on
+.B floating
+or tiled mode.
 .SH SEE ALSO
 .BR dmenu (1)
 .SH BUGS
 .I monsterwm
 is under active development. Please report all bugs to the author.
 .SH AUTHOR
-Ivan Kanakarakis <ivan.kanak at gmail.com>
+Ivan c00kiemon5ter Kanakarakis <ivan.kanak at gmail.com>