\chapter{Basic configuration}
\label{chap:config}

This chapter should help your configure Ion to your liking. As  the your
probably already know, Ion uses Lua as a configuration and extension 
language. If you're new to it, you might first want to read some Lua 
documentation as already suggested and pointed to in the Introduction
before continuing with this chapter.

Section \ref{sec:conffiles}is an overview of the multiple configuration
files Ion uses and as a perhaps more understandable introduction to the
general layout of the configuration files, a walk-through of the main 
configuration file \file{cfg\_ion.lua} is provided in section 
\ref{sec:walkthrough}.
How keys and mouse action are bound to functions is described in detail
in \ref{sec:bindings} and in section \ref{sec:winprops} winprops are
explained. Finally, the statusbar is explained in \ref{sec:statusbar}.
For a reference on exported functions, see section \ref{sec:exports}.

\section{The configuration files}
\label{sec:conffiles}

Ion3, to which document applies, stores its stock configuration files in
\file{/usr/local/etc/ion3/} unless you, the OS package maintainer or 
whoever  installed the package on the system has modified the variables
\code{PREFIX}\index{PREFIX@\code{PREFIX}} or
\code{ETCDIR}\index{ETCDIR@\code{ETCDIR}} in
\file{system.mk}\index{system.mk@\file{system.mk}} before compiling Ion.
In the first case you probably know where to find the files and in 
the other case the system administrator or the OS package maintainer
should  have provided documentation to point to the correct location. 
If these instructions are no help in locating the correct directory, 
the command \code{locate cfg_ion.lua} might help provided \code{updatedb} 
has been run recently. 

User configuration files go in \file{\~{}/.ion3/}. 
Ion always searches the user configuration file directory before the stock
configuration file directory for files. Therefore, if you want to change
some setting, it is advised against that you modify the stock configuration
files in-place as subsequent installs of Ion will restore the stock
configuration files. Instead you should always make a copy of the stock
file in \file{\~{}/.ion3/} and modify this file. For sake of maintainability
of your customised configuration, it is recommended against copying all of
the files there. Only copy those files you actually need to modify. Most 
simple customisations, such as changes in a few bindings, are best done 
entirely within \file{cfg\_ion.lua}.

All the configuration files are named \file{cfg\_*.lua} with the ``\file{*}''
part varying. The configuration file for each module \file{mod\_modname} is
\file{cfg\_modname.lua}, with \file{modname} varying by the module in
question. Configuration files can also be compiled into \file{.lc} files,
and these are attempted by the configuration file search routines before
\file{.lua} files.

The following table summarises these and other configuration
files:

\begin{tabularx}{\linewidth}{
      p{\widthof{cfg-bindings.lua}}%
      X}
    \hline
    File & Description \\
    \hline
    \file{cfg\_ion.lua} & 
    The main configuration file \\
    %
    \file{cfg\_ioncore.lua} & 
    Configuration file for Ion's core library.
    Most of the bindings and menus are configured here. Bindings that are
    specific to some module are configured in the module's configuration
    file. For details, see section \ref{sec:bindings}. \\
    %
    \file{cfg\_kludges.lua} & 
    Settings to get some applications behave more nicely have been 
    collected here. See section \ref{sec:winprops}. \\
    %
    \file{cfg\_layouts.lua} & 
    Some workspace layouts are defined here. \\
    %
    \file{cfg\_tiling.lua} 
    \file{cfg\_query.lua} 
    \file{cfg\_menu.lua} 
    \file{cfg\_dock.lua} 
    \file{cfg\_statusbar.lua} 
    \dots & Configuration files for different modules. \\
\end{tabularx}

Additionally, there's the file \file{look.lua} that configures the 
drawing engine, but it is covered in chapter \ref{chap:gr}.

\section{A walk through \file{cfg\_ion.lua}}
\label{sec:walkthrough}

As already mentioned \file{cfg\_ion.lua} is Ion's main configuration
file. Some basic 'feel' settings are usually configured there and
the necessary modules and other configuration files configuring some 
more specific aspects of Ion are loaded there. In this section we
take a walk through the stock \file{cfg\_ion.lua}.
Notice that most of the settings are commented-out (\verb!--! is a 
line comment in Lua) in the actual file, as they're the defaults
nevertheless.

The first thing done in the file, is to set
\begin{verbatim}
META="Mod1+"
ALTMETA=""
\end{verbatim}
These settings cause most of Ion's key bindings to use \key{Mod1} as the
modifier key. If \code{ALTMETA} is set, it is used as modifier for the
keys that don't normally use a modifier. Note that these two are Lua 
variables used in the configuration files only, and not Ion settings. 
For details on modifiers and key binding setup in general, see section
\ref{sec:bindings}.

Next we do some basic feel configuration:

\begin{verbatim}
ioncore.set{
    dblclick_delay=250,
    kbresize_delay=1500,
}
\end{verbatim}

These two will set the delay between button presses in a double click, and
the timeout to quit resize mode in milliseconds.

\begin{verbatim}
ioncore.set{
    opaque_resize=true,
    warp=true
}
\end{verbatim}

The first of these two settings enables opaque resize mode: in move/resize
move frames and other objects mirror you actions immediately. If opaque
resize is disabled, a XOR rubber band is shown during the mode instead.
This will, unfortunately, cause Ion to also grab the X server and has some
side effects. 

There are some other options as well; see the documentation
for \fnref{ioncore.set} for details.

As a next step, in the actual \file{cfg\_ion.lua} file, we load
\file{cfg\_defaults.lua}. However, it is merely a convenience file for
doing exactly what we will going through below, and what is commented
out in the actual file. If you do not want to load what 
\file{cfg\_defaults.lua} loads, just comment out the corresponding 
line, and uncomment the lines for the files that you want:

\begin{verbatim}
--dopath("cfg_defaults")
dopath("cfg_ioncore")
dopath("cfg_kludges")
dopath("cfg_layouts")
\end{verbatim}

Most bindings and menus are defined in \file{cfg\_ioncore.lua}.
Details on making such definitions follow in sections \ref{sec:bindings} 
and \ref{sec:menus}, respectively. 
some kludges or ``winprops'' to make some applications behave better
under Ion are collected in \file{cfg\_kludges.lua}; see section
\ref{sec:winprops} for details. In addition to these, this file
lists quite a few statements of the form
\begin{verbatim}
ioncore.defshortening("[^:]+: (.*)(<[0-9]+>)", "$1$2$|$1$<...$2")
\end{verbatim}
These are used to configure how Ion attempts to shorten window titles
when they do not fit in a Tab. The first argument is a POSIX regular
expression that is used to match against the title and the next is
a rule to construct a new title of a match occurs. This particular
rule is used to shorten e.g. 'Foo: barbaz<3>' to 'barba{\ldots}<3>'; for
details see the function reference entry for \fnref{ioncore.defshortening}.
Finally, \file{cfg\_layouts.lua} defines some workspace layouts, available
through the \key{F9} workspace creation query.

To actually be able to do something besides display windows in full screen
mode, we must next load some modules:

\begin{verbatim}
dopath("mod_query")
dopath("mod_menu")
dopath("mod_tiling")
dopath("mod_statusbar")
--dopath("mod_dock")
dopath("mod_sp")
\end{verbatim}


\input{conf-bindings.tex}

\input{conf-menus.tex}

\input{conf-winprops.tex}

\input{conf-statusbar.tex}