more FAQ

doc/developers/faq.rst

@@ -10,19 +10,20 @@ Should I include and track also files generated by Autocmake in my repository?
 Yes, you probably want to do that. Autocmake generates a number of files which
 in principle could be generated at configure- or build-time.  However, you
 probably do not want the users of your code to run any Autocmake scripts like
-``update.py`` to generate the files they need to build the project. They will
+``update.py`` to generate the files they need to build the project. The users
-run ``setup.py`` directly and expect everything to just work (TM).
+of your code will run ``setup.py`` directly and expect everything to just work
+(TM).
 
 
 The update.py script is overwriting my CMakeLists.txt and setup.py, isn't this bad?
 -----------------------------------------------------------------------------------
 
-It's not as bad as it first looks. It's a feature. Normally ``CMakeLists.txt``
+No, it is not as bad as it first looks. It is a feature. Normally
-and ``setup.py`` should not contain any explicit customization and therefore should not
+``CMakeLists.txt`` and ``setup.py`` should not contain any explicit
-contain anything that could not be regenerated. In any case you should use
+customization and therefore should not contain anything that could not be
-version control so that you can inspect and compare changes introduced to
+regenerated. In any case you should use version control so that you can inspect
-``CMakeLists.txt`` and ``setup.py`` and possibly revert them. See also the next
+and compare changes introduced to ``CMakeLists.txt`` and ``setup.py`` and
-remark.
+possibly revert them. See also the next remark.
 
 
 But I need to manually edit and customize CMakeLists.txt and setup.py every time I run update.py!?
@@ -36,10 +37,11 @@ which get assembled into the front-end scripts.
 Where is a good place to list my sources and targets?
 -----------------------------------------------------
 
-As mentioned above ``CMakeLists.txt`` is not a good place because this file is generated
+As mentioned above ``CMakeLists.txt`` is not a good place because this file is
-from ``autocmake.cfg`` and your modifications would become overwritten at some point.
+generated from ``autocmake.cfg`` and your modifications would become
-A good solution for this is to list your sources and targets in ``src/CMakeLists.txt``
+overwritten at some point.  A good standard is to organize your sources under
-and include the latter in ``autocmake.cfg`` using::
+``src/`` and to list your sources and targets in ``src/CMakeLists.txt``.  You
+can include the latter in ``autocmake.cfg`` using::
 
   [src]
   source: https://github.com/scisoft/autocmake/raw/master/modules/src.cmake
@@ -49,3 +51,16 @@ targets in a custom module in a local file and include it like this::
 
   [my_sources]
   source: custom/my_sources.cmake
+
+
+How do I know whether I need to rerun updata.py?
+------------------------------------------------
+
+You need to rerun the ``update.py`` script in the following situations:
+
+- To fetch updates to CMake modules which you include from the web.
+- If you have added, removed, moved, or renamed CMake module files in
+  ``autocmake.cfg`` and wish to propagate the change to ``CMakeLists.txt`` and
+  the ``setup.py`` script.
+- If you automatically infer configuration from the CMake module documentation and
+  this documentation changes.

doc/users/faq.rst

@@ -27,4 +27,6 @@ How can I redefine compiler flags?
 
 If you export compiler flags using the environment variables ``FCFLAGS``,
 ``CFLAGS``, or ``CXXFLAGS``, respectively, then the configuration will use
-those flags and neither augment them, nor redefine them.
+those flags and neither augment them, nor redefine them. Setting
+these environment variables you have full control over the flags
+without editing CMake files.