diff --git a/docs/Makefile b/docs/Makefile
index 1542062499f623adeed5d6c623c49e473f69c84e..e1457cd191a231ecb46cacf98ece47348e609dfe 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -2,10 +2,10 @@
 #maruku=ruby -I~/maruku/lib ~/maruku/bin/maruku
 maruku=maruku
 
-out=out/csm_manual.pdf out/csm_manual.html
+out=csm_manual.pdf csm_manual.html
 
 all: $(out)
-
+	cp $(out) ..
 
 src=\
   preamble.txt \
@@ -15,14 +15,14 @@ src=\
   install-ruby.txt \
   laserdata.txt \
   formats.txt \
-  examples.txt 
+  examples.txt \
+  embedding.txt
 
 
 %: tmp_%
 	cp $< $@
 
-out/csm_manual.txt: $(src)
-	mkdir -p out
+csm_manual.txt: $(src)
 	cat $^ > $@
 
 %.pdf: %.txt
diff --git a/docs/basic/Makefile b/docs/basic/Makefile
new file mode 100644
index 0000000000000000000000000000000000000000..c32cba3f7d83b5aa12f947b01a1025e633364c43
--- /dev/null
+++ b/docs/basic/Makefile
@@ -0,0 +1,4 @@
+CSM_FLAGS=`pkg-config --libs --cflags csm`
+
+myprogram: myprogram.c
+	gcc $(CSM_FLAGS) -o myprogram myprogram.c
diff --git a/docs/basic/myprogram.c b/docs/basic/myprogram.c
new file mode 100644
index 0000000000000000000000000000000000000000..d07f1f0578faaa77ff445aa05b712731be763967
--- /dev/null
+++ b/docs/basic/myprogram.c
@@ -0,0 +1,5 @@
+#include <csm/csm_all.h>
+
+int main() {
+	
+}
\ No newline at end of file
diff --git a/docs/embedding.txt b/docs/embedding.txt
new file mode 100644
index 0000000000000000000000000000000000000000..79c036ed58d99c1685ed80cc71cfb2d14fe08feb
--- /dev/null
+++ b/docs/embedding.txt
@@ -0,0 +1,65 @@
+
+## Embedding CSM in your programs ##
+
+### Linking to CSM ###
+
+When CSM is installed, a [pkgconfig] ``csm.pc`` file is installed as well.
+This makes it easy to link to CSM. 
+
+[pkgconfig]: http://pkg-config.freedesktop.org/wiki/
+
+For example, on my system, after installing CSM, I can run ``pkgconfig`` to
+get the C preprocessors and linker flags.
+
+This is what I get on my system (on yours, paths will be different, of course).
+
+     $ pkg-config --cflags csm  
+       -I/sw/include -I/Users/andrea/svn/cds/csm/deploy/include/cairo
+       -I/Users/andrea/svn/cds/csm/deploy/include
+
+     $ pkg-config --libs csm 
+       -L/sw/lib -L/Users/andrea/svn/cds/csm/deploy/lib 
+       -lcsm-static -lgsl -lgslcblas -lm
+
+If you use GNU Make, a basic Makefile for your program linking to CSM
+would be something like:
+
+	CSM_FLAGS=`pkg-config --libs --cflags csm`
+
+	myprogram: myprogram.c
+		gcc $(CSM_FLAGS) -o myprogram myprogram.c
+
+You can download the sources for this example in the repository (directory `docs/example-linking-make`).
+
+If you use [CMake] --- and you should! --- it is reccomended that 
+you use something like the following in your ``CMakeLists.txt``.
+
+	cmake_minimum_required(VERSION 2.4)
+	project(myproject)
+
+	# Require we have pkgconfig installed
+	find_package(PkgConfig REQUIRED)
+	# Tell pkgconfig to look for CSM
+	pkg_check_modules(CSM REQUIRED csm)
+
+	IF(${CSM_FOUND})
+		MESSAGE("CSM_LIBRARY_DIRS: ${CSM_LIBRARY_DIRS}")
+		MESSAGE("CSM_LIBRARIES: ${CSM_LIBRARIES}")
+		MESSAGE("CSM_INCLUDE_DIRS: ${CSM_INCLUDE_DIRS}")
+
+		INCLUDE_DIRECTORIES(${CSM_INCLUDE_DIRS}) # important! 
+		LINK_DIRECTORIES(${CSM_LIBRARY_DIRS})    # important! 
+	ELSE(${CSM_FOUND})	
+		MESSAGE(FATAL_ERROR "CSM not found. Check that the environment \
+		variable PKG_CONFIG_PATH includes the path containing the file 'csm.pc'.")
+	ENDIF(${CSM_FOUND})		
+
+	add_executable(myprogram myprogram.c)
+
+	target_link_libraries(myprogram ${CSM_LIBRARIES}) # important! 
+
+You can download the sources for this example in the repository (directory `docs/example-linking-cmake`).
+
+[CMake]: http://www.cmake.org/
+
+
diff --git a/docs/examples.txt b/docs/examples.txt
index d1a4b522b25bcb3f31f08bbe992fd8d71e2ec34e..0b4321f413c863a937fdcec2840cfdd33bc646da 100644
--- a/docs/examples.txt
+++ b/docs/examples.txt
@@ -38,13 +38,16 @@ Create the animation:
 Actually, there are a million reasons for which it shouldn't work.
 If it gives strange results, try the following:
 
-1) Plot the data! Plot the input and plot the output using `log2pdf`.
-2) Plot the animation! Use the procedure above and inspect the resulting videos.
-3) Double-check the parameters you are using. Note that there are some like
+1. Plot the data! Plot the input and plot the output using `log2pdf`.
+
+2. Plot the animation! Use the procedure above and inspect the resulting videos.
+
+3. Double-check the parameters you are using. Note that there are some like
    `max_correspondence_dist` which depend on the scale of your data. A value
    of 2m might work for a big robot making large movements, but not for a little
    Khepera.
-4) Smooth your data -- if your sensor is very noisy, like an Hokuyo, it's worth
+
+4. Smooth your data -- if your sensor is very noisy, like an Hokuyo, it's worth
    to do simple low-pass filtering. Especially for PLICP which uses the orientation
    information.