diff --git a/doc/userdoc.org b/doc/userdoc.org
index 9d602b398b99193f6568ecb534ff0ebc425e8205..f3e7ce3171053c72aad5474b3bec902dd230cc6c 100644
--- a/doc/userdoc.org
+++ b/doc/userdoc.org
@@ -2451,9 +2451,9 @@ The output contains also ~git~ information
 *****  ~resetRandomSeed: void -> void~
 
 At the start of ~pugs~, a *common* random seed is defined for all ~MPI~
-processes. The seed is written automatically written in the preamble
-of the listing (in the documentation the ~--no-preamble~ option is used
-this is why it is not displayed in examples).
+processes. The seed is automatically written in the preamble of the
+listing (in the documentation the ~--no-preamble~ option is used this is
+why it is not displayed in examples).
 
 The ~resetRandomSeed~ creates a *new shared* random and displays its value.
 #+NAME: reset-random-seed
@@ -2581,14 +2581,18 @@ This is an important module. It provides mesh utilities tools.
 The ~boundary~ type is a boundary descriptor: it refers to a boundary of
 a ~mesh~ that is either designated by an integer or by a ~string~.
 
-A ~boundary~ can be used refer to an interface, it can designate a set
-of nodes, edges or faces. The ~boundary~ (descriptor) itself is not
-related to any ~mesh~, thus the nature of the ~boundary~ is precised when
-it is used with a particular ~mesh~.
+A ~boundary~ can designate a set of nodes, edges or faces. The ~boundary~
+(descriptor) itself is not related to any ~mesh~, thus the nature of the
+~boundary~ is precised when it is used with a particular ~mesh~.
+
+#+BEGIN_warning
+A ~boundary~ *cannot* be used to refer to an interface (/ie/ an inner set of
+items)..
+#+END_warning
 
 ***** ~zone~
 
-Following the same idea, a ~zone~ is a descriptor of set of cells. It
+Following the same idea, a ~zone~ is a descriptor of a set of cells. It
 can be either defined by an integer or by a ~string~. Its meaning is
 precised when it is associated with a ~mesh~.
 
@@ -2893,7 +2897,7 @@ available in parallel
 
 ***** ~transform: mesh*function -> mesh~
 
-This function allows to compute a new mesh as the transformation a
+This function allows to compute a new mesh as the transformation of a
 given mesh by displacing its nodes through a user defined function.
 
 For a mesh of dimension $d$, the mesh must be a function $\mathbb{R}^d
@@ -2914,12 +2918,14 @@ write_mesh(gnuplot_writer("transformed"), m1);
 #+END_SRC
 
 #+BEGIN_note
-One should keep in mind that the mesh produced the ~transform~ function
-*shares* the same connectivity than the given mesh. This means that in
-~pugs~ internals, there is only one connectivity object.
+One should keep in mind that the mesh produced by the ~transform~
+function *shares* the same connectivity than the given mesh. This means
+that in ~pugs~ internals, there is only one connectivity object for
+these two meshes.
 #+END_note
 
-The result of the previous script is given on Figure [[fig:transformed]].
+The result of the previous script is given on Figure
+[[fig:transformed]]. They all share the same connectivity in memory.
 
 #+NAME: transformed-img
 #+BEGIN_SRC gnuplot :exports results :file (substitute-in-file-name "${PUGS_SOURCE_DIR}/doc/transformed.png")
@@ -3042,7 +3048,7 @@ The type of values in each cells for a $\mathbb{P}_0$ function can be
 $\mathbb{R}$, $\mathbb{R}^1$, $\mathbb{R}^2$, $\mathbb{R}^3$,
 $\mathbb{R}^{1\times1}$, $\mathbb{R}^{2\times2}$ or $\mathbb{R}^{3\times3}$.
 
-For simplicity in this document, we denote these types specific
+For simplicity in this document, we denote these specific
 $\mathbb{P}_0$ types as $\mathbb{P}_0(\mathbb{R})$,
 $\mathbb{P}_0(\mathbb{R}^1)$, $\mathbb{P}_0(\mathbb{R}^2)$,
 $\mathbb{P}_0(\mathbb{R}^3)$, $\mathbb{P}_0(\mathbb{R}^{1\times1})$,
@@ -3330,7 +3336,7 @@ Let us give an example.
 
   let uh:Vh, uh = interpolate(m, P0(), u);
 #+END_SRC
-In this exampel the discrete function ~uh~ is a
+In this example the discrete function ~uh~ is a
 $\mathbb{P}_0(\mathbb{R}^3)$ function defined on a 2d ~mesh~. The ~P0()~
 function returns the type of interpolation ($\mathbb{P}_0$).
 
