update to wmiiwm.1, rewrote parts, cleaned groff formatting

cmd/wm/wmiiwm.1

@@ -3,8 +3,8 @@
 wmiiwm \- window manager improved 2 (core)
 .SH SYNOPSIS
 .B wmiiwm
-.RB \-a
-.IR <address>
+.R \-a
+.I <address>
 .RB [ \-c ]
 .RB [ \-v ]
 .SH DESCRIPTION
@@ -12,34 +12,35 @@ wmiiwm \- window manager improved 2 (core)
 .BR wmiiwm (1)
 is the core of the window manager improved 2.
 .P
-.BR wmii
+.B wmii
 is a dynamic window manager for X11. In contrast to static window management
 the user rarely has to think about how to organize windows, no matter what he
 is doing or how many applications are used at the same time. The window manager
-adapts to the current environment and helps the user to fit to his needs,
-rather than forcing him to use a preset, fixed layout and trying to
-shoehorn all windows and applications into it.
+adapts to the current environment and fits to the needs of the user, rather 
+than forcing him to use a preset, fixed layout and trying to shoehorn all
+windows and applications into it.
 .P
-.BR wmii
+.B wmii
 supports classic and tiled window management with extended keyboard and mouse
-control.  The classic window management arranges windows in a floating layer,
-whereas windows can be moved and resized freely.  The tiled window management 
+control. The classic window management arranges windows in a floating layer
+in which windows can be moved and resized freely. The tiled window management 
 is based on columns which split up the screen horizontally. Each column handles
-arbitrary windows and arranges them vertically in a non-overlapping way,
-whereas windows can be moved and resized between and within columns freely.
+arbitrary windows and arranges them vertically in a non-overlapping way. They
+can then be moved and resized between and within columns at will.
 .P
-.BR wmii
-provides a virtual filesystem which represents the internal state pretty much
-similiar to the procfs of Unix operating systems.  Modifying this virtual
-filesystem results in changing the state of the window manager. The virtual
-filesystem service can be accessed through 9P-capable client programs,
-like
+.B wmii
+provides a virtual filesystem which represents the internal state similar to
+the procfs of Unix operating systems. Modifying this virtual filesystem results
+in changing the state of the window manager. The virtual filesystem service can
+be accessed through 9P-capable client programs, like
 .BR wmiir (1) .
 This allows simple and powerful remote control of the core window manager.
 .P
-.BR wmii
+.B wmii
 basically consists of clients, columns, views, and the bar, which are described
-in detail in the next section.
+in detail in the
+.B Terminology
+section.
 .SS Options
 .TP
 .BI \-a " address"
@@ -49,9 +50,9 @@ uses to listen for connections.  The syntax for
 .I address
 is taken (along with many other profound ideas) from the Plan 9 operating
 system and has the form
-.BR unix!/path/to/socket 
+.B unix!/path/to/socket 
 for unix socket files, and
-.BR tcp!hostname!port
+.B tcp!hostname!port
 for tcp sockets.
 .TP
 .B \-c
@@ -75,29 +76,33 @@ A (rectangular) drawable X object which is displayed on a screen, usually an
 application window.
 .TP 2
 Client
-An application window surrounded with a frame window, which contains a border
-and a title-bar. The title-bar consists of two labels, the tags of a client, and
-the client's title.
+An application window surrounded by a frame window containing a border and a
+title-bar. The title-bar normally shows only two labels, one displaying the
+tags of a client and the other the client's name. However, if the containing
+column is in maximized mode, a third label is required. It shows which client
+is currently visible and more importantly, the number of clients within the
+column.
 .TP 2
 Floating layer
 A screen layer of
-.BR wmii
+.B wmii
 on top of all other layers, where clients are arranged in a floating way.
 They can be resized or moved freely.
 .TP 2
 Managed layer
 A screen layer of
-.BR wmii
+.B wmii
 behind the floating layer, where clients are arranged in a non-overlapping
-(managed) way.  The window manager keeps track that they not overlap each others.
-The managed layer consists of columns.
+(managed) way.  Here, the window manager dynamically assigns each client a
+size and position. The managed layer consists of columns.
 .TP 2
 Tag
