[gnome-continuous-yocto/gnomeostree-3.28-rocko: 1653/8267] ref-manual: Updated the do_install reference section.

[Emmanuele Bassi <ebassi src gnome org>]

commit 4f27aa6e3ade0bbaef08c4244cccb252fbaabaf1
Author: Scott Rifenbark <srifenbark gmail com>
Date:   Mon Jul 18 12:18:50 2016 -0700

    ref-manual: Updated the do_install reference section.
    
    Fixes [YOCTO #9966]
    
    Added quite a bit of detail to this task's description.
    
    (From yocto-docs rev: c29d86813b9cb9bc1c9c02aeffb5cfd99fc5a542)
    
    Signed-off-by: Scott Rifenbark <srifenbark gmail com>
    Signed-off-by: Richard Purdie <richard purdie linuxfoundation org>

 documentation/ref-manual/ref-tasks.xml |   47 ++++++++++++++++++++++++++++---
 1 files changed, 42 insertions(+), 5 deletions(-)
---
diff --git a/documentation/ref-manual/ref-tasks.xml b/documentation/ref-manual/ref-tasks.xml
index 97c8a9e..a9559bb 100644
--- a/documentation/ref-manual/ref-tasks.xml
+++ b/documentation/ref-manual/ref-tasks.xml
@@ -241,11 +241,48 @@
         <title><filename>do_install</filename></title>
 
         <para>
-            Copies files from the compilation directory, which is defined by
-            the
-            <link linkend='var-B'><filename>B</filename></link> variable,
-            to a holding area defined by the
-            <link linkend='var-D'><filename>D</filename></link> variable.
+            Copies files that are to be packaged into the holding area
+            <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>.
+            This task runs with the current working directory set to
+            <filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename>,
+            which is the compilation directory.
+            <note>
+                <title>Caution</title>
+
+                <para>
+                    When installing files, be careful not to set the owner and
+                    group IDs of the installed files to unintended values.
+                    Some methods of copying files, notably when using the
+                    recursive <filename>cp</filename> command, can preserve the
+                    UID and/or GID of the original file, which is usually not
+                    what you want.
+                    The host-user-contaminated QA check checks for files
+                    that probably have the wrong ownership.
+                </para>
+
+                <para>
+                    Safe methods for installing files include the following:
+                    <itemizedlist>
+                        <listitem><para>
+                            The <filename>install</filename> utility.
+                            This utility is the preferred method.
+                            </para></listitem>
+                        <listitem><para>
+                            The <filename>cp</filename> command with the
+                            "--no-preserve=ownership" option.
+                            </para></listitem>
+                        <listitem><para>
+                            The <filename>tar</filename> command with the
+                            "--no-same-owner" option.
+                            See the <filename>bin_package.bbclass</filename>
+                            file in the <filename>meta/classes</filename>
+                            directory of the
+                            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
+                            for an example.
+                            </para></listitem>
+                    </itemizedlist>
+                </para>
+            </note>
         </para>
     </section>