@@ -3473,7 +3479,7 @@ function as a list of user function, the previous function
 ****** ~integrate: mesh*(zone)*quadrature*function -> Vh~
 
 This function is an enhancement of the function defined in
-[[integrate-classic]]. It allow to specify a ~zone~ list which defines the
+[[integrate-classic]]. It allows to specify a ~zone~ list which defines the
 set of cells where the integration is operated.
 
 #+BEGIN_SRC shell :exports results :results none
@@ -3561,18 +3567,18 @@ sets of cells where to integrate the list of user functions.
 
 ***** Random mesh generators
 
-For numerical it is often useful to create meshes with random vertices
-positions. This is the aim of the functions that are described in this
-section. These function share some properties.
+For numerical tests purpose, it is often useful to create meshes with
+random vertices positions. This is the aim of the functions that are
+described in this section. These function share some properties.
 - The generate mesh is always suitable for calculations in the sense
   that cells volumes are warrantied to be positive.
 - Generated cells can be non-convex.
 - One has to specify boundary conditions to drive the mesh
   displacement on boundaries.
 - The obtained mesh does not depend on parallelism: it is exactly the
-  same whichever is the number of ~MPI~ processes. It only depends on
-  the random seed (see paragraph [[set-random-seed]] how to set the random
-  seed to obtain the exact same mesh through different runs).
+  same whichever the number of ~MPI~ processes is. It only depends on
+  the random seed (see in paragraph [[set-random-seed]] how to set the
+  random seed to obtain the exact same mesh through different runs).
 
 ****** ~randomizeMesh: mesh*(boundary_condition) -> mesh~
 
@@ -3586,7 +3592,7 @@ The supported boundary conditions are the following:
 - ~symmetry~: the vertices are displaced in the plane formed by the
   ~boundary~
 One should refer to the section [[boundary-condition-descriptor]] for a
-description of the boundary condition descriptors.
+documentation of the boundary condition descriptors.
 
 #+BEGIN_note
 Let us precise these boundary conditions behavior
@@ -3652,7 +3658,7 @@ Running this script one gets the ~mesh~ displayed on Figure
 ****** ~randomizeMesh: mesh*(boundary_condition)*function -> mesh~
 
 This function is a variation of the previous one. It allows
-additionally to provide a characteristic function that designates the
+to additionally provide a characteristic function that designates the
 vertices that can be displaced.
 
 The characteristic function *must* be a function of $\mathbb{R}^d
@@ -3719,7 +3725,7 @@ This allows for instance to build a random mesh step-by-step.
 
 ***** Boundary condition descriptors <<boundary-condition-descriptor>>
 
-In this paragraph, we describe the set of boundary condition
+In this paragraph, we discuss the set of boundary condition
 descriptors that are provided by the ~scheme~ module.
 
 #+BEGIN_note
@@ -3783,8 +3789,12 @@ chosen inside the script.
 #+BEGIN_warning
 While ~pugs~ is written to deal with general polygonal and polyhedral
 meshes, quadrature formulas are not yet implemented on the general
-elements. Supported elements are triangles, quadrangles, tetrahedra
+elements. Supported elements are triangles, quadrangles, tetrahedra,
 pyramids, prisms and hexahedra.
+
+For completeness, let us state that they are also available for
+diamond cells that can be decomposed into two tetrahedra or two
+pyramids.
 #+END_warning
 
 ****** ~Gauss: N -> quadrature~
@@ -4022,7 +4032,7 @@ Additionally these operators are defined
     \mathtt{*}: \mathbb{V}_h \times  \mathbb{S}\to \mathbb{V}_h.
   \end{equation*}
 #+end_src
-Following logic, if for instance the right operand is an ~R^2~
+Following the logic, if for instance the right operand is an ~R^2~
 expression, the left operand ~Vh~ must be of type
 $\mathbb{P}_0(\mathbb{R})$ or $\mathbb{P}_0(\mathbb{R}^{2\times 2})$.
 
@@ -4131,7 +4141,7 @@ different.
 ***** ~writer~
 
 Variables of this type manage outputs: which format is used and
-eventually writing policy. This policy sets for instance the time
+eventually the writing policy. This policy sets for instance the time
 period of for time dependent post processing.
 
 **** ~writer~ provided functions
@@ -4270,7 +4280,7 @@ There is two ~gnuplot~ writers. One is dedicated to output of dimension
 dimension 1 and 2 (~gnuplot_writer~).
 
 Both of these writers can be used for single output or time series