-Alphanumeric strings which can be assigned to a client. This allows to address
-single clients or groups of clients with a single tag, e.g.
-.IR work ,
+Alphanumeric strings which can be assigned to a client. This provides a
+mechanism to group clients with similar properties. Clients can have one
+tag, e.g.
+.I work ,
 or several tags, e.g.
-.IR work+mail.
+.I work+mail.
 Tags are separated with the
 .I +
 character.
@@ -114,17 +119,17 @@ moved and resized between and within columns freely.
 .TP 2
 Bar
 The bar at the bottom of the screen displays a label for each view and
-allows to create arbitrary user-defined labels.
+allows the creation of arbitrary user-defined labels.
 .TP 2
 Event
 An event is a message which can be read from a special file in the filesystem
 of
-.BR wmiiwm
+.B wmiiwm
 like a mouse button press, a key press, or a message written by a different
 9P-client.
 .SS Basic window management
 Running a raw
-.BR wmiiwm
+.B wmiiwm
 process without the
 .BR wmii (1)
 script, provides basic window management capabilities already. However to use
@@ -138,154 +143,164 @@ filesystem.
 The filesystem can be accessed through connecting to the
 .I address
 of
-.BR wmiiwm
+.B wmiiwm
 with any 9P-capable client, like
 .BR wmiir (1).
 .SS File system
 The
-.BR wmiiwm
+.B wmiiwm
 filesystem is designed with simplicity and clarity in mind. It consists of
 logical namespaces which represent its internal state and data structure in a
-straight-forward way.
+straight-forward way. The following is a short description of each file and
+directory contained within the filesystem. For more information on the actual
+data stored in these files and the syntax recognized by each, see the
+.B Syntax of files
+section below.
 .TP 2
 Root directory
-.TP
-/bar/
+.PD 0
+.RS 2
+.TP 2
+/bar
 This directory contains a representation of each label in the bar.
+.PD
 .TP
-/client/
+/client
 This directory contains a representation of each client.
 .TP
 /ctl
 This file understands the internal commands
 .IR quit ,
 which quits the window manager, and
-.IR view
+.I view
 .IR <tag> ,
 which switches to a view for the specific tag.
 .TP
-/def/
+/def
 This directory contains a representation of all default options.
 .TP
 /event
 This file reports events. Reading this file is blocking, this means that
 a 9P-client will not exit until
-.BR wmiiwm
+.B wmiiwm
 quits, or until the client is terminated explicitely.
 .TP
 /tags
 This file contains a list of newline-separated tags currently in use.
 .TP
-/view/
+/view
 This and all other directories contain a representation of each view. The
-.I /view/
+.I /view
 directory points to the currently selected view.
-.TP 2
-Bar directory
+.RE
 .TP
+Bar directory
+.PD 0
+.RS 2
+.TP 2
 /bar/X/colors
-This file defines the colors as RGB-tuple of the specific label, described in detail below.
+This file defines the colors as an RGB-tuple of the specific label.
+.PD
 .TP
 /bar/X/data
 This file contains the text displayed by the label, it may be empty.
-.TP 2
-Clients directory
+.RE
 .TP
+Clients directory
+.PD 0
+.RS 2
+.TP 2
 /client/X/class
 This file contains the X property
+.PD
 .I WM_CLASS
 in the form of
-.IR <Class>:<instance> .
+.IR <Class> : <instance> .
 .TP
 /client/X/ctl
 This file understands the internal client-specific commands
 .IR kill ,
 which kills (closes) the specific client nicely,
-.IR sendto
-.IR prev
-|
-.IR next
-|
-.IR toggle
-|
-.IR <0..n> ,
-which sends the client to the previous, next, or explicitely addressed column, and the
-.IR swap
-.IR prev
-|
-.IR next
-|
-.IR up
-|
-.IR down 
-command,
-which swaps the client with an adjacent client in the specific direction.
+.I sendto
+.IR <prev|next|toggle|0..n> ,
+which sends the client to the previous, next, or explicitely addressed column,
+and the
+.I swap <prev|next|up|down>
+command, which swaps the client with an adjacent client in the specific
+direction.
 .TP
 /client/X/geom
-This file contains the current geometry of the client's frame and can be used to resize
-the client, described in detail below.
+This file contains the current geometry of the client's frame and can be used
+to resize the client.
 .TP
 /client/X/index
 This file contains the index of the client in the
-.I /client/
+.I /client
 namespace.
 .TP
 /client/X/name
 This file contains the name of the client read by the X property
