* guile: some improvements to the manual

guile/mu-guile.texi

@@ -55,12 +55,23 @@ Documentation License.''
 
 Welcome to @t{mu-guile}!
 
-@t{mu-guile} is a binding of the @t{mu} email search-engine for the @t{guile}
+@t{mu} is a program for indexing and searching your e-mails. It can search
-programming language. Using this binding, you can write simple (and not so
+your messages in many different ways, but sometimes that may not be
-simple) programs/scripts to data-mine your e-mail corpus.
+enough. If you have very specific queries, or want do generate some
+statistics, you need some more power. 
+
+@t{mu-guile} is made for those cases. @t{mu-guile} exposes the internals of
+@t{mu} and its database to the @t{guile} programming language. Guile is the
+@emph{GNU Ubiquitous Intelligent Language for Extensions} - a version of the
+@emph{Scheme} programming language and the official GNU extension language.
+
+Guile/Scheme is a member of the @emph{Lisp} family of programming languages --
+like emacs-lisp, @emph{Racket}, Common Lisp. If you're not familiar with
+Scheme, @t{mu-guile} is an excellent opportunity to learn a bit about!
+
+Trust me, it's not very hard -- and it it's @emph{fun}!
 
 @menu
-* Introduction::
 * Getting started::
 * Initializing mu-guile::
 * Messages::
@@ -74,44 +85,65 @@ Appendices
 * GNU Free Documentation License::  The license of this manual.
 @end menu
 
-@node Introduction
-@chapter Introduction
-
-@t{mu} is a program for indexing and searching e-mails stored in maildirs.
-
-@t{guile} is the @emph{GNU Ubiquitous Intelligent Language for Extensions} - a
-version of the @emph{Scheme} programming language and the official GNU
-extension language.
-
-@t{mu-guile} connects @t{mu} and @t{guile}, and allows you to easily write
-programs for your specific needs.
-
 @node Getting started
 @chapter Getting started
 
 @menu
 * Installation::
-* First steps::
+* Making sure it works::
 @end menu
 
-This chapter walks you through the installation and some basic steps to ensure
+This chapter walks you through the installation and the basic setup. 
-things work correctly.
 
 @node Installation
 @section Installation
 
