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