mirrors/wmii
1
0
Fork 0
mirror of https://github.com/0intro/wmii synced 2024-12-02 10:17:10 +03:00
Code Issues Packages Projects Releases Wiki Activity
3078597d0a
wmii/doc/guide_en.tex
Anselm R. Garbe fa43df527d removed swapping
2006-05-19 17:38:45 +02:00

1006 lines
40 KiB
TeX
Raw Blame History

%TODO: please mention the /def/rules mechanism!
%guide to wmii-4
%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-4}}
\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}
\newcommand{\wmii}{\emph{wmii}}
\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-4%
\thanks{Thanks to the wmii community, in particular all the
people mentioned at \href{http://wmii.de/index.php/WMII/People}{WMII/people}.}
}
%\email{stepardo@gmail.com \and saoret.one@gmail.com}
\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-4. People who have used wmi, \wmii-2.5 or even ion will get
to know what is new and different in \wmii-4, 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-4 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 goals is to not exceed $10 k$ lines of
code~\footnote{ benefit of the $10 k$ SLOC restriction is that
it's easier to read/understand, thus it's easier to use and get
used to it}.
\wmii{} tries to be very portable and to give the user as much
freedom as possible.
\wmii-4 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 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 towards new ideas, and willing to spend some
time learning \wmii-4~\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-4 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-4 you should probably read
the whole document ``sequentially'', i.e. from beginning to end.
Another possibility is to read/consume the guide ``on demand'' as
you notice you need more information or details to understand
better some concept. We recommend you to read the introductory
chapters first, use some time to get settled in 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
it 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 trustworthy package, 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, which will
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
potentially incompatible versions.
\item Unpack it:
\begin{verbatim}
tar xzf wmii-4.tar.gz
cd wmii-4
\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-4 to be installed to. If you are unsure, keep the
default, it won't break your system.
\item Run make and make install:
\begin{verbatim}
make && make install
\end{verbatim}
\item Setup 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}
% Not necessary, .xinitrc is sourced by xinit anyways
%
% Make sure that the \emph{\~{}/.xinitrc} is executable:
%
% \begin{verbatim}
% chmod u+x ~/.xinitrc
% \end{verbatim}
\end{enumerate}
Now you are finished. Please note that autoconf tools are not used
for various reasons~\footnote{ read
\hrefx{http://www.ohse.de/uwe/articles/aal.html} and
\hrefx{http://lists.cse.psu.edu/archives/9fans/2003-November/029714.html}
for further details}. Please don't ask the \wmii{} developers to use autoconf,
they won't listen to you.
\section{Terminology}
\label{sec:terms}
Before you actually start doing your first steps in \wmii, first the
terminology has to be clarified.
\subsection{Clients}
A client is a program, that provides you a graphical user interface for
a special purpose, e.g. a web browser, or a terminal.
\subsection{Focus}
The (input) focus is the client, which currently receives your input.
In X11 exactly one client can get your input at a time. If you input
some command into your terminal, the terminal window has the input focus,
whereas all the other windows do not receive the input you enter.
\subsection{Events}
An event is a message generated by X server to notify X clients about
states. For instance, X generates a button press event, if you click
into a window.
\subsection{Tags}
A tag is an alphanumeric string you can associate to clients,
which allows you to group clients in a natural way.
In \wmii, there are no workspaces anymore. Instead, all clients matching a
particular tag are displayed at a time. For instance, if you tag your
browser and a terminal window with the tag ``web-browser'', and you request
to view all clients matching this tag, \wmii{} will display your browser
and the terminal on the screen.
It is also possible to give clients multiple tags, which is described later.
\subsection{View}
A view is the set of displayed clients, which match a specific single tag.
A view is pretty similar to the ``workspace'' metaphor in other window
managers, though more powerful.
Only one view can be visible at a time.
Views are related to the tags, which are currently in use. You have exactly
one view for each single tag, thus you can only view sets of clients which
match an existing tag.
If you destroy the last client with a tag, the view of this tag is
destroyed.
\subsection{Column}
A column is a distinct part of a view, where clients are arranged
automatically in a vertical direction.
In \wmii, you are able to divide each view into different columns.
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 is
destroyed automatically.
% no, a view might contain floating clients only as well
% Please be aware, that every view has at least one column or a floating window.
\subsection{Layout}
A layout is the arrangement of clients in a column.
There are three different ways to arrange clients in a column.
\paragraph{default} This layout arranges each client with
equally vertical space fitting into the column's height.
\paragraph{maximum} This layout arranges all clients with
the same geometry as the column, showing only one of them at a time.
\paragraph{stacking} This layout arranges all clients
like a stack, where only the focused client is completely
visible, and all other clients can be accessed through its title-bars.
This is an alternative approach to \emph{tabbing}.
\section{Getting started}
Now it is time to start diving into the \wmii{} user experience. I suggest you
to try everything described by yourself immediately, instead of first reading
it, to avoid "memory leakage". It is very helpful, if you print this
document on paper or have it available on a different screen, because you might not
be able to view it during your first steps in \wmii.
Note, that the \emph{MOD} key I am referring to, may resemble
different keys on different systems. By default it is the
\emph{Mod1} or \emph{Alt} key in X11. Normally this is the key labelled with
\emph{Alt} on your keyboard.
The notation \emph{MOD}-\emph{Key} means to press \emph{MOD} and
\emph{Key} both at the same time.
All key combinations can be freely configured, but for the sake of
simplicity I'll stick with the default key combinations for this
guide. You will learn how to alter the bindings in the
section \ref{sec:scripting}.
The default key combinations heavily use the home row navigation keys
\emph{h} (left), \emph{j} (down), \emph{k} (up), and \emph{l} (right),
which are associated with the specific direction.
\subsection{First steps}
\label{subsec:firststeps}
Start your X session now. 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 this guide :-)
First of all, press \emph{MOD-Enter} to start an xterm. It will
take half of the vertical space, so you have two equally arranged
windows. If you press \emph{MOD-Enter} again, you have three
windows that are arranged equally.
To switch between the three windows, press
\emph{MOD-j}, which cycles the focus between the three windows.
You can also press \emph{MOD-k} to switch to the window above or
\emph{MOD-j} to switch to the window below the current.
Now look at the title-bars of those windows. They display
important information: the first label contains the tag of
the window. The second label displays the window's title.
Similar information is displayed in the status-bar at the bottom. The
first labels display the tags currently in use and highlight the currently
selected view. On the right side some status information is displayed, by
default the system load and the current time (see
subsection~\ref{subsec:status} for details).
\subsection{Using columns}
As described earlier, \wmii{} uses columns to arrange your windows.
Your view already consists of a single column.
Next, you will create a new column.
In \wmii{} columns always consists of at least a single client,
thus to create a new column, you need at least two clients at hand.
Now focus a client of your choice and press \emph{MOD-Shift-l},
which moves the client rightwards. As you see, \wmii{} creates
a new column by dividing the view horizontally in two equally big
areas. The focused client has been moved into the new column.
If you close the last client of a column, the column is destroyed
immediately. If the last client of the current view is closed,
the view will be removed accordingly as well.
If you press \emph{MOD-j} to change focus, you will see that \wmii
actually cycles the focus in the current column only.
To change the focus to a different column, you can press \emph{MOD-l}
(right) and \emph{MOD-h} (left) respectively.
It is also possible to swap adjacent clients among columns. To swap
clients leftwards, press \emph{MOD-Control-h}. To swap clients
rightwards, press \emph{MOD-Control-l}.
\subsection{What about layouts?}
Layouts arrange clients in a column. They are related to a single
column. Thus it is possible to have different columns in one view, each
using another layout.
The default layout arranges each client of the column with equally
vertical space. You can enable this layout with \emph{MOD-d}
(where the ``d'' stands for default) explicitly.
The stacking layout can be enabled with \emph{MOD-s}. As you see now,
there is only one client using as much space as possible, and only
title-bars of the other clients displayed in the column. You can
switch between the clients in the column using \emph{MOD-j}.
The max-layout maximises all clients to the same geometry as the column.
Only the focused client is displayed at a time, all other clients
are behind it. You can switch between the clients with \emph{MOD-j}.
\subsection{Floating layer}
To handle clients in the classical way, like in conventional window
managers, the so-called ``floating layer'' is used. Actually there are a
bunch of clients which don't fit well into the tiled world, because they
have been designed with the conventional window management in mind,
for instance clients like the Gimp or xmms.
While \wmii{} is a dynamic window manager, which does the window arrangement
for you automatically, those old fashioned programs rely on the
conventional window managing concept, where all the clients fly around on
your desktop and you are forced to constantly order the mess.
To attach such broken clients to the floating layer, you can toggle the
focus between floating and managed layer through pressing \emph{MOD-Space}.
The \emph{MOD-Shift-Space} shortcut toggles the focused window between
floating and managed layer.
Note, the floating layer is addressed as the zeroth-column internally.
\subsection{Tags}
Up to now all your clients were tagged with ``1'', and you only had
this single view. But a single view does not scale well, once
too many clients appear which are used for different unrelated tasks.
Thus you might want to have a view per task, e.g. a view
with your editor and your programming tools, another view
with your browser, and a third view with your music jukebox.
The good news is, that the tagging concept provides a very dynamic way to
achieve such kinds of grouping.
You can 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 through pressing \emph{MOD-Number}.
Normally, whenever a new client appears, it automatically inherits the tag
of the currently selected view.
%% TODO: better tag handling (this is about to change in \wmii{} till
%%version 3)
Note, there are more powerful uses of tags you will learn about 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?}
Most X-clients have a menu option or button to be closed. For the rare
cases they don't provide a mouse-driven way, like in most terminals,
you can press \emph{MOD-Shift-c} to close a window.
\subsection{How do I start programs?}
You may start programs from a terminal. But \wmii{} contains a special
keyboard-driven program menu, which is accessible through pressing
\emph{MOD-p}. Please note, that the content of this menu is provided by a
simple shell-script.
You will see a list of programs. If you start typing, the
menu will cut the list and only display items which match
the input you entered so far (in that order). Whenever there is
only one item left, the menu highlights 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 can 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
decisions about window arrangement, thus taking most extra work away
from the user and letting him concentrate on his work. This can also be
seen as tacit window management.
\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, they were able to
split the task into several smaller binaries, each with a distinct
job.
\subsection{The glue that puts it all together---9P}
Programs in the Unix world usually communicate via buffers which are
addressed by (file) descriptors, one of them are sockets.
To create a lightweight but powerful communication protocol, the \wmii
developers closely looked at the design of Plan9 and chose the 9P
protocol.
The basic ideas for configuring and running \wmii{} were taken from
the Acme user interface for programmers of Plan9. Similar to Acme,
\wmii{} provides a filesystem-interface, which can be accessed by
9P clients. This allows to interact with any different kind of
application through a file system interface, which might be implemented
in any programming language of choice. This also avoids to force
client programmers to a specific programming language or paradigm.
The interface of \wmii{} can be compared to the \emph{procfs} file
system of the Linux kernel.
If you want to interact with a running \wmii{} process, you can access its 9P
file-system service through either using the bundled tool \emph{wmiir} or
the 9P2000 kernel module of a Linux kernel later than 2.4.16+. Using the
kernel module has the advantage to mount the filesystem of \wmii{} into your
file system hierarchy directly, though it has the drawback that this need
\emph{root} privileges.
\subsection{Tools}
This section provides a basic overview about the tools which are bundled
with \wmii. But for a more detailed description, you should read the associated
man page of the specific tool.
\begin{description}
\item
\emph{wmiir} is a small tool we is used to access the
virtual file-system service of \wmii{} remotely. It basically supports four
operations:
\begin{itemize*}
\item read
\item write
\item remove
\item create
\end{itemize*}
wmiir needs to know the address of the file-system service to work
with. On startup, \wmii{} exports the \verb+WMII_ADDRESS+ environment variable,
which points to the address of the file-system service of \wmii.
This address can be:
\begin{itemize*}
\item a local unix socket address like \verb+unix!/path/to/socket+
\item a tcp-capable socket address like \verb+tcp!hostname:port+
\end{itemize*}
If you want to work on a different filesystem, you may specify it
manually with the \emph{-a address} command line option.
A sample invocation looks like:
\begin{verbatim}
wmiir read /
\end{verbatim}
This command actually prints the contents of the root directory of the
virtual file-system of \wmii.
\item
\emph{wmiimenu} is a generic keyboard-driven menu, which matches items
through providing patterns. You may want to learn more about it by reading
the man-page.
\item
\emph{wmiiwarp} is a tiny tool to warp the mouse pointer at specific
coordinates on your screen.
\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 current X selection to
STDOUT. This is useful for scripts.
\end{description}
\subsection{Conclusion}
The virtual file-system service of \wmii{} and the tools presented enable
you to fully control the window manager from scripts.
You will see some examples in the next section
\ref{sec:scripting}.
\section{Scripting wmii}
\label{sec:scripting}
In this chapter you will see how to control \wmii{} through scripts. I will
give you some pointers, that you can start scripting on your own.
\subsection{Language}
As mentioned earlier, the only requirement for interacting with \wmii{} is to
access its file-system service. The easiest way to do this, is by using
the wmiir tool. Thus shell scripts are the easiest way of adapting \wmii
too fit your needs.
Hence, you can control \wmii{} in any programming language you want. However,
\wmii's default scripts are written in a subset of ``sh'' that is POSIX
compliant, to keep \wmii{} as \emph{portable} as possible.
To keep simplicity, the following examples will stick to ``sh'' as well,
and don't depend on python, tcl, ruby, \dots
% - 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} which points to \texttt{/usr/local/etc}
or \texttt{\$HOME/.wmii-4} by default}.
Through pressing \emph{MOD-a} you can open the actions menu. It works
similar to the program menu, but only displays actions.
You might want to add your own actions through writing shell scripts in the
default \wmii{} configuration directory or in the \texttt{\$HOME/.wmii-4}.
This works, because in the \wmii{} controlling script exports the variable
\verb+$PATH+ as\\ \verb+$PATH=~/.wmii-4:$CONFPREFIX/wmii:$PATH+ before
launching the wmiiwm, this way local user actions under
\verb+~/.wmii-4+ 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 immediately.
To do so, just open the actions menu (with pressing \emph{MOD-a}) and
choose the \emph{wmiirc} action. It's also possible to launch \wmii{} actions
directly from a terminal, which is a neat side effect that results from
exporting \verb+$PATH+ in the \wmii{} startup script.
\subsection{wmiirc}
\emph{wmiirc} is a special ``sh''-script which is launched on startup
of \wmii{} to take care of configuring and controlling \wmii.
It does so through writing data to several files of the virtual \wmii
file-system, and through reading events reported by \wmii{} during runtime.
Events are mostly shortcut presses, mouse clicks or user-defined.
The events are processed in a loop in the script.
Thus, for the basic configuration of \wmii, like changing the default
modifier key \emph{MOD=Mod1} or the navigation keys this script is
the place to look at.
The name \emph{wmiirc} means \wmii{} \emph{run command}, because ``rc'' is an
old Unix abbreviation for ``run command''.
\subsection{Changing the style}
The style of \wmii-4 is defined through font and colour values, which are
unobtrusively exported with the following \emph{environment variables}.
\begin{verbatim}
WMII_SELCOLORS='#000000 #eaffff #8888cc'
WMII_NORMCOLORS='#000000 #ffffea #bdb76b'
WMII_FONT=static
\end{verbatim}
\verb+WMII_SELCOLORS+ defines the colours of the selected client's window
title and border, whereas \verb+WMII_NORMCOLORS+ defines the colours of all
unselected clients. The numbers are hexadecimal rgb tuple-values, which you
might know from HTML. You can grab them with the Gimps colour-chooser for instance.
The first colour defines the text colour of strings in bars and menus.
The second colour defines the background colour of bars and clients, and
the third colour defines the 1px borders surrounding bars and clients.
\verb+WMII_FONT+ defines the font which should be used for drawing text.
in title-bars, the status-bar, and the wmiimenu.
You can query for different fonts using \emph{xfontsel} for instance.
\subsection{Filling the status-bar}
\label{subsec:status}
The status bar of \wmii{} has it's own \verb+/bar+ directory with
a 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 drawn, while the second contains the data
which is displayed.
Now 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. You can open a terminal and run
\verb+wmiir read /event+ to see how the events are generated
when you click onto the status-bar. This is a mechanism that allows
controlling applications directly from the bar. If you've
finished and you want to get rid of your label,
a \verb+wmiir remove /bar/foo+ command.
If you want to learn more, take a look at the status script and
visit \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*}
Now open the default status script and try to understand yourself,
how it works \verbatiminput{../rc/status}. The first line is a handy
\verb+xwrite+ function declaration, to prevent you from several verbosity
when issuing a write to some file. The following 3 lines take care of
creating and setting up the \verb+status+ label. The last section is a
\verb+while+ loop
that \emph{tries} to write the system load and date information
to the bar.\\
The tricky bit is, that it \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 exits cleanly, which makes sense
because nobody wants a program that updates a nonexistent label.\\
Now go back to the first lines of the script, and note
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, hence all
the writes made from any previously running \verb+status+ script
will fail, thus they will finish. This way we make sure that
we only run one status script at each time. And thus we keep the
one-to-one correspondence between label and status script.
\subsection{Assigning new tags}
As mentioned before, you can achieve more powerful things with tags, than
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 can now view the ``web'' tag by executing the following:
\begin{verbatim}
echo -n view web | wmiir write /ctl
\end{verbatim}
As the development of \wmii-4 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.
% TODO:
% I would also like to put/see a recommended readings or bibliography
% section this will be of course biased by my use of plumber and acme
% from p9p but i think it's worth mentioning both them here. similar to:
% http://wmii.de/contrib/guide-es/beginnersguide/node10.html
\section{The End}
\label{sec:end}
We hope this helps you getting used to \wmii.
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 [/client]
\begin{itemize*}
\item the clients namespace
\end{itemize*}
\item [/client/n]
\begin{itemize*}
\item every client, including ones not shown in the view has a namespace here
\item \verb+n+ is a non-negative integer and clients are numbered oldest first
\end{itemize*}
\item [/client/n/class]
\begin{itemize*}
\item a file containing the class:instance information for client \verb+n+
\end{itemize*}
\item [/client/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 [/client/n/geom]
\begin{itemize*}
\item the window geometry of client \verb+n+
\item displayed as four blank separated integers (x y width height?)
\end{itemize*}
\item [/client/n/index] contains the client's index in the /client namespace, in this case n
\item [/client/n/name]
\begin{itemize*}
\item the name of client \verb+n+ as it's seen by \wmii{} (displayed in the tagbar)
\end{itemize*}
\item [/client/n/tags]
\begin{itemize*}
\item a plus(+)-separated 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 separated list of the keys to be grabbed by \wmii
\item [/def/rules]
\begin{itemize*}
\item a newline separated list of rules to specify how to automatically tag clients
\item matches against the class.instance values of a client
\item syntax: \verb+/$regex/ -> $tag+ (tag might be \~{} to indicate floating mode
\end{itemize*}
\item [/def/colwidth] with of newly created columns (in px)
\item [/def/colmode] mode of newly created columns
\item [/view]
\begin{itemize*}
\item a manifestation of the collection of clients associated with a specific
tag
\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 separated 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&send client to prev column \\
\verb+$MODKEY+-Shift-l&send client to next column \\
\verb+$MODKEY+-Shift-space&send client to/from floating column 0 \\
\verb+$MODKEY+-Shift-[0-9]&send client to tag/view [0-9] \\
Layouts&\\
\verb+$MODKEY+-d&select default layout \\
\verb+$MODKEY+-s&select stacked layout \\
\verb+$MODKEY+-m&select max layout \\
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-4\\
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}
Reference in New Issue View Git Blame Copy Permalink