add documentation about configuremake errors on unrecognized options

docs/easybuild-v5/enhancements.md

@@ -7,7 +7,6 @@ Various significant enhancements are included in EasyBuild v5.0, including:
 - [New function to run shell commands: `run_shell_cmd`][run_shell_cmd]
 - [Interactive debugging of failing shell commands via `env.sh` and `cmd.sh` scripts][interactive-debugging-failing-shell-commands]
 - [New collection of easyconfig templates][collection-easyconfig-templates]
-- [Don't raise error when required extensions are not found when installing extensions in parallel][parallel-extensions-install]
 - [Mark support for installing extensions in parallel as stable (no longer experimental)][parallel-extensions-install-stable]
 - [Mark easystack support as stable (no longer experimental)][easystack-stable]
 - [Reproducible tarballs for sources created via `git_config`][reproducible-tarballs-git_config]
@@ -76,13 +75,6 @@ status codes are reported in the corresponding logs.
 
 ---
 
-## Don't raise error when required extensions are not found when installing extensions in parallel {: #parallel-extensions-install }
-
-*(more info soon)*
-
----
-
-
 ## Mark support for installing extensions in parallel as stable (no longer experimental) {: #parallel-extensions-install-stable }
 
 *(more info soon)*
@@ -359,14 +351,31 @@ If the software uses the `.mod` extension for a different type of file then the
 
 ---
 
-## Let `ConfigureMake` generic easyblock error out on unrecognized `configure` options { : #configuremake-unrecognized-configure-options }
-
-*(more info soon)*
-
+## Let `ConfigureMake` generic easyblock error out on unrecognized `configure` options { : #configuremake-unknown-configure-options }
+
+The generic easyblock `ConfigureMake` in EasyBuild 5.0 will catch warnings from
+the `configure` command about unrecognized options being passed to it. Such
+options often reveal old configuration options that do not apply to the current
+version of the software being installed. Since `configure` just ignores
+unrecognized options, this situation can lead to misconfigured software and
+failures. Therefore, `ConfigureMake` will error out and stop the installation
+whenever such a warning is found.
+
+The following example shows the relevant log messages for such a case:
+
+```log
+== INFO Running shell command './configure --prefix=/software/MPICH/4.2.1-GCC-12.3.0  --build=x86_64-pc-linux-gnu  --host=x86_64-pc-linux-gnu FFLAGS="-w -fallow-argument-mismatch -O2" --with-device=ch4:ucx --with-ucx=$EBROOTUCX --with-thread-package=pthreads --enable-fast --enable-shared --enable-sharedlibs=gcc --enable-static --enable-f77 --enable-fc --enable-cxx' in /build/MPICH/4.2.1/GCC-12.3.0/mpich-4.2.1
+== INFO Output of './configure ...' shell command (stdout + stderr):
+configure: WARNING: unrecognized options: --with-thread-package, --enable-sharedlibs, --enable-fc
+[...]
+== INFO Shell command completed successfully (see output above): ./configure ...
+  >> command completed: exit 0, ran in 00h02m03s
+== ERROR EasyBuild encountered an error (at easybuild/easybuild-framework/easybuild/base/exceptions.py:126 in __init__): Found unrecognized configure options: --with-thread-package, --enable-sharedlibs, --enable-fc (at easybuild/easybuild-easyblocks/easybuild/easyblocks/generic/configuremake.py:355 in configure_step)
+```
 
 ---
 
-## Require `download_instructions` for non-public sources {: require_download_instructions }
+## Require `download_instructions` for non-public sources { : #require_download_instructions }
 
 [`download_instructions`][download_instructions] is a new easyconfig parameter
 in EasyBuild 5.0 used to specify instructions, or information, on

docs/easybuild-v5/index.md

@@ -68,7 +68,6 @@ Various significant enhancements are included in EasyBuild v5.0, including:
 - [New function to run shell commands: `run_shell_cmd`](run_shell_cmd.md)
 - [Interactive debugging of failing shell commands via `env.sh` and `cmd.sh` scripts](../interactive-debugging-failing-shell-commands.md)
 - [New collection of easyconfig templates](enhancements.md#collection-easyconfig-templates)
-- [Don't raise error when required extensions are not found when installing extensions in parallel](enhancements.md#parallel-extensions-install)
 - [Mark support for installing extensions in parallel as stable (no longer experimental)](enhancements.md#parallel-extensions-install-stable)
 - [Mark easystack support as stable (no longer experimental)](enhancements.md#easystack-stable)
 - [Reproducible tarballs for sources created via `git_config`](enhancements.md#reproducible-tarballs-git_config)
@@ -83,7 +82,8 @@ Various significant enhancements are included in EasyBuild v5.0, including:
 - [Support not using `$PYTHONPATH` to specify the location of installed Python packages (via `--prefer-python-search-path`)](enhancements.md#PYTHONPATH-vs-EBPYTHONPREFIXES)
 - [Revamp of easyconfig parameter `modextrapaths`](enhancements.md#modextrapaths-revamp)
 - [Detect Fortran `.mod` files in `GCCcore` installations](enhancements.md#mod-files)
-- [Let `ConfigureMake` generic easyblock error out on unrecognized `configure` options](enhancements.md#configuremake-unrecognized-configure-options)
+- [Let `ConfigureMake` generic easyblock error out on unrecognized `configure` options](enhancements.md#configuremake-unknown-configure-options)
+- [Require `download_instructions` for non-public sources](enhancements.md#require_download_instructions)
 
 ---
 

docs/writing-easyconfig-files.md

@@ -477,7 +477,7 @@ sources = [{
     in favour of the Python dictionary format described above; see also
     [Specifying source files as 2-element tuples to provide a custom extraction command][depr_sources_2_element_tuple].
 
-#### Using `download_instructions` for user-side part of installation {: download_instructions }
+#### Using `download_instructions` for user-side part of installation { : #download_instructions }
 
 In some cases, getting some of the files required for an installation
 cannot be automated. Reasons for this include: