user-manual-metadata: Reorganization of chapter.

Reorganization of the whole chapter into a more reasonable
layout.  Addition of various sections to make organization
happen.

Signed-off-by: Bill Traynor <wmat@alphatroop.com>

1 files changed, 265 insertions, 219 deletions

diff --git a/doc/user-manual/user-manual-metadata.xml b/doc/user-manual/user-manual-metadata.xml
index 6f7090852..1ea380354 100644
--- a/doc/user-manual/user-manual-metadata.xml
+++ b/doc/user-manual/user-manual-metadata.xml
@@ -44,8 +44,9 @@
     </para>
     </section>
 
+<section>
     <section>
-      <title>Basic variable setting</title>
+      <title>Basic Variable Setting</title>
       <para>
         <screen>
         <varname>VARIABLE</varname> = "value"</screen>
@@ -56,7 +57,7 @@
     </section>
     
     <section>
-      <title>Variable expansion</title>
+      <title>Variable Expansion</title>
       <para>BitBake supports variables referencing one another's contents using
 	      a syntax which is similar to shell scripting:
       </para>
@@ -73,7 +74,7 @@
     </section>
     
     <section>
-      <title>Setting a default value (?=)</title>
+      <title>Setting a Default Value (?=)</title>
       <para>
         <screen>
         <varname>A</varname>?= "aval"</screen>
@@ -89,7 +90,7 @@
     </section>
     
     <section>
-      <title>Setting a weak default value (??=)</title>
+      <title>Setting a Weak Default Value (??=)</title>
       <para>
         <screen>
         <varname>A</varname>??= "somevalue" 
@@ -113,7 +114,7 @@
     </section>
     
     <section>
-      <title>Immediate variable expansion (:=)</title>
+      <title>Immediate Variable Expansion (:=)</title>
       <para>:= results in a variable's contents being expanded immediately,
 	      rather than when the variable is actually used.
       </para>
@@ -139,9 +140,11 @@
 	      <literal>cvalappend</literal>.
       </para>
     </section>
-    
+</section>
+
+
     <section>
-      <title>Appending (+=) and prepending (=+)</title>
+      <title>Appending (+=) and Prepending (=+)</title>
       <para>
         <screen>
         <varname>B</varname> = "bval" 
@@ -160,7 +163,7 @@
       </para>
     </section>
     <section>
-	    <title>Appending (.=) and prepending (=.) without spaces</title>
+	    <title>Appending (.=) and Prepending (=.) without spaces</title>
 	    <para>
 		    <screen>
 			    <varname>B</varname> = "bval" 
@@ -168,11 +171,10 @@
 			    <varname>C</varname> = "cval" 
 			    <varname>C</varname>=. "test"
 		    </screen>
-	</para>
-	<para>In this example,
-		<varname>B</varname> 
-		is now
-		<literal>bvaladditionaldata</literal> 
+	    </para>
+	    <para>In this example,
+	    <varname>B</varname>		is now
+		   <literal>bvaladditionaldata</literal> 
 		and 
 		<varname>C</varname> 
 		is 
@@ -201,8 +203,50 @@ yourself.</para>
                 <para>In this example, <varname>FOO</varname> is now <literal>789 123456</literal>.</para>
     </section>
 
+<section>
+	<title>Variable Flags</title>
+	<para>Variables can have associated flags which provide a way of 
+		tagging extra information onto a variable.
+		Several flags are used internally by BitBake but they can be 
+		used externally too if needed.
+		The standard operations mentioned above also work on flags.
+	</para>
+	<para>
+		<screen>
+			<varname>VARIABLE</varname>
+			[
+			<varname>SOMEFLAG</varname>
+			] = "value"
+		</screen>
+	</para>
+	<para>In this example,
+		<varname>VARIABLE</varname> 
+		has a flag, 
+		<varname>SOMEFLAG</varname> 
+		that is set to 
+		<literal>value</literal>.
+	</para>
+	</section>
+	
+<section>
+	<title>Inline Python variable expansion</title>
+	<para>
+		<screen>
+			<varname>DATE</varname> =
+			 "${@time.strftime('%Y%m%d',time.gmtime())}"
+		 </screen>
+	</para>
+	<para>This would result in the
+		<varname>DATE</varname> 
+		variable containing today's date.
+	</para>
+	</section>
+	
+<section>
+     <title>Conditional Syntax (Overrides)</title>
+     
     <section>