-output. In the case of single output, the filename is completed by
+outputs. In the case of single output, the filename is completed by
 adding the extension ~.gnu~, in the case of time series, the filename is
 extending by adding ~.abcd.gnu~, where ~abcd~ is the number of the output
 in the series.
@@ -4284,11 +4294,11 @@ which is warrantied by ~pugs~ for explicit methods).
 #+END_note
 
 For an obvious practical reason, each ~gnuplot~ file starts with a
-preamble that indicates running information.
+preamble that indicates the running information.
 
-This information contains, the production date of the file. The ~pugs~
+This information contains, the production date of the file, the ~pugs~
 version (including the hash key of the last commit) and a summary of
-the output data to easy its use. For ~gnuplot~ files, this is the
+the output data to ease its use. For ~gnuplot~ files, this is the
 location where the provided name (to the discrete function) is used.
 
 In the case of time series the "physical" time of output is also
@@ -4307,9 +4317,9 @@ This writer family make only sense in 1d.
 
 #+BEGIN_note
 In parallel, as soon as the saved data themselves are the same, the
-~gnuplot_1d_writer~ generates *exactly* the same files since the
-coordinates of the post processed data are sorted according to growing
-abscissa.
+~gnuplot_1d_writer~ generates *exactly* the same files (whichever is the
+number of processors) since the coordinates of the post processed data
+are sorted according to growing abscissa.
 #+END_note
 
 ******* ~gnuplot_1d_writer: string -> writer~
@@ -4439,11 +4449,11 @@ times:
 
 ****** ~gnuplot_writer~ functions <<gnuplot-writer-function>>
 
-This writer differs from the previous one since it draws the cells and
-affects the cell value to the nodes. This produces larger files but
-allow 2d representation. Also, if the saved data is exactly the same
-in parallel, the order of the cells is generally different since they
-are written processor by processor.
+These writers differ from the previous ones since it draws the cells
+and affects the cell value to its nodes. This produces larger files
+but allows 2d representations. Also, if the saved data is exactly the
+same in parallel, the order of the cells is generally different since
+they are written processor by processor.
 
 Additionally, this writer allows to write 2d meshes, see paragraph
 [[write-mesh]].
@@ -4542,9 +4552,9 @@ performance reasons. For each time step a ~pvtu~ file is generate to
 handle parallelism. And for a complete time series, a ~pvd~ file is
 produced. This is the file that should be loaded.
 
-Observe that each of these files (~vtu~, ~pvti~ and ~pvd~) contains a
-comment that contains the creation date and the version of ~pugs~ that
-was run.
+Observe that each of these files (~vtu~, ~pvtu~ and ~pvd~) contains a
+comment that stores the creation date and the version of ~pugs~ that was
+run.
 
 The use is exactly the same than for ~gnuplot~ writers so we do not
 provide full examples.
@@ -4566,16 +4576,16 @@ the provided ~string~.
 
 ***** ~write~, ~force_write~ and ~write_mesh~ functions
 
-One a mesh writer has been defined, these functions are called to
+Once a mesh writer has been defined, these functions are called to
 effectively generate the post processing files.
 
 ****** ~write: writer*(output) -> void~
 
-As a parameter, it takes a ~writer~ that is not a time series one and a
+As parameters, it takes a ~writer~ that is not a time series one and a
 list of ~output~ (which are named discrete functions that are defined on
 the *same* mesh).
 
-There have already shown a lot of examples of use of the ~write~
+We have already shown a lot of examples of use of the ~write~
 function. So let us focus on improper calls.
 
 Trying to use a time series ~writer~
@@ -4717,16 +4727,16 @@ The last post processing time is now 1.
 ****** ~write_mesh: writer*mesh -> void~ <<write-mesh>>.
 
 This function just saves a ~mesh~ using a ~writer~. The ~gnuplot_1d_writer~
-cannot write mesh. And the ~writer~ argument must not be time series
+cannot write mesh. And the ~writer~ argument must be a non time series
 ~writer~.
 
 
 *** The ~socket~ module
 
-This module is more dedicated to developers that intend to drive ~pugs~
-or to couple it to other codes using sockets.
+This module is more dedicated to developers that intend to couple ~pugs~
+to other codes using sockets.
 
-We describe here language utilities that can be useful but effective
+We describe here language utilities that can be useful, but effective
 coupling generally requires ~C++~ coding.
 
 Here is the list of the functions and types that the module provides.
@@ -4758,7 +4768,7 @@ For instance running the following code
 #+END_SRC
 gives
 #+RESULTS: print-socket
-The output uses the classical format: ~machine_nam:port_number~.
+The output uses the classical format: ~machine_name:port_number~.
 
 **** ~socket~ provided functions