-@t{mu-guile} is part of @t{mu} - by installing the latter, the former will be
+@t{mu-guile} is part of @t{mu} - by installing the latter, the former is
-installed as well, provided that you have @t{guile} version 2.0 installed.
+installed as well. At the time of writing, there are no distribution-provided
+packaged versions of @t{mu-guile}; so for now, you need to follow the steps
+below.
+
+@subsection Guile 2.x
+
+@t{mu-guile} is built automatically when @t{mu} is built, if you have
+@t{guile} installed (@t{mu} checks for this during @t{configure}). Thus, the
+first step is to ensure you have @t{guile} installed.
+
+On Debian/Ubuntu you can install @t{guile} 2.x using the @t{guile-2.0-dev}
+package (and its dependencies):
+@example
+$ sudo apt-get install guile-2.0-dev
+@end example
+
+At the time of write, there are no official packages for
+Fedora@footnote{@url{https://bugzilla.redhat.com/show_bug.cgi?id=678238}}.  If
+you are using Fedora or any other system that does not have packages, you need
+to compile @t{guile} from
+source@footnote{@url{http://www.gnu.org/software/guile/manual/html_node/Obtaining-and-Installing-Guile.html#Obtaining-and-Installing-Guile}}.
+
+@subsection gnuplot
+
+For creating graphs with @t{mu-guile}, you need the @t{gnuplot} program --
+most likely, there is a package available for your system; for example:
+
+@example
+$ sudo apt-get install gnuplot
+@end example
+
+and in Fedora:
+
+@example
+$ sudo yum install gnuplot
+@end example
+
+@subsection mu
 
 At the time of writing, there are no distribution packages for @t{mu-guile},
 so we are assuming installation from source packages.
 
-Installation follows the normal sequence of:
+Assuming @t{guile} 2.x is installed correctly, @t{mu} finds it during its
-@example
+@t{configure}-stage, and creates @t{mu-guile}. Building @t{mu} follows the
-$ tar xvfz mu-<version>.tar.gz  # use the specific version
+normal steps -- please see the @t{mu} documentation for the details.
-$ cd mu-<version>
-$./configure
-@end example
 
 The output of @t{./configure} should end with a little text describing the
 detected versions of various libraries @t{mu} depends on. In particular, it
@@ -122,27 +154,25 @@ Guile version                        : 2.0.3.82-a2c66
 @end example
 
 If you don't see any line referring to @t{guile}, please install it, and run
-@t{configure} again. Note once more, @t{mu-guile} requires @t{guile} version
+@t{configure} again. After a succesfull @t{./configure}, we can make and
-2.0.
+install the package:
-
-After a succesfull @t{./configure}, we can make and install the package:
 
 @example
 $ make && sudo make install
 @end example
 
-After this, @t{mu} and @t{mu-guile} should be installed. Note that the above
+@subsection mu-guile
-instructions will normally install things under @t{/usr/local}; you may need
-to update @t{guile}'s @t{%load-path} to find it there.
 
-You can check the current load-path with the following:
+After this, @t{mu} and @t{mu-guile} are installed -- usually somewhere under
+@t{/usr/local}.You may need to update @t{guile}'s @code{%load-path} to find it
+there. You can check the current @code{%load-path} with the following:
 
 @example
 guile -c '(display %load-path)(newline)'
 @end example
 
-If necessary, you can add the @t{%load-path} by adding something like the
+If necessary, you can add the @t{%load-path} by adding to your
-following to your @file{~/.guile}:
+@file{~/.guile}:
 
 @lisp
 (set! %load-path (cons "/usr/local/share/guile/site/2.0" %load-path))
@@ -153,24 +183,23 @@ Or, alternatively, you can set @t{GUILE_LOAD_PATH}:
 export GUILE_LOAD_PATH="/usr/local/share/guile/site/2.0"
 @end example
 
-Note, in both cases the directory should be the directory that contains the
+In both cases the directory should be the directory that contains the
-installed @t{mu.scm}; so if you installed @t{mu} under a different prefix, you
+installed @t{mu.scm}; if you installed @t{mu} under a different prefix, you
-must change the load-path accordingly.
+must change the @code{%load-path} accordingly. After this, you should be ready
+to go!
 
-After this, you should be ready to go.
+@node Making sure it works
-
+@section Making sure it works
-@node First steps
-@section First steps
 
 Assuming @t{mu-guile} has been installed correctly (@ref{Installation}), and
 also assuming that you have already indexed your e-mail messages (if
 necessary, see the @t{mu-index} man-page), we are ready to start @t{mu-guile};
 a session may look something like this:
 
+@cartouche
 @verbatim
-$ guile
+GNU Guile 2.0.5.123-4bd53
-GNU Guile 2.0.3.82-a2c66
+Copyright (C) 1995-2012 Free Software Foundation, Inc.
-Copyright (C) 1995-2011 Free Software Foundation, Inc.
 
 Guile comes with ABSOLUTELY NO WARRANTY; for details type `,show w'.
 This program is free software, and you are welcome to redistribute it
@@ -179,47 +208,58 @@ under certain conditions; type `,show c' for details.
 Enter `,help' for help.
 scheme@(guile-user)>
 @end verbatim
+@end cartouche
 
-Now, we need to load some of the @t{mu-guile} modules:
+@noindent
+Now, copy-paste the following after the prompt:
 
-@verbatim
+@cartouche
-scheme@(guile-user)> (use-modules (mu) (mu message))
+@lisp
-@end verbatim
+(use-modules (mu))
-
+(mu:initialize)
-This will load the basic modules for dealing with messages. After we have
+(for-each
-loaded the modules, we need to initialize the @t{mu-guile} system:
-
-@verbatim
-scheme@(guile-user)> (mu:initialize)
-@end verbatim
-
-When this is done, we can start querying the database. We discuss various
-methods and functions later in this manual, but just to give an example, let's
-get a list of the subjects of all messages that mention @emph{hello}:
-
-@verbatim
-scheme@(guile-user)> (for-each
     (lambda(msg)
        (format #t "Subject: ~a\n" (mu:subject msg)))
         (mu:message-list "hello"))
+@end lisp
+@end cartouche
+
+@noindent
+After pressing @key{Enter}, you should get a list of all subjects of messages
+that match @t{hello}: 
+
+@verbatim
+...
+Subject: RE: The Bird Serpent War Cataclysm
+Subject: Hello!
+Subject: Re: post-run tomorrow
+Subject: When all is lost
+...
 @end verbatim
 
-Note, the multi-lines in the example are only for readability; since it can be
+@noindent
-a bit uncomfortable to type long sequences at the 'REPL' (the Guile
+If all this works, congratulations! @t{mu-guile} is installed now, ready to
-command-line), we recommend using a tool like
+serve your every whim!
-Geiser@footnote{@url{http://www.nongnu.org/geiser/}}.
 
 @node Initializing mu-guile
 @chapter Initializing mu-guile
 
+In the previous, we have installed @t{mu-guile}, and in @ref{Making sure it works}
+tried some simple script, to make sure everything works as expected. In this
+and the following chapters, we take a closer look programming with
+@t{mu-guile}.
+
 It is possible to write separate programs with @t{mu-guile}, but for now we'll
 do things @emph{interactively}, i.e., from the Guile-prompt (``@abbr{REPL}'').
 
-We start our @t{mu-guile} session by starting @t{guile}:
+As we have seen, we start our @t{mu-guile} session by starting @t{guile}:
+
+@verbatim
+$ guile
+@end verbatim
 
 @cartouche
 @verbatim
-$ guile
 GNU Guile 2.0.5.123-4bd53
 Copyright (C) 1995-2012 Free Software Foundation, Inc.
 
@@ -234,27 +274,28 @@ scheme@(guile-user)>
 
 The first thing we need to do is loading the modules. All the basics are in
 the @t{(mu)} module, with some statistical extras in @t{(mu stats)}, and some
-graph plotting functionality in @t{(mu plot)}.
+graph plotting functionality in @t{(mu plot)}@footnote{@code{(mu plot)}
+requires the @t{gnuplot} program}.
 
-Let's simply load all of them:
+Let's load all of them:
 
 @verbatim
 scheme@(guile-user)> (use-modules (mu) (mu stats) (mu plot))
 @end verbatim
 
-Assuming you have installed everything correctly, the first time you do this,
+The first time you do this, @t{guile} will probably respond by showing some
-@t{guile} will probably respond by showing some message about compiling the
+messages about compiling the modules, and then return to you with another
-modules, and then return to you with another prompt.
+prompt. Before we can do anything with @t{mu guile}, we need to initialize the
-
-Before we can do anything with @t{mu guile}, we need to initialize the
 system. This goes like this:
 
 @verbatim
 scheme@(guile-user)> (mu:initialize)
 @end verbatim
 
-Which will use the default location of @file{~/.mu}. Or, instead, if you keep
+This opens the database for reading, using the default location of
-your @t{mu} data in a non-standard place:
+@file{~/.mu}. 
+
+If you keep your @t{mu} database in a non-standard place:
 
 @verbatim
 scheme@(guile-user)> (mu:initialize "/path/to/my/mu/")