]> git.decadent.org.uk Git - ion3.git/blob - doc/conf.tex
ed19b517b91c7b47b8c7af03822170900f376d2f
[ion3.git] / doc / conf.tex
1
2 \chapter{Basic configuration}
3 \label{chap:config}
4
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.
10
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. Finally, the statusbar is explained in \ref{sec:statusbar}.
19 For a reference on exported functions, see section \ref{sec:exports}.
20
21 \section{The configuration files}
22 \label{sec:conffiles}
23
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. 
36
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.
46
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
51 files:
52
53 \begin{tabularx}{\linewidth}{
54       p{\widthof{cfg-bindings.lua}}%
55       X}
56     \hline
57     File & Description \\
58     \hline
59     \file{cfg\_ion.lua} & 
60     The main configuration file \\
61     %
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}. \\
67     %
68     \file{cfg\_kludges.lua} & 
69     Settings to get some applications behave more nicely have been 
70     collected here. See section \ref{sec:winprops}. \\
71     %
72     \file{cfg\_layouts.lua} & 
73     Some workspace layouts are defined here. \\
74     %
75     \file{cfg\_tiling.lua} 
76     \file{cfg\_query.lua} 
77     \file{cfg\_menu.lua} 
78     \file{cfg\_dock.lua} 
79     \file{cfg\_statusbar.lua} 
80     \dots & Configuration files for different modules. \\
81 \end{tabularx}
82
83 Additionally, there's the file \file{look.lua} that configures the 
84 drawing engine, but it is covered in chapter \ref{chap:gr}.
85
86 \section{A walk through \file{cfg\_ion.lua}}
87 \label{sec:walkthrough}
88
89 As already mentioned \file{cfg\_ion.lua} is Ion's main configuration
90 file. Some basic 'feel' settings are usually configured there and
91 the necessary modules and other configuration files configuring some 
92 more specific aspects of Ion are loaded there. In this section we
93 take a walk through the stock \file{cfg\_ion.lua}.
94 Notice that most of the settings are commented-out (\verb!--! is a 
95 line comment in Lua) in the actual file, as they're the defaults
96 nevertheless.
97
98 The first thing done in the file, is to set
99 \begin{verbatim}
100 META="Mod1+"
101 ALTMETA=""
102 \end{verbatim}
103 These settings cause most of Ion's key bindings to use \key{Mod1} as the
104 modifier key. If \code{ALTMETA} is set, it is used as modifier for the
105 keys that don't normally use a modifier. Note that these two are Lua 
106 variables used in the configuration files only, and not Ion settings. 
107 For details on modifiers and key binding setup in general, see section
108 \ref{sec:bindings}.
109
110 Next we do some basic feel configuration:
111
112 \begin{verbatim}
113 ioncore.set{
114     dblclick_delay=250,
115     kbresize_delay=1500,
116 }
117 \end{verbatim}
118
119 These two will set the delay between button presses in a double click, and
120 the timeout to quit resize mode in milliseconds.
121
122 \begin{verbatim}
123 ioncore.set{
124     opaque_resize=true,
125     warp=true
126 }
127 \end{verbatim}
128
129 The first of these two settings enables opaque resize mode: in move/resize
130 move frames and other objects mirror you actions immediately. If opaque
131 resize is disabled, a XOR rubber band is shown during the mode instead.
132 This will, unfortunately, cause Ion to also grab the X server and has some
133 side effects. 
134
135 There are some other options as well; see the documentation
136 for \fnref{ioncore.set} for details.
137
138 As a next step, in the actual \file{cfg\_ion.lua} file, we load
139 \file{cfg\_defaults.lua}. However, it is merely a convenience file for
140 doing exactly what we will going through below, and what is commented
141 out in the actual file. If you do not want to load what 
142 \file{cfg\_defaults.lua} loads, just comment out the corresponding 
143 line, and uncomment the lines for the files that you want:
144
145 \begin{verbatim}
146 --dopath("cfg_defaults")
147 dopath("cfg_ioncore")
148 dopath("cfg_kludges")
149 dopath("cfg_layouts")
150 \end{verbatim}
151
152 Most bindings and menus are defined in \file{cfg\_ioncore.lua}.
153 Details on making such definitions follow in sections \ref{sec:bindings} 
154 and \ref{sec:menus}, respectively. 
155 some kludges or ``winprops'' to make some applications behave better
156 under Ion are collected in \file{cfg\_kludges.lua}; see section
157 \ref{sec:winprops} for details. In addition to these, this file
158 lists quite a few statements of the form
159 \begin{verbatim}
160 ioncore.defshortening("[^:]+: (.*)(<[0-9]+>)", "$1$2$|$1$<...$2")
161 \end{verbatim}
162 These are used to configure how Ion attempts to shorten window titles
163 when they do not fit in a Tab. The first argument is a POSIX regular
164 expression that is used to match against the title and the next is
165 a rule to construct a new title of a match occurs. This particular
166 rule is used to shorten e.g. 'Foo: barbaz<3>' to 'barba{\ldots}<3>'; for
167 details see the function reference entry for \fnref{ioncore.defshortening}.
168 Finally, \file{cfg\_layouts.lua} defines some workspace layouts, available
169 through the \key{F9} workspace creation query.
170
171 To actually be able to do something besides display windows in full screen
172 mode, we must next load some modules:
173
174 \begin{verbatim}
175 dopath("mod_query")
176 dopath("mod_menu")
177 dopath("mod_tiling")
178 dopath("mod_statusbar")
179 --dopath("mod_dock")
180 dopath("mod_sp")
181 \end{verbatim}
182
183
184 \input{conf-bindings.tex}
185
186 \input{conf-menus.tex}
187
188 \input{conf-winprops.tex}
189
190 \input{conf-statusbar.tex}
191
192