--- a
+++ b/website/faqsandhowtos/UnityLens.txt
@@ -0,0 +1,109 @@
+== Building and Installing the Ubuntu Unity Recoll Lens
+
+Important preliminary notes:
+
+- This only makes sense for Ubuntu versions using the Unity environment:
+ Natty (11.04), Oneiric (11.10), Precise (12.04), and later.
+- _Remember that you still need to use the recoll GUI (or the recollindex
+ //command) to get the indexing going !_
+- The Lens is artificially limited to showing at most 20 results. Use the
+ recoll GUI for more complete capabilities (or edit rclsearch.py, change
+ the "if actual_results >= 20:" line).
+
+
+=== The Lens with Recoll 1.17 and later
+
+If you are willing to install or upgrade to Recoll version 1.17, all
+necessary packages are on the Recoll PPA, you just need to add the
+repository to your system sources and add or upgrade the packages: *_/This
+is the recommended approach!_*
+
+----
+sudo add-apt-repository ppa:recoll-backports/recoll-1.15-on
+sudo apt-get update
+sudo apt-get install recoll-lens recoll
+----
+
+This document may still be useful if you want to modify the lens source
+code.
+
+=== The Lens with older Recoll versions
+
+If, for some reason, you wish to test the Lens with an older Recoll
+version, read the following.
+
+Please not that such an installation is somewhat crippled: you will not be
+able to display results for embedded documents (emails inside an mbox,
+attachments etc.). This requires a recoll command line option which is only
+available in 1.17
+
+The Lens is based on the Recoll Python module which is not built by default
+for versions prior to 1.17, so so you will first need to pull the Recoll
+source code (for you version), then untar and proceed with the
+configure/build instructions below.
+
+The following uses --prefix=/usr. I have no real reason to believe
+that this would not work with /usr/local (lenses are also searched there by
+default). If you confirm that things work with another prefix, please drop
+me a line.
+
+When doing this over a previous Recoll compilation, run a "make clean" to
+get rid of the non-PIC objects.
+
+Note that the following instructions change nothing to your existing Recoll
+installation, they only install the Python module and the Unity Lens,
+recoll, recollindex etc. are unaffected.
+
+'/TOP/OF/RECOLL/SRC' designates the top of the recoll source tree.
+
+=== Configure and build the recoll library and python module, install the module
+
+The following needs the development packages for Xapian, Python and zlib.
+
+----
+cd /TOP/OF/RECOLL/SRC
+# May fail if no previous build was performed
+make clean
+
+# the gui/x11 disabling is just here to avoid having to install the
+# development libraries for Qt.
+configure --prefix=/usr --enable-pic --without-x --disable-qtgui
+make
+
+cd python/recoll
+python setup.py build
+sudo python setup.py install
+----
+
+=== Build and install the Unity Lens
+
+----
+cd /TOP/OF/RECOLL/SRC
+cd desktop/unity-lens-recoll
+configure --prefix=/usr --sysconfdir=/etc
+sudo make install
+
+----
+
+Voil��, it should work...
+
+Try to start the Dash, you should see the Recoll checkerboard (or
+whatever...) in the Lens list.
+
+The Recoll Lens expects a Recoll query language string, so you can use
+field searches, directory, size, and date filtering (see the
+link:http://www.lesbonscomptes.com/recoll/usermanual/rcl.search.lang.html[Recoll
+manual] for a description of the query language).
+
+If you want to disable the Lens, I think that you just have to delete
+'/usr/share/unity/lenses/recoll'
+
+Other installed files:
+
+----
+/usr/libexec/unity-recoll-daemon
+/usr/share/dbus-1/services/unity-lens-recoll.service
+/usr/share/doc/unity-lens-recoll
+/usr/share/unity-lens-recoll
+----
+