documentation/dev-manual: Edits from Tom Zanussi.

Tom Zanussi provided a review up through part of the "model"
chapter.  I have implemented his comments mosty verbatim.

Reported-by: Tom Zanussi
(From yocto-docs rev: 693d4fadd4b34ffef9953fb1850d381ff7c028a3)

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

4 files changed, 28 insertions, 15 deletions

diff --git a/documentation/dev-manual/dev-manual-intro.xml b/documentation/dev-manual/dev-manual-intro.xml
index 85eea51..da6abd4 100644
--- a/documentation/dev-manual/dev-manual-intro.xml
+++ b/documentation/dev-manual/dev-manual-intro.xml
@@ -35,7 +35,7 @@
             <itemizedlist>
                 <listitem><para>Information that lets you get set 
                     up to develop using the Yocto Project.</para></listitem>
-                <listitem><para>Information to help developers that are new to the open source environment 
+                <listitem><para>Information to help developers who are new to the open source environment 
                     and to the distributed revision control system Git, which the Yocto Project 
                     uses.</para></listitem>
                 <listitem><para>An understanding of common end-to-end development models.</para></listitem>
@@ -63,7 +63,7 @@
             <itemizedlist>
                 <listitem><para>Step-by-step instructions if those instructions exist in other Yocto 
                     Project documentation.  
-                    For example, The Application Development Toolkit (ADT) User’s Guide contains detailed 
+                    For example, the Application Development Toolkit (ADT) User’s Guide contains detailed 
                     instruction on how to obtain and configure the 
                     <trademark class='trade'>Eclipse</trademark> Yocto Plug-in.</para></listitem>
                 <listitem><para>Reference material.  
@@ -153,7 +153,7 @@
                     OpenedHand has since been acquired by Intel Corporation.</para></listitem>
                 <listitem><para><emphasis>
                     <ulink url='http://www.intel.com/'>Intel Corporation</ulink>:</emphasis>
-                    The company who acquired OpenedHand in 2008 and continues development on the 
+                    The company that acquired OpenedHand in 2008 and continues development on the 
                     Yocto Project.</para></listitem>
                 <listitem><para><emphasis>
                     <ulink url='http://www.openembedded.org/'>OpenEmbedded</ulink>:</emphasis>
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index f2912b1..296c59b 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -51,7 +51,7 @@
 
         <para>
             A BSP is a package of recipes that, when applied, during a build results in 
-            an image you can run on a particular board.  
+            an image that you can run on a particular board.  
             Thus, the package, when compiled into the new image, supports the operation of the board.  
         </para>
 
@@ -61,8 +61,8 @@
         </note>
 
         <para>
-            The remainder of this section presents the basic steps to create a BSP basing it on an 
-            existing BSP that ships with the Yocto Project.
+            The remainder of this section presents the basic steps used to create a BSP 
+            based on an existing BSP that ships with the Yocto Project.
             You can reference the "<link linkend='dev-manual-bsp-appendix'>BSP Development Example</link>"
             appendix for a detailed example that uses the Crown Bay BSP as a base BSP from which to start.
         </para>
@@ -85,12 +85,12 @@
                 <listitem><para><emphasis>Establish a local copy of the Yocto Project files on your 
                     system</emphasis>:  You need to have the Yocto Project files available on your host system. 
                     Having the Yocto Project files on your system gives you access to the build
-                    process and tools you need.
+                    process and to the tools you need.
                     For information on how to get these files, see the
                     "<link linkend='getting-setup'>Getting Setup</link>" section.</para></listitem>
                 <listitem><para><emphasis>Establish a local copy of the base BSP files</emphasis>:  Having    
                     the BSP files on your system gives you access to the build
-                    process and tools you need for creating a BSP.
+                    process and to the tools you need for creating a BSP.
                     For information on how to get these files, see the
                     "<link linkend='getting-setup'>Getting Setup</link>" section.</para></listitem>    
                 <listitem><para><emphasis>Choose a Yocto Project-supported BSP as your base BSP</emphasis>:  
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index 54dd71a..0efcbbb 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -11,7 +11,7 @@
     closed, proprietary environment.  
     Additionally, the Yocto Project uses specific tools and constructs as part of its development 
     environment.  
-    The chapter specifically addresses open source philosophy, licensing issues, code repositories, 
+    This chapter specifically addresses open source philosophy, licensing issues, code repositories, 
     the open source distributed version control system Git, and best practices using the Yocto Project.
 </para>
 
@@ -73,7 +73,7 @@
         Conversely, if you are a developer that is not interested in contributing back to the 
         Yocto Project, you have the ability to simply download and extract release tarballs
         and use them within the Yocto Project environment.
-        All that is required is a particular release of Yocto Project, a kernel, and 
+        All that is required is a particular release of the Yocto Project and 
         your application source code.  
     </para>
 
@@ -599,7 +599,7 @@
     </para>
 
     <para>
-        Following is some guidance on which mailing list to use for what type of defect:
+        The following is some guidance on which mailing list to use for what type of defect:
         <itemizedlist>
             <listitem><para>For defects against the Yocto Project build system Poky, send 
                 your patch to the  
@@ -778,6 +778,11 @@
                     <para>If you provide several commits as part of the command, 
                     the <filename>git format-patch</filename> command produces a numbered 
                     series of files in the current directory – one for each commit.
+                    If you have more than one patch, you should also use the 
+                    <filename>--cover</filename> option with the command, which generates a 
+                    cover letter as the first "patch" in the series.  
+                    You can then edit the cover letter to provide a description for 
+                    the series of patches.
                     For information on the <filename>git format-patch</filename> command, 
                     see <filename>GIT_FORMAT_PATCH(1)</filename> displayed using the  
                     <filename>man git-format-patch</filename> command.</para></listitem>
@@ -790,7 +795,15 @@
                     or remote Mail Transport Agent (MTA) such as 
                     <filename>msmtp</filename>, <filename>sendmail</filename>, or through a direct
                     <filename>smtp</filename> configuration in your Git <filename>config</filename>
-                    file.</para>
+                    file.
+                    If you are submitting patches through email only, it is very important
+                    that you submit them without any whitespace or HTML formatting that 
+                    either you or your mailer introduces.
+                    The maintainer that receives your patches needs to be able to save and 
+                    apply them directly from your emails.
+                    A good way to verify that what you are sending will be applicable by the 
+                    maintainer is to do a dry run and send them to yourself and then 
+                    save and apply them as the maintainer would.</para>
                     <para>The <filename>git send-email</filename> command is the preferred method
                     for sending your patches since there is no risk of compromising whitespace
                     in the body of the message, which can occur when you use your own mail client.
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index df1d59f..2a93ec6 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -43,7 +43,7 @@
 </section>
 
 <section id='getting-setup'>
-    <title>Getting Setup</title>
+    <title>Getting Set Up</title>
 
     <para>
         Here is what you need to get set up to use the Yocto Project:
@@ -141,8 +141,8 @@
      Checking out files: 100% (36898/36898), done.                </literallayout></para></listitem>
             <listitem id='poky-extras-repo'><para><emphasis>
                 The <filename>poky-extras</filename> Git Repository</emphasis>:
-                The <filename>poky-extras</filename> Git repository contains metadata needed to 
-                build the kernel image.
+                The <filename>poky-extras</filename> Git repository contains metadata needed 
+                only if you are modifying and building the kernel image.
                 In particular, it contains the kernel <filename>.bbappend</filename> files that you 
                 edit to point to your locally modified kernel source files and to build the kernel
                 image.