-	    <title>Conditional metadata set</title>
+	    <title>Conditional Metadata</title>
 	    <para>OVERRIDES is a 
 		    <quote>:</quote> 
 		    separated variable containing each item you want to satisfy
@@ -238,7 +282,7 @@ yourself.</para>
     </section>
     
     <section>
-	    <title>Conditional appending</title>
+	    <title>Conditional Appending</title>
 	    <para>BitBake also supports appending and prepending to variables 
 		    based on whether something is in OVERRIDES.
 		    Example:
@@ -252,15 +296,135 @@ yourself.</para>
 			    <varname>DEPENDS_append_machine</varname> 
 			    = "libmad"
 		    </screen>
-	</para>
-	<para>In this example, 
-		<varname>DEPENDS</varname> '
-		is set to
+		    </para>
+		    <para>In this example,
+		    <varname>DEPENDS</varname> is set to
 		<literal>glibc ncurses libmad</literal>.
 	</para>
 	</section>
+
+<section>
+	<title>Variable Interaction: Worked Examples</title>
+	<para>Despite the documentation of the different forms of variable 
+		definition above, it can be hard to work out what happens when 
+		variable operators are combined.
+		This section documents some common questions people have 
+		regarding the way variables interact.
+	</para>
+	</section>
+	
+	<section>
+	<title>Override and Append Ordering</title>
+	<para>There is often confusion about which order overrides and the 
+		various append operators take effect.
+	</para>
+	<para>
+		<screen>
+			<varname>OVERRIDES</varname> 
+			= "foo" 
+			<varname>A_foo_append</varname> 
+			= "X"</screen>
+	</para>
+	<para>In this case, X is unconditionally appended to the variable 
+		<varname>A_foo</varname>. 
+		Since foo is an override, A_foo would then replace 
+		<varname>A</varname>.</para>
+	<para>
+		<screen>
+			<varname>OVERRIDES</varname> 
+			= "foo" 
+			<varname>A</varname> 
+			= "X" 
+			<varname>A_append_foo</varname> 
+			= "Y"
+		</screen>
+	</para>
+	<para>In this case, only when foo is in OVERRIDES, Y is appended to the
+		variable 
+		<varname>A</varname> 
+		so the value of 
+		<varname>A</varname> 
+		would become XY (NB: no spaces are appended).
+	</para>
+	<para>
+		<screen>
+			<varname>OVERRIDES</varname> 
+			= "foo" 
+			<varname>A_foo_append</varname> 
+			= "X" 
+			<varname>A_foo_append</varname>
+			+= "Y"
+		</screen>
+        </para>
+	<para>This behaves as per the first case above, but the value of
+		<varname>A</varname> 
+		would be "X Y" instead of just "X".
+	</para>
+	<para>
+		<screen>
+			<varname>A</varname> 
+			= "1" 
+			<varname>A_append</varname> 
+			= "2" 
+			<varname>A_append</varname> 
+			= "3" 
+			<varname>A</varname>
+			+= "4" 
+			<varname>A</varname>
+			.= "5"
+		</screen>
+        </para>
+	<para>Would ultimately result in 
+		<varname>A</varname> 
+		taking the value "1 4523" since the _append operator executes 
+		at the same time as the expansion of other overrides.
+	</para>
+	</section>
 	
 	<section>
