ref-manual, dev-manual: Review comments applied to package repository

Changes are the review comments from Paul Eggleton regarding
setting up the optional package repository on the host that
can be used by Smart.  These changes reflect the fact that
the task is not package-type dependent or host web server
dependent.

(From yocto-docs rev: 779989878bcc9501ddc4570519d93325442a8493)

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

2 files changed, 100 insertions, 108 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index e6fd4fb363..6ad61d633a 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -606,27 +606,27 @@
                 <filename>EXTRA_IMAGE_FEATURES</filename></title>
 
             <para>
-                Ultimately, you might want to add extra image features to the 
+                Ultimately, you might want to add extra image features to the
                 set by using the
                 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'>IMAGE_FEATURES</ulink></filename>
                 variable.
                 To create these features, the best reference is
-                <filename>meta/classes/core-image.bbclass</filename>, which 
+                <filename>meta/classes/core-image.bbclass</filename>, which
                 shows how you can add features.
                 In summary, the file looks at the contents of the
-                <filename>IMAGE_FEATURES</filename> variable and then maps those 
+                <filename>IMAGE_FEATURES</filename> variable and then maps those
                 contents into a set of tasks or packages.
                 Based on this information, the build system automatically
-                generates the 
+                generates the
                 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'> IMAGE_INSTALL</ulink></filename>
                 variable.
-                You can add extra features by extending the class or creating a 
-                custom class for use with specialized image 
+                You can add extra features by extending the class or creating a
+                custom class for use with specialized image
                 <filename>.bb</filename> files.
                 You can also add more features by configuring the
                 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</ulink></filename>
-                variable in the <filename>local.conf</filename> file found in 
-                the <filename>local.conf</filename> file, which is located in  
+                variable in the <filename>local.conf</filename> file found in
+                the <filename>local.conf</filename> file, which is located in
                 the <link linkend='build-directory'>Build Directory</link>.
             </para>
 
@@ -634,25 +634,25 @@
                 <title>Choosing the SSH Server</title>
 
                 <para>
-                    The Yocto Project ships with two SSH servers you can use 
+                    The Yocto Project ships with two SSH servers you can use
                     with your images: Dropbear and OpenSSH.
-                    Dropbear is a minimal SSH server appropriate for 
-                    resource-constrained environments, while OpenSSH is a 
+                    Dropbear is a minimal SSH server appropriate for
+                    resource-constrained environments, while OpenSSH is a
                     well-known standard SSH server implementation.
-                    By default, the <filename>core-image-sato</filename> image 
+                    By default, the <filename>core-image-sato</filename> image
                     is configured to use Dropbear.
-                    The <filename>core-image-basic</filename> and 
-                    <filename>core-image-lsb</filename> images both 
+                    The <filename>core-image-basic</filename> and
+                    <filename>core-image-lsb</filename> images both
                     include OpenSSH.
-                    The <filename>core-image-minimal</filename> image does not 
+                    The <filename>core-image-minimal</filename> image does not
                     contain an SSH server.
                 </para>
 
                 <para>
                     You can customize your image and change these defaults.
                     Edit <filename>IMAGE_FEATURES</filename> variable
-                    so that it configures the image you are working with to 
-                    include <filename>ssh-server-dropbear</filename> or 
+                    so that it configures the image you are working with to
+                    include <filename>ssh-server-dropbear</filename> or
                     <filename>ssh-server-openssh</filename>.
                 </para>
             </section>
@@ -661,24 +661,24 @@
                 <title>Creating a Read-Only Root Filesystem</title>
 
                 <para>
-                    Another example of customizing your image could be setting 
+                    Another example of customizing your image could be setting
                     up a read-only filesystem.
-                    Suppose, for security reasons, you need to disable the 
+                    Suppose, for security reasons, you need to disable the
                     your target device's root filesystem's write permisions
                     (i.e. you need a read-only root filesystem).
                     Or, perhaps you are running the device's operating system
                     from a read-only storage device.
-                    For either case, you can customize your image for 
+                    For either case, you can customize your image for
                     that behavior.
                 </para>
 
                 <para>
-                    To create a read-only root filesystem, simply add the 
+                    To create a read-only root filesystem, simply add the
                     "read-only-rootfs" feature to your image.
-                    Using either of the following statements in your 
-                    image recipe or from within the 
-                    <filename>local.conf</filename> file found in the Build 
-                    Directory causes the build system to create a 
+                    Using either of the following statements in your
+                    image recipe or from within the
+                    <filename>local.conf</filename> file found in the Build
+                    Directory causes the build system to create a
                     read-only root filesystem:
                     <literallayout class='monospaced'>
      IMAGE_FEATURES = "read-only-rootfs"
@@ -2320,16 +2320,16 @@
             <para>
                 It is easiest to have something to start with when creating
                 your own distribution.
-                You can use the Yocto Project out-of-the-box to create the 
+                You can use the Yocto Project out-of-the-box to create the
                 <filename>poky-tiny</filename> distribution.
-                Ulitmately, you will want to make changes in your own 
-                distribution that are likely modeled after  
+                Ulitmately, you will want to make changes in your own
+                distribution that are likely modeled after
                 <filename>poky-tiny</filename>.
                 <note>
-                    To use <filename>poky-tiny</filename> in your build, 
-                    set the <filename>DISTRO</filename> variable in your 
-                    <filename>local.conf</filename> file to "poky-tiny" 
-                    as described in the 
+                    To use <filename>poky-tiny</filename> in your build,
+                    set the <filename>DISTRO</filename> variable in your
+                    <filename>local.conf</filename> file to "poky-tiny"
+                    as described in the
                     "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>"
                     section.
                 </note>
@@ -2344,7 +2344,7 @@
                 Dynamic memory contains memory that is allocated at runtime,
                 stacks, hash tables, and so forth.
                 Temporary memory is recovered after the boot process.
-                This memory consists of memory used for decompressing 
+                This memory consists of memory used for decompressing
                 the kernel and for the <filename>__init__</filename>
                 functions.
             </para>
@@ -2560,7 +2560,7 @@
             <title>Look for Other Ways to Minimize Size</title>
 
             <para>
-                Depending on your particular circumstances, other areas that you 
+                Depending on your particular circumstances, other areas that you
                 can trim likely exist.
                 The key to finding these areas is through tools and methods
                 described here combined with experimentation and iteration.
@@ -2570,35 +2570,35 @@
                         In general, follow this process:
                         <orderedlist>
                             <listitem><para>Remove <filename>eglibc</filename>
-                                features from  
+                                features from
                                 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
                                 that you think you don't need.</para></listitem>
                             <listitem><para>Build your distribution.
                                 </para></listitem>
-                            <listitem><para>If the build fails due to missing 
-                                symbols in a package, determine if you can 
-                                reconfigure the package to not need those 
+                            <listitem><para>If the build fails due to missing
+                                symbols in a package, determine if you can
+                                reconfigure the package to not need those
                                 features.
-                                For example, change the configuration to not 
-                                support wide character support as is done for 
+                                For example, change the configuration to not
+                                support wide character support as is done for
                                 <filename>ncurses</filename>.
-                                Or, if support for those characters is needed, 
-                                determine what <filename>eglibc</filename> 
-                                features provide the support and restore the 
+                                Or, if support for those characters is needed,
+                                determine what <filename>eglibc</filename>
+                                features provide the support and restore the
                                 configuration.
                                 </para></listitem>
                             <listitem><para>Rebuild and repeat the process.
                                 </para></listitem>
                         </orderedlist></para></listitem>
                     <listitem><para><filename>busybox</filename>:
-                        For BusyBox, use a process similar as described for 
+                        For BusyBox, use a process similar as described for
                         <filename>eglibc</filename>.
-                        A difference is you will need to boot the resulting 
-                        system to see if you are able to do everything you 
+                        A difference is you will need to boot the resulting
+                        system to see if you are able to do everything you
                         expect from the running system.
                         You need to be sure to integrate configuration fragments
-                        into Busybox because BusyBox handles its own core 
-                        features and then allows you to add configuration 
+                        into Busybox because BusyBox handles its own core
+                        features and then allows you to add configuration
                         fragments on top.
                         </para></listitem>
                 </itemizedlist>
