[ex1][README] improve doc

appl/example1/README.md

@@ -12,12 +12,17 @@ to this example is the file `example1.cc` which is located in this folder.
 
 Two main orientations are considered for the quadrilaterals, for both of which
 a corresponding instance of the `QuadrilateralSampler` class is created.
-For example, we instantiate the sampler class for the second orientation with:
+For example, we instantiate an instance of this class by writing:
 
 ```cpp
-using QuadSampler = QuadrilateralSampler<worldDimension>;
+static constexpr int worldDimension = 3;
+
+using ctype = double;
 using Distro = std::normal_distribution<ctype>;
-QuadSampler quadSampler2(makeUniformPointSampler(domain),         // use a new point sampler instance!
+using QuadSampler = QuadrilateralSampler<worldDimension>;
+
+Box<ctype> domain(0.0, 0.0, 0.0, 1.0, 1.0, 1.0);
+QuadSampler quadSampler(makeUniformPointSampler(domain),         // point sampler that samples the center points of the quadrilaterals
                         Distro(toRadians(0.0), toRadians(5.0)),  // strike angle: mean value & standard deviation
                         Distro(toRadians(0.0), toRadians(5.0)),  // dip angle: mean value & standard deviation
                         Distro(0.5, 0.1),                        // edge length: mean value & standard deviation
@@ -28,22 +33,22 @@ The first constructor argument is a point sampler with which the center points o
 the quadrilaterals are sampled. Here we use uniformly sampled points in the unit
 cube, which is represented by an instance of the `Box` class,  stored in the
 variable `domain`. The second and third arguments define the distributions for
-the strike and dip angle, where in this case we use uniform distributions with
+the strike and dip angle (for details see the [class documentation][2]), where in this case we use uniform distributions with
 a mean value of 0° and a standard deviation of 5°. The fourth argument is the
 distribution to be used for sampling the edge lengths, while the last argument
 defines a minimum value below which the edge length must not fall.
 
-The quadrilaterals are then sampled from the two samplers `quadSampler1` and
+In the example, the quadrilaterals are sampled from the two samplers `quadSampler1` and
 `quadSampler2`, using the `()` operator:
 
 ```cpp
 auto quad = sampleIntoSet1 ? quadSampler1() : quadSampler2();
 ```
 
-In this example we use the boolean variable `sampleIntoSet1` to determine from
+Here, we use the boolean variable `sampleIntoSet1` to determine from
 which sampler we should sample the next quadrilateral (more details follow below).
 The variable `quad` holds a new candidate for an entity of the network, however,
-However, we want to enforce certain constraints such as a minimum distance between
+we want to enforce certain constraints such as a minimum distance between
 entities. For this we use instances of the `EntityNetworkConstraints` class and
 configure it as desired. For example, the constraints on entities of the same
 orientation are defined in this example as follows:
@@ -68,7 +73,7 @@ if (!constraintsOnSelf.evaluate(entitySet, quad))
 where `entityset1` and `entitySet2` are of type `std::vector<Quadrilateral>` and
 store all quadrilaterals that are accepted. The function `evaluate` of the
 `EntityNetworkConstraints` class evaluates the constraints for `quad` against all
-entities contained in `entitySet` and returns `true` only if there no violation of
+entities contained in `entitySet` and returns `true` only if no violation of
 any of the defined constraints has been found. After an admissible quadrilateral
 has been generated, the line
 
@@ -80,7 +85,7 @@ sampleIntoSet1 = !sampleIntoSet1;
 at the end of the loop makes sure that a quadrilateral of the other orientation
 is sampled next. In [Example 3][0] we will get to know how to use helper classes
 that store different entity sets and automatically sample from various sampler
-classes such that this does not have to be done manually.
+classes such that this can be written more easily.
 
 After the desired number of entities has been generated, the entities are cast
 into an entity network using the builder class:
@@ -101,5 +106,15 @@ writer.write("network", // filename of the .geo files (will add extension .geo a
              0.1);      // element size to be used
 ```
 
+Note that with the `EntityNetworkBuilder` class we have created a network that
+solely carries information about the fracture entities. We have not defined any
+domain in this example, the unit cube in the variable `domain` was only used to
+sample the center points of the quadrilaterals. Thus, the geometry files written
+by the `GmshWriter` also only contain data on the fracture entities. This can be
+used in contexts where one is only interested in the fractures. In the following
+examples we will see how to construct fracture networks embedded in one or more
+(sub-)domains.
+
 [0]: https://git.iws.uni-stuttgart.de/DennisGlaeser/frackit/tree/master/appl/example3
 [1]: http://gmsh.info/
+[2]: https://git.iws.uni-stuttgart.de/DennisGlaeser/frackit/blob/master/frackit/sampling/quadrilateralsampler.hh