+	<title>Key Expansion</title>
+	<para>Key expansion happens at the data store finalisation time just
+		before overrides are expanded.
+	</para>
+	<para>
+		<screen>
+			<varname>A${B}</varname> 
+			= "X"
+			<varname>B</varname> 
+			= "2" 
+			<varname>A2</varname> 
+			= "Y"
+		</screen>
+	</para>
+	<para>So in this case 
+		<varname>A2</varname> 
+		would take the value of "X".
+	</para>
+	</section>
+	</section>
+	
+<section>
+<title>Inheritance</title>
+<section>
+	<title>Inheritance</title>
+	<para>
+		<emphasis>NOTE:</emphasis> This is only supported in .bb 
+		and .bbclass files.
+	</para>
+	<para>The <literal>inherit</literal> directive is a means of specifying
+		what classes of functionality your .bb requires.
+		It is a rudimentary form of inheritance.
+		For example, you can easily abstract out the tasks involved in
+		building a package that uses autoconf and automake, and put 
+		that into a bbclass for your packages to make use of. 
+		A given bbclass is located by searching for 
+		classes/filename.bbclass in 
+		<envar>BBPATH</envar>, 
+		where filename is what you inherited.
+	</para>
+	</section>
+
+<section>
 	<title>Inclusion</title>
 	<para>Next, there is the 
 		<literal>include</literal> directive, that causes BitBake to
@@ -271,11 +435,12 @@ yourself.</para>
 		line is a relative path, BitBake will locate the first one it
 		can find within 
 		<envar>BBPATH</envar>.
+   FIX ME: This section requires improvement.
 	</para>
 	</section>
 	
 	<section>
-	<title>Requiring inclusion</title>
+	<title>Requiring Inclusion</title>
 	<para>In contrast to the 
 		<literal>include</literal> 
 		directive, 
@@ -285,25 +450,27 @@ yourself.</para>
 		Otherwise it will behave just like the 
 		<literal>include</literal> 
 		directive.
+		FIX ME: This section requires improvement.
+		
 	</para>
 	</section>
 	
 	<section>
-	<title>Inline Python variable expansion</title>
+	<title>INHERIT Configuration Directive</title>
 	<para>
-		<screen>
-			<varname>DATE</varname> =
-			 "${@time.strftime('%Y%m%d',time.gmtime())}"
-		 </screen>
-	</para>
-	<para>This would result in the
-		<varname>DATE</varname> 
-		variable containing today's date.
-	</para>
-	</section>
-	
+	     This configuration directive causes the named class to be inherited at this point during parsing.
+	     This variable is only valid in configuration files.
+	     </para>
+	     
+	     <para>ADD MORE HERE</para>
+	     
+</section>
+</section>
+
+<section>
+     <title>Functions and Tasks</title>
 	<section>
-	<title>Defining executable metadata</title>
+	<title>Defining Executable Metadata</title>
 	<para>
 		<emphasis>NOTE:</emphasis> 
 		This is only supported in .bb and .bbclass files.
@@ -326,7 +493,7 @@ yourself.</para>
 	</section>
 	
 	<section>
-	<title>Defining Python functions into the global Python namespace
+	<title>Defining Python Functions into the Global Python Namespace
 	</title>
 	<para>
 		<emphasis>NOTE:</emphasis> 
@@ -353,51 +520,7 @@ yourself.</para>
 	</para>
 	</section>
 	
-	<section>
-	<title>Variable flags</title>
-	<para>Variables can have associated flags which provide a way of 
-		tagging extra information onto a variable.
-		Several flags are used internally by BitBake but they can be 
-		used externally too if needed.
-		The standard operations mentioned above also work on flags.
-	</para>
-	<para>
-		<screen>
-			<varname>VARIABLE</varname>
-			[
-			<varname>SOMEFLAG</varname>
-			] = "value"
-		</screen>
-	</para>
-	<para>In this example,
-		<varname>VARIABLE</varname> 
-		has a flag, 
-		<varname>SOMEFLAG</varname> 
-		that is set to 
-		<literal>value</literal>.
-	</para>
-	</section>
-	
-	<section>
-	<title>Inheritance</title>
-	<para>
-		<emphasis>NOTE:</emphasis> This is only supported in .bb 
-		and .bbclass files.
-	</para>
-	<para>The <literal>inherit</literal> directive is a means of specifying
-		what classes of functionality your .bb requires.
-		It is a rudimentary form of inheritance.
-		For example, you can easily abstract out the tasks involved in
-		building a package that uses autoconf and automake, and put 
-		that into a bbclass for your packages to make use of. 
-		A given bbclass is located by searching for 
-		classes/filename.bbclass in 
-		<envar>BBPATH</envar>, 
-		where filename is what you inherited.
-	</para>
-	</section>
-	
-	<section>
+		<section>
 	<title>Tasks</title>
 	<para>
 		<emphasis>NOTE:</emphasis> 
