wmii/doc/guide_en.tex

%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{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--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{
    the $10 k$ SLOC restriction benefits 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 many
    freedom as possible.

    Wmii--3 is the third mayor release of the second generation of the
    window manager improved~\footnote{ the ii is actually a roman
    letter for the number 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 or editors.

    I hope you are open minded against new ideas, and willing to spend
    some time learning it~\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 the
    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 possibly read
    the whole document. Another possibility is 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
    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 paragraph.

    For all those who are still reading this, let me tell you you are
    on the good side because if you grab the sources and compile them
    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 messing
    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 may 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 you can give for clients. That allows you to
    group clients.  In wmii, there are no workspaces anymore. Instead,
    we simply show 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 equally
    much 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 you to 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 may 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,
    that you didn'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 its 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 in 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 another layout.

    The default layout is to give each client in the column equally
    much 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 use all the space in the column each. Only the focused
    client is visible and the other 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 the 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 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 per
    \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. If 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 the
    \emph{action}. It's also possible launch wmii actions directly
    from an xterm (or similar terminal emulator program), this is a nice
    side effect that results of 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 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, as changing the default
    modifier key \emph{MOD=Mod1} or the navigation keys (by default
    the \emph{hjkl} vim home row) this is probably the place to look
    at.

  \subsection{Changing the looks}

    The look of wmii-3 is determined by colours 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
    Gimps colour-chooser.

    The definitions are as follows: the first is the colour of the
    strings 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 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 much 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&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-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}