-.I WM_NAME .
+.IR WM_NAME .
 .TP
 /client/X/tags
 This file contains the tags of the client.
-.TP 2
-Defaults directory
+.RE
 .TP
+Defaults directory
+.PD 0
+.RS 2
+.TP 2
 /def/border
 This file defines the default border width for all clients in
-.IR <0..n>
+.PD
+.I <0..n>
 pixels.
 .TP
 /def/colmode
-This file defines the default column mode of newly created columns, described in detail below.
+This file defines the default column mode of newly created columns.
 .TP
 /def/colwidth
-This file defines the default width of newly created columns, described in detail below.
+This file defines the default width of newly created columns.
 .TP
 /def/font
-This file defines the font which should be used by its name, like that ones grabbed with the
+This file defines the font which should be used by its name, like that ones
+grabbed with the
 .BR xfontsel (1)
 utility for X.
 .TP
 /def/grabmod
-This file defines the default modifier for mouse-grabs, described in detail below.
+This file defines the default modifier for mouse-grabs.
 .TP
 /def/keys
-This file contains a newline-separated list of all shortcuts which should be grabbed by
-.BR wmiiwm
+This file contains a newline-separated list of all shortcuts which should
+be grabbed by
+.B wmiiwm
 and which are reported as events.
 .TP
 /def/normcolors
-This file defines the colors of unselected clients and bar labels,
-described in detail below.
+This file defines the colors of unselected clients and bar labels
 .TP
 /def/rules
-This file defines the rules for applying default tags to all existing and newly created clients,
-described in detail below.
+This file defines the rules for applying default tags to all existing and newly
+created clients.
 .TP
 /def/selcolors
-This file defines the colors of selected clients and bar labels,
-described in detail below.
-.TP 2
-View directory
+This file defines the colors of selected clients and bar labels.
+.RE
 .TP
-/view/X/
-This directory contains a representation of a column or the floating layer.
-The
-.I /view/sel/
+View directory
+.PD 0
+.RS 2
+.TP 2
+/view/X
+This directory contains a representation of a column or the floating layer. The
+.I /view/sel
 directory points to the currently selected column or floating layer.
+.PD
 .TP
 /view/ctl
 This file understands the internal view-specific command
-.IR select
+.I select
 .IR <0..n> ,
 which selects the specific area, 0 means floating layer, all other numeric
 values address the specific column from left to right.
@@ -293,44 +308,48 @@ values address the specific column from left to right.
 /view/name
 This file contains the view's name which corresponds to the currently viewed
 clients containing the equivalent tag.
-.TP 2
-Column and floating layer directory
+.RE
 .TP
-/view/X/Y/
+Column and floating layer directory
+.PD 0
+.RS 2
+.TP 2
+/view/X/Y
 This directory contains a representation of a client of this column or floating
 layer respectively. Its contents are the same as in the
-.I /client/X/
+.I /client/X
 namespace described above.
+.PD
 .TP
 /view/X/ctl
 This file understands the internal column-specific command
-.IR select
+.I select
 .IR <0..n> ,
 which selects the specific client from top to bottom.
 .TP
 /view/X/mode
 This file defines the column mode of this column, described in detail below.
 Note, floating layer directories do not contain this file.
+.RE
 .SS Syntax of files
 All files of the filesystem described above can be read, most of them can be
 written as well. Most of the only can be written using valid syntax.
 .TP 2
 colors, selcolors, normcolors
 Each of these files expects three blank-separated color values of the form
-.IR #RRGGBB
-.IR #RRGGBB
+.I #RRGGBB #RRGGBB
 .IR #RRGGBB .
 The order defines foreground, background, and border colors respectively.
 .TP 2
 geom
-Each of this file expects four blank-separated alphanumeric values which define the
+Each of these files expects four blank-separated alphanumeric values which define the
 client's geometry in the order
-.IR <x>
-.IR <y>
-.IR <width>
+.I <x>
+.I <y>
+.I <width>
 .IR <height> .
-Each value for itself can be absolute like
-.I <0..n> ,
+Each value can be absolute like
+.IR <0..n> ,
 or an alignment value such as
 .IR north ,
 .IR west ,
@@ -339,18 +358,18 @@ or an alignment value such as
 or
 .IR center .
 The alignment values address the specific screen border or center respectively.