@@ -454,6 +577,65 @@ yourself.</para>
 	</para>
 	</section>
 	
+<section>
+	<title>Parsing</title>
+	<section>
+		<title>Configuration files</title>
+		<para>The first kind of metadata in BitBake is configuration
+			metadata.
+			This metadata is global, and therefore affects
+			<emphasis>all</emphasis> 
+			packages and tasks that are executed.
+		</para>
+		<para>BitBake will first search the current working directory 
+			for an optional "conf/bblayers.conf" configuration 
+			file.
+			This file is expected to contain a BBLAYERS variable 
+			that is a space delimited list of 'layer' directories.
+			For each directory in this list, a "conf/layer.conf" 
+			file will be searched for and parsed with the LAYERDIR 
+			variable being set to the directory where the layer was
+			found.
+			The idea is these files will setup BBPATH and other 
+			variables correctly for a given build directory
+			automatically for the user.
+		</para>
+		<para>BitBake will then expect to find 'conf/bitbake.conf'
+			somewhere in the user specified 
+			<envar>BBPATH</envar>. 
+			That configuration file generally has include 
+			directives to pull in any other metadata  (generally 
+			files specific to architecture, machine,
+			<emphasis>local</emphasis>and so on).
+		</para>
+		<para>Only variable definitions and include directives are
+			allowed in .conf files.
+		</para>
+	</section>
+<section>
+	<title>Classes</title>
+	<para>BitBake classes are our rudimentary inheritance mechanism. 
+		As briefly mentioned in the metadata introduction, they're 
+		parsed when an
+		<literal>inherit</literal> 
+		directive is encountered, and they are located in classes/ 
+		relative to the directories in
+		<envar>BBPATH</envar>.
+	</para>
+	</section>
+<section>
+        <title>.bb files</title>
+	<para>A BitBake (.bb) file is a logical unit of tasks to be executed.
+		Normally this is a package to be built.
+		Inter-.bb dependencies are obeyed.
+		The files themselves are located via the 
+		<varname>BBFILES</varname> 
+		variable, which is set to a space separated list of .bb files,
+		and does handle wildcards.
+	</para>
+	</section>
+    </section>	
+	
 	<section>
 	<title>Events</title>
 	<para>
@@ -537,108 +719,9 @@ yourself.</para>
 		(<varname>FILESPATH</varname>).
 	</para>
 	</section>
