-Don't forget to run the "make distcheck" target after any modification
-to the cmake files: it checks whether all necessary files are present
-in the distribution.
-
-\section cmake_dev_guide_ex How to add examples?
-
-First of all, are you sure that you want to create an example, or is
-it merely a new test case? The examples located in examples/ must be
-interesting to the users. It is expected that the users will take one
-of these examples and start editing it to make it fit their needs. If
-what you are about to write is merly a test, exercising a specific
-part of the tool suite but not really interesting to the users, then
-you want to add it to the teshsuite/ directory.
-
-Actually, the examples are also used as regresion tests by adding tesh
-files and registering them to the testing infrastructure (for that,
-don't forget to add a tesh file and follow the instructions of
-section \ref inside_cmake_addtest). The main difference is that
-examples must be interesting to the users in addition.
-
-In both cases, you have to create a CMakeList.txt in the chosen source
-directory. It must specify where to create the executable, the source
-list, dependencies and the name of the binary.
+Once you're done, you must run "make distcheck" to ensure that you did not forget to add any file to the distributed
+archives. This ensures that everything was commited correctly, so you have to first commit before running
+"make distcheck". If you forgot something, you want to "git commit --amend". But never amend a commit that you already
+pushed to public repositories! Do a second commit in that case.
+
+\section inside_cmake_examples How to add an example?
+
+The first rule is that the content of examples/ must be interesting to the users. It is expected that the users will
+take one of these examples and start editing it to make it fit their needs. So, it should be self-contained,
+informative, and should use only the public APIs.
+
+To ensure that all examples actually work as expected, every example is also used as an integration test (see
+@ref inside_tests), but you should still strive to keep the code under examples/ as informative as possible for the
+users. In particular, torture test cases should be placed in teshsuite/, not examples/, so that the users don't stumble
+upon them by error.
+
+To add a new example, the first thing is to find the right place to add it. The examples/ directory is organized as
+follows:
+ - examples/java/ for examples using the Java bindings to the MSG API. This directory contains packages (app, async,
+ cloud, ...) which in turn contain individual examples. If your new example fits in an existing package, add it here,
+ or create a new package otherwise.
+ - examples/msg/ for examples using the MSG API. Here the naming convention is package-example (e.g., app-masterworker).
+ Again, please try to fit to an existing package before creating a new one.
+ - examples/platforms/ only contains platforms descriptions in the XML format (see @ref platform for details)
+ - examples/s4u/ for examples using the emerging S4U API
+ - examples/simdag/ for examples using the SimDag API
+ - examples/smpi/ or examples using the SMPI API
+
+In each of these directories, there is a CMakeLists.txt file that has to be edited to include the new examples. For
+instance, examples/msg/CMakeLists.txt starts with a loop over all the (currently) existing tests in which we
+ - compile and link the source file (which has to be named as the directory
+ - add the source and tesh files to the distribution.