ref-manual: Added warnings about using package_tar

This option to the PACKAGE_CLASSES variable is broken and not
supported.  I added several warnings saying such.  We opted to
keep the documentation rather than eliminating it completely to
prevent questions should someone find the code and wonder why
it is not documented.

Reported-by: Robert P. J. Day <rpjday@crashcourse.ca>
(From yocto-docs rev: 1acf3da2034c4c3f74acee1ccb375f0450ed90a0)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

2 files changed, 24 insertions, 12 deletions

diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
index fed25b25e6..54691ec9f6 100644
--- a/documentation/ref-manual/ref-classes.xml
+++ b/documentation/ref-manual/ref-classes.xml
@@ -2160,6 +2160,11 @@
         <link linkend='ref-classes-package_ipk'><filename>package_ipk</filename></link>,
         and
         <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>.
+        <note><title>Warning</title>
+            The <filename>package_tar</filename> class is broken and not
+            supported.
+            It is recommended that you do not use this class.
+        </note>
     </para>
 
     <para>
@@ -2298,6 +2303,12 @@
 <section id='ref-classes-package_tar'>
     <title><filename>package_tar.bbclass</filename></title>
 
+    <note><title>Warning</title>
+        The <filename>package_tar</filename> class is broken and is not
+        supported.
+        It is recommended that you do not use it.
+    </note>
+
     <para>
         The <filename>package_tar</filename>
         class provides support for creating packages that use the
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 281c4e3e2d..337c3f4397 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -4444,6 +4444,11 @@
                     or
                     <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>
                     class.
+                    <note><title>Warning</title>
+                        The <filename>package_tar</filename> class is broken
+                        and is not supported.
+                        It is recommended that you do not use it.
+                    </note>
                 </para>
 
                 <para>
@@ -6932,6 +6937,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                     <literallayout class='monospaced'>
      PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk package_tar"
                     </literallayout>
+                    <note><title>Warning</title>
+                        While it is a legal option, the
+                        <filename>package_tar</filename> class is broken
+                        and is not supported.
+                        It is recommended that you do not use it.
+                    </note>
                     The build system uses only the first argument in the list
                     as the package manager when creating your image or SDK.
                     However, packages will be created using any additional
@@ -6939,20 +6950,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                     For example, if you use the following in your
                     <filename>local.conf</filename> file:
                     <literallayout class='monospaced'>
-     PACKAGE_CLASSES ?= "package_ipk package_tar"
+     PACKAGE_CLASSES ?= "package_ipk"
                     </literallayout>
                     The OpenEmbedded build system uses the IPK package manager
-                    to create your image or SDK as well as generating
-                    TAR packages.
-                </para>
-
-                <para>
-                    You cannot specify the
-                    <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>
-                    class first in the list.
-                    Files using the <filename>.tar</filename> format cannot
-                    be used as a substitute packaging format
-                    for DEB, RPM, and IPK formatted files for your image or SDK.
+                    to create your image or SDK.
                 </para>
 
                 <para>