@@ -3126,8 +3126,9 @@
             <title>Setting Up Runtime Package Management</title>
 
             <para>
-                It is possible to set up a repository that is a host-based
-                package feed from which you can install packages on the 
+                For RPM, IPK, and DEB package formats, it is possible to set
+                up a repository that is a host-based
+                package feed from which you can install packages on the
                 target system during runtime.
                 Doing so is optional and depends on the following:
                 <itemizedlist>
@@ -3135,14 +3136,14 @@
                         You take specific steps to set up the feed.
                         </para></listitem>
                     <listitem><para>
-                        When you build your image, you select to use the 
-                        RPM package manager by setting the 
+                        When you build your image, you select to use the
+                        appropriate package manager by setting the
                         <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>
                         variable.
                         </para></listitem>
                     <listitem><para>
-                        You have Apache 2 installed and configured on the 
-                        development host.
+                        You have a supported web server, such as Apache 2,
+                        installed and configured on the development host.
                         </para></listitem>
                     <listitem><para>
                         You have <filename>createrepo</filename> installed on
@@ -3152,14 +3153,16 @@
             </para>
 
             <para>
-                Here are the steps to set up this optional package feed:
+                Following are the steps to set up the optional repository.
+                This examples assumes you are using RPM and the Apache 2
+                server:
                 <orderedlist>
                     <listitem><para>
                         Add the directory to your Apache configuration, which
-                        you can find at 
+                        you can find at
                         <filename>/etc/httpd/conf/httpd.conf</filename>.
                         Use commands similar to these on the development system.
-                        These example commands assume a top-level 
+                        These example commands assume a top-level
                         <link linkend='source-directory'>Source Directory</link>
                         named <filename>poky</filename> in your home directory:
                         <literallayout class='monospaced'>
@@ -3169,7 +3172,7 @@
          &lt;Directory "~/poky/build/tmp/deploy/rpm"&gt;
            Options +Indexes
          &lt;/Directory&gt;
-     &lt;/VirtualHost&gt; 
+     &lt;/VirtualHost&gt;
                         </literallayout>
                         </para></listitem>
                     <listitem><para>
@@ -3177,35 +3180,23 @@
                         For all commands, be sure you have root privileges.
                         </para>
                         <para>
-                        If your development system is using Fedora or  
+                        If your development system is using Fedora or
                         CentOS, use the following:
-                        </para>
-                            <note>
-                                <emphasis>Note to Self:</emphasis> Paul says that
-                                some of the distros (Fedora and CentOS in 
-                                particular) might have different commands based 
-                                on the distro version.
-                                We need links for the reader to follow for the 
-                                specifics.  
-                                We don't want to have to document all this 
-                                distro-specific stuff.
-                            </note>
-                        <para>
-                            <literallayout class='monospaced'>
-     service httpd reload 
-                            </literallayout>
-                            For Ubuntu, use the following:
-                            <literallayout class='monospaced'>
+                        <literallayout class='monospaced'>
+     service httpd reload
+                        </literallayout>
+                        For Ubuntu, use the following:
+                        <literallayout class='monospaced'>
      /etc/init.d/apache2 reload
-                            </literallayout>
-                            For OpenSUSE, use the following:
-                            <literallayout class='monospaced'>
+                        </literallayout>
+                        For OpenSUSE, use the following:
+                        <literallayout class='monospaced'>
      /etc/init.d/apache2 reload
-                            </literallayout>
+                        </literallayout>
                         </para></listitem>
                     <listitem><para>
                         Change your working directory to
-                        <filename>tmp/deploy/rpm</filename> in the 
+                        <filename>tmp/deploy/rpm</filename> in the
                         <link linkend='build-directory'>Build Directory</link>.
                         </para></listitem>
                     <listitem><para>
@@ -3217,13 +3208,13 @@
                         </para>
                         <para>
                             <note>
-                                If you're updating, add 
+                                If you're updating, add
                                 <filename>&dash;&dash;update</filename> to save some time.
                             </note>
                         </para></listitem>
                     <listitem><para>
                         If you are using Security-Enhanced Linux (SELinux),