-	
-	<section>
-	<title>Variable interaction: Worked Examples</title>
-	<para>Despite the documentation of the different forms of variable 
-		definition above, it can be hard to work out what happens when 
-		variable operators are combined.
-		This section documents some common questions people have 
-		regarding the way variables interact.
-	</para>
-	</section>
-	
-	<section>
-	<title>Override and append ordering</title>
-	<para>There is often confusion about which order overrides and the 
-		various append operators take effect.
-	</para>
-	<para>
-		<screen>
-			<varname>OVERRIDES</varname> 
-			= "foo" 
-			<varname>A_foo_append</varname> 
-			= "X"</screen>
-	</para>
-	<para>In this case, X is unconditionally appended to the variable 
-		<varname>A_foo</varname>. 
-		Since foo is an override, A_foo would then replace 
-		<varname>A</varname>.</para>
-	<para>
-		<screen>
-			<varname>OVERRIDES</varname> 
-			= "foo" 
-			<varname>A</varname> 
-			= "X" 
-			<varname>A_append_foo</varname> 
-			= "Y"
-		</screen>
-	</para>
-	<para>In this case, only when foo is in OVERRIDES, Y is appended to the
-		variable 
-		<varname>A</varname> 
-		so the value of 
-		<varname>A</varname> 
-		would become XY (NB: no spaces are appended).
-	</para>
-	<para>
-		<screen>
-			<varname>OVERRIDES</varname> 
-			= "foo" 
-			<varname>A_foo_append</varname> 
-			= "X" 
-			<varname>A_foo_append</varname>
-			+= "Y"
-		</screen>
-        </para>
-	<para>This behaves as per the first case above, but the value of
-		<varname>A</varname> 
-		would be "X Y" instead of just "X".
-	</para>
-	<para>
-		<screen>
-			<varname>A</varname> 
-			= "1" 
-			<varname>A_append</varname> 
-			= "2" 
-			<varname>A_append</varname> 
-			= "3" 
-			<varname>A</varname>
-			+= "4" 
-			<varname>A</varname>
-			.= "5"
-		</screen>
-        </para>
-	<para>Would ultimately result in 
-		<varname>A</varname> 
-		taking the value "1 4523" since the _append operator executes 
-		at the same time as the expansion of other overrides.
-	</para>
-	</section>
-	
-	<section>
-	<title>Key Expansion</title>
-	<para>Key expansion happens at the data store finalisation time just
-		before overrides are expanded.
-	</para>
-	<para>
-		<screen>
-			<varname>A${B}</varname> 
-			= "X"
-			<varname>B</varname> 
-			= "2" 
-			<varname>A2</varname> 
-			= "Y"
-		</screen>
-	</para>
-	<para>So in this case 
-		<varname>A2</varname> 
-		would take the value of "X".
-	</para>
-	</section>
-	
+		
 	<section>
-	<title>Dependency handling</title>
+	<title>Dependencies</title>
 	<para>BitBake handles dependencies at the task level since to allow for
 		efficient operation with multiple processes executing in 
 		parallel, a robust method of specifying task dependencies is
@@ -731,42 +814,6 @@ yourself.</para>
 	</section>
 	
 	<section>
-	<title>Parsing</title>
-	<section>
-		<title>Configuration files</title>
-		<para>The first kind of metadata in BitBake is configuration
-			metadata.
-			This metadata is global, and therefore affects
-			<emphasis>all</emphasis> 
-			packages and tasks that are executed.
-		</para>
-		<para>BitBake will first search the current working directory 
-			for an optional "conf/bblayers.conf" configuration 
-			file.
-			This file is expected to contain a BBLAYERS variable 
-			that is a space delimited list of 'layer' directories.
-			For each directory in this list, a "conf/layer.conf" 
-			file will be searched for and parsed with the LAYERDIR 
-			variable being set to the directory where the layer was
-			found.
-			The idea is these files will setup BBPATH and other 
-			variables correctly for a given build directory
-			automatically for the user.
-		</para>
-		<para>BitBake will then expect to find 'conf/bitbake.conf'
-			somewhere in the user specified 
-			<envar>BBPATH</envar>. 
-			That configuration file generally has include 
-			directives to pull in any other metadata  (generally 
-			files specific to architecture, machine,
-			<emphasis>local</emphasis>and so on).
-		</para>
-		<para>Only variable definitions and include directives are
-			allowed in .conf files.
-		</para>
-	</section>
-	
-	<section>
 	<title>Classes</title>
 	<para>BitBake classes are our rudimentary inheritance mechanism. 
 		As briefly mentioned in the metadata introduction, they're 
@@ -777,8 +824,7 @@ yourself.</para>
 		<envar>BBPATH</envar>.
 	</para>
 	</section>
-	
-	<section>
+<section>
         <title>.bb files</title>
 	<para>A BitBake (.bb) file is a logical unit of tasks to be executed.
 		Normally this is a package to be built.
@@ -789,5 +835,5 @@ yourself.</para>
 		and does handle wildcards.
 	</para>
 	</section>
-    </section>
+
 </chapter>