diff --git a/doc/userdoc.org b/doc/userdoc.org
index db900f9b000b77a91b86e41899913e0cbcef3e36..e34c7c8db15bc611cb08795810f7a2b08c8d5c33 100644
--- a/doc/userdoc.org
+++ b/doc/userdoc.org
@@ -2567,7 +2567,7 @@ as ${(x^y)}^z$. Thus, using the ~pow~ function avoids any confusion.
 
 *** The ~mesh~ module
 
-This is an important module. It provide mesh utilities tools.
+This is an important module. It provides mesh utilities tools.
 #+NAME: get-module-info-mesh
 #+BEGIN_SRC pugs :exports both :results output
   cout << getModuleInfo("mesh") << "\n";
@@ -2832,7 +2832,7 @@ is built only once. This means that is one writes for instance
   let dual_mesh_1:mesh, dual_mesh_1 = diamondDual(primal_mesh);
   let dual_mesh_2:mesh, dual_mesh_2 = diamondDual(primal_mesh);
 #+END_SRC
-then the meshes ~dual_mesh_1~ and ~dual_mesh_2~ will refer to the same
+then the variables ~dual_mesh_1~ and ~dual_mesh_2~ will refer to the same
 ~mesh~ in memory.
 #+END_note
 
@@ -2939,9 +2939,17 @@ The result of the previous script is given on Figure [[fig:transformed]].
 ***** ~relax: mesh*mesh*R -> mesh~
 
 This function is a simple utility that computes a ~mesh~ as the /mean/ of
-two other mesh that share the same connectivity. The connectivity must
-be the *same in memory*, this means that constructing two identical
-meshes with /equivalent/ connectivity is not allowed.
+two other mesh that share the same connectivity.  The coordinates of
+the vertices of the relaxed mesh $\mathcal{M}_2$, are given by
+\begin{equation*}
+\forall r\in\mathcal{R},\quad\mathbf{x}_r^{\mathcal{M}_2} =  (1-\theta) \mathbf{x}_r^{\mathcal{M}_0} + \theta \mathbf{x}_r^{\mathcal{M}_1}.
+\end{equation*}
+
+#+BEGIN_warning
+The connectivity must be the *same in memory*, this means that
+constructing two identical meshes with /equivalent/ connectivity is not
+allowed.
+#+END_warning
 
 Thus for instance, the following code
 #+NAME: relax-with-similar-connecticities
@@ -2971,14 +2979,9 @@ let m2: mesh, m2 = relax(m0, m1, 0.3);
 write_mesh(gnuplot_writer("relax_example_m2", 0), m2);
 #+END_SRC
 
-In this example, the relaxation parameter is set to $\theta=0.3$, this
-means that the coordinates of any vertex of the relaxed mesh
-$\mathcal{M}_2$, are given by
-\begin{equation*}
-\forall r\in\mathcal{R},\quad\mathbf{x}_r^{\mathcal{M}_2} =  (1-\theta) \mathbf{x}_r^{\mathcal{M}_0} + \theta \mathbf{x}_r^{\mathcal{M}_1}
-\end{equation*}
-
-The different meshes produced in this example are displayed on Figure [[fig:relax]].
+In this example, the relaxation parameter is set to $\theta=0.3$.  The
+different meshes produced in this example are displayed on Figure
+[[fig:relax]].
 
 #+NAME: relax-img
 #+BEGIN_SRC gnuplot :exports results :file (substitute-in-file-name "${PUGS_SOURCE_DIR}/doc/relax.png")
@@ -3000,7 +3003,8 @@ The different meshes produced in this example are displayed on Figure [[fig:rela
 #+RESULTS: relax-img
 
 This function is mainly useful to reduce the displacement of nodes
-when using the ~randomizeMesh~ functions (see section [[scheme]]).
+when using the ~randomizeMesh~ functions (see section [[scheme]]) for
+instance.
 
 **** The ~scheme~ module<<scheme>>