I reviewed the guide from the tip and fixed up some of the English grammar. I tried not to change the flavor of what you said at all. Hope it's useful to you.
-Ross
%guide to wmii-3 %Copyright (C) 2005, 2006 by Steffen Liebergeld, Salva Peir\'o
%This program is free software; you can redistribute it and/or
%modify it under the terms of the GNU General Public License
%as published by the Free Software Foundation, version 2
%This program is distributed in the hope that it will be useful,
%but WITHOUT ANY WARRANTY; without even the implied warranty of
%MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
%GNU General Public License for more details.
%You should have received a copy of the GNU General Public License
%along with this program; if not, write to the Free Software
%Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
%02110-1301, USA.
\documentclass[12pt,a4paper]{article} %options given to article are inherited to all packages
\usepackage[latin1]{inputenc}
\usepackage[left=3cm,top=2cm,right=2cm,bottom=3cm]{geometry}
\usepackage{times}
\usepackage{hyperref} % option [dvipdfm] disables clickable refs
\hypersetup{pdftex, colorlinks=true, linkcolor=blue, filecolor=blue,
pagecolor=blue, urlcolor=blue, pdfauthor={Steffen Liebergeld, Salva Pei\'ro},
pdftitle={A Guide to wmii--3}}
\usepackage{indentfirst,moreverb}
% remove this if you want, it's just a matter of imposed imperialist cultures
% so if I'm given the chance to choose I choose to indent the first paragraph
% (I learn this way in the school, and don't want to relearn the british way)
%% welcome to the dirty tricks section
\newcommand{\hrefx}[1]{\href{#1}{#1}} % explicit \href
% un'% below so latex2html can handle refs correctly (until a better solution is found)
%\usepackage{html} % gives clickable refs to latex2html
%\renewcommand{\href}[2]{\htmladdnormallink{#2}{#1}}
%\renewcommand{\hrefx}[1]{\htmladdnormallink{#1}{#1}}
%\renewcommand{\verbatiminput}[1]{\input{#1}}
\renewcommand{\familydefault}{\sfdefault}
\newenvironment{itemize*}
{\begin{itemize}
\setlength{\itemsep}{0pt}
\setlength{\parskip}{0pt}}
{\end{itemize}}
\date{\today}
\author{
Steffen\\Liebergeld \\\\
\small{with help from}\\
Salvador\\Peir\'o
}
\title{A Guide to wmii--3%
\thanks{Thanks to the wmii community, in particular all the
people mentioned at \href{http://wmii.de/index.php/WMII/People}{WMII/people}.}
}
[EMAIL PROTECTED] \and [EMAIL PROTECTED]
\begin{document}
\maketitle
\tableofcontents
\newpage
\section{Abstract}
\subsection{The purpose of this document}
This document tries to be a good starting point for people new to
wmii--3. People who have used wmi, wmii--2.5 or even ion will get
to know what is new and different in wmii--3, and people who have
never used a tiling window manager before will fall in love with
the new concept.
\subsection{Wmii --- the second generation of window manager improved}
Wmii--3 is a new kind of window manager. It is designed to have a
small memory footprint, be extremely modularised and have as
little code as possible, thus ensuring as few bugs as possible. In
fact, one of our official goal is to not to exceed $10 k$ lines of
code~\footnote{
benefits of the $10 k$ SLOC restriction are that it's easier
to read/understand, thus it's easier to use and get used to.}.
Wmii tries to be very portable and to give the user as much
freedom as possible.
Wmii--3 is the third major release of the second generation of the
window manager improved~\footnote{ the ii is actually the roman
numeral for 2.}. Wmii first introduced a new paradigm
in version 2.5, namely the dynamic window management, that
overcomes the limitations imposed by the WIMP paradigm (see also
the companion \emph{wmii.tex}).
\subsection{Target audience}
I presume the reader already has experience with Unix, knows all
the basic terminology and concepts like files and editors.
I hope you are open minded to new ideas, and willing to spend
some time learning wmii-3~\footnote{remember the refrain: ``nobody can
teach you what you don't want to know''.}.
If you only want to know how to operate wmii-3 and are not
interested in the inner workings or in scripting, you may read
sections \ref{sec:conf&install}, \ref{sec:terms} and subsection
\ref{subsec:firststeps} and skip the rest.
However, to get the most out of wmii--3 you should probably read
the whole document. Another possibility is to read the
introductory chapters first, spend some time to getting settled into the
wmii--world and read the scripting chapters later on.
\section{Configuration and install}
\label{sec:conf&install}
\subsection{Obtaining wmii}
Wmii is licensed under the MIT/X Consortium License, which
basically means it is free software, and you are free to download
from \hrefx{http://wmii.de} free of charge~\footnote{ please have
a look at \hrefx{http://wmii.de/repos/wmii/LICENSE} for
details}.
\subsection{Configuration and Installation}
First of all, have a look if there are binary packages of wmii in
your distribution. Debian, Ubuntu and Gentoo should already have
good packages. If you found a package to trust, you may now safely
skip this section.
For all those who are still reading this, let me tell you that you are
on the good side because if you grab the sources and compile them yourself
you'll benefit from having everything in it's original place, so
it'll ease your use of wmii.
\begin{enumerate}
\item Uninstalling a previous version:
\begin{verbatim}
cd /path/to/wmii-previous
make uninstall && make clean
\end{verbatim}
In case you're installing a newer version of wmii, this is the
first thing you should do otherwise you'll end up mixing
binaries, configuration files and manual--pages of different and
thus incompatible versions, to do this run the above commands.
\item Unpack it:
\begin{verbatim}
tar xzf wmii-3.tar.gz
cd wmii-3
\end{verbatim}
\item Edit the configuration:
\begin{verbatim}
vim config.mk
\end{verbatim}
The most important variable to set is the \verb+PREFIX+, which
states where you want wmii--3 to be installed to.
\item Run make and make install:
\begin{verbatim}
make && make install
\end{verbatim}
\item Instruct the X--server to start wmii as your default window
manager. You may do that by editing the file \emph{\~{}/.xinitrc}.
\begin{verbatim}
#!/bin/sh
exec wmii
\end{verbatim}
Make sure that the \emph{\~{}/.xinitrc} is executable:
\begin{verbatim}
chmod u+x ~/.xinitrc
\end{verbatim}
\end{enumerate}
And you are finished. Please note that we do not use the autoconf
tools for various reasons, you can read about it here~\footnote{
\hrefx{http://www.ohse.de/uwe/articles/aal.html} and
\hrefx{http://lists.cse.psu.edu/archives/9fans/2003-November/029714.html}
} . Please don't ask us to use autoconf, we won't do it.
\section{Terminology}
\label{sec:terms}
Before you actually start doing your first steps in wmii, we have to
make sure we are both talking about the same things. So here is some
terminology.
\subsection{Clients}
A client is a program, that draws a window to the
screen~\footnote{ Actually it is the program that requests the
X--server to draw the window. But never mind;-)}. For example your
browser or your xterm is a client.
\subsection{Focus}
In X11, exactly one client gets the user's input. If you write some
command in your xterm, this xterm has the focus, whereas all the
other windows do not receive/react on the input you
give~\footnote{ Actually this is not precise at all, because some
programs catch input before it is sent to the focused client. But
you do not need to care about this.}. We will say, from now on,
that the xterm has the focus.
\subsection{Events}
Events are generated by your input. For example when you click
into a window, that is an event. Events are used, for example, to
interact with the window manager. You will see how this works
later on.
\subsection{Tags}
Tags are names/labels that you can give to clients to allow you to
visually group them. In wmii, there are no workspaces anymore. Instead,
wmii simply shows only one tag at one time. Thus, if you name a
client ``web-browser'' and request the wm to only show the tag
``web-browser'', you will only see that one client. If you tag a
xterm with the same tag, it will also be shown, when your first
client with the tag ``web-browser'' is visible. It is also possible
to give clients multiple tags, but more on this later.
\subsection{View}
The view concept refers to the tags that you want to view at a
given time, so when you request the window manager to only show
windows with one particular tag, you may call this a view. You
might imagine, that this somehow resembles the ``workspace'' of
other window managers.
You might have different views with only one of them visible at a
particular time. Thus, the concept of ``view'' is completely
virtual.
Views are defined by the tags only, so if you don't have a tag of
a particular name, you don't have a view of that name. Similarly,
if you destroy the last client with one tag, the view with the
same name also gets destroyed.
\subsection{Column}
In wmii, you are able to divide each view into different columns,
which are distinct parts of the screen, divided by an invisible
line between each other. You should be aware, that every column
holds at least one client. As soon as you close the last client of
a column, the column will be destroyed.
Please be aware, that every view has at least one column.
\subsection{Layout}
You may order clients in a column in three different ways. The
first, which is also the default, is to give each window an equal
amount of vertical space in a column. The second is to have each client
maximised in the column, showing only one of them at a time, while
hiding the others. And last but not least you may have the clients
stacked, which means to have one client use as much space as
possible and to show only the title--bars of the other windows.
\section{Getting started}
It is now time to start diving into the wmii user experience. I
suggest that you try the things I describe yourself immediately
instead of first reading it, forgetting half of it and then trying
to start. It is very helpful if you have this document printed out
or have it on a different machine, since you won't be able to view
it during your first steps in wmii.
On a special note, the \emph{MOD} key I am referring to may resemble
different keys on different platforms. It is what X knows as the
\emph{Mod1} or \emph{Alt} key. Probably this is the key labelled with
\emph{Alt} at the left of the space--bar on your keyboard.
The notation \emph{MOD}--\emph{Key} means to press \emph{MOD}, hold
it and to press \emph{Key}.
All key combinations may be freely configured, but for the sake of
simplicity I'll stick with the default bindings for this
introduction. You can find out how to alter the bindings in the
section \ref{sec:scripting}.
\subsection{First steps}
\label{subsec:firststeps}
You may now start your X session. Since it is the first time you
start wmii, a window with a little tutorial will show up. You are
free to read it, but you may also follow the beginners guide :-)
First of all, press \emph{MOD--Enter} to start an xterm. It will
take half of the vertical space, so you now have two equally big
windows. If you press \emph{MOD--Enter} again, you have three
windows that are equally big.
To switch between the three windows, you may now press
\emph{MOD--j}, which cycles the focus between the three windows.
You may also press \emph{MOD--k} to switch to the window above or
\emph{MOD--j} to switch to the window below the current.
Now have a look at the title--bars of those windows. They show some
important information: the first term is the name of the tag of
the window. The following term shows the title of the window.
The same information is also shown on the menu--bar. The first
things are names of the different tags you gave to your windows,
with the current view highlighted. On the right side it shows some
system status information like the load and the current time
(see subsection~\ref{subsec:status} for details).
\subsection{Using columns}
As you know wmii uses columns to align your windows. Even now,
though you don't really see it, your view already consists of one
maximised column. The next step is to create a new column.
In wmii columns are defined by their clients. Thus you need a client
to create a new column. That is why you may now focus a client of
your choice and press \emph{MOD--Shift--l}. As you see, wmii created
a new column by dividing the view horizontally into two equally big
spaces. The last focused client has been put into the new column.
If you close the last window of a column, the column will vanish
immediately. And when the last column is gone, the view will be
removed accordingly.
It should be clear, that you really need at least two clients to
have two columns.
If you press \emph{MOD--j} to change focus, you will see that wmii
actually cycles the focus in the current column only. That is why
you need commands to change the current column.
In wmii you may use \emph{MOD--l} to change to the column on the
right and \emph{MOD--h} to change to the column on the left.
It is also possible to make a client swap columns. To move a
client to the column on the left, press \emph{MOD--Control--h} and
to move it to the right column, press \emph{MOD--Control--l}.
\subsection{What about layouts?}
Layouts are different methods of how to align windows in a
column. They apply only to one column each. Thus it is possible to
have different columns in one view, each having a different layout.
The default layout is to give each client in the column an equal
amount of vertical space. You may enable this layout with \emph{MOD--d}
(where the ``d'' stands for default).
Another layout is the stacked layout. You enable stacking by
\emph{MOD--s}. As you see now, there in only one client using as
much space as possible, whereas you only see the title--bars of the
other clients in the column. You may still switch between the
clients in the column using \emph{MOD--j}.
The third layout is the max-layout, which maximises all the
clients to each use all the space in the column. Only the focused
client is visible and the others are hidden behind. You may still
switch between those clients with \emph{MOD--j}.
\subsection{Float pages}
You may have asked yourself how classical clients, consisting of
multiple windows fit into the picture.
Well, they don't. But wmii has a solution to make them usable
nevertheless. For clients like the Gimp or xmms there is a special
mode, which has completely different semantics.
While wmii is a dynamic window manager, which really takes all the
work of positioning and aligning clients from you, those old
fashioned programs rely on the old window managing concept, where
all the clients fly around on the desktop and the user has to tell
them where to stay. We have the term floating windows for this
rule.
To come to the point: wmii also allows you to use floating
clients. You may toggle your focus between floating and column
modes by pressing \emph{MOD--Space}. While \emph{MOD--Shift--Space}
toggles the focused window between floating and column modes .
As a side note, this floating mode is actually the zeroth column
internally. That is why there is not much special internal
handling needed.
\subsection{Tags}
Up to now all your clients had the tag ``1'', and you only had
this one view. It is obvious that having only one view might
become a problem if there are too many clients cluttering it and
making it a pure mess. Also you might want to have a view with
your editor and your programming tools and another with your
browser and a third with your music jukebox.
The good news is, that with the concept of tags and views this is
actually possible.
You may give the focused client another tag by pressing
\emph{MOD--Shift--Number}, number being one of the numbers 0 to 9.
You can then switch views by pressing \emph{MOD--Number}.
Whenever a new client is created, it automatically gets the tag of
the current view.
%% TODO: better tag handling (this is about to change in wmii till
%%version 3)
For the moment I'll just tell you that there are further
possibilities with tags, but they are mostly accessible with
advanced techniques you will learn in the next chapter. You will
then be able to assign multiple tags to one client and to use
proper strings as tags.
\subsection{How do I close a window?}
Well, first of all every X-client should have an option to close a
window. But --as Murphy said-- the world isn't like it should
be. Thus, the window manager has to provide a fix for this. In
wmii, we abandoned silly title-bar buttons and created a shortcut
\emph{MOD--Shift--c} to close a window.
\subsection{How do I start programs?}
You may start programs out of an xterm. But in wmii, there is a
special program launcher, which is accessible via
\emph{MOD--p}. Please note, that the logic behind this program
launcher is mainly implemented in a shell--script.
You will see a list of programs. If you now start to type, the
launcher will cut that list to only show programs whose names
include the letters you typed (in that order). Whenever there is
only one option left, the launcher chooses it and you can start it
by pressing \emph{Enter}. You are free to cancel any action by
pressing \emph{ESC}.
Thus, if you want to start firefox, just type ``fire'' and press
enter~\footnote{On my system it is sufficient to type ``efo'' to
start firefox;-)}.
\subsection{How do I quit wmii?}
You may quit wmii by using the action's menu (\emph{MOD--a})
and selecting the action ``quit'. That's all.
\section{Looking under the hood}
In this chapter you will learn how wmii was designed, which ideas
the wmii developers followed and how it was implemented.
\subsection{Dynamic window management}
Wmii was designed around the new idea of dynamic window
management. Dynamic window management means, that the window
manager should make all the decisions about where to place a new
client itself, thus taking all the extra work from the user and
letting him concentrate on his work.
\subsection{Modularity -- using distinct tools for distinct tasks}
The developers of wmii know about the most powerful ideas of
Unix. One of them is the idea to use distinct tools for distinct
tasks. By carefully designing the window manager, we were able to
split the task into two smaller binaries, each with a distinct
job.
\subsection{The glue that puts it all together -- 9P}
Programs in Unix have several different possibilities to exchange
information, the most powerful being sockets.
To create a lightweight but powerful communication protocol, we
looked closely at the design of Plan9 and chose the 9P2000
protocol.
The basic ideas for configuring and running wmii were taken from
Plan9 too. Like in Plan9, everything configurable in wmii has a
file--like interface, so everything is accessed consistently Thus,
if you want to interact with a running wmii, you may access those
files either using the shipped tool \emph{wmiir} or -- if you use
9P2000 -- you may also mount the virtual file--system of wmii under
some directory in the hierarchy maintained by the OS kernel.
\subsection{Tools}
This section gives a little overview of the tools that come wmii,
but for more detailed explanations you should read the man page of
each tool that comes with wmii.
\begin{description}
\item
\emph{wmiir} is a little tool we use to alter the files in the
virtual file--system of wmii. It basically has four operations:
\begin{itemize*}
\item read
\item write
\item remove
\item create
\end{itemize*}
Wmiir needs to know the address of the file-system to work
on, so on startup wmii sets the environment variable
\verb+WMII_ADDRESS+ to make sure any tool wanting to
communicate with wmiiwm know it's file--system address.
This address can be:
\begin{itemize*}
\item a local unix address given with \verb+unix!/path/to/socket+
\item a tcp address given with \verb+tcp!hostname:port+
\end{itemize*}
If you want to work on another file--system, you may specify it
manually with the switch \emph{-a address}. A sample invocation
would look like the following:
\begin{verbatim}
wmiir read /
\end{verbatim}
This command actually prints the root of the virtual file-system
of wmii.
\item
\emph{wmiimenu} is a generic X11 menu. It is highly adaptable,
efficient and supports user-defined contents. You may want to
learn more about it by reading the man-page.
\item
\emph{wmiiwarp} is a little tool to position the mouse pointer to
different places. It only takes two coordinates as arguments.
\item
\emph{wmiiwm} is the main window manager binary. You may interact
with its virtual file-system only.
\item
\emph{wmiipsel} prints the contents of the X clipboard to
STDOUT. This is useful for scripts.
\end{description}
\subsection{Conclusion}
By having the virtual file-system and a lightweight protocol to
fit our tools together, we are now able to fully script our window
manager. You will see some examples in the section
\ref{sec:scripting}.
\section{Scripting wmii}
\label{sec:scripting}
In this chapter you will see how to script wmii. I will give you
some notes so you can start scripting on your own.
\subsection{Language}
As you've seen the only requirement for interacting with wmii is
to do operations on wmii's file-system hierarchy, and the easiest
way to do this need is by using wmiir, so shell scripting is the
easiest way of adapting wmii too fit your needs.
Given the above, you may script wmii in any programming language
you want. However, wmii's default scripts are written in a subset
of ``sh'' that is POSIX compliant so wmii is \emph{portable}. As
we don't need more complexity and wanted to give examples that
worked everywhere without dependencies on python, tcl, ruby, \dots
thus the following examples will stick with the well known ``sh''.
% - who doesn't have a shell?, extra! we're giving them for free this week
\subsection{Actions}
In wmii you may group certain tasks into \emph{actions}. Actions
are nothing more than simple scripts which are located either in
your local or in the default wmii configuration
directory~\footnote{ \texttt{\$CONFPREFIX} is set in
\emph{config.mk} and by default points to \texttt{/usr/local/etc}
or \texttt{\~{}/.wmii-3} if you have such a directory}.
By pressing \emph{MOD-a} you can open the actions-menu. It works
similar to the program launcher, but only shows actions.
You might want to add your own actions by writing shell scripts
and putting them into the right directory. For this you should
place a copy of the default action from the default wmii
configuration directory to your \texttt{\~{}/.wmii-3}, this way
your local copy will be executed instead.
This works because in the \emph{wmii} launcher script alters and
exports the variable \verb+$PATH+ as\\
\verb+$PATH=~/.wmii-3:$CONFPREFIX/wmii:$PATH+ before
launching the wmiiwm, this way local user actions under
\verb+~/.wmii-3+ take precedence over the defaults from
\verb+$CONFPREFIX/wmii+ of the default actions.
You may edit this file on the fly, which means you don't need to
stop wmii before editing. After you've finished editing, you may
simply run wmiirc and the changes will take effect. To do so just
open the actions menu (via \emph{MOD-a}) and choose wmiirc as the
\emph{action}. It's also possible to launch wmii actions directly
from an xterm (or similar terminal emulator program), this is a nice
side effect that results from exporting \verb+$PATH+ in the wmii
startup script.
\subsection{wmiirc}
\emph{wmiirc} is a special ``sh''-script which is run on startup
of wmii. It's name is the result of ${}wmiirc=wmii+rc$~\footnote{
see \hrefx{http://en.wikipedia.org/wiki/Rc}.} , so as it's name
says it takes care of running a set of commands for configuring
wmii. It does so by setting up the initial file-system, writing
some values to certain files and then enters the handling event
loop to react on events like key-presses, mouse clicks or
artificial events.
For the basic configuration of wmii, such as changing the default
modifier key \emph{MOD=Mod1} or the navigation keys (by default
the \emph{hjkl} vim home row) this is the place to look.
\subsection{Changing the looks}
The look of wmii-3 is determined by colours and font only. And because we
wanted small and unimportant things to be as unobstrusive as
possible, we used another virtue of unix: \emph{Environment
variables}.
\begin{verbatim}
WMII_SELCOLORS='#000000 #eaffff #8888cc'
WMII_NORMCOLORS='#000000 #ffffea #bdb76b'
WMII_FONT=static
\end{verbatim}
\verb+WMII_SELCOLORS+ define the colours of the selected clients
window title and border, whereas \verb+WMII_NORMCOLORS+ defines
the colours of all the other clients. The numbers are hexadecimal
rgb, which you might know from HTML. You might get them with the
Gimp's colour-chooser.
The definitions are as follows: the first number is the colour of the
text in bars and menus. The second is the main colour of bar
borders, whereas the third defines the borders and is used for the
3D-effects of title-bars and menus.
\verb+WMII_FONT+ accepts font names or full font strings, which
you might get from xfontsel. It defines the font to be used in
titlebars, status-bar and in wmiimenu.
\subsection{Filling the status-bar}
\label{subsec:status}
The status bar of wmii has it's own directory \verb+/bar+ with
one subdirectory for each of the labels created. So while editing
this document my status-bar looked like:
\begin{verbatim}
$ wmiir read /bar
d-r-x------ salva salva 0 Mon Apr 17 14:19:51 2006 1
d-r-x------ salva salva 0 Mon Apr 17 14:19:51 2006 2
d-r-x------ salva salva 0 Mon Apr 17 14:19:51 2006 status
\end{verbatim}
At the same time each of the subdirectories contains two files,
\begin{verbatim}
$ wmiir read /bar/status
--rw------- salva salva 23 Mon Apr 17 14:22:14 2006 colors
--rw------- salva salva 23 Mon Apr 17 14:22:14 2006 data
\end{verbatim}
The first file contains the colour definitions that control how the
bar will be painted (appearance), while the second holds the data
to show (content).
So you can start your own experiments by creating a new label, and
exploring and modifying it by reading \& writing values to it's
\verb+colors+ \& \verb+data+ files. A nice feature of the bar
(and clients) is that they generate events corresponding to mouse
clicks on them. So you can open a terminal and launch
\verb+wmiir read /event+ and and see how the events are generated
when you click the bar, this is a mechanism that allows
controlling applications directly from the bar, when you've
finished, and don't need the \verb+foo+ label anymore, just issue
a \verb+wmiir remove /bar/foo+.
If you want to know more take a look at the status script and have
a look at the pages at \hrefx{http://wmii.de} for good examples,
like the following:
\begin{itemize*}
\item \emph{status}: monitoring remaining battery, temperature, \dots on laptops
\item \emph{status-mpd}: controlling the running mpd
\item \emph{status-load}: show the machine load
\item \emph{status-net}: monitoring wireless network signal
\end{itemize*}
And last read the default status script and ask yourself: what
does it do? \verbatiminput{../rc/status} The first line is a
\verb+xwrite+ function declaration, to save us from typing a lot
by issuing a write over the file named by the first argument. The
following 3 lines take care of creating and setting up the
\verb+status+ label. And the last section is a \verb+while+ loop
that \emph{tries} to write the machine's load and date information
to the bar.\\
The tricky bit here is \emph{tries}, so what could make the write
fail? If \verb+xwrite+ tried to write to a non existent (removed)
label, then it would fail, thus the condition of the loop would be
false, and the status script would end cleanly, which makes sense
because who wants a program that updates a nonexistent label.\\
Now if we go back to the first lines of the script you can see
that there is a \verb+sleep delay+ between the removal of the
label and it's creation.
This ensures that the \verb+status+ label will not exist, so all
the writes made from a any previously running \verb+status+ script
to it will fail, so they will finish. This way we make sure that
we only run one at each time. And thus we keep the one-to-one
correspondence between label and status script.\\
Now if you think that was neat, go to a public library and pick up
a copy of for example: \href{http://tpop.awl.com}{The Practice of
Programming} (recall I don't get a cent for this).
\subsection{Assigning new tags}
As I told you before, you can do many more things with tags than
what you can do with the standard key-bindings. You might use any
string as a tag. You may even use more than one tag per client. To
do so, you have to separate the tags with a ``+''.
\begin{verbatim}
echo -n web+code | wmiir write /view/sel/sel/tags
\end{verbatim}
This command would give the current focused client the tags
``web'' and ``code''.
You may now go to the new view web by executing the following:
\begin{verbatim}
echo -n view web | wmiir write /ctl
\end{verbatim}
As the development of wmii-3 progressed, it became clear that this
action is so common, that it got its own keybinding. By default
\emph{MOD-t} brings up a menu to choose a view and
\emph{MOD-Shift-t} brings up a menu enabling you to assign new
tags to the focused client.
\section{The End}
\label{sec:end}
We hope this has eased your way through wmii, because this is the
purpose of this document and so, if you've seen something that you
think is wrong, confusing or missing in this document, feel free
to drop us a note:
Contact information is to be found here:
\href{http://wmii.de/index.php/BeginnersGuide}{direct mail},
\href{http://wmii.de/index.php/MailingList}{[wmii]} mailing-list,
\href{http://wmii.de/index.php/IRC}{\#wmii} irc channel or even
with smoke signals~\footnote{ but don't ask us for advice, here
you're on your own \texttt{;-P}.}.
Also remember that wmii is written by people with taste, so most
of the decisions made have strong reasons supporting them, so if
you think something doesn't make sense or doesn't fit into the
picture, just try to understand it by yourself first before
asking, probably you'll end up learning a lot and if its really
wrong in the end, you'll provide us with much better feedback to
solve the issue.
\newpage
\section{Appendix}
\label{sec:appendix}
\subsection{filesystem}
\begin{description}
\item [/bar]
\begin{itemize*}
\item the bar namespace
\item to add a label, create /bar/\verb+label+ (this automatically creates the
\verb+colors+ and \verb+data+ files.
\item to delete it, remove /bar/\verb+label+
\end{itemize*}
\item [/bar/label]
\begin{itemize*}
\item each bar has it's own namespace which is named according to it's
label
\item label can be any arbitrary string
\end{itemize*}
\item [/bar/label/data]
\begin{itemize*}
\item the data written to the label \verb+label+
\end{itemize*}
\item [/bar/label/colors]
\begin{itemize*}
\item the colours of the bar
\end{itemize*}
\item [/clients]
\begin{itemize*}
\item the clients namespace
\end{itemize*}
\item [/clients/n]
\begin{itemize*}
\item every client, including ones not shown in the view has a namespace here
\item \verb+n+ is a non-negative interger and clients are numbered oldest first
\end{itemize*}
\item [/clients/n/class]
\begin{itemize*}
\item a file containing the class:instance information for client \verb+n+
\end{itemize*}
\item [/clients/n/ctl]
\begin{itemize*}
\item control file for client \verb+n+
\item accepted commands:
\begin{itemize*}
\item kill (removes client)
\item sendto \verb+area|prev|next|new+
\item swap \verb+up|down|prev|next+
\end{itemize*}
\end{itemize*}
\item [/clients/n/geom]
\begin{itemize*}
\item the window geometry of client \verb+n+
\item displayed as four blank seperated integers (x y width height?)
\end{itemize*}
\item [/clients/n/name]
\begin{itemize*}
\item the name of client \verb+n+ as it's seen by wmii (displayed in the tagbar)
\end{itemize*}
\item [/clients/n/tags]
\begin{itemize*}
\item a plus(+)-seperated list of tags to which client \verb+n+ is related
\end{itemize*}
\item [/ctl]
\begin{itemize*}
\item the wmii control file and command interface
\item accepted commands:
\begin{itemize*}
\item quit
\item retag
\item view \verb+tag+
\end{itemize*}
\end{itemize*}
\item [/def]
\item [/def/border] width of the border around clients
\item [/def/font] the font used by wmii (an xlib font name)
\item [/def/keys] a newline seperated list of the keys to be watched by wmii
\item [/def/rules]
\begin{itemize*}
\item a newline seperated list of rules to specify how to automatically tag clients
\item matches against the class.instance valuas of a client
\item syntax: \verb+/$regex/ -> $tag+ (tag might be \~{} to indicate floating mode
\end{itemize*}
\item [/view]
\begin{itemize*}
\item a manifestation of the collection of clients associated with a specifiy
tag or tags
\end{itemize*}
\item [/view/area]
\begin{itemize*}
\item each area has its own namespace in the current view
\item the areas are numbered starting with 0
\item 0 is always the floating area, the others are columns
\end{itemize*}
\item [/view/area/ctl]
\begin{itemize*}
\item accepted commands:
\begin{itemize*}
\item select \verb+client|prev|next+
\item client refers to the client number relative to the number and
age of the clients in \verb+area+
\end{itemize*}
\end{itemize*}
\item [/view/area/mode] the current layout for the area, equal, stack or max
\item [/view/area/sel] the selected client of the area
\item [/view/area/client] the namespace for each client in \verb+area+
\item [/view/ctl] accepted commands: select \verb+area|prev|next|toggle+
\item [/view/sel] the selected area in workspace
\item [/view/tag] the tag which is common to all clients in the workspace
\end{description}
\newpage
\subsection{keybindings}
Here are the default keybindings. \verb+$MODKEY+ is a placeholder, which is
usually mapped to Mod1 or Alt.
\begin{table}[h]
\begin{tabular}{|l|l|}
\hline % Puts in a horizontal line
Keybinding &Action \\ %Table Headers , columns seperated by &,
%rows ended by \\
\hline
\hline
Moving Focus&\\
\verb+$MODKEY+-h&move focus to prev column \\
\verb+$MODKEY+-l&move focus to next column \\
\verb+$MODKEY+-j&move focus to next client in column \\
\verb+$MODKEY+-k&move focus to prev client in column \\
\verb+$MODKEY+-space&toggle to/from floating column 0 \\
\verb+$MODKEY+-[0-9]&select tag/view [0-9] \\
Moving Clients&\\
\verb+$MODKEY+-Control-h&swap client with last client of prev column \\
\verb+$MODKEY+-Control-l&swap client with last client of next column \\
\verb+$MODKEY+-Control-j&swap client down in the column \\
\verb+$MODKEY+-Control-k&swap client up in the column \\
\verb+$MODKEY+-Shift-h&move client to prev column \\
\verb+$MODKEY+-Shift-l&move client to next column \\
\verb+$MODKEY+-Shift-j&move client down within the column \\
\verb+$MODKEY+-Shift-k&move client up within the column \\
\verb+$MODKEY+-Shift-space&send client to/from floating column 0 \\
\verb+$MODKEY+-Shift-[0-9]&send client to tag/view [0-9] \\
\verb+$MODKEY+-Click1&move client with the mouse \\
\verb+$MODKEY+-Click3&resize client with the mouse \\
Layouts&\\
\verb+$MODKEY+-d&select default layout \\
\verb+$MODKEY+-s&select stacked layout \\
\verb+$MODKEY+-m&select max layout \\
\verb+$MODKEY+-f&maximize floating client \\
Menu Bar Functions&\\
\verb+$MODKEY+-a&choose action from menu bar \\
\verb+$MODKEY+-p&choose program from menu bar \\
\verb+$MODKEY+-t&choose view from menu bar \\
\verb+$MODKEY+-Shift-t&assign tag(s) to client from menu bar \\
Clients and Applications&\\
\verb+$MODKEY+-Return&open terminal client \\
\verb+$MODKEY+-Shift-c&kill client \\
\hline
\end{tabular}
\caption{Default keybindings of wmii}
\end{table}
\newpage
\section{Credits}
\label{sec:credits}
\begin{description}
\item [Author] Steffen Liebergeld
\item [Main critic and inquisitor] Salvador Peir\'o
\item [Helpers]
Anselm Garbe \\
Denis Grelich \\
Ross Mohn \\
Neptun Florin \\
Jochen Schwartz \\
Adrian Ratnapala \\
\end{description}
\section{Copyright notice}
guide to wmii-3\\
Copyright (C) 2005, 2006 by Steffen Liebergeld, Salva Peir\'o
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, version 2
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301, USA.
\end{document}
_______________________________________________ [email protected] mailing list http://wmii.de/cgi-bin/mailman/listinfo/wmii
