dev-manual, ref-manual: Applied review comments for read-only-rootfs, etc.

1. Applied changes from Paul to the read-only-rootfs section.

2. Applied changes form Paul to the customizing images by using
   IMAGE_FEATURES and EXTRA_IMAGE_FEATURES variables.  This
   was a simple rewrite of a sentence.

3. Updated the note in both the IMAGE_FEATURES and
   EXTRA_IMAGE_FEATURES glossary entries to specify inside
   of an image recipe (more specific).

(From yocto-docs rev: 762b9e4d3b45a9602284cf4dd1ac281dcbbed7f5)

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

2 files changed, 60 insertions, 58 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 1b57e60d05..2d13038f41 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -611,11 +611,11 @@
                 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
                 and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
                 variables.
-                Although both variables function nearly equivalent, best
-                practices dictate using <filename>IMAGE_FEATURES</filename>
+                Although the functions for both variables are nearly equivalent,
+                best practices dictate using <filename>IMAGE_FEATURES</filename>
                 from within a recipe and using
                 <filename>EXTRA_IMAGE_FEATURES</filename> from within
-                your <filename>local.conf</filename>, which is found in the
+                your <filename>local.conf</filename> file, which is found in the
                 <link linkend='build-directory'>Build Directory</link>.
             </para>
 
@@ -1026,8 +1026,8 @@
             <title>Post-Installation Scripts</title>
 
             <para>
-                To add a post-installation (postinstall) script to a package,
-                add a <filename>pkg_postinst_PACKAGENAME()
+                To add a post-installation script to a package, add a
+                <filename>pkg_postinst_PACKAGENAME()
                 </filename> function to the <filename>.bb</filename> file and use
                 <filename>PACKAGENAME</filename> as the name of the package you want to attach to the
                 <filename>postinst</filename> script.
@@ -3461,23 +3461,55 @@
         <note>
             Supporting a read-only root filesystem requires that the system and
             applications do not try to write to the root filesystem.
-            If writes are attempted, they need to gracefully fail.
+            You must configure all parts of the target system to write
+            elsewhere, or gracefully fail in the event of failing to
+            write to the root filesystem.
         </note>
 
+        <section id='creating-the-root-filesystem'>
+            <title>Creating the Root Filesystem</title>
+
+            <para>
+                To create the read-only root filesystem, simply add the
+                <filename>read-only-rootfs</filename> 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
+                <link linkend='build-directory'>Build Directory</link>
+                causes the build system to create a read-only root filesystem:
+                <literallayout class='monospaced'>
+     IMAGE_FEATURES = "read-only-rootfs"
+                </literallayout>
+                or
+                <literallayout class='monospaced'>
+     EXTRA_IMAGE_FEATURES = "read-only-rootfs"
+                </literallayout>
+            </para>
+
+            <para>
+                For more information on how to use these variables, see the
+                "<link linkend='usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></link>"
+                section.
+                For information on the variables, see
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
+                and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>.
+            </para>
+        </section>
+
         <section id='post-installation-scripts'>
             <title>Post-Installation Scripts</title>
 
             <para>
                 It is very important that you make sure all
-                Post-Installation (postinstall) scripts
+                post-Installation (<filename>pkg_postinst</filename>) scripts
                 for packages that are installed into the image can be run
                 at the time when the root filesystem is created during the
                 build on the host system.
                 These scripts cannot attempt to run during first-boot on the
                 target device.
-                With the read-only root filesystem feature enabled,
+                With the <filename>read-only-rootfs</filename> feature enabled,
                 the build system checks during root filesystem creation to make
-                sure all postinstall scripts succeed.
+                sure all post-installation scripts succeed.
                 If any of these scripts still need to be run after the root
                 filesystem is created, the build immediately fails.
                 These checks during build time ensure that the build fails
@@ -3486,22 +3518,24 @@
             </para>
 
             <para>
