diff --git a/doc/source/sw-description.rst b/doc/source/sw-description.rst
index 36c02b2..51fe670 100644
--- a/doc/source/sw-description.rst
+++ b/doc/source/sw-description.rst
@@ -318,6 +318,231 @@ while another device can have raw flash and install an UBI filesystem. Neverthel
 both just a different format of the same release and they could be described together in sw-description.
 It is important to understand the priorities how SWUpdate scans for entries during the parsing.
 
+Using links
+-----------
+
+sw-description can become very complex. Let's think to have just one board, but in multiple
+hw revision and they differ in Hardware. Some of them can be grouped together, some of them
+require a dedicated section. A way (but not the only one !) could be to add *mode* and selects
+the section with `-e stable,<rev number>`.
+
+::
+
+	software =
+	{
+		version = "0.1.0";
+
+		myboard = {
+	            stable = {
+
+			hardware-compatibility: ["1.0", "1.2", "2.0", "1.§, "3.0", "3.1"];
+			rev-1.0: {
+				images: (
+					...
+				);
+				scripts: (
+					...
+				);
+			}
+			rev-1.2: {
+				hardware-compatibility: ["1.2"];
+				images: (
+					...
+				);
+				scripts: (
+					...
+				);
+			}
+			rev-2.0: {
+				hardware-compatibility: ["2.0"];
+				images: (
+					...
+				);
+				scripts: (
+					...
+				);
+			}
+			rev-1.3: {
+				hardware-compatibility: ["1.3"];
+				images: (
+					...
+				);
+				scripts: (
+					...
+				);
+			}
+
+			rev-3.0:
+			{
+				hardware-compatibility: ["3.0"];
+				images: (
+					...
+				);
+				scripts: (
+					...
+				);
+	                }
+			rev-3.1:
+			{
+				hardware-compatibility: ["3.1"];
+				images: (
+					...
+				);
+				scripts: (
+					...
+				);
+			}
+		     }
+	        }
+	}
+
+If each of them requires an own section, it is the way to do. Anyway, it is more probable
+than revisions can be grouped together, for example board with the same major revision
+number could have the same installation instructions. This leads in the example to 3 groups
+for rev1.X, rev2.X and rev3.X. Links allow to group section together. When a string is found
+when SWUpdate searches for a group (images, files, script, bootenv), it replaces the current path
+in the tree with the value of the string. In this way, the example above can be written in this way:
+
+::
+
+	software =
+	{
+		version = "0.1.0";
+
+		myboard = {
+	            stable = {
+
+			hardware-compatibility: ["1.0", "1.2", "2.0", "1.3, "3.0", "3.1"];
+			rev-1x: {
+				images: (
+					...
+				);
+				scripts: (
+					...
+				);
+			}
+                        rev1.0 = {
+                                ref = "#../rev-1x";
+                        }
+                        rev1.2 = {
+                                ref = "#../rev-1x";
+                        }
+                        rev1.3 = {
+                                ref = "#../rev-1x";
+                        }
+			rev-2x: {
+				images: (
+					...
+				);
+				scripts: (
+					...
+				);
+			}
+                        rev2.0 = {
+                                ref = "#../rev-2x";
+                        }
+
+			rev-3x:
+			{
+				images: (
+					...
+				);
+				scripts: (
+					...
+				);
+	                }
+                        rev3.0 = {
+                                ref = "#../rev-3x";
+                        }
+                        rev3.1 = {
+                                ref = "#../rev-3x";
+                        }
+		     }
+	        }
+	}
+
+The link can be absolute or relative. The keyword *"ref"* is used to indicate a link. If this is found, SWUpdate
+will traverse the tree and replaces the current path with the values find in the string pointed by "ref". There are
+simple rules for a link:
+
+       - it must start with the character '#' 
+       - "." points to the current level in the tree
+       - ".." points to the parent level in the tree
+       - "/" is used as filed separator in the link
+
+
+A relative path has a number of
+leading "../" to move the current cursor to the parent leaf of the tree.
+In the following example, rev40 sets a link to a "common" section, where `images`
+is found. This is sets via a link, too, to a section in the parent node.
+The path `software.myboard.stable.common.images`  is then replaced by
+`software.myboard.stable.trythis` 
+
+::
+
+	software =
+	{
+	  version = {
+		  ref = "#../commonversion";
+	  }
+
+	  hardware-compatibility = ["rev10", "rev11", "rev20"];
+
+	  commonversion = "0.7-linked";
+
+	pc:{
+	  stable:{
+
+	    common:{
+		images = 
+		{
+		  ref = "#../../trythis";
+		}
+	      };
+
+	    trythis:(
+		{
+		filename = "rootfs1.ext4";
+		device = "/dev/mmcblk0p8";
+		type = "raw";
+		} ,
+		{
+		filename = "rootfs5.ext4";
+		device = "/dev/mmcblk0p7";
+		type = "raw";
+		}
+	      );
+	    pdm3rev10:
+	      {
+	      images:(
+		  {
+		  filename = "rootfs.ext3"; device = "/dev/mmcblk0p2";}
+		);
+	      uboot:(
+		  { name = "bootpart";
+		  value = "0:2";}
+		);
+	      };
+	      pdm3rev11 =
+	      {
+		ref = "#../pdm3rev10";
+	      }
+	      pdm3rev20 =
+	      {
+		ref = "#../pdm3rev10";
+	      }
+	      pdm3rev40 =
+	      {
+		ref = "#../common";
+	      }
+	    };
+	  };
+	}
+
+
+Each entry in sw-description can be redirect by a link as in the above example for the
+"version" attribute.
+
 hardware-compatibility
 ----------------------
 
