New section on keeping the XML file up to date (#22)

* added documentation about restart task

* added section on how to keep XML file up to date

* improved explanations

Author: manueldsdias

working_with_github.rst

@@ -413,6 +413,59 @@ changes will be selectively applied to the official repository via the pull
 request process.
 
 
+.. _github_rundat_vars:
+
+Keeping the XML file up to date
+===============================
+
+This procedure is only meant for *Contributors*.
+
+ONETEP uses an XML log file to store information about the internal state of the
+calculation in an easier to parse way. Currently this is only used in a limited way,
+to assist with determining whether a ONETEP calculation can be restarted or continued,
+as described in :ref:`restarting_onetep`. A major part of the XML file is used to store
+the values of the variables which are declared at the top of ``rundat_mod.F90``. This
+information was previously invisible during the calculation unless specific write
+statements were present or added to the code. In order to systematise this and to make it
+easier to handle the long list of variables declared in ``rundat_mod.F90``, a new module
+called ``rundat_new_mod.F90`` was introduced in which those variables are part of a derived
+data type, and auxiliary subroutines are available to interact with it. The XML I/O is
+mostly handled by ``rundat_xml_mod.F90``. These two files are very long and are actually
+auto-generated, so that the developer should never modify them directly (with a small
+exception mentioned later in point 4).
+
+The ``rundat_new_mod.F90`` and the ``rundat_xml_mod.F90`` files are auto-generated by a
+small program included in the ``rundat_new`` folder (top level with respect to the ONETEP
+source distribution). If new variables are added to ``rundat_mod.F90`` or changes are made
+to existing variables, the auto-generated code also needs to be updated. To do so, the
+following steps should be followed:
+
+  1. Ensure that all variables declared in ``rundat_mod.F90`` have matching declarations 
+     in the file ``rundat_vars.F90`` within the folder ``rundat_new``. If some are missing
+     or need correcting the developer has to do this by hand. Point 3 can help with this.
+
+  2. Auto-generate the ``rundat_new_mod.F90`` and the ``rundat_xml_mod.F90`` files by running
+     the ``make_rundat_new.sh`` script also given in the ``rundat_new`` folder.
+     ``make_rundat_new.sh`` is currently very primitive; if ``gfortran`` is not available
+     as a compiler this has to be manually corrected in the script.
+
+  3. The ``make_rundat_new.sh`` script also generates a comparison table between the
+     variables listed in ``rundat_mod.F90`` and in ``rundat_vars.F90``. The table is in the
+     file ``parse_out`` in the ``rundat_new`` folder. This can be useful to figure out which
+     variables might be missing from ``rundat_vars.F90`` or if some changes have been made
+     to them.
+
+  4. Check if the ``rundat_new_mod.F90`` and the ``rundat_xml_mod.F90`` files comply with
+     the ONETEP coding standards with respect to maximum code line lenghts. If not, the
+     offending lines require manual editing to insert line breaks (this will be 
+     fixed/automated in the near future).
+
+At present there is no significant consequence if the variables in the XML file are
+not up to date with the ones declared in ``rundat_mod.F90``, unless they are needed for
+checkpointing/restarting/continuing ONETEP runs. In any case, it is recommended to follow
+the steps explained in the previous paragraph to keep everything up to date and consistent.
+
+
 .. _github_pull_request:
 
 Creating a pull request