-                        you need to label the files as being accessible 
+                        you need to label the files as being accessible
                         through Apache.
                         Use the following command from the development host:
                         <literallayout class='monospaced'>
@@ -3232,14 +3223,14 @@
                         </para></listitem>
                     <listitem><para>
                         On the target machine, add the repository to Smart.
-                        For <filename>somealias</filename>, provide a local 
+                        For <filename>somealias</filename>, provide a local
                         alias for the repository:
                         <literallayout class='monospaced'>
      smart channel &dash;&dash;add &lt;somealias&gt; type=rpm-md baseurl=http://server.name/rpm
                         </literallayout>
                         </para></listitem>
                     <listitem><para>
-                        Also from the target machine, fetch the repository 
+                        Also from the target machine, fetch the repository
                         information using this command:
                         <literallayout class='monospaced'>
      smart update
@@ -3249,9 +3240,9 @@
             </para>
 
             <para>
-                After taking these steps and making sure that the other 
+                After taking these steps and making sure that the other
                 requirements mentioned at the beginning of the section are met,
-                reboot the target device to take advantage of runtime package 
+                reboot the target device to take advantage of runtime package
                 installations.
             </para>
         </section>
diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
index e2f1611b5b..a03a68b6e9 100644
--- a/documentation/ref-manual/ref-classes.xml
+++ b/documentation/ref-manual/ref-classes.xml
@@ -328,51 +328,52 @@
     </para>
 
     <para>
+        If you take the optional step to set up a repository (package feed)
+        on the development host that can be used by Smart, you can
+        install packages from the feed while you are running the image
+        on the target (i.e. runtime installation of packages).
+        For information on how to set up this repository, see the
+        "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-runtime-package-management'>Setting Up Runtime Package Management</ulink>"
+         in the Yocto Project Development Manual.
+    </para>
+
+    <para>
         The package class you choose can affect build-time performance and has space
         ramifications.
         In general, building a package with IPK takes about thirty percent less
         time as compared to using RPM to build the same or similar package.
-        This comparison takes into account a complete build of the package with 
+        This comparison takes into account a complete build of the package with
         all dependencies previously built.
-        The reason for this discrepancy is because the RPM package manager 
-        creates and processes more 
-        <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> than the 
+        The reason for this discrepancy is because the RPM package manager
+        creates and processes more
+        <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> than the
         IPK package manager.
         Consequently, you might consider setting <filename>PACKAGE_CLASSES</filename>
         to "package_ipk" if you are building smaller systems.
     </para>
 
     <para>
-        Before making your decision on package manager, however, you should 
+        Before making your decision on package manager, however, you should
         consider some further things about using RPM:
         <itemizedlist>
             <listitem><para>
                 RPM starts to provide more abilities than IPK due to
                 the fact that it processes more metadata.
-                For example, this information includes individual file types, 
-                file checksum generation and evaluation on install, sparse file 
-                support, conflict detection and resolution for Multilib systems, 
+                For example, this information includes individual file types,
+                file checksum generation and evaluation on install, sparse file
+                support, conflict detection and resolution for Multilib systems,
                 ACID style upgrade, and repackaging abilities for rollbacks.
                 </para></listitem>
             <listitem><para>
-                For smaller systems, the extra space used for the Berkley 
-                Database and the amount of metadata when using RPM can affect 
+                For smaller systems, the extra space used for the Berkley
+                Database and the amount of metadata when using RPM can affect
                 your ability to perform on-device upgrades.
                 </para></listitem>
-            <listitem><para>
-                If you take the steps to set up a repository (package feed)    
-                on the development host that can be used by Smart, you can
-                install packages from the feed while you are running the image
-                on the target (i.e. runtime installation of packages).
-                For information on how to set up this repository, see the 
-                "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-runtime-package-management'>Setting Up Runtime Package Management</ulink>"
-                 in the Yocto Project Development Manual.
-            </para></listitem>
-        </itemizedlist> 
+        </itemizedlist>
     </para>
 
     <para>
-        You can find additional information on the effects of the package 
+        You can find additional information on the effects of the package
         class at these two Yocto Project mailing list links:
         <itemizedlist>
             <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006362.html'>