2 \chapter{Basic configuration}
5 This chapter should help your configure Ion to your liking. As the your
6 probably already know, Ion uses Lua as a configuration and extension
7 language. If you're new to it, you might first want to read some Lua
8 documentation as already suggested and pointed to in the Introduction
9 before continuing with this chapter.
11 Section \ref{sec:conffiles} is an overview of the multiple configuration
12 files Ion uses and as a perhaps more understandable introduction to the
13 general layout of the configuration files, a walk-through of the main
14 configuration file \file{ion.lua} is provided in section
15 \ref{sec:walkthrough}.
16 How keys and mouse action are bound to functions is described in detail
17 in \ref{sec:bindings} and in section \ref{sec:winprops} winprops are
18 explained. For a reference on exported functions, see section
21 \section{The configuration files}
24 Ion3, to which document applies, stores its stock configuration files in
25 \file{/usr/local/etc/ion3/} unless you, the OS package maintainer or
26 whoever installed the package on the system has modified the variables
27 \code{PREFIX}\index{PREFIX@\code{PREFIX}} or
28 \code{ETCDIR}\index{ETCDIR@\code{ETCDIR}} in
29 \file{system.mk}\index{system.mk@\file{system.mk}} before compiling Ion.
30 In the first case you probably know where to find the files and in
31 the other case the system administrator or the OS package maintainer
32 should have provided documentation to point to the correct location.
33 If these instructions are no help in locating the correct directory,
34 the command \code{locate cfg_ion.lua} might help provided \code{updatedb}
35 has been run recently.
37 User configuration files go in \file{\~{}/.ion3/}.
38 Ion always searches the user configuration file directory before the stock
39 configuration file directory for files. Therefore, if you want to change
40 some setting, it is advised against that you modify the stock configuration
41 files in-place as subsequent installs of Ion will restore the stock
42 configuration files. Instead you should always make a copy of the stock
43 file in \file{\~{}/.ion3/} and modify this file. When searching
44 for a file, if no extension or path component is given, compiled \file{.lc}
45 files are attempted before \file{.lua} files.
47 All the configuration files are named \file{cfg\_*.lua} with the ''\file{*}''
48 part varying. The configuration file for each module \file{mod\_modname} is
49 \file{cfg\_modname.lua}, with \file{modname} varying by the module in
50 question. The following table summarises these and other configuration
53 \begin{tabularx}{\linewidth}{
54 p{\widthof{cfg-bindings.lua}}%
60 The main configuration file \\
62 \file{cfg\_ioncore.lua} &
63 Configuration file for Ion's core library.
64 Most of the bindings and menus are configured here. Bindings that are
65 specific to some module are configured in the module's configuration
66 file. For details, see section \ref{sec:bindings}. \\
68 \file{cfg\_kludges.lua} &
69 Settings to get some applications behave more nicely have been
70 collected here. See section \ref{sec:winprops}. \\
72 \file{cfg\_tiling.lua}
76 \file{cfg\_statusbar.lua}
77 \dots & Configuration files for different modules. \\
80 Additionally, there's the file \file{look.lua} that configures the
81 drawing engine, but it is covered in chapter \ref{chap:gr}.
83 \section{A walk through \file{cfg\_ion.lua}}
84 \label{sec:walkthrough}
86 As already mentioned \file{cfg\_ion.lua} is Ion's main configuration
87 file. Some basic 'feel' settings are usually configured there and
88 the necessary modules and other configuration files configuring some
89 more specific aspects of Ion are loaded there. In this section we
90 take a walk through the stock \file{cfg\_ion.lua}.
91 Notice that most of the settings are commented-out (\code{--} is a
92 line comment in Lua) in the actual file, as they're the defaults
95 The first thing one in the file is to set
100 These settings cause most of Ion's key bindings to use \key{Mod1} as the
101 modifier key. If \code{ALTMETA} is set, it is used as modifier for the keys
102 that don't normally use a modifier. for details on modifiers and key
103 binding setup in general see section \ref{sec:bindings}.
105 Next we do some basic feel configuration:
114 These two will set the delay between button presses in a double click, and
115 the timeout to quit resize mode in milliseconds.
124 The first of these two settings enables opaque resize mode: in move/resize
125 move frames and other objects mirror you actions immediately. If opaque
126 resize is disabled, a XOR rubber band is shown during the mode instead.
127 This will, unfortunately, cause Ion to also grab the X server and has some
130 Next we load the configuration for Ion's core, and some kludges:
133 dopath("cfg_ioncore")
134 dopath("cfg_kludges")
137 Most bindings and menus are defined in \file{cfg\_ioncore.lua}.
138 Details on making such definitions follow in sections \ref{sec:bindings}
139 and \ref{sec:menus}, respectively.
140 some kludges or ''winprops'' to make some applications behave better
141 under Ion are colledted in \file{cfg\_kludges.lua}; see section
142 \ref{sec:winprops} for details. In addition to these, this file
143 lists quite a few statements of the form
145 ioncore.defshortening("[^:]+: (.*)(<[0-9]+>)", "$1$2$|$1$<...$2")
147 These are used to configure how Ion attempts to shorten window titles
148 when they do not fit in a Tab. The first argument is a POSIX regular
149 expression that is used to match against the title and the next is
150 a rule to construct a new title of a match occurs. This particular
151 rule is used to shorten e.g. 'Foo: barbaz<3>' to 'barba{\ldots}<3>'; for
152 details see the function reference entry for \fnref{ioncore.defshortening}.
154 To actually be able to do something besides display windows in full screen
155 mode, we must next load some modules:
158 dopath("cfg_modules")
159 --dopath("mod_query")
161 --dopath("mod_tiling")
162 --dopath("mod_statusbar")
167 We actually load there another file listing the default selection of
168 modules. If you only want to load additional modules, just uncomment
169 the corresponding line. If you want to disable loading some modules,
170 comment out the the line loading \file{cfg\_modules}, and uncomment
171 the lines for the modules you want, or add more.
174 \input{conf-bindings.tex}
176 \input{conf-menus.tex}
178 \input{conf-winprops.tex}