[svn-upgrade] Integrating new upstream version, ion3 (20070506)

[ion3.git] / doc / confintro.tex

diff --git a/doc/confintro.tex b/doc/confintro.tex
index 9331614e9ab073b1de415851eca02827ee36a4ea..a04af82fd62efb09d479b28499fc40bd54f064d2 100644 (file)
--- a/doc/confintro.tex
+++ b/doc/confintro.tex
@@ -1,52 +1,50 @@
 
 \chapter{Introduction}
 
 
 \chapter{Introduction}
 

-This document is an ''advanced user'' manual for Ion, the X11 window manager,
-and version 3 specifically. It is an attempt attempt at documenting what is 
-in Ion's configuration files, how to configure Ion by simple modifications 
+This document is an ``advanced user'' manual for the X11 window manager
+Ion, version 3. It is an attempt at documenting things that go into Ion's
+configuration files, how to configure Ion by simple modifications 

 to these files and how to write more complex extensions in Lua, the 
 lightweight configuration and scripting language used by Ion. 
 
 to these files and how to write more complex extensions in Lua, the 
 lightweight configuration and scripting language used by Ion. 
 

-Readers unfamiliar with Lua is advised to first glance at the Lua manual at 
+Readers unfamiliar with Lua might first want to first glance at some 
+Lua documentation at

 
 

-\centerurl{http://www.lua.org/docs.html}
+\begin{center}
+    \url{http://www.lua.org/docs.html}, or \\
+    \url{http://lua-users.org/wiki/LuaTutorial},
+\end{center}

 
 

-and perhaps some tutorial pages at the lua-users wiki:
-
-\centerurl{http://lua-users.org/wiki/LuaTutorial}
+although this should not be strictly necessary for basic modifications
+of configuration files for anyone with at least some familiarity with
+programming languages.

 
 Back in this document, first in chapter \ref{chap:prelim} some key
 
 Back in this document, first in chapter \ref{chap:prelim} some key

-concepts and relations are explained. These include the module system
-and Ion's object and class hierarchies. While it might not at first 
-occur that knowing such things would be necessary to \emph{configure} 
-a program, this  material is essential because of the object-oriented 
-nature of most of Ion's scripting interface.
-
-The new user, fed up with the default key bindings and eager to just
-quickly configure Ion to his liking may question the reasons for 
-exposing the ''heavy'' internal OO structure in the scripting and
-configuration interface. I'm not the one to  blame him for that. 
-Sure it would be faster to configure Ion to everyone's liking
-if a simpler binding configuration interface was provided. Such an
-interface would, however, also be far more limited and make writing
-extensions more complicated and the advantages from using a real 
-scripting language would be partly lost. One more advantage from
-a rich scripting and configuration interface is that it allows 
-implementing scripts to read alternate configuration file formats,
-ones that could be, for example, modified by external configuration tools. 
-
-In chapter \ref{chap:config} the very basic Ion configuration know-how
-is provided. All the different configuration files and their locations
-are explained and instructions are given to allow the reader to
-configure bindings and so-called ''winprops''. Chapter \ref{chap:gr}
-explains the notion of drawing engines and graphical styles and how to
-write new looks for Ion and more advanced aspects of Ion's scripting 
-interface are documented in chapter \ref{chap:tricks} (a work in 
-progress).
-
+concepts and relations are explained. These include the module system,
+and Ion's object (or ``region'') and class hierarchies. While it may
+not be necessary to study the latter for basic copy-paste modifications
+of configuration files -- for that you should not really need this
+manual either -- it is, however, essential to for more extensive
+customisation, due to the semi-object-oriented nature of most of
+Ion's scripting interface. Knowing the different object types also
+helps dealing with the different binding ``contexts'' (see
+Section \ref{sec:bindings}) that to some extent mirror these classes.
+
+The new user, fed up with the default key bindings and eager to 
+just quickly configure Ion to his liking, may therefore just want
+to skip to Chapter \ref{chap:config}, and attempt to work from therefore.
+That chapter provides the very basic Ion configuration know-how
+is provided: all the different configuration files and their locations
+are explained, instructions are given to allow the reader to
+configure bindings and so-called ``winprops'', and the statusbar
+templates are also explained. 
+
+Next, Chapter \ref{chap:gr} explains the notion of drawing engines
+and graphical styles and how to write new looks for Ion. More advanced
+aspects of Ion's scripting interface are documented in Chapter 
+\ref{chap:tricks}. 

 Finally, most of the functions provided by Ion's scripting interface
 Finally, most of the functions provided by Ion's scripting interface

-are listed and documented in the Function reference in chapter
-\ref{sec:exports}. At the end of the document is an alphabetical
-listing of all these functions.
-
+are listed and documented in the Function reference in Chapter
+\ref{sec:exports}. At the end of the document an alphabetical
+listing of all these functions may be found.