+++ /dev/null
-doc/bspwm.1.txt
\ No newline at end of file
--- /dev/null
+## Description
+
+*bspwm* is a tiling window manager that represents windows as the leaves of a full binary tree.
+
+It only responds to X events, and the messages it receives on a dedicated socket.
+
+*bspc* is a program that writes messages on *bspwm*'s socket.
+
+*bspwm* doesn't handle any keyboard or pointer inputs: a third party program (e.g. *sxhkd*) is needed in order to translate keyboard and pointer events to *bspc* invocations.
+
+The outlined architecture is the following:
+
+```
+ PROCESS SOCKET
+sxhkd --------> bspc <------> bspwm
+```
+
+## Configuration
+
+The default configuration file is `$XDG_CONFIG_HOME/bspwm/bspwmrc`: this is simply a shell script that calls *bspc*.
+
+Keyboard and pointer bindings are defined with [sxhkd](https://github.com/baskerville/sxhkd).
+
+Example configuration files can be found in the `examples` directory.
+
+## Monitors, desktops and windows
+
+*bspwm* holds a list of monitors.
+
+A monitor is just a rectangle that contains desktops.
+
+A desktop is just a pointer to a tree.
+
+Monitors only show the tree of one desktop at a time (their focused desktop).
+
+The tree is a partition of a monitor's rectangle into smaller rectangular regions.
+
+Each node in a tree either has zero or two children.
+
+Each internal node is responsible for splitting a rectangle in half.
+
+A split is defined by two parameters: the type (horizontal or vertical) and the ratio (a real number *r* such that *0 < r < 1*).
+
+Each leaf node holds exactly one window.
+
+## Insertion Modes
+
+### Prelude
+
+When *bspwm* receives a new window, it inserts it into a window tree at the specified insertion point (a leaf) using the insertion mode specified for that insertion point.
+
+The insertion mode tells *bspwm* how it should alter the tree in order to insert new windows on a given insertion point.
+
+By default the insertion point is the focused window and its default insertion mode is *automatic*.
+
+### Automatic Mode
+
+The *automatic* mode, as opposed to the *manual* mode, doesn't require any user choice: the new window will *take the space* of the insertion point.
+
+For example, let's consider the following scenario:
+
+```
+ a a a
+ / \ / \ / \
+ 1 b ---> 1 c ---> 1 d
+ / \ / \ / \
+ 2 3 4 b 5 c
+ ^ ^ / \ ^ / \
+ 3 2 b 4
+ / \
+ 3 2
+
+ +-----------------------+ +-----------------------+ +-----------------------+
+ | | | | | | | | |
+ | | 2 | | | 4 | | | 5 |
+ | | ^ | | | ^ | | | ^ |
+ | 1 |-----------| | 1 |-----------| | 1 |-----------|
+ | | | | | | | | | 3 | |
+ | | 3 | | | 3 | 2 | | |-----| 4 |
+ | | | | | | | | | 2 | |
+ +-----------------------+ +-----------------------+ +-----------------------+
+
+ X Y Z
+```
+
+In state *X*, the insertion point, *2* is in automatic mode.
+
+When we add a new window, *4*, the whole tree rooted at *b* is reattached, as the second child of a new internal node, *c*.
+
+The splitting parameters of *b* (type: *horizontal*, ratio: *½*) are copied to *c* and *b* is rotated by 90° clockwise.
+
+The tiling rectangle of *4* in state *Y* is equal to the tiling rectangle of *2* in state *X*.
+
+Then the insertion of *5*, with *4* as insertion point, leads to *Z*.
+
+The automatic mode generates window spirals that rotate clockwise (resp. anti-clockwise) if the insertion point is the first (resp. second) child of its parent.
+
+### Manual Mode
+
+The user can specify a region in the insertion point where the next new window should appear by sending a *window --presel DIR* message to *bspwm*.
+
+The *DIR* argument allows to specify how the insertion point should be split (horizontally or vertically) and if the new window should be the first or the second child of the new internal node (the insertion point will become its *brother*).
+
+After doing so the insertion point goes into *manual* mode.
+
+For example, let's consider the following scenario:
+
+```
+ a a a
+ / \ / \ / \
+ 1 b ---> c b ---> c b
+ ^ / \ / \ / \ / \ / \
+ 2 3 4 1 2 3 d 1 2 3
+ ^ / \
+ 5 4
+ ^
+
++-----------------------+ +-----------------------+ +-----------------------+
+| | | | | | | | | |
+| | 2 | | 4 | 2 | | 5 | 4 | 2 |
+| | | | ^ | | | ^ | | |
+| 1 |-----------| |-----------|-----------| |-----------|-----------|
+| ^ | | | | | | | |
+| | 3 | | 1 | 3 | | 1 | 3 |
+| | | | | | | | |
++-----------------------+ +-----------------------+ +-----------------------+
+
+ X Y Z
+```
+
+In state *X*, the insertion point is *1*.
+
+We send the following message to *bspwm*: *window --presel up*.
+
+Then add a new window: *4*, this leads to state *Y*: the new internal node, *c* becomes *a*'s first child.
+
+Finally we send another message: *window --presel left* and add window *5*.
+
+The ratio of the preselection (that ends up being the ratio of the split of the new internal node) can be change with the *window --ratio* message.
+
+## Supported protocols and standards
+
+- The RandR and Xinerama protocols.
+- A subset of the EWMH and ICCCM standards.
.\" Title: bspwm
.\" Author: [see the "Author" section]
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
-.\" Date: 11/13/2015
+.\" Date: 11/15/2015
.\" Manual: Bspwm Manual
.\" Source: Bspwm 0.9
.\" Language: English
.\"
-.TH "BSPWM" "1" "11/13/2015" "Bspwm 0\&.9" "Bspwm Manual"
+.TH "BSPWM" "1" "11/15/2015" "Bspwm 0\&.9" "Bspwm Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.RS 4
Use the given configuration file\&.
.RE
-.SH "CONFIGURATION"
-.sp
-\fBbspwm\fR has only two sources of informations: the X events it receives and the messages it reads on a dedicated socket\&.
-.sp
-The default configuration file is \fI$XDG_CONFIG_HOME/bspwm/bspwmrc\fR\&.
-.sp
-Keyboard and pointer bindings are defined with sxhkd\&.
-.sp
-Example configuration files can be found in the \fBexamples\fR directory\&.
-.SH "SPLITTING MODES"
-.sp
-New windows are inserted in the tree as close as possible to the focused window\&.
-.sp
-There are only two splitting modes: \fIautomatic\fR and \fImanual\fR\&.
-.sp
-The default mode is \fIautomatic\fR\&. The \fImanual\fR mode is entered by sending a \fBpreselection\fR message\&.
-.sp
-Example: insertion of a new node (number 4) into the given tree in \fIautomatic\fR mode:
-.sp
-.if n \{\
-.RS 4
-.\}
-.nf
- b c
- / \e / \e
- 3 a \-\-> 4 b
- ^ / \e ^ / \e
- 2 1 3 a
- / \e
- 2 1
- +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
- | | | | | |
- | | 2 | | | 3 |
- | | | | | |
- | 3 |\-\-\-\-\-\-\-\-\-\-\-\-| \-\-> | 4 |\-\-\-\-\-\-\-\-\-\-\-\-|
- | ^ | | | ^ | | |
- | | 1 | | | 1 | 2 |
- | | | | | | |
- +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
-.fi
-.if n \{\
-.RE
-.\}
-.sp
-Same action, but the mode is \fImanual\fR, and a \fBwindow \-\-presel up\fR message was sent beforehand:
-.sp
-.if n \{\
-.RS 4
-.\}
-.nf
- b b
- / \e / \e
- 3 a \-\-> c a
- ^ / \e / \e / \e
- 2 1 4 3 2 1
- ^
-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
-| | | | | |
-| | 2 | | 4 | 2 |
-| | | | ^ | |
-| 3 |\-\-\-\-\-\-\-\-\-\-\-\-| \-\-> |\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-|
-| ^ | | | | |
-| | 1 | | 3 | 1 |
-| | | | | |
-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
-.fi
-.if n \{\
-.RE
-.\}
-.SH "CONTAINERS"
-.sp
-Each monitor contains at least one desktop\&.
-.sp
-Each desktop contains at most one tree\&.
.SH "COMMON DEFINITIONS"
.sp
.if n \{\
locked
.RS 4
Ignores the
-\fBclose\fR
+\fBwindow \-\-close\fR
message\&.
.RE
.PP
\fIpresel_border_color\fR
.RS 4
Color of the
-\fBpresel\fR
+\fBwindow \-\-presel\fR
message feedback\&.
.RE
.PP
\fBbspwm\fR\&. If it isn\(cqt defined, then the following path is used:
\fI/tmp/bspwm<host_name>_<display_number>_<screen_number>\-socket\fR\&.
.RE
-.SH "PANELS"
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-Any EWMH compliant panel (e\&.g\&.:
-\fItint2\fR,
-\fIbmpanel2\fR, etc\&.)\&.
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-A custom panel (have a look at the files in
-\fIexamples/panel\fR)\&.
-.RE
-.SH "KEY FEATURES"
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-Configured and controlled through messages\&.
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-Multiple monitors support\&.
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-EWMH support\&.
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-Hybrid tiling\&.
-.RE
.SH "CONTRIBUTORS"
.sp
.RS 4
.SH "AUTHOR"
.sp
Bastien Dejean <nihilhill at gmail\&.com>
-.SH "MAILING LIST"
-.sp
-bspwm at librelist\&.com
*-c* 'CONFIG_PATH'::
Use the given configuration file.
-Configuration
--------------
-
-*bspwm* has only two sources of informations: the X events it receives and the messages it reads on a dedicated socket.
-
-The default configuration file is '$XDG_CONFIG_HOME/bspwm/bspwmrc'.
-
-Keyboard and pointer bindings are defined with https://github.com/baskerville/sxhkd[sxhkd].
-
-Example configuration files can be found in the *examples* directory.
-
-Splitting Modes
----------------
-
-New windows are inserted in the tree as close as possible to the focused window.
-
-There are only two splitting modes: 'automatic' and 'manual'.
-
-The default mode is 'automatic'. The 'manual' mode is entered by sending a *preselection* message.
-
-Example: insertion of a new node (number 4) into the given tree in 'automatic' mode:
-
-----
- b c
- / \ / \
- 3 a --> 4 b
- ^ / \ ^ / \
- 2 1 3 a
- / \
- 2 1
- +-------------------------+ +-------------------------+
- | | | | | |
- | | 2 | | | 3 |
- | | | | | |
- | 3 |------------| --> | 4 |------------|
- | ^ | | | ^ | | |
- | | 1 | | | 1 | 2 |
- | | | | | | |
- +-------------------------+ +-------------------------+
-----
-
-Same action, but the mode is 'manual', and a *window --presel up* message was sent beforehand:
-
-----
- b b
- / \ / \
- 3 a --> c a
- ^ / \ / \ / \
- 2 1 4 3 2 1
- ^
-+-------------------------+ +-------------------------+
-| | | | | |
-| | 2 | | 4 | 2 |
-| | | | ^ | |
-| 3 |------------| --> |------------|------------|
-| ^ | | | | |
-| | 1 | | 3 | 1 |
-| | | | | |
-+-------------------------+ +-------------------------+
-----
-
-Containers
-----------
-
-Each monitor contains at least one desktop.
-
-Each desktop contains at most one tree.
-
Common Definitions
------------------
-------------
locked::
- Ignores the *close* message.
+ Ignores the *window --close* message.
sticky::
Stays in the focused desktop of its monitor.
Color of the border of an unfocused window.
'presel_border_color'::
- Color of the *presel* message feedback.
+ Color of the *window --presel* message feedback.
'focused_locked_border_color'::
Color of the border of a focused locked window of a focused monitor.
'BSPWM_SOCKET'::
The path of the socket used for the communication between *bspc* and *bspwm*. If it isn't defined, then the following path is used: '/tmp/bspwm<host_name>_<display_number>_<screen_number>-socket'.
-Panels
-------
-
-* Any EWMH compliant panel (e.g.: 'tint2', 'bmpanel2', etc.).
-* A custom panel (have a look at the files in 'examples/panel').
-
-Key Features
-------------
-
-* Configured and controlled through messages.
-* Multiple monitors support.
-* EWMH support.
-* Hybrid tiling.
-
Contributors
------------
Bastien Dejean <nihilhill at gmail.com>
-Mailing List
-------------
-
-bspwm at librelist.com
-
////
vim: set ft=asciidoc:
////
projects / bspwm.git / commitdiff