--- a/src/README
+++ b/src/README
@@ -58,14 +58,12 @@
    help):
 
      * Support for the more advanced Xapian concepts like relevance feedback.
-     * An interactive configuration tool. You need to edit files by hand for
-       now.
-     * Packages, rpm or other. It's all tar files currently.
+     * An interactive configuration tool.
+     * Rpms or other kinds of packages.
      * A more polished user interface with online help and better
        documentation.
-     * Translations for the user interface.
+     * More translations for the user interface.
      * A few more filters for less common file types.
-     * An history tool for queries and documents.
      * Integration with the KDE desktop.
 
    I very much welcome suggestions or (gasp) code.
@@ -103,6 +101,30 @@
      * Installation
      * User manual
 
+Introduction: full text search.
+
+   A full text search program will let you search for data by specifying the
+   terms that you think appear in the content you are looking for.
+
+   You do not need to remember in what file or email message you stored a
+   given piece of information. You just ask for related terms, and the tool
+   will return a list of documents where those terms are prominent.
+
+   In addition, the tool will automatically expand your search to terms
+   related to the ones you specified. Ie: a search for floor will also look
+   for floors, flooring etc. With Recoll you can disable this expansion when
+   entering the query.
+
+   Recoll, like most such search tools, works by remembering where terms
+   appear in your document files. The acquisition process is called
+   indexation. The resulting database can be big (roughly the size of the
+   original documents in practise). This used to be a big issue, but it is
+   probably not any more, now that text documents are tiny blots among the
+   sea of multimedia data, especially for a personal system.
+
+   Recoll is not a document archive. It can only display data from files that
+   still exist where they lived when they were indexed.
+
 Using Recoll
 
   Indexation
@@ -111,27 +133,38 @@
    this, you need to edit the configuration file ($HOME/.recoll/recoll.conf).
    Follow the comments in the file to adjust the parameters.
 
-   Indexing is performed either by the recollindex program, or by the
+   Indexation is performed either by starting the recollindex program, or the
    indexing thread inside the recoll program (use the File menu).
+
+   It is best to avoid interrupting the indexation process, as this can leave
+   the database in a bad state. This is not a serious problem, as you then
+   just need to clear everything and restart the indexation. The database
+   files are stored in the $RECOLL_CONFDIR/xapiandb directory, which you can
+   just delete when needed.
 
   Simple search
 
-   Enter search term(s) in the text field at the top left. Clicking the
-   Search button or hitting the Enter key will start a search. By default,
-   this will look for documents with any of the terms (the ones with more
-   terms will get better scores). Use the Advanced search dialog for other
-   kinds of searches
+   Start the recoll program, then enter search term(s) in the text field at
+   the top left of the window. Clicking the Search button or hitting the
+   Enter key will start a search. By default, this will look for documents
+   with any of the terms (the ones with more terms will get better scores).
+   Use the Advanced search dialog for other kinds of searches
 
    A list of results will be displayed in the main list window. Clicking on
    an entry will open an internal preview window for the document.
    Double-clicking will attempt to start an external viewer (have a look at
    the ~/.recoll/mimeconf file to see how these are configured).
 
+   Documents that you actually view (with the internal preview or an external
+   tool) are entered into the document history, which is remembered. You can
+   display the history list by using the Tools / Doc History menu entry.
+
   Search tips, shortcuts
 
    Entering a capitalized word in any search field will prevent stem
    expansion (example: Recoll will not look for gardening if you enter Garden
-   instead of garden).
+   instead of garden). This is the only case where character case will make a
+   difference for a Recoll search.
 
    A phrase can be looked for by enclosing it in double quotes. Example:
    "user manual" will look only for occurrences of user immediately followed