diff --git a/Pmodules/modbuild.in b/Pmodules/modbuild.in
index 6620c9b..a87ab5f 100755
--- a/Pmodules/modbuild.in
+++ b/Pmodules/modbuild.in
@@ -115,6 +115,9 @@ MISCELLANEOUS OPTIONS:
 -v | --verbose )
         Verbose output.
 
+--debug )
+	Run in debug mode.
+
 -j N | --jobs=N
         Run N parallel make jobs.
 
@@ -498,6 +501,19 @@ build_modules_yaml(){
 		_result='base'
 	}
 
+	yaml_get_group(){
+		local -n _result="$1"
+		local fname="$2"
+		local version="$3"
+		local idx="$4"
+		_result=$(${yq} -Ne e ".\"${version}\"[${idx}].group" \
+			     "${fname}" 2>/dev/null)
+		(( $? == 0 )) && return
+		_result=$(${yq} -Ne e ".group" "${fname}" 2>/dev/null)
+		(( $? == 0 )) && return
+		_result=''
+	}
+
 	yaml_get_systems(){
 		local -n _result="$1"
 		local fname="$2"
@@ -511,6 +527,19 @@ build_modules_yaml(){
 		_result='any'
 	}
 
+	yaml_get_operating_systems(){
+		local -n _result="$1"
+		local fname="$2"
+		local version="$3"
+		local idx="$4"
+		_result=$(${yq} -Ne e ".\"${version}\"[${idx}].operating_systems" \
+			     "${fname}" 2>/dev/null)
+		(( $? == 0 )) && return
+		_result=$(${yq} -Ne e ".operating_systems" "${fname}" 2>/dev/null)
+		(( $? == 0 )) && return
+		_result='any'
+	}
+
 	yaml_get_dependencies(){
 		local -n _result="$1"
 		local fname="$2"
diff --git a/doc/Overlays.adoc b/doc/Overlays.adoc
index d08004b..b486cc6 100644
--- a/doc/Overlays.adoc
+++ b/doc/Overlays.adoc
@@ -10,6 +10,7 @@ Please note: This document is work in progress!
 
 === System wide
 
+==== Example
 .A system wide configuration file `/opt/psi/config/Pmodules.yaml`
 ====
 ....
@@ -22,11 +23,34 @@ DistfilesDir: /opt/psi/var/distfiles
 Overlays:
   base:
     install_root: /opt/psi
+    modulefiles_root: /opt/psi
   devel:
     install_root: /opt/psi
     modulefiles_root: ${HOME}/modulefiles
 ....
 ====
+==== YAML Format
+.Format
+====
+....
+Overlays:
+  <name>:
+    install_root: <installation-root>
+    modulefiles_root: <modulefiles-root>
+    type: <type of overlay>
+  ...
+....
+====
+`<name>`:: Name of overlay. Note: whitespace in the name is not supported.
+`<name>.install_root`:: The root of the software installation. This key is mandatory.
+`<name>.modulefiles_root`:: The root of the modulefile hierarchy. This key is optional and defaults to `<name>.install_root>
+`<name>.type`:: The type of the overlay, see below. This key is optional and the default value is `n`.
+
+==== Overlay types
+`n`:: Normal overlay.
+`h`:: Hiding overlay.
+`r`:: Replacing overlay.
+
 === User defined overlays
 
 Each user can define his own overlays in `$HOME/.Pmodules/Pmodules.yaml`. 
@@ -39,6 +63,7 @@ The old format of the variants file is simple but very limited and almost imposs
 
 === With a YAML variants file
 
+==== Example of a variants file in YAML format
 .A YAML variants file
 ====
 ....
@@ -53,13 +78,15 @@ hdf5_serial/1.12.2:
 ....
 ====
 
-.YAML format of varaints file
+==== Format specification
+.YAML format
 ....
+relstage: <default-release-stage>
 overlay: <default-overlay>
 systems: <default-systems>
 
-<module-name>/<version>:
-  - with: <ohierarchical-build-dependencies>
+<name>/<version>:
+  - with: <hierarchical-build-dependencies>
     dependencies: <other-build-dependencies>
     relstate: <release-stage>
     overlay: <overlay>
@@ -67,6 +94,24 @@ systems: <default-systems>
   ...
 ...
 ....
+==== Defaults
+Default values can be overriden per version/variant.
 
+`overlay`:: The default overlay the module will be installed in. This value can be overriden for dedicated versions/variants.
+`systems`:: The default for supported systems.
 
-=== With a legacy variants file
+==== Versions and Variants
+
+`<name>/<version>`:: An array with variants for this version.
+
+`<name>/<version>.[i].with`:: Hierarchical dependencies for variant `i`.
+
+`<name>/<version>.[i].dependencies`:: Build/run-time dependencies for variant `i`.
+
+`<name>/<version>.[i].relstage`:: Relase stage of variant `i`.
+
+`<name>/<version>.[i].overlay`:: Overlay of variant `i`.
+
+`<name>/<version>.[i].systems`:: Supported systems.
+
+=== Legacy format