From fded970a0709d928f70224d8b61534e9353ee6dd Mon Sep 17 00:00:00 2001
From: Scott Rifenbark <srifenbark@gmail.com>
Date: Sat, 2 Sep 2017 10:01:47 -0700
Subject: bitbake-user-manual: Clarified inherit, include, require
 relationships

Fixes [YOCTO #12032]

I applied some re-writing to help clarify the relationships between
the inherit, include, and require directives.

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
---
 .../bitbake-user-manual-metadata.xml               | 41 ++++++++++++++++++----
 1 file changed, 34 insertions(+), 7 deletions(-)

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml b/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
index 999d295e1..310b9d20d 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
@@ -899,11 +899,12 @@
 
             <para>
                 The <filename>inherit</filename> directive is a rudimentary
-                means of specifying what classes of functionality your
-                recipes require.
+                means of specifying functionality contained in class files
+                that your recipes require.
                 For example, you can easily abstract out the tasks involved in
                 building a package that uses Autoconf and Automake and put
-                those tasks into a class file that can be used by your recipe.
+                those tasks into a class file and then have your recipe
+                inherit that class file.
             </para>
 
             <para>
@@ -925,10 +926,13 @@
             </para>
 
             <para>
-                If necessary, it is possible to inherit a class
-                conditionally by using
-                a variable expression after the <filename>inherit</filename>
-                statement.
+                An advantage with the inherit directive as compared to both
+                the
+                <link linkend='include-directive'>include</link> and
+                <link linkend='require-inclusion'>require</link> directives
+                is that you can inherit class files conditionally.
+                You can accomplish this by using a variable expression
+                after the <filename>inherit</filename> statement.
                 Here is an example:
                 <literallayout class='monospaced'>
      inherit ${VARNAME}
@@ -984,6 +988,17 @@
                 within <filename>BBPATH</filename>.
             </para>
 
+            <para>
+                The include directive is a more generic method of including
+                functionality as compared to the
+                <link linkend='inherit-directive'>inherit</link> directive,
+                which is restricted to class (i.e. <filename>.bbclass</filename>)
+                files.
+                The include directive is applicable for any other kind of
+                shared or encapsulated functionality or configuration that
+                does not suit a <filename>.bbclass</filename> file.
+            </para>
+
             <para>
                 As an example, suppose you needed a recipe to include some
                 self-test definitions:
@@ -1017,6 +1032,18 @@
                 being parsed at the location of the directive.
             </para>
 
+            <para>
+                The require directive, like the include directive previously
+                described, is a more generic method of including
+                functionality as compared to the
+                <link linkend='inherit-directive'>inherit</link> directive,
+                which is restricted to class (i.e. <filename>.bbclass</filename>)
+                files.
+                The require directive is applicable for any other kind of
+                shared or encapsulated functionality or configuration that
+                does not suit a <filename>.bbclass</filename> file.
+            </para>
+
             <para>
                 Similar to how BitBake handles
                 <link linkend='include-directive'><filename>include</filename></link>,
-- 
cgit 1.2.3-korg