update parts of doc

doc/developers/bootstrap.rst

@@ -19,41 +19,38 @@ On the MS Windows system, you can use the PowerShell wget-replacement::
 
   $ Invoke-WebRequest https://github.com/coderefinery/autocmake/raw/master/update.py -OutFile update.py
 
-This creates (or updates) the following files (an existing ``autocmake.cfg`` is
+This creates (or updates) the following files (an existing ``autocmake.yml`` is
 not overwritten by the script)::
 
   cmake/
-      autocmake.cfg      # edit this file
+      autocmake.yml      # edit this file
       update.py          # no need to edit
-      lib/
+      autocmake/         # no need to edit
-          config.py      # no need to edit
+          ...            # no need to edit
-          docopt/
-              docopt.py  # no need to edit
 
-Note that all other listed files are overwritten (use version control).
+Note that ``update.py`` and files under ``autocmake/``
+are overwritten (use version control).
 
 
 Generating the CMake infrastructure
 -----------------------------------
 
-Now customize ``autocmake.cfg`` to your needs
+Now customize ``autocmake.yml`` to your needs
-(see :ref:`autocmake_cfg`)
+(see :ref:`autocmake_yml`)
 and then run the ``update.py`` script which
 creates ``CMakeLists.txt`` and a setup script in the target path::
 
   $ python update.py ..
 
-The script also downloads external CMake modules specified in ``autocmake.cfg`` to a directory
+The script also downloads external CMake modules specified in ``autocmake.yml`` to a directory
 called ``downloaded/``::
 
   cmake/
-      autocmake.cfg      # edit this file
+      autocmake.yml      # edit this file
       update.py          # no need to edit
-      lib/
+      autocmake/         # no need to edit
-          config.py      # no need to edit
+          ...            # no need to edit
-          docopt/
+      downloaded/        # contains CMake modules fetched from the web
-              docopt.py  # no need to edit
-          downloaded/    # contains CMake modules fetched from the web
 
 
 Building the project

doc/developers/configuration.rst

@@ -1,5 +1,5 @@
 
-.. _autocmake_cfg:
+.. _autocmake_yml:
 
 Configuring autocmake.cfg
 =========================

doc/developers/customizing-modules.rst

@@ -3,7 +3,7 @@
 Customizing CMake modules
 =========================
 
-The ``update.py`` script assembles modules listed in ``autocmake.cfg`` into
+The ``update.py`` script assembles modules listed in ``autocmake.yml`` into
 ``CMakeLists.txt``. Those that are fetched from the web are placed inside
 ``downloaded/``.  You have several options to customize downloaded CMake
 modules:
@@ -22,7 +22,7 @@ Adapt local copies of CMake modules
 
 A slightly better solution is to download the CMake modules that you wish you customize
 to a separate directory (e.g. ``custom/``) and source the customized CMake
-modules in ``autocmake.cfg``. Alternatively you can serve your custom modules
+modules in ``autocmake.yml``. Alternatively you can serve your custom modules
 from your own http server.
 
 
@@ -34,19 +34,30 @@ the branched customized versions. This will make it easier for you
 to stay up-to-date with upstream development.
 
 
-Overriding defaults
+Overriding settings
 -------------------
 
-Some modules use interpolations to set defaults, see for instance
+If you source a module which contains directives such as
-https://github.com/coderefinery/autocmake/blob/master/modules/boost/boost.cmake#L33-L36.
+``define``,
-These can be modified within ``autocmake.cfg``, e.g.:
+``docopt``,
-https://github.com/coderefinery/autocmake/blob/master/test/boost_libs/cmake/autocmake.cfg#L9
+``export``, or
+``fetch``, and you wish to modify those,
+then you can override these settings in ``autocmake.yml``.
+Settings in ``autocmake.yml`` take precedence over
+settings imported by a sourced module.
+
+As an example consider the Boost module which defines and uses
+interpolation variables ``major``, ``minor``, and ``patch``, see
+https://github.com/coderefinery/autocmake/blob/master/modules/boost/boost.cmake#L52-L54.
+
+The recommended way to customize these is in ``autocmake.yml``, e.g.:
+https://github.com/coderefinery/autocmake/blob/master/test/boost_libs/cmake/autocmake.yml#L12-L17.
 
 
 Create own CMake modules
 ------------------------
 
-Of course you can also create own modules and source them in ``autocmake.cfg``.
+Of course you can also create own modules and source them in ``autocmake.yml``.
 
 
 Contribute customizations to the "standard library"

doc/developers/example.rst

@@ -4,7 +4,7 @@ Example Hello World project
 ===========================
 
 This is a brief example for the busy and impatient programmer. For a longer
-tour please see :ref:`autocmake_cfg`.
+tour please see :ref:`autocmake_yml`.
 
 We start with a mixed Fortran-C project with the following sources::