-Thus they provide a resolution-independent way to address specific coordinates.
+Thus they provide a resolution-independent way of addressing specific coordinates.
 Absolute values can be prepended with the
 .I +
 or
 .I -
 operators, which makes them relative, e.g.
-.I -40 .
+.IR -40 .
 Alignment values can be appended with a relative value to address special positions, e.g.
-.I south-16 .
+.IR south-16 .
 .TP 2
 colmode, mode
-Each of this file expects a single value of the form
+Each of these files expects a single value of the form
 .IR default ,
 .IR stack ,
 or
@@ -365,75 +384,76 @@ This file expects a single value of the form
 .IR Mod4 ,
 or
 .IR Mod5 .
-The specific value corelates with the specific modifier key defined in X, usually
+The specific value corresponds to the specific modifier key defined in X.
 .IR Mod1
-is the
+is usually the
 .IR Alt
-key on most keyboard layouts.
+key for most keyboard layouts.
 .TP 2
 keys
 This file expects a newline-separated list of shortcuts of the form
-.BI [<modifier>\-]<key> .
-As modifier a value of the form
+.BI [<modifier>\-] <key> .
+The modifier can be one or a combination of the following values:
 .IR Mod1 ,
 .IR Mod2 ,
 .IR Mod3 ,
 .IR Mod4 ,
 .IR Mod5 ,
 .IR Control ,
-.IR Shift ,
 or
-.IR Mod1\-Control\-Shift 
-are valid. You can combine one
-.IR Modn
-value with either
-.IR Control 
-or 
-.IR Shift
-or none. Also no modifier at all is valid syntax.
-The key value must correlate to the key symbol reported by the
+.IR Shift .
+For example, a valid modifier might be
+.IR Mod1-Control-Shift .
+It's also possible to have no modifier at all and just a key. This is still
+valid syntax. The key and modifier values must correspond to the key symbols
+reported by the
 .BR xev (1)
 utility.
 .TP 2
 rules
-This file expects a newline-separated list of rules of the form
-.BI /regexp/
-.BI \->
-.BI <tag> .
+This file expects a newline-separated list of rules, each taking the form
+.B /regexp/
+\->
+.IR <tag> ,
+where
+.I regexp
+must be a POSIX compliant regular expression as defined in
+.BR regex (7).
 See the
-.BR wmiirc
+.B wmiirc
 script for examples.
 The rules are matched against the
 .I class
 and 
 .I name
-file contents of a client whenever written. If the rule file is empty,
-.BR wmiiwm
-by default assigns the
-.IR nil
-tag to each client, thus there is also only a nil-view with an empty rule file.
-Clients who contain a tag already, except the
-.IR nil
-tag, are not matched. Rules are applied from top to bottom of these file
-contents, thus order matters. The special
-.IR ~
-tag has to be assigned in a separate rule, and which is matched always.
-It makes a matching client floating at creation or retag-time.
+file contents of a client whenever written. The order in which the rules occur
+is important since they are applied from top to bottom.
+.RS 2
+.PP
+If the rule file is empty,
+.B wmiiwm
+assigns the
+.I nil
+tag to each client by default, resulting in only the nil-view.
+Clients that contain a tag already, except the
+.I nil
+tag, are not matched.
+.PP
 The special
-.IR !
-tag inherits the currently viewed tag, if no tag has been matched so far,
-and should be defined before the last rule always.
-The last rule should define the default tag which overrides the
-.IR nil
-tag, if a different default is wished, e.g.
-.IR 1 .
-Usually the last rule tag, if a different default is wished, e.g.
-.IR 1 .
-Usually the last rule should be
-.BI /.*/
-.BI ->
-.BI <default\-tag> .
-The syntax for the regular expression must be POSIX compliant.
+.I ~
+tag makes the matched client floating at the time of creation or retag. It
+has to be assigned in a seperate rule and is always matched. The special
+.I !
+causes the matched client to inherit the currently viewed tag but only if no
+rule has yet matched. It should always be defined right before the last rule.
+If a default tag other than
+.I nil
+is desired, e.g.
+.IR 1,
+then the last rule should be defined in the following form:
+.B /.*/
+\->
+.IR <default\-tag> .
 .SH SEE ALSO
 .BR wmii (1),
 .BR wmiimenu (1),