changeset: 2591:ffde0ad06d64
tag: tip
user: Kris Maglione <kris_AT_suckless.org>
date: Thu Nov 12 19:38:31 2009 -0500
files: doc/wmii.pdf doc/wmii.tex man/wmii.1 man/wmii.man1
description:
Some doc updates.
Update issue #155.
I hope that this addresses most of your concerns.
diff -r 8b73e587b951 -r ffde0ad06d64 doc/wmii.pdf
Binary file doc/wmii.pdf has changed
diff -r 8b73e587b951 -r ffde0ad06d64 doc/wmii.tex
--- a/doc/wmii.tex Sun Nov 08 16:31:43 2009 -0500
+++ b/doc/wmii.tex Thu Nov 12 19:38:31 2009 -0500
@@ -13,7 +13,9 @@
\usepackage{xcolor}
\usepackage[xetex,breaklinks,colorlinks,linkcolor=black]{hyperref}
+% Indexes
\makeindex
+\let\primary=\textbf
\setmainfont[Mapping=tex-text, Numbers=OldStyle]{Palatino LT Std}
@@ -22,6 +24,8 @@
\def\titlebar#1{%
\begin{center}\includegraphics[width=5.5in]{#1.png}\end{center}}
+\def\man#1#2{#2\textbf{(#1)}}
+
% Key specs
\def\key#1{{\small$\langle$\addfontfeature{Numbers=Lining}#1\/$\rangle$}}
\let\<=<
@@ -52,7 +56,7 @@
% the grabbed characters, since we can't escape them in the
% verbatim environment.
\colorlet{comment}{gray}
-\colorlet{string}{yellow!80!black!100}
+\colorlet{string}{red!100!black!90}
\let\‘=‘
\let\“=“
\catcode`¶=6
@@ -603,7 +607,7 @@
There are several configuration schemes available for \wmii. If
you're only looking to add basic key bindings, status monitors,
-{\it et cetera}, you should have no trouble modifying the stock
+\emph{et cetera}, you should have no trouble modifying the stock
configuration for your language of choice. If you're looking for
deeper knowledge of \wmii's control interface though, this
section is for you. We'll proceed by building a configuration
@@ -757,6 +761,10 @@
\section{Keys}
+\label{keybindings}
+\index{key bindings}
+\index{filesystem!/!keys}
+\index{filesystem!/!event}
Now to the part you've no doubt been waiting for: binding keys.
When binding keys, you need to be aware of two files, |/keys|
and |/event|. The former defines which keys \wmii\ needs to
@@ -847,30 +855,44 @@
\section{Control Files}
-Most filesystem objects, including the root directory, have
-control files, named |ctl|. The first line of most control files
-is the canonical name of the directory they reside in, which
-comes in handy for the special |sel/| directories, which are
-aliases for the currently selected object of a group. The
-following lines represent properties of the object. Control
-files may be written to, in similar syntax to the values that
-can be read, to update those properties. For instance, if a file
-contains:
+Several directories including the root, have control files,
+named |ctl|. These files are used to control the object (e.g., a
+client or tag) represented by the directory. Each line of the
+file, with the possible section of the first, represents a
+control variable and its value. In the case of all but the root
+|/ctl| file, the first line represents the id of the directory.
+In the case of |/tag/foo/ctl|, for instance, the first line
+should read |foo|. This is useful when dealing with the special
+|sel/| directories. For instance, when |foo| is the selected
+tag, the special |/tag/sel| directory is a link to |/tag/foo|,
+and the first line of |/tag/sel/ctl| will read |foo|, just as
+if you'd accessed |/tag/foo/ctl| directly.
+
+The rest of the lines, the control variables, can be modified by
+writing new values to the control file. For instance, if a
+client is fullscreen, its control file will contain the line:
\begin{code}
Fullscreen on
\end{code}
-\noindent either of the following, when written to the file,
-will disable the |Fullscreen| state:
+\noindent To restore the client from fullscreen, either of the
+following lines may be written to its control file:
\begin{code}
Fullscreen off
Fullscreen toggle
\end{code}
+When next read, the |Fullscreen on| line will have been replaced
+with |Fullscreen off|. No care need be taken to preserve the
+other contents of the file. They're generated anew each time
+it's read.
+
\section{Clients}
+\def\clientlabel{/client/$\langle\mathit{client}\rangle$/}
+\index{filesystem!/client/*/@\clientlabel|(}
Clients are represented by directories under the |/client/|
tree. Subdirectory names represent the client's X11 window ID.
The special |sel/| directory represents the currently selected
@@ -878,6 +900,7 @@
\begin{description}
\item[ctl] The control file. The properties are:
+ \index{filesystem!/client/*/@\clientlabel!ctl}
\begin{description}
\item[Fullscreen] The client's fullscreen state. When
|on|, the client is displayed fullscreen on all of its
@@ -892,9 +915,13 @@
\item[props] The client's window class (the X11 |WM_CLASS|
property) and title string, separated by colons. This file
is not writable.
+ \index{filesystem!/client/*/@\clientlabel!props}
\item[label] The client's window title. May be written to
change the client's title.
- \item[tags] The client's tags. Tag names are separated by |+|
+ \index{filesystem!/client/*/@\clientlabel!label}
+ \item[tags]
+ \index{filesystem!/client/*/@\clientlabel!tags}
+ The client's tags. Tag names are separated by |+|
signs. Tags beginning and ending with |/| are treated as
regular expressions. If the written value begins with a |+|
or a |-|, the tags are updated rather than overwritten. Tag
@@ -905,6 +932,8 @@
|foobar|, but not the tag |foodstand|.
\end{description}
+\index{filesystem!/client/*/@\clientlabel|)}
+
\subsection{Key Bindings}
To control clients, we'll add the following key bindings:
@@ -968,76 +997,85 @@
\section{Views}
+\def\taglabel{/tag/$\langle\mathit{tag}\rangle$/}
+\index{filesystem!/tag/*/@\taglabel|(}
Views are represented by directories under the |/tag/| tree. The
special |sel/| directory represents the currently selected
client. The |sel| tag is treated similarly elsewhere. The files
in these directories are:
\begin{description}
- \item[ctl] The view's control file. The properties are:
- \item[select ‹Area›] Select the column ‹Area›, where
- ‹Area› is a 1-based column index, or |~| for the floating
- area. It may be optionally preceded by ‹Screen›|:|, where
- ‹Screen› is a 0-based Xinerama screen index, or “sel”. When
- omitted, ‹Screen› defaults to 0, the primary screen.
- \item[select ‹Area› ‹Client Index›] Select the column ‹Area›, and
- the ‹Client Index›th client.
- \item[select client ‹Client ID›] Select the client with the
- X11 window ID ‹Client ID›.
- \item[select ‹Direction›]
- Select the client in ‹Direction› where ‹Direction› may be
- one of ‹up $\wedge$ down $\wedge$ left $\wedge$ right›.
- \item[send client ‹Client ID› ‹Area›] Send ‹Client ID› to
- ‹Area›. ‹Area› may be |sel| for the selected area, and
- |client ‹Client ID›| may be |sel| for the currently selected
- client.
- \item[send client ‹Client ID› ‹Direction›]
- Send ‹Client ID› to a column or position in its column in
- the given direction.
- \item[send client ‹Client ID› toggle] If ‹Client ID› is
- floating, send it to the managed layer. If it's managed,
- send it to the floating layer.
- \item[swap client ‹Client ID› \ldots] The same as the |send|
- commands, but swap ‹Client ID› with the client at the given
- location.
- \item[colmode ‹Area› ‹Mode›] Set ‹Area›'s mode to ‹Mode›,
- where ‹Mode› is a string of values similar to tag
- specifications. Values which may be added and removed are as
- follows for managed areas:
+ \item[ctl]
+ The view's control file. The properties are:
+ \index{filesystem!/tag/*/@\taglabel!ctl|(}
+ \begin{description}
+ \item[select ‹Area›] Select the column ‹Area›, where
+ ‹Area› is a 1-based column index, or |~| for the floating
+ area. It may be optionally preceded by ‹Screen›|:|, where
+ ‹Screen› is a 0-based Xinerama screen index, or “sel”. When
+ omitted, ‹Screen› defaults to 0, the primary screen.
+ \item[select ‹Area› ‹Client Index›] Select the column ‹Area›, and
+ the ‹Client Index›th client.
+ \item[select client ‹Client ID›] Select the client with the
+ X11 window ID ‹Client ID›.
+ \item[select ‹Direction›]
+ Select the client in ‹Direction› where ‹Direction› may be
+ one of ‹up $\wedge$ down $\wedge$ left $\wedge$ right›.
+ \item[send client ‹Client ID› ‹Area›] Send ‹Client ID› to
+ ‹Area›. ‹Area› may be |sel| for the selected area, and
+ |client ‹Client ID›| may be |sel| for the currently selected
+ client.
+ \item[send client ‹Client ID› ‹Direction›]
+ Send ‹Client ID› to a column or position in its column in
+ the given direction.
+ \item[send client ‹Client ID› toggle] If ‹Client ID› is
+ floating, send it to the managed layer. If it's managed,
+ send it to the floating layer.
+ \item[swap client ‹Client ID› \ldots] The same as the |send|
+ commands, but swap ‹Client ID› with the client at the given
+ location.
+ \item[colmode ‹Area› ‹Mode›] Set ‹Area›'s mode to ‹Mode›,
+ where ‹Mode› is a string of values similar to tag
+ specifications. Values which may be added and removed are as
+ follows for managed areas:
- \begin{description}
- \item[stack] One and only one client in the area is
- uncollapsed at any given time. When a new client is
- selected, it is uncollapsed and the previously selected
- client is collapsed.
- \item[max] Collapsed clients are hidden from view
- entirely. Uncollapsed clients display an indicator
- {\it‹n›/‹m›}, where ‹m› is the number of collapsed
- clients directly above and below the client, plus one,
- and ‹n› is the client's index in the stack.
- \item[default] Like subtracting the stack mode, but all
- clients in the column are given equal height.
- \end{description}
+ \begin{description}
+ \item[stack] One and only one client in the area is
+ uncollapsed at any given time. When a new client is
+ selected, it is uncollapsed and the previously selected
+ client is collapsed.
+ \item[max] Collapsed clients are hidden from view
+ entirely. Uncollapsed clients display an indicator
+ {\it‹n›/‹m›}, where ‹m› is the number of collapsed
+ clients directly above and below the client, plus one,
+ and ‹n› is the client's index in the stack.
+ \item[default] Like subtracting the stack mode, but all
+ clients in the column are given equal height.
+ \end{description}
- For the floating area, the values are the same, except that
- in |max| mode, floating clients are hidden when the managed
- layer is selected.
- \item[grow ‹Frame› ‹Direction› {[‹Amount›]}] Grow ‹Frame› in
- the given direction, by ‹Amount›. ‹Amount› may be any
- integer, positive or negative. If suffixed with |px|,
- it specifies an exact pixel amount, otherwise it specifies a
- “reasonable increment”. Defaults to 1.
+ For the floating area, the values are the same, except that
+ in |max| mode, floating clients are hidden when the managed
+ layer is selected.
+ \item[grow ‹Frame› ‹Direction› {[‹Amount›]}] Grow ‹Frame› in
+ the given direction, by ‹Amount›. ‹Amount› may be any
+ integer, positive or negative. If suffixed with |px|,
+ it specifies an exact pixel amount, otherwise it specifies a
+ “reasonable increment”. Defaults to 1.
- ‹Frame› may be one of:
- \begin{itemize}
- \item client ‹Client ID›
- \item ‹Area› ‹Client Index›
- \end{itemize}
- \item[nudge ‹Frame› ‹Direction› {[‹Amount›]}] Like
- |grow|, but move the client in ‹Direction› instead of
- resizing it.
+ ‹Frame› may be one of:
+ \begin{itemize}
+ \item client ‹Client ID›
+ \item ‹Area› ‹Client Index›
+ \end{itemize}
+ \item[nudge ‹Frame› ‹Direction› {[‹Amount›]}] Like
+ |grow|, but move the client in ‹Direction› instead of
+ resizing it.
+ \end{description}
+ \index{filesystem!/tag/*/@\taglabel!ctl|)}
\end{description}
+\index{filesystem!/tag/*/@\taglabel|)}
+
\subsection{Key Bindings}
We'll use the following key bindings to interact with views:
@@ -1112,8 +1150,10 @@
The root filesystem contains the following:
+\index{!filesystem!/|(}
\begin{description}
\item[ctl] The control file. The properties are:
+ \index{filesystem!/!ctl}
\begin{description}
\item[bar on ‹top $\wedge$ bottom›] Controls where the bar
is shown.
@@ -1128,7 +1168,16 @@
clients and the default color of bar buttons.
\item[font ‹Font›] The font used throughout \wmii. If
prefixed with |xft:|, the Xft font renderer is used, and
- fonts may be antialiased.
+ fonts may be antialiased. Xft font names follow the
+ fontconfig formula. For instance, 10pt, italic Lucida
+ Sans would be specified as
+
+ \begin{code}
+ xft:Lucida Sans-10:italic
+ \end{code}
+
+ See \man 1 {fc-match}.
+
\item[grabmod ‹Modifier Keys›] The key which must be
pressed to move and resize windows with the mouse
without clicking hot spots.
@@ -1157,8 +1206,46 @@
searched for the executable. Otherwise, the whole
argument is passed to the shell for evaluation.
\end{description}
+ \item[keys] The global keybindings. See section \ref{keybindings}.
+ \index{filesystem!/!keys|primary}
+ \item[event] The global event feed. See section \ref{keybindings}.
+ \index{filesystem!/!event|primary}
+ \item[colrules]
+ \index{filesystem!/!colrules}
+ The |/colrules| file contains a list of
+ rules which affect the width of newly created columns.
+ Rules have the form:
+
+ \begin{quote}\texttt{
+ /‹regex›/ -> ‹width›{\color{gray}[}+‹width›{\color{gray}]*}}
+ \end{quote}
+
+ When a new column, ‹n›, is created on a view whose
+ name matches ‹regex›, the ‹n›th given
+ ‹width› percentage of the screen is given to it. If
+ there is no ‹n›th width, $1/\mbox{‹ncol›th}$ of the
+ screen is given to it.
+
+ \item[tagrules]
+ \index{filesystem!/!tagrules}
+ The |/tagrules| file contains a list of
+ rules similar to the colrules. These rules specify
+ the tags a client is to be given when it is created.
+ Rules are specified:
+
+ \begin{quote}\texttt{
+ /‹regex›/ -> ‹tag›{\color{gray}[}+‹tag›{\color{gray}]*}}
+ \end{quote}
+
+ When a client's ‹name›:‹class›:‹title› matches
+ ‹regex›, it is given the tagstring ‹tag›. There are
+ two special tags. |!|, which is deprecated, and identical
+ to |sel|, represents the current tag. |~|
+ represents the floating layer.
\end{description}
+\index{!filesystem!/|)}
+
\subsection{Configuration}
We'll need to let \wmii\ know about our previously defined theme
diff -r 8b73e587b951 -r ffde0ad06d64 man/wmii.1
--- a/man/wmii.1 Sun Nov 08 16:31:43 2009 -0500
+++ b/man/wmii.1 Thu Nov 12 19:38:31 2009 -0500
@@ -329,8 +329,10 @@
A left or right bar has been clicked or has a
button pressed over it.
.TP
-...
-To be continued...
+
+
+For a more comprehensive list of available events, see
+\fIwmii.pdf\fR\fI[2]\fR
.RS -8
.TP
@@ -565,6 +567,7 @@
.P
\fI[1]\fR http://www.suckless.org/wiki/wmii/tips/9p_tips
+\fI[2]\fR @DOCDIR@/wmii.pdf
.\" man code generated by txt2tags 2.5 (http://txt2tags.sf.net)
diff -r 8b73e587b951 -r ffde0ad06d64 man/wmii.man1
--- a/man/wmii.man1 Sun Nov 08 16:31:43 2009 -0500
+++ b/man/wmii.man1 Thu Nov 12 19:38:31 2009 -0500
@@ -250,7 +250,7 @@
screen is given to it.
: tagrules
- The //tagrules// file contains a list of
+ The _tagrules_ file contains a list of
rules similar to the colrules. These rules specify
the tags a client is to be given when it is created.
Rules are specified:
@@ -289,10 +289,10 @@
: [Left|Right]Bar[Click|MouseDown] <button> <bar>
A left or right bar has been clicked or has a
button pressed over it.
- : ...
- To be continued...
- :
+ :
<<
+ For a more comprehensive list of available events, see
+ _wmii.pdf_[2]
: ctl
The _ctl_ file takes a number of messages to
@@ -473,4 +473,5 @@
@DOCDIR@/wmii.pdf
[1] http://www.suckless.org/wiki/wmii/tips/9p_tips
+[2] @DOCDIR@/wmii.pdf
Received on Fri Nov 13 2009 - 00:42:59 UTC
This archive was generated by hypermail 2.2.0 : Fri Nov 13 2009 - 00:48:05 UTC