X-Git-Url: https://git.decadent.org.uk/gitweb/?a=blobdiff_plain;f=doc%2Fconf.tex;fp=doc%2Fconf.tex;h=0000000000000000000000000000000000000000;hb=a6561c9679cd701b0d50c3cfd44e4664f7df2b2f;hp=6ec99ecc0303a06e2d591749021c3e5598aca516;hpb=cd09055902de482a1be019bf4b4efdae64c98d35;p=ion3.git diff --git a/doc/conf.tex b/doc/conf.tex deleted file mode 100644 index 6ec99ec..0000000 --- a/doc/conf.tex +++ /dev/null @@ -1,198 +0,0 @@ - -\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} - -