Overlays doc added

doc/Overlays.adoc

@@ -0,0 +1,72 @@
+= Overlays
+:TOC:
+:sectnums:
+
+Please note: This document is work in progress!
+
+== What are Overlays and for what can they be used?
+
+== Overlay configuration
+
+=== System wide
+
+.A system wide configuration file `/opt/psi/config/Pmodules.yaml`
+====
+....
+DefaultGroups: Tools:Programming
+DefaultReleaseStages: stable
+ReleaseStages: unstable:stable:deprecated
+TmpDir: /opt/psi/var/tmp/${USER}
+DistfilesDir: /opt/psi/var/distfiles
+
+Overlays:
+  base:
+    install_root: /opt/psi
+  devel:
+    install_root: /opt/psi
+    modulefiles_root: ${HOME}/modulefiles
+....
+====
+=== User defined overlays
+
+Each user can define his own overlays in `$HOME/.Pmodules/Pmodules.yaml`. 
+
+== Working with overlays
+
+== Building modules
+
+The old format of the variants file is simple but very limited and almost impossible to extend for new features. To overcome the limitations a new format using YAML for variants files has been introduced. For the time being both format are supported. But it is highly recommended to use the YAML format for new modules and to migrate existing variants files in the old format to the new.
+
+=== With a YAML variants file
+
+.A YAML variants file
+====
+....
+overlay: base
+
+hdf5_serial/1.12.2:
+- with: gcc/{5.5.0,6.5.0,7.5.0,10.2.0,10.3.0} 
+  relstage: stable
+- with: gcc/{8.5.0,9.5.0,11.3.0,12.1.0}
+  relstage: unstable
+  overlay: devel                 
+....
+====
+
+.YAML format of varaints file
+....
+overlay: <default-overlay>
+systems: <default-systems>
+
+<module-name>/<version>:
+  - with: <ohierarchical-build-dependencies>
+    dependencies: <other-build-dependencies>
+    relstate: <release-stage>
+    overlay: <overlay>
+    systems: <systems>
+  ...
+...
+....
+
+
+=== With a legacy variants file