Update documentation for simple examples

doc/examples.dox

@@ -21,57 +21,87 @@
   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
 
-/** \page Examples
- * Documentation page for example programs.
- *
- * * To begin with, consider the following example program that outputs
+/** \page Examples Documentation for selected example programs
+ *
+ * p4est is the name of both the software library and its central data type,
+ * a dynamic-adaptive forest of octrees partitioned in parallel.
+ * The library comes with various example programs under the subdirectory
+ * [example](https://github.com/cburstedde/p4est/tree/master/example).
+ * Most have both a 2D and a 3D version.
+ * When the library is configured `--enable-mpi`, they can all be run in
+ * parallel on any number of MPI ranks, even on small computers.
+ *
+ * One first helpful program to try out is called `p4est_simple` (2D version)
+ * and `p8est_simple` (3D version), both under
+ * [simple](https://github.com/cburstedde/p4est/tree/master/example/simple).
+ * We showcase some results further below on this page, and we encourage
+ * everyone to play with the command line arguments.
+ *
+ * ### The first step example
+ *
+ * Quite some time later, we created a range of step-by-step examples under
+ * [steps](https://github.com/cburstedde/p4est/tree/master/example/steps).
+ * Let us begin here with the first one that generates a mesh spelling
  * 'Hello, World!': \ref steps/p4est_step1.c.
  *
- *  This program performs refinement on a simple domain based on provided
- * image data. As a result, the output VTK file displays the phrase
- * 'Hello World' by the mesh.
+ *  This program performs refinement on a simple domain based on hardcoded
+ * image data.
+ * As a result, the output VTK file displays the phrase 'Hello World' by the
+ * mesh refinement.
  *
- *  Usage:
- *    > `p4est_step1`
- *  * No. of trees: 1
- *  * Maximum no. of level: 6
+ * Usage may be one of:
+ *
+ *  > `p4est_step1`
+ *  or with MPI:
+ *  > `mpirun -np 3 p4est_step1`
+ *
+ * * No. of trees: 1
+ * * Maximum refinement level: 6
  *
  *  \image html HW.png
  *
- * * Another illustrative example can be found in: \ref simple/simple2.c
+ * ### The historic simple example
  *
- *  This program creates/refines & coarsen/balances/partitions a internally
- * predefined geometry. As a result, the output VTK files display all
+ * Another illustrative example can be found in \ref simple/simple2.c.
+ * The refinement pattern is generated by some hardcoded prescriptions based
+ * on a quadrant's tree number, refinement level and coordinates.
+ * Please see the documentation under that link for a full list of configurations.
+ *
+ * This program creates/refines & coarsens/balances/partitions one
+ * of several available geometries specified on the command line.
+ * As a result, the output VTK files document all
  * the steps of the mesh manipulation process.
  *
  *  * Example: circle
  *
  *    Create a connectivity structure for an donut-like circle.
  * The circle consists of 6 trees connecting each other by their faces.
- * The trees are laid out as a hexagon between [-2, 2] in the y direction
- * and [-sqrt(3), sqrt(3)] in the x direction.  The hexagon has flat
+ * The trees are laid out as a hexagon between \f$[-2, 2]\f$ in the y direction
+ * and \f$[-\sqrt{3}, \sqrt{3}]\f$ in the x direction.  The hexagon has flat
  * sides along the y direction and pointy ends in x.
  *
  *    Usage:
  *    > `p4est_simple circle 5`
- *    or with mpi:
+ *    or with MPI:
  *    > `mpirun -np 4 p4est_simple circle 5`
+ *
  *    * No. of trees: 6
- *    * Maximum no. of level: 5
+ *    * Maximum refinement level: chosen on the command line as 5
  *
  *  \image html circle_balanced_lv5.png
  *
  *  * Example: drop
  *
  *    Create a connectivity structure for a five-trees geometry with a hole.
- * The geometry covers the square [0, 3]**2, where the hole is [1, 2]**2.
+ * The geometry covers the square \f$[0, 3]^2\f$, where the hole is \f$[1, 2]^2\f$.
  *
  *    Usage:
  *    > `p4est_simple drop 5`
- *    or with mpi:
- *    > `mpirun -np 4 p4est_simple drop 5`
+ *    or with MPI:
+ *    > `mpirun -np 7 p4est_simple drop 5`
+ *
  *    * No. of trees: 5
- *    * Maximum no. of level: 5
+ *    * Maximum no. of level: chosen on the command line as 5
  *
  *  \image html drop_balanced_lv5.png
  */