Feature doc installation: add to doxygen page

doc/doxygen/installation.dox

@@ -20,10 +20,13 @@
  *
  * Once the package lists are updated, you can install `p4est` using `apt-get`.
  *
- * > `sudo apt-get install libp4est-VERSION`
+ * > `sudo apt-get install libp4est-<VERSION>`
  *
  * The available version can be found in the
- * [debian package tracker](https://packages.qa.debian.org/p/p4est.html)
+ * [debian package tracker](https://packages.qa.debian.org/p/p4est.html),
+ * or by running
+ *
+ * > `apt-cache search p4est`
  *
  * \section tarbuild Installing p4est from a .tar.gz archive
  *
@@ -34,11 +37,12 @@
  * The `configure` script from the toplevel directory of the unpacked tar file
  * can be executed as is.
  * We recommend to create an empty build directory.
- * \subsection steps1 Step-by-step Guide
+ *
+ * \subsection steps1 Step-by-step guide
  *
  * \subsubsection unpack_tarball 1. Unpack the tarball
  *
- * > `tar -xzf p4est-VERSION.tar.gz`
+ * > `tar -xzf p4est-<VERSION>.tar.gz`
  *
  * \subsubsection create_dir 2. Create and change into a build directory
  *
@@ -48,48 +52,62 @@
  *
  * \subsubsection run_script 3. Run the configure script
  *
- * > `../p4est-VERSION/configure`
+ * > `../p4est-<VERSION>/configure --help`
+ *
+ * > `../p4est-<VERSION>/configure --enable-mpi --etc...`
+ *
+ * You may also set environment variables like `CFLAGS="-Wall -g"`.
  *
  * \subsubsection complile_software 4. Compile the software
  *
- * > `make -j`
+ * > `make -j V=0`
+ *
+ * The environment variable `V=0` suppresses most of `make`'s console output.
+ *
+ * \subsubsection install_software 5. Install the software (optional)
  *
- * \subsubsection install_software 5. Install the software
+ * > `make install V=0`
  *
- * > `make install`
+ * The software is installed by default into the prefix `./local`.
+ * This can be changed by setting `configure --prefix=<PATH>`.
  *
  * \section install Building from source on Unix-like systems
+ *
  * For a more hands-on approach, consider cloning the
- *   p4est GitHub repository. You'll need familiarity with the revision control
- *   tool `git` or its GUI frontends. The branch `prev3-develop` is recommended
- *   as it has minimized dependencies and houses the latest algorithms. To
- *   generate the configure script, call the `./bootstrap` script in the p4est
- *   top-level source directory. This requires a working installation of GNU
- *   autoconf, automake, and libtool.
+ * p4est GitHub repository. You'll need familiarity with the revision control
+ * tool `git` or its GUI frontends. The branch `develop` is recommended
+ * as it has minimized dependencies and houses the latest algorithms. To
+ * generate the configure script, call the `./bootstrap` script in the p4est
+ * top-level source directory. This requires a working installation of GNU
+ * autoconf, automake, and libtool.
  *
  * \subsection prerequisites Prerequisites
- * - For the installation from source, we suggest using the autotools. Ensure you
- *   have:
- *   - \p automake
- *   - \p autoconf
- *   - \p libtool
- *   - \p make
+ * - For the installation from source, we still prefer the autotools
+ *   over the CMake system (which has recently been added).
+ *   Ensure you have:
+ *   - \c automake
+ *   - \c autoconf
+ *   - \c libtool
+ *   - \c make
  *
- * \subsection optional Optional Components
- * - For enhancing parallel processing, having \p MPI is advisable.
+ * \subsection optional Optional components
+ * - For enhancing parallel processing, having \c MPI is advisable
+ *   and configuring `--enable-mpi`.
  *
- * \subsection steps2 Step-by-step Guide
+ * \subsection steps2 Step-by-step guide
  *
- * \subsubsection source_retrieval 1. Source Retrieval
+ * \subsubsection source_retrieval 1. Source retrieval
  *
  * > `git clone https://github.com/cburstedde/p4est.git`
  *
- * \subsubsection bootstrap 2. Bootstrap Execution
+ * \subsubsection bootstrap 2. Bootstrap execution
  *
- * Navigate to the \p p4est directory and initiate the bootstrap script,
+ * Navigate to the \c p4est directory and initiate the bootstrap script,
  * especially if you've cloned it from GitHub:
  *
- * > `cd p4est` `./bootstrap`
+ * > `cd p4est`
+ *
+ * > `./bootstrap`
  *
  * \subsubsection setup 3. Setting up p4est
  *
@@ -102,11 +120,12 @@
  *
  * > `../p4est/configure [OPTIONS]`
  *
- * The \p configure script is quite versatile and has multiple options, among
+ * The \c configure script is quite versatile and has multiple options, among
  * them:
+ *
  * - `--enable-debug`: Activates debugging mode, increasing verbosity and turns
  *   on `P4EST_ASSERT` for checks.
- * - `--enable-mpi`: This integrates the mpi.h header and triggers MPI compiler
+ * - `--enable-mpi`: This integrates the `mpi.h` header and triggers MPI compiler
  *   wrappers. Without this option, MPI routine wrappers are employed for serial
  *   compilation.
  * - `--disable-mpiio`: This avoids using `MPI_File` based calls.
@@ -118,43 +137,59 @@
  * prints a list of currently available options to configure.
  *
  * A common developer-oriented configuration might resemble:
- * > relative/path/to/configure CFLAGS="-Wall -Wuninitialized -O0 -g"
- * > --enable-mpi --enable-debug
+ *
+ * > `relative/path/to/configure CFLAGS="-Wall -Wuninitialized -O0 -g" --enable-mpi --enable-debug`
  *
  * While a production-oriented configuration could be:
- * > relative/path/to/configure CFLAGS="-Wall -Wno-unused-but-set-variable -O2"
- * > --enable-mpi
  *
- * \subsubsection compile 4. Compiling p4est After configuration, the next step
- * is the compilation of \p p4est:
+ * > `relative/path/to/configure CFLAGS="-Wall -Wno-unused-but-set-variable -O2" --enable-mpi`
+ *
+ * \subsubsection compile 4. Compiling p4est
  *
- * > `make -j`
+ * After configuration, the next step is the compilation of \c p4est:
  *
- * > `make install -j`
+ * > `make -j V=0`
  *
- * \subsubsection verification 5. Verification Step It's recommended to execute
- * the \p p4est test programs post-installation to ensure everything is in
- * order:
- * > `make check`
+ * > `make install -j V=0`
  *
- * \subsubsection api_docs 6. Autogenerated API Documentation
+ * \subsubsection verification 5. Verification Step
+ *
+ * It's recommended to execute the \c p4est test programs post-installation
+ * to ensure everything is in order:
+ *
+ * > `make -j4 check V=0`
+ *
+ * Where the `-j` option limits parallel make to at most four targets at the same time.
+ *
+ * \subsubsection api_docs 6. Autogenerated API documentation
  *
  * The Doxygen output for p4est and libsc can be recreated with the following
  * command after the configuration process:
  *
  * > `make doxygen`
  *
- * \subsubsection integration 7. Integrating with p4est For projects aiming to
- * incorporate \p p4est as an external library:
- * > `export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/p4est_install/lib` Append to
- * the compile command: `-I$HOME/p4est_install/include -L$HOME/p4est_install/lib
- * -lp4est -lm`
+ * This requires the doxygen program and produces html, latex and man format
+ * documentation under `doc`.
+ *
+ * \subsubsection integration 7. Integrating with p4est
+ *
+ * For projects aiming to incorporate \c p4est as an external library
+ *
+ * > `export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/p4est_install/lib`
+ *
+ * to be able to run built executables that dynamically link to p4est.
+ * Append to the compile command:
+ *
+ * > `-I$HOME/p4est_install/include -L$HOME/p4est_install/lib -lp4est -lsc -lz -lm`
+ *
+ * For full functionality, we expect a zlib that provides the function
+ * `adler32_combine`.
  *
  * \section further Further information and links
  *
- * You may also find a detailed documentation for installation on both
- * [Linux](https://github.com/cburstedde/p4est/blob/prev3-develop/INSTALL) and
- * [Windows](https://github.com/cburstedde/p4est/blob/prev3-develop/INSTALL_WINDOWS)
+ * You may find further documentation for installation on both
+ * [Linux](https://github.com/cburstedde/p4est/blob/develop/INSTALL) and
+ * [Windows](https://github.com/cburstedde/p4est/blob/develop/INSTALL_WINDOWS)
  * in the source folder.
  *
  * For users with Windows 10 version 2004 and higher, you may also try