-                Most of the common postinstall scripts generated by the build
-                system for the out-of-the-box Yocto Project are engineered
+                Most of the common post-installation scripts generated by the
+                build system for the out-of-the-box Yocto Project are engineered
                 so that they can run during root filesystem creation
-                (e.g. postinstall scripts for caching fonts).
+                (e.g. post-installation scripts for caching fonts).
                 However, if you create and add custom scripts, you need
                 to be sure they can be run during file system creation.
             </para>
 
             <para>
-                Here are some common problems that prevent postinstall
-                scripts from running during root filesystem creation:
+                Here are some common problems that prevent
+                post-installation scripts from running during root filesystem
+                creation:
                 <itemizedlist>
-                    <listitem><para>Not using
+                    <listitem><para><emphasis>Not using
                         <filename>$</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink>
-                        in front of absolute paths.
-                        The build system defines <filename>$D</filename>, and
+                        in front of absolute paths:</emphasis>
+                        The build system defines <filename>$D</filename>
+                        at root filesystem creation time, and
                         it is blank when run on the target device.
                         This implies two purposes for <filename>$D</filename>:
                         ensuring paths are valid in both the host and target
@@ -3509,11 +3543,11 @@
                         environment is being used as a method for taking
                         appropriate actions.
                         </para></listitem>
-                    <listitem><para>Attempting to run processes that are
+                    <listitem><para><emphasis>Attempting to run processes that are
                         specific to or dependent on the target
-                        architecture.
+                        architecture:</emphasis>
                         You can work around these attempts by using native
-                        tools to accomplish the same processes (tasks), or
+                        tools to accomplish the same tasks, or
                         by alternatively running the processes under QEMU,
                         which has the <filename>qemu_run_binary</filename>
                         function.
@@ -3522,8 +3556,6 @@
                         class in the
                         <link linkend='source-directory'>Source Directory</link>.
                         </para></listitem>
-                    <listitem><para>Using hardware features specific to the machine.
-                        </para></listitem>
                 </itemizedlist>
             </para>
         </section>
@@ -3532,45 +3564,15 @@
             <title>Areas With Write Access</title>
 
             <para>
-                With the read-only root filesystem feature enabled, any
-                attempt by the target to write to the root filesystem at
+                With the <filename>read-only-rootfs</filename> feature enabled,
+                any attempt by the target to write to the root filesystem at
                 runtime fails.
                 Consequently, you must make sure that you configure processes
                 and applications that attempt these types of writes do so
-                to directories with write access (i.e.
+                to directories with write access (e.g.
                 <filename>/tmp</filename> or <filename>/var/run</filename>).
             </para>
         </section>
-
-        <section id='creating-the-root-filesystem'>
-            <title>Creating the Root Filesystem</title>
-
-            <para>
-                To create the 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
-                <link linkend='build-directory'>Build Directory</link>
-                causes the build system to create a read-only root filesystem:
-                <literallayout class='monospaced'>
-     IMAGE_FEATURES = "read-only-rootfs"
-                </literallayout>
-                or
-                <literallayout class='monospaced'>
-     EXTRA_IMAGE_FEATURES = "read-only-rootfs"
-                </literallayout>
-            </para>
-
-            <para>
-                For more information on how to use these variables, see the
-                "<link linkend='usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></link>"
-                section.
-                For information on the variables, see
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
-                and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>.
-            </para>
-        </section>
     </section>
 
     <section id="platdev-gdb-remotedebug">
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index ccb48e438b..d54b5bcdfc 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -954,8 +954,8 @@ Core layer for images cannot be removed
                     Although you can use this variable from within a recipe,
                     best practices dictate that you do not.
                     <note>
-                        To enable primary features from within the image, use
-                        the
+                        To enable primary features from within the image
+                        recipe, use the
                         <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
                         variable.
                     </note>
@@ -1243,7 +1243,7 @@ Core layer for images cannot be removed
                     <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
                     best practices dictate that you do not.
                     <note>
-                        To enable extra features from outside the image,
+                        To enable extra features from outside the image recipe,
                         use the
                         <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> variable.
                     </note>