more detailed usage examples. As for the rest of the documentation
(and of SimGrid, actually), any contribution is welcome.
+@section howto_churn How to model churn
+
+One of the biggest challenges in P2P settings is to cope with the
+churn, meaning that resources keep appearing and disappearing. In
+SimGrid, you can always change the state of each host manually, with
+eg simgrid::s4u::Host::on(). To reduce the burden when the churn is
+high, you can also attach a **state profile** to the host directly.
+
+This is not possible from S4U yet (TODO), and you should use the \c
+state_file attribute of @ref pf_tag_host or @ref pf_tag_cluster.
+
+Every lines (but the last) of such files describe timed events with
+the form "date value". Example:
+
+~~~{.py}
+ 1 0
+ 2 1
+ LOOPAFTER 8
+~~~
+
+ - At time t=1, the host is turned off (value 0 means OFF)
+ - At time t=2, it is turned back on (other values means ON)
+ - At time t=10, the history is reset (because that's 8 seconds after
+ the last event). So the host will be turned off again at t=11.
+
+If your trace does not contain a LOOPAFTER line, then your profile is
+only executed once and not repetitively.
+
+@section howto_multicore How to model multicore machines
+
+Multicore machines are very complex, and there is many way to model
+them. The default models of SimGrid are coarse grain and capture some
+elements of this reality. Here is how to declare simple multicore hosts:
+
+@code{xml}
+ <host id="mymachine" speed="8Gf" core="4"/>
+@endcode
+
+It declares a 4-cores host called "mymachine", each core computing 8
+GFlops per second. If you put one activity of 8 GFlop on this host, it
+will be computed in 1 second (by default, activities are
+single-threaded and cannot leverage the computing power of more than
+one core). If you put two of them together, they will still be
+computed in one second, and so on up to 4 tasks. If you put 5 tasks,
+they will share the total computing resource, and all tasks will be
+computed at 5/4 = 1.25 second. That's a very simple model, but that's
+all what you will get by default from SimGrid.
+
+@subsection howto_multicore_pinning Pinning tasks to cores
+
+This model does not account for any sort of resource reservation such
+as task pinning (where you manually select on which core each of the
+existing activity should execute). If you want to go that way, the
+best is probably to model you 4-core processor as 4 separte hosts, and
+assigning the activities to cores by migrating them to the declared
+hosts. In some sense, this is takes the whole Network-On-Chip idea
+really seriously.
+
+Some extra complications may arise if you go that way. If you have
+more tasks than cores, you'll have to [schedule your
+tasks](https://en.wikipedia.org/wiki/Scheduling_%28computing%29#Operating_system_process_scheduler_implementations)
+yourself on the cores (so don't do that if you can avoid). Since you
+cannot have more than one network model, you will end up with a TCP
+connexion between your cores. You probably want to work this around in
+your application by never starting any simulated communication between
+your cores. Instead, connect equally all cores to the external
+network.
+
+Modeling a multicore CPU as a set of SimGrid hosts may seem strange
+and unconvincing, but some users achieved very realistic simulations
+of multi-core and GPU machines this way.
@section howto_bootenergy Modeling machine bootup and shutdown periods
