1 files changed, 15 insertions, 12 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 4a58a6f490..6ae7730f81 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1400,8 +1400,13 @@
             <title>Understanding Recipe Syntax</title>
 
             <para>
-                The basic items that make up a BitBake recipe file are
-                as follows:
+                Understanding recipe file syntax is important for
+                writing recipes.
+                The following list overviews the basic items that make up a
+                BitBake recipe file.
+                For more complete BitBake syntax descriptions, see the
+                "<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink>"
+                chapter of the BitBake User Manual.
                 <itemizedlist>
                     <listitem><para><emphasis>Variable Assignments and Manipulations:</emphasis>
                         Variable assignments allow a value to be assigned to a
@@ -1519,18 +1524,16 @@
                         <filename>local.conf</filename> file for variables
                         that are allowed to come through from the external
                         environment.
-                        Doing so allows you to actually set variables from
-                        the external environment that would otherwise be
-                        overwritten.</para>
-                        <para>Here is an example:
+                        </para>
+                        <para>Here is an example where
+                        <filename>VAR1</filename> is set to "New value" if
+                        it is currently empty.
+                        However, if <filename>VAR1</filename> has already been
+                        set, it remains unchanged:
                         <literallayout class='monospaced'>
      VAR1 ?= "New value"
                         </literallayout>
-                        In the previous example, <filename>VAR1</filename> is
-                        set to "New value" if it is currently empty.
-                        However, if <filename>VAR1</filename> has already been
-                        set, it remains unchanged.</para>
-                        <para>In this next example, <filename>VAR1</filename>
+                        In this next example, <filename>VAR1</filename>
                         is left with the value "Original value":
                         <literallayout class='monospaced'>
      VAR1 = "Original value"
@@ -1632,7 +1635,7 @@
                         </literallayout>
                         </para></listitem>
                     <listitem><para><emphasis>Shell Function Syntax:</emphasis>
-                        Use shell function syntax as if you were writing a shell
+                        Write shell functions as if you were writing a shell
                         script when you describe a list of actions to take.
                         You should ensure that your script works with a generic
                         <filename>sh</filename> and that it does not require