doc: Make magic groups documentation clearer

Signed-off-by: Sol Jerome <sol.jerome@gmail.com>

4 files changed, 33 insertions, 17 deletions

diff --git a/doc/appendix/guides/centos.txt b/doc/appendix/guides/centos.txt
index 525cb5a98..119c3d2f8 100644
--- a/doc/appendix/guides/centos.txt
+++ b/doc/appendix/guides/centos.txt
@@ -211,13 +211,17 @@ line of ``bcfg2.conf``.  Then create Packages layout (as per
             </YUMSource>
     </Sources>
 
-Due to the `Magic Groups`_, we need to modify our Metadata. Let's
-add a **centos5.4** group which inherits a **centos** group
-(this should replace the existing **redhat** group) present in
-``/var/lib/bcfg2/Metadata/groups.xml``. The resulting file should look
-something like this
+Due to the :ref:`server-plugins-generators-packages-magic-groups`,
+we need to modify our Metadata. Let's add a **centos5.4** group which
+inherits a **centos** group (this should replace the existing **redhat**
+group) present in ``/var/lib/bcfg2/Metadata/groups.xml``. The resulting
+file should look something like this
 
-.. _Magic Groups: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Plugins/Packages#MagicGroups
+.. note::
+
+    The reason we are creating a release-specific group in this case is
+    that the YUMSource above is specific to the 5.4 release of centos.
+    That is, it should not apply to other releases (5.1, 5.3, etc).
 
 .. code-block:: xml
 
diff --git a/doc/appendix/guides/fedora.txt b/doc/appendix/guides/fedora.txt
index 12432b04f..e8c1af7b6 100644
--- a/doc/appendix/guides/fedora.txt
+++ b/doc/appendix/guides/fedora.txt
@@ -216,13 +216,18 @@ mirror near your location according the `Mirror list`_ .
 	    </YUMSource>
 	</Sources>
 
-.. _Magic Groups: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Plugins/Packages#MagicGroups
 
-Due to the `Magic Groups`_, we need to modify our Metadata. Let's
-add a **fedora13** group which inherits a **fedora** group
-(this should replace the existing **redhat** group) present in
-``/var/lib/bcfg2/Metadata/groups.xml``. The resulting file should look
-something like this
+Due to the :ref:`server-plugins-generators-packages-magic-groups`,
+we need to modify our Metadata. Let's add a **fedora13** group which
+inherits a **fedora** group (this should replace the existing **redhat**
+group) present in ``/var/lib/bcfg2/Metadata/groups.xml``. The resulting
+file should look something like this
+
+.. note::
+
+    The reason we are creating a release-specific group in this case is
+    that the YUMSource above is specific to the 13th release of fedora.
+    That is, it should not apply to other releases (14, 15, etc).
 
 .. code-block:: xml
 
diff --git a/doc/appendix/guides/ubuntu.txt b/doc/appendix/guides/ubuntu.txt
index 24338c6d2..56480796d 100644
--- a/doc/appendix/guides/ubuntu.txt
+++ b/doc/appendix/guides/ubuntu.txt
@@ -169,12 +169,17 @@ Create Packages layout (as per :ref:`packages-exampleusage`) in
       </APTSource>
     </Sources>
 
-Due to the `Magic Groups`_, we need to modify our Metadata. Let's add
-an **ubuntu-lucid** group which inherits the **ubuntu** group already
-present in ``/var/lib/bcfg2/Metadata/groups.xml``. The resulting file
-should look something like this
+Due to the :ref:`server-plugins-generators-packages-magic-groups`,
+we need to modify our Metadata. Let's add an **ubuntu-lucid**
+group which inherits the **ubuntu** group already present in
+``/var/lib/bcfg2/Metadata/groups.xml``. The resulting file should look
+something like this
 
-.. _Magic Groups: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Plugins/Packages#MagicGroups
+.. note::
+
+    The reason we are creating a release-specific group in this case is
+    that the APTSource above is specific to the lucid release of ubuntu.
+    That is, it should not apply to other releases (hardy, maverick, etc).
 
 .. code-block:: xml
 
diff --git a/doc/server/plugins/generators/packages.txt b/doc/server/plugins/generators/packages.txt
index 83a4ddb8a..b65efcff5 100644
--- a/doc/server/plugins/generators/packages.txt
+++ b/doc/server/plugins/generators/packages.txt
@@ -15,6 +15,8 @@ information, Packages delegates control of package version information to
 the underlying package manager, installing the latest version available
 through those channels.
 
+.. _server-plugins-generators-packages-magic-groups:
+
 "Magic Groups"
 ==============