usermanual: Prepare to change from using numbers for chapater and section

URL's to using names. This required id's to be added to all of the sections and
chapters. I also renamed the id's in the recipes section from bb_ to
recipes_. This will allow for stable URLs into the user manual on the web
site. The change to the makefile to activate this is not yet commited.

2 files changed, 709 insertions, 458 deletions

diff --git a/usermanual/chapters/recipes.xml b/usermanual/chapters/recipes.xml
index 521dc27b0d..9d65b399b4 100644
--- a/usermanual/chapters/recipes.xml
+++ b/usermanual/chapters/recipes.xml
@@ -1,8 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<chapter>
+<chapter id="chapter_recipes">
   <title>Recipes</title>
 
-  <section id="bb_introduction" xreflabel="introduction">
+  <section id="recipes_introduction" xreflabel="introduction">
     <title>Introduction</title>
 
     <para>A bitbake recipe is a set of instructions that describe what needs
@@ -26,7 +26,7 @@
     then first take a look at the chapter on bitbake usage.</para>
   </section>
 
-  <section id="bb_syntax" xreflabel="syntax">
+  <section id="recipes_syntax" xreflabel="syntax">
     <title>Syntax of recipes</title>
 
     <para>The basic items that make up a bitbake recipe file are:</para>
@@ -259,7 +259,7 @@ mv fixed.recipe.bb myrecipe.bb</screen></para>
           <para>Python code is indicated by a proceeding @ sign in the
           variable assignment.<screen>CXXFLAGS := "${@'${CXXFLAGS}'.replace('-frename-registers', '')}"</screen>More
           information about using python is available in the <xref
-          linkend="bb_advanced_python" /> section.</para>
+          linkend="recipes_advanced_python" /> section.</para>
         </listitem>
       </varlistentry>
 
@@ -282,7 +282,7 @@ mv fixed.recipe.bb myrecipe.bb</screen></para>
     files you should refer to the bitbake use manual.</para>
   </section>
 
-  <section id="bb_versioning" xreflabel="versioning">
+  <section id="recipes_versioning" xreflabel="versioning">
     <title>Recipe naming: Names, versions and releases</title>
 
     <para>Recipes in OpenEmbedded use a standard naming convention that
@@ -394,7 +394,7 @@ mv fixed.recipe.bb myrecipe.bb</screen></para>
     edit the URL:<screen>SRC_URI = "ftp://ftp.vim.org/pub/vim/unix/vim-${PV}.tar.bz2"</screen></para>
   </section>
 
-  <section id="bb_variables" xreflabel="variables">
+  <section id="recipes_variables" xreflabel="variables">
     <title>Variables</title>
 
     <para>One of the most confusing part of bitbake recipes for new users is
@@ -476,7 +476,7 @@ mv fixed.recipe.bb myrecipe.bb</screen></para>
     </variablelist>
   </section>
 
-  <section id="bb_header" xreflabel="header">
+  <section id="recipes_header" xreflabel="header">
     <title>Header</title>
 
     <para>Practically all recipes start was the header section which describes
@@ -552,7 +552,7 @@ mv fixed.recipe.bb myrecipe.bb</screen></para>
     </variablelist>
   </section>
 
-  <section id="bb_sources" xreflabel="sources">
+  <section id="recipes_sources" xreflabel="sources">
     <title>Sources: Downloading, patching and additional files</title>
 
     <para>A recipes purpose is to describe how to take a software package and
@@ -669,7 +669,7 @@ mv fixed.recipe.bb myrecipe.bb</screen></para>
     linkend="src_uri_variable" /> section of the reference chapter.</para>
   </section>
 
-  <section id="bb_directories" xreflabel="directories">
+  <section id="recipes_directories" xreflabel="directories">
     <title>Directories: What goes where</title>
 
     <para>A large part of the work or a recipe is involved with specifying
@@ -897,7 +897,7 @@ S = "${WORKDIR}/widgets"</screen></para>
       chapter.</para>
     </section>
 
-    <section id="bb_filespath_dir" xreflabel="FILESPATH/FILESDIR">
+    <section id="recipes_filespath_dir" xreflabel="FILESPATH/FILESDIR">
       <title>FILESPATH/FILESDIR: Finding local files</title>
 
       <para>The file related variables are used by bitbake to determine where
@@ -1031,7 +1031,7 @@ ${FILE_DIRNAME}/${PN}:${FILE_DIRNAME}/files:${FILE_DIRNAME}"</screen></para>
     </section>
   </section>
 
-  <section id="bb_examples" xreflabel="examples">
+  <section id="recipes_examples" xreflabel="examples">
     <title>Basic examples</title>
 
     <para>By now you should know enough about the bitbake recipes to be able
@@ -1039,7 +1039,7 @@ ${FILE_DIRNAME}/${PN}:${FILE_DIRNAME}/files:${FILE_DIRNAME}"</screen></para>
     a more advanced example that uses the autotools helper class (to be
     described later) to build an autoconf based package.</para>
 
-    <section id="bb_helloworld_example" xreflabel="hello world example">
+    <section id="recipes_helloworld_example" xreflabel="hello world example">
       <title>Hello world</title>
 
       <para>Now it's time for our first recipe. This is going to be one of the
@@ -1311,7 +1311,7 @@ tmp/work/helloworld-0.1-r0/install/helloworld/usr/bin/helloworld: ELF 32-bit LSB
       That's exactly what we wanted.</para>
     </section>
 
-    <section id="bb_autoconf_example" xreflabel="autoconf example">
+    <section id="recipes_autoconf_example" xreflabel="autoconf example">
       <title>An autotools package</title>
 
       <para>Now for an example of a package that uses autotools. These are
@@ -1385,7 +1385,7 @@ inherit autotools</screen></para>
     </section>
   </section>
 
-  <section id="bb_depenencies" xreflabel="dependencies">
+  <section id="recipes_depenencies" xreflabel="dependencies">
     <title>Dependencies: What's needed to build and/or run the
     package?</title>
 
@@ -1436,7 +1436,7 @@ inherit autotools</screen></para>
     via the auto shared libs dependency code.</para>
   </section>
 
-  <section id="bb_methods" xreflabel="methods">
+  <section id="recipes_methods" xreflabel="methods">
     <title>Methods: Inbuilt methods to make your life easier</title>
 
     <para>There are several helper functions defined by the base class, which
@@ -1663,7 +1663,7 @@ inherit autotools</screen></para>
           <note>
             <para>The ${@...} syntax is used to call python functions from
             within a recipe or class. This is described in more detail in the
-            <xref linkend="bb_advanced_python" /> section.</para>
+            <xref linkend="recipes_advanced_python" /> section.</para>
           </note>
 
           <para>The following example from the openssl recipe shows the
@@ -1681,7 +1681,7 @@ inherit autotools</screen></para>
     </variablelist>
   </section>
 
-  <section id="bb_packages" xreflabel="packages">
+  <section id="recipes_packages" xreflabel="packages">
     <title>Packaging: Defining packages and their contents</title>
 
     <para>A bitbake recipe is a set of instructions from creating one, or
@@ -2130,7 +2130,7 @@ NOTE: package helloworld-0.1-r0: task do_package: completed</screen>Except in
     </section>
   </section>
 
-  <section id="bb_tasks" xreflabel="tasks">
+  <section id="recipes_tasks" xreflabel="tasks">
     <title>Tasks: Playing with tasks</title>
 
     <para>Bitbake steps through a series of tasks when building a recipe.
@@ -2241,7 +2241,7 @@ addtask unpack_extra after do_unpack before do_patch</screen></para>
     </variablelist>
   </section>
 
-  <section id="bb_classes" xreflabel="classes">
+  <section id="recipes_classes" xreflabel="classes">
     <title>Classes: The separation of common functionality</title>
 
     <para>This section is to be completed.</para>
@@ -2261,7 +2261,7 @@ addtask unpack_extra after do_unpack before do_patch</screen></para>
     </itemizedlist>
   </section>
 
-  <section id="bb_staging" xreflabel="staging">
+  <section id="recipes_staging" xreflabel="staging">
     <title>Staging: Making includes and libraries available for
     building</title>
 
@@ -2282,7 +2282,7 @@ addtask unpack_extra after do_unpack before do_patch</screen></para>
     </itemizedlist>
   </section>
 
-  <section id="bb_autoconf" xreflabel="about autoconf">
+  <section id="recipes_autoconf" xreflabel="about autoconf">
     <title>Autoconf: All about autotools</title>
 
     <para>This section is to be completed:</para>
@@ -2314,7 +2314,7 @@ addtask unpack_extra after do_unpack before do_patch</screen></para>
     </itemizedlist>
   </section>
 
-  <section id="bb_installation_scripts" xreflabel="installation scripts">
+  <section id="recipes_installation_scripts" xreflabel="installation scripts">
     <title>Installation scripts: Running scripts during package install and/or
     removal</title>
 
@@ -2420,7 +2420,7 @@ pkg_postinst_${PN}-rdisc6 () {
           <para>This class is used by daemons to register there init scripts
           with the init code.</para>
 
-          <para>Details are provided in the <xref linkend="bb_initscripts" />
+          <para>Details are provided in the <xref linkend="recipes_initscripts" />
           section.</para>
         </listitem>
       </varlistentry>
@@ -2467,7 +2467,7 @@ pkg_postinst_${PN}-rdisc6 () {
           system will create a symlink to the correct alternative from one or
           more available on the system.</para>
 
-          <para>Details are provided in the <xref linkend="bb_alternatives" />
+          <para>Details are provided in the <xref linkend="recipes_alternatives" />
           section.</para>
         </listitem>
       </varlistentry>
@@ -2508,7 +2508,7 @@ pkg_postinst_${PN}-rdisc6 () {
     postinst script it uses the update-rc.d class which will result in an
     additional entry being added to the postinst script to register the init
     scripts and start the daemon (via call to update-rc.d as describes in the
-    <xref linkend="bb_alternatives" /> section).<screen>inherit autotools update-rc.d
+    <xref linkend="recipes_alternatives" /> section).<screen>inherit autotools update-rc.d
 
 ...
 
@@ -2539,7 +2539,7 @@ fi</screen></para>
     <emphasis role="bold">group</emphasis> files for example.)</para>
   </section>
 
-  <section id="bb_conffiles" xreflabel="conf files">
+  <section id="recipes_conffiles" xreflabel="conf files">
     <title>Configuration files</title>
 
     <para>Configuration files that are installed as part of a package require
@@ -2571,7 +2571,7 @@ fi</screen></para>
     package.</para>
   </section>
 
-  <section id="bb_package_relationships"
+  <section id="recipes_package_relationships"
            xreflabel="package relationships files">
     <title>Package relationships</title>
 
@@ -2635,7 +2635,7 @@ fi</screen></para>
     </variablelist>
   </section>
 
-  <section id="bb_fakeroot" xreflabel="fakeroot">
+  <section id="recipes_fakeroot" xreflabel="fakeroot">
     <title>Fakeroot: Dealing with the need for "root"</title>
 
     <para>Sometimes packages requires root permissions in order to perform
@@ -2658,7 +2658,7 @@ fi</screen></para>
     the reference section: <xref linkend="fakeroot" />.</para>
   </section>
 
-  <section id="bb_native" xreflabel="native">
+  <section id="recipes_native" xreflabel="native">
     <title>Native: Packages for the build host</title>
 
     <para>This section is to be completed.</para>
@@ -2674,7 +2674,7 @@ fi</screen></para>
     </itemizedlist>
   </section>
 
-  <section id="bb_development" xreflabel="development">
+  <section id="recipes_development" xreflabel="development">
     <title>Development: Strategies for developing recipes</title>
 
     <para>This section is to be completed.</para>
@@ -2698,7 +2698,7 @@ fi</screen></para>
     </itemizedlist>
   </section>
 
-  <section id="bb_advanced_versioning" xreflabel="advanced versioning">
+  <section id="recipes_advanced_versioning" xreflabel="advanced versioning">
     <title>Advanced versioning: How to deal with rc and pre versions</title>
 
     <para>Special care needs to be taken when specify the version number for
@@ -2770,7 +2770,7 @@ fi</screen></para>
     expected.</para>
   </section>
 
-  <section id="bb_require" xreflabel="require">
+  <section id="recipes_require" xreflabel="require">
     <title>Require/include: Reusing recipe contents</title>
 
     <para>In many packages where you are maintaining multiple versions you'll
@@ -2833,7 +2833,7 @@ do_configure() {
 }</screen></para>
   </section>
 
-  <section id="bb_advanced_python" xreflabel="advanced python">
+  <section id="recipes_advanced_python" xreflabel="advanced python">
     <title>Python: Advanced functionality with python</title>
 
     <para>Recipes permit the use of python code in order to perform complex
@@ -2887,7 +2887,7 @@ do_configure() {
 
           <para>This is most commonly seen in existing recipes when settings
           the <emphasis role="bold">FILESDIR</emphasis> variable (as described
-          in the <xref linkend="bb_filespath_dir" /> section). By obtaining
+          in the <xref linkend="recipes_filespath_dir" /> section). By obtaining
           name of the recipe file itself, <emphasis
           role="bold">FILE</emphasis>, and then using os.path.dirname to strip
           the filename part:<screen>FILESDIR = "${@os.path.dirname(bb.data.getVar('FILE',d,1))}/make-${PV}"</screen>Note
@@ -3060,7 +3060,7 @@ do_configure() {
 }</screen></para>
   </section>
 
-  <section id="bb_defaultpreference" xreflabel="default preference">
+  <section id="recipes_defaultpreference" xreflabel="default preference">
     <title>Preferences: How to disable packages</title>
 
     <para>This section is to be completed.</para>
@@ -3080,7 +3080,7 @@ do_configure() {
     </itemizedlist>
   </section>
 
-  <section id="bb_initscripts" xreflabel="initscripts">
+  <section id="recipes_initscripts" xreflabel="initscripts">
     <title>Initscripts: How to handle daemons</title>
 
     <para>This section is to be completed.</para>
@@ -3108,7 +3108,7 @@ do_configure() {
     </itemizedlist>
   </section>
 
-  <section id="bb_alternatives" xreflabel="alternatives">
+  <section id="recipes_alternatives" xreflabel="alternatives">
     <title>Alternatives: How to handle the same command in multiple
     packages</title>
 
@@ -3125,7 +3125,7 @@ do_configure() {
     </itemizedlist>
   </section>
 
-  <section id="bb_volatiles" xreflabel="volatiles">
+  <section id="recipes_volatiles" xreflabel="volatiles">
     <title>Volatiles: How to handle the /var directory</title>
 
     <para>The <emphasis role="bold">/var</emphasis> directory is for storing
@@ -3244,7 +3244,7 @@ do_configure() {
     </section>
   </section>
 
-  <section>
+  <section id="recipes_misc">
     <title>Miscellaneous</title>
 
     <para>This section is to be completed.</para>
diff --git a/usermanual/usermanual.xml b/usermanual/usermanual.xml
index 0ef0ed456c..65efe23818 100644
--- a/usermanual/usermanual.xml
+++ b/usermanual/usermanual.xml
@@ -1,322 +1,430 @@
-<?xml version='1.0'   encoding='utf-8'?>
+<?xml version="1.0" encoding="UTF-8"?>
 <!--
   ex:ts=4:sw=4:sts=4:et
   -*- tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*-
 -->
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-                      "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY class-autotools           SYSTEM "reference/class_autotools.xml">
-<!ENTITY class-binconfig           SYSTEM "reference/class_binconfig.xml">
-<!ENTITY dirs-install              SYSTEM "reference/dirs_install.xml">
-<!ENTITY dirs-staging              SYSTEM "reference/dirs_staging.xml">
-<!ENTITY class-distutils           SYSTEM "reference/class_distutils.xml">
-<!ENTITY fakeroot                  SYSTEM "reference/fakeroot.xml">
-<!ENTITY class-image_ipkg          SYSTEM "reference/class_image_ipkg.xml">
-<!ENTITY image-types               SYSTEM "reference/image_types.xml">
-<!ENTITY class-pkgconfig           SYSTEM "reference/class_pkgconfig.xml">
-<!ENTITY class-rootfs_ipkg         SYSTEM "reference/class_rootfs_ipkg.xml">
-<!ENTITY var-section               SYSTEM "reference/var_section.xml">
-<!ENTITY var-src-uri               SYSTEM "reference/var_src_uri.xml">
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+<!ENTITY chapter-recipes SYSTEM "chapters/recipes.xml">
+<!ENTITY class-autotools SYSTEM "reference/class_autotools.xml">
+<!ENTITY class-binconfig SYSTEM "reference/class_binconfig.xml">
+<!ENTITY dirs-install SYSTEM "reference/dirs_install.xml">
+<!ENTITY dirs-staging SYSTEM "reference/dirs_staging.xml">
+<!ENTITY class-distutils SYSTEM "reference/class_distutils.xml">
+<!ENTITY fakeroot SYSTEM "reference/fakeroot.xml">
+<!ENTITY class-image_ipkg SYSTEM "reference/class_image_ipkg.xml">
+<!ENTITY image-types SYSTEM "reference/image_types.xml">
+<!ENTITY class-pkgconfig SYSTEM "reference/class_pkgconfig.xml">
+<!ENTITY class-rootfs_ipkg SYSTEM "reference/class_rootfs_ipkg.xml">
+<!ENTITY var-section SYSTEM "reference/var_section.xml">
+<!ENTITY var-src-uri SYSTEM "reference/var_src_uri.xml">
 <!ENTITY class-update-alternatives SYSTEM "reference/class_update-alternatives.xml">
-<!ENTITY class-update-rcd          SYSTEM "reference/class_update-rc.d.xml">
-<!ENTITY chapter-usage             SYSTEM "chapters/usage.xml">
-<!ENTITY chapter-recipes           SYSTEM "chapters/recipes.xml">
+<!ENTITY class-update-rcd SYSTEM "reference/class_update-rc.d.xml">
 ]>
 <book>
-    <bookinfo>
-        <title>OpenEmbedded User Manual</title>
-        <authorgroup>
-            <corpauthor>OpenEmbedded Team</corpauthor>
-        </authorgroup>
-        <copyright>
-            <year>2006</year>
-            <holder>Holger Hans Peter Freyther</holder>
-            <holder>Koen Kooi</holder>
-            <holder>Detlef Vollmann</holder>
-            <holder>Jamie Lenehan</holder>
-            <holder>Marcin Juszkiewicz</holder>
-        </copyright>
-
-        <legalnotice>
-            <para>This work is licensed under the Creative Commons Attribution License. To view a copy of this license, visit <ulink url="http://creativecommons.org/licenses/by/2.0/">http://creativecommons.org/licenses/by/2.0/</ulink> or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.</para>
-        </legalnotice>
-    </bookinfo>
-
-
-    <chapter>
-        <title>Introduction</title>
-        <section>
-            <title>Overview</title>
-                <para> Like any build tool (make, ant, jam), the OpenEmbedded build tool BitBake controls how to build things and the build dependencies. But unlike single project tools like <command>make</command> it is not based on one makefile or a closed set of inter-dependent makefiles, but collects and manages an open set of largely independent build descriptions (package recipes) and builds them in proper order. </para>
-            <para>To be more precise: <ulink url="http://www.openembedded.org"><application>OpenEmbedded</application></ulink> is a set of metadata used to cross-compile, package and install software packages. <application>OpenEmbedded</application> is being used to build and maintain a number of embedded Linux distributions, including OpenZaurus, Angström, Familiar and SlugOS.</para>
-        <para>The primary use-case of <application>OpenEmbedded</application> are:
-            <itemizedlist>
-                <listitem><para>Handle cross-compilation.</para></listitem>
-                <listitem><para>Handle inter-package dependencies</para></listitem>
-                <listitem><para>Must be able to emit packages (tar, rpm, ipk)</para></listitem>
-                <listitem><para>Must be able to create images and feeds from packages</para></listitem>
-                <listitem><para>Must be highly configurable to support many machines, distribution and architectures.</para></listitem>
-                <listitem><para>Writing of metadata must be easy and reusable</para></listitem>
-            </itemizedlist>
-        </para>
-        <para>Together with <ulink url="http://bitbake.berlios.de/manual"><application>BitBake</application></ulink>, OpenEmbedded satisfies all these and many more. Flexibility and power have always been the priorities.</para>
-        </section>
-
-
-       <section>
-            <title>History</title>
-            <para>OpenEmbedded was invented and founded by the creators of the OpenZaurus project.  At this time the project had pushed <emphasis>buildroot</emphasis> to its limits. It supported the creation of <emphasis>ipk</emphasis> packages, feeds and images and had support for more than one machine. But it was impossible to use different patches, files for different architectures, machines or distributions. To overcome this shortcoming OpenEmbedded was created.</para>
-            <para>After a few months other projects started using OpenEmbedded and contributing back. On 7 December 2004 Chris Larson split the project into two parts: BitBake, a generic task executor and OpenEmbedded, the metadata for BitBake.</para>   
-       </section>
-    </chapter>
-
-
-    <chapter>
-        <title>Metadata</title>
-        <section>
-            <title>File Layout</title>
-            <para>OpenEmbedded has six directories three of them hold <application>BitBake</application> metadata.</para>
-
-            <para>The <emphasis>conf</emphasis> directory is holding the bitbake.conf, machine and distribution configuration. bitbake.conf is read when <application>BitBake</application> is started and this will include among others a local.conf the machine and distribution configuration files. These files will be searched in the <command>BBPATH</command> environment variable.</para>
-
-            <para><emphasis>classes</emphasis> is the directory holding <application>BitBake</application> bbclass. These classes can be inherited by the <application>BitBake</application> files. BitBake automatically inherits the base.bbclass on every parsed file. <command>BBPATH</command> is used to  find the class.</para>
-
-            <para>In <emphasis>packages</emphasis> the <application>BitBake</application> files are stored. For each task or application we have a directory. These directories store the real <application>BitBake</application> files. They are the ones ending with <emphasis>.bb</emphasis>. And for each application and version we have one.</para>
-
-        </section>
-        <section>
-            <title>Syntax</title>
-            <para>OpenEmbedded has files ending with <emphasis>.conf</emphasis>, <emphasis>.inc</emphasis>,
-<emphasis>.bb</emphasis> and<emphasis>.bbclass</emphasis>. The syntax and semantic of these files are best
-described in the <ulink url="http://bitbake.berlios.de/manual"><application>BitBake</application> manual</ulink>. </para>
-        </section>
-        <section>
-            <title>Classes</title>
-            <para>OpenEmbedded provides special <application>BitBake</application> classes to ease compiling, packaging and other things. FIXME.</para>
-        </section>
-        <section>
-            <title>Writing Meta Data (Adding packages)</title>
-           <para>This page will guide you trough the effort of writing a .bb file or <emphasis>recipe</emphasis> in BitBake speak.</para>
-
-            <para>Let's start with the easy stuff, like the package description, license, etc:
-
-                <screen>
+  <bookinfo>
+    <title>OpenEmbedded User Manual</title>
+
+    <authorgroup>
+      <corpauthor>OpenEmbedded Team</corpauthor>
+    </authorgroup>
+
+    <copyright>
+      <year>2006</year>
+
+      <holder>Holger Hans Peter Freyther</holder>
+
+      <holder>Koen Kooi</holder>
+
+      <holder>Detlef Vollmann</holder>
+
+      <holder>Jamie Lenehan</holder>
+
+      <holder>Marcin Juszkiewicz</holder>
+    </copyright>
+
+    <legalnotice>
+      <para>This work is licensed under the Creative Commons Attribution
+      License. To view a copy of this license, visit <ulink
+      url="http://creativecommons.org/licenses/by/2.0/">http://creativecommons.org/licenses/by/2.0/</ulink>
+      or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford,
+      California 94305, USA.</para>
+    </legalnotice>
+  </bookinfo>
+
+  <chapter id="chapter_introduction">
+    <title>Introduction</title>
+
+    <section id="intro_overview">
+      <title>Overview</title>
+
+      <para>Like any build tool (make, ant, jam), the OpenEmbedded build tool
+      BitBake controls how to build things and the build dependencies. But
+      unlike single project tools like <command>make</command> it is not based
+      on one makefile or a closed set of inter-dependent makefiles, but
+      collects and manages an open set of largely independent build
+      descriptions (package recipes) and builds them in proper order.</para>
+
+      <para>To be more precise: <ulink
+      url="http://www.openembedded.org"><application>OpenEmbedded</application></ulink>
+      is a set of metadata used to cross-compile, package and install software
+      packages. <application>OpenEmbedded</application> is being used to build
+      and maintain a number of embedded Linux distributions, including
+      OpenZaurus, Angström, Familiar and SlugOS.</para>
+
+      <para>The primary use-case of <application>OpenEmbedded</application>
+      are: <itemizedlist>
+          <listitem>
+            <para>Handle cross-compilation.</para>
+          </listitem>
+
+          <listitem>
+            <para>Handle inter-package dependencies</para>
+          </listitem>
+
+          <listitem>
+            <para>Must be able to emit packages (tar, rpm, ipk)</para>
+          </listitem>
+
+          <listitem>
+            <para>Must be able to create images and feeds from packages</para>
+          </listitem>
+
+          <listitem>
+            <para>Must be highly configurable to support many machines,
+            distribution and architectures.</para>
+          </listitem>
+
+          <listitem>
+            <para>Writing of metadata must be easy and reusable</para>
+          </listitem>
+        </itemizedlist></para>
+
+      <para>Together with <ulink
+      url="http://bitbake.berlios.de/manual"><application>BitBake</application></ulink>,
+      OpenEmbedded satisfies all these and many more. Flexibility and power
+      have always been the priorities.</para>
+    </section>
+
+    <section id="intro_history">
+      <title>History</title>
+
+      <para>OpenEmbedded was invented and founded by the creators of the
+      OpenZaurus project. At this time the project had pushed
+      <emphasis>buildroot</emphasis> to its limits. It supported the creation
+      of <emphasis>ipk</emphasis> packages, feeds and images and had support
+      for more than one machine. But it was impossible to use different
+      patches, files for different architectures, machines or distributions.
+      To overcome this shortcoming OpenEmbedded was created.</para>
+
+      <para>After a few months other projects started using OpenEmbedded and
+      contributing back. On 7 December 2004 Chris Larson split the project
+      into two parts: BitBake, a generic task executor and OpenEmbedded, the
+      metadata for BitBake.</para>
+    </section>
+  </chapter>
+
+  <chapter id="chapter_metadata">
+    <title>Metadata</title>
+
+    <section id="metadata_file_layout">
+      <title>File Layout</title>
+
+      <para>OpenEmbedded has six directories three of them hold
+      <application>BitBake</application> metadata.</para>
+
+      <para>The <emphasis>conf</emphasis> directory is holding the
+      bitbake.conf, machine and distribution configuration. bitbake.conf is
+      read when <application>BitBake</application> is started and this will
+      include among others a local.conf the machine and distribution
+      configuration files. These files will be searched in the
+      <command>BBPATH</command> environment variable.</para>
+
+      <para><emphasis>classes</emphasis> is the directory holding
+      <application>BitBake</application> bbclass. These classes can be
+      inherited by the <application>BitBake</application> files. BitBake
+      automatically inherits the base.bbclass on every parsed file.
+      <command>BBPATH</command> is used to find the class.</para>
+
+      <para>In <emphasis>packages</emphasis> the
+      <application>BitBake</application> files are stored. For each task or
+      application we have a directory. These directories store the real
+      <application>BitBake</application> files. They are the ones ending with
+      <emphasis>.bb</emphasis>. And for each application and version we have
+      one.</para>
+    </section>
+
+    <section id="metadata_syntax">
+      <title>Syntax</title>
+
+      <para>OpenEmbedded has files ending with <emphasis>.conf</emphasis>,
+      <emphasis>.inc</emphasis>, <emphasis>.bb</emphasis>
+      and<emphasis>.bbclass</emphasis>. The syntax and semantic of these files
+      are best described in the <ulink
+      url="http://bitbake.berlios.de/manual"><application>BitBake</application>
+      manual</ulink>.</para>
+    </section>
+
+    <section id="metadata_classes">
+      <title>Classes</title>
+
+      <para>OpenEmbedded provides special <application>BitBake</application>
+      classes to ease compiling, packaging and other things. FIXME.</para>
+    </section>
+
+    <section id="metadata_writing_data">
+      <title>Writing Meta Data (Adding packages)</title>
+
+      <para>This page will guide you trough the effort of writing a .bb file
+      or <emphasis>recipe</emphasis> in BitBake speak.</para>
+
+      <para>Let's start with the easy stuff, like the package description,
+      license, etc: <screen>
 DESCRIPTION = "My first application, a really cool app containing lots of foo and bar"
 LICENSE = "GPLv2"
 HOMEPAGE = "http://www.host.com/foo/"
-                </screen>
-
-The description and license fields are mandatory, so better check them twice.
-            </para>
-
-            <para>The next step is to specify what the package needs to build and run, the so called <emphasis>dependencies</emphasis>:
+                </screen> The description and license fields are mandatory, so
+      better check them twice.</para>
 
-                <screen>
+      <para>The next step is to specify what the package needs to build and
+      run, the so called <emphasis>dependencies</emphasis>: <screen>
 DEPENDS = "gtk+"
 RDEPENDS = "cool-ttf-fonts"
-                </screen>
-
-The package needs gtk+ to build ('DEPENDS') and requires the 'cool-ttf-fonts' package to run ('RDEPENDS'). OE will add run-time dependencies on libraries on its own via the so called <emphasis>shlibs</emphasis>-code, but you need to specify everything other by yourself, which in this case is the 'cool-ttf-fonts' package.
-            </para>
-
-            <para>After entering all this OE will know what to build before trying to build your application, but it doesn't know where to get it yet. So let's add the source location:
-
-                <screen>
+                </screen> The package needs gtk+ to build ('DEPENDS') and
+      requires the 'cool-ttf-fonts' package to run ('RDEPENDS'). OE will add
+      run-time dependencies on libraries on its own via the so called
+      <emphasis>shlibs</emphasis>-code, but you need to specify everything
+      other by yourself, which in this case is the 'cool-ttf-fonts'
+      package.</para>
+
+      <para>After entering all this OE will know what to build before trying
+      to build your application, but it doesn't know where to get it yet. So
+      let's add the source location: <screen>
 SRC_URI = "http://www.host.com/foo/files/${P}.tar.bz2;md5sum=yoursum"
-                </screen>
-
-This will tell the fetcher to where to download the sources from and it will check the integrity using md5sum if you provided the appropriate <emphasis>yoursum</emphasis>. You can make one by doing <screen>md5sum foo-1.9.tar.bz2</screen> and replacing <emphasis>yoursum</emphasis> with the md5sum on your screen. A typical md5sum will look like this: <screen>a6434b0fc8a54c3dec3d6875bf3be8mtn </screen>Notice the <emphasis>${P}</emphasis> variable, that one holds the package name, <emphasis>${PN}</emphasis> in BitBake speak and the package version, <emphasis>${PV}</emphasis> in BitBake speak. It's a short way of writing <emphasis>${PN}-${PV}</emphasis>. Using this notation means you can copy the recipe when a new version is released without having to alter the contents. You do need to check if everything is still correct, because new versions mean new bugs.
-            </para>
-
-            <para>Before we can move to the actual building we need to find out which build system the package is using. If we're lucky, we see a <emphasis>configure</emphasis> file in the build tree this is an indicator that we can <emphasis>inherit autotools</emphasis> if we see a <emphasis>.pro</emphasis> file, it might be qmake, which needs <emphasis>inherit qmake</emphasis>. Virtually all gtk apps use autotools:
-
-                <screen>
+                </screen> This will tell the fetcher to where to download the
+      sources from and it will check the integrity using md5sum if you
+      provided the appropriate <emphasis>yoursum</emphasis>. You can make one
+      by doing <screen>md5sum foo-1.9.tar.bz2</screen> and replacing
+      <emphasis>yoursum</emphasis> with the md5sum on your screen. A typical
+      md5sum will look like this: <screen>a6434b0fc8a54c3dec3d6875bf3be8mtn </screen>Notice
+      the <emphasis>${P}</emphasis> variable, that one holds the package name,
+      <emphasis>${PN}</emphasis> in BitBake speak and the package version,
+      <emphasis>${PV}</emphasis> in BitBake speak. It's a short way of writing
+      <emphasis>${PN}-${PV}</emphasis>. Using this notation means you can copy
+      the recipe when a new version is released without having to alter the
+      contents. You do need to check if everything is still correct, because
+      new versions mean new bugs.</para>
+
+      <para>Before we can move to the actual building we need to find out
+      which build system the package is using. If we're lucky, we see a
+      <emphasis>configure</emphasis> file in the build tree this is an
+      indicator that we can <emphasis>inherit autotools</emphasis> if we see a
+      <emphasis>.pro</emphasis> file, it might be qmake, which needs
+      <emphasis>inherit qmake</emphasis>. Virtually all gtk apps use
+      autotools: <screen>
 inherit autotools pkgconfig
-                </screen>
-
-We are in luck! The package is a well-behaved application using autotools and pkgconfig to configure and build it self.
-            </para>
-
-            <para>Lets start the build:
+                </screen> We are in luck! The package is a well-behaved
+      application using autotools and pkgconfig to configure and build it
+      self.</para>
 
-                <screen>
+      <para>Lets start the build: <screen>
 <command>bitbake</command> foo
-                </screen>
-
-Depending on what you have built before and the speed of your computer this can take a few seconds to a few hours, so be prepared.
-            </para>
-
-            <para>
-.... some time goes by .....
-            </para>
+                </screen> Depending on what you have built before and the
+      speed of your computer this can take a few seconds to a few hours, so be
+      prepared.</para>
 
-            <para>Your screen should now have something like this on it:
+      <para>.... some time goes by .....</para>
 
-                <screen>
+      <para>Your screen should now have something like this on it: <screen>
 NOTE: package foo-1.9-r0: task do_build: completed
 NOTE: package foo-1.9: completed
 NOTE: build 200605052219: completed
-                </screen>
-            </para>
-
-            <para>All looks well, but wait, let's scroll up:
+                </screen></para>
 
-
-                <screen>
+      <para>All looks well, but wait, let's scroll up: <screen>
 NOTE: the following files where installed but not shipped:
     /usr/weirdpath/importantfile.foo
-                </screen>
-
-OE has a standard list of paths which need to be included, but it can't know everything, so we have to tell OE to include that file as well:
-
-                <screen>
+                </screen> OE has a standard list of paths which need to be
+      included, but it can't know everything, so we have to tell OE to include
+      that file as well: <screen>
 FILES_${PN} += "/usr/weirdpath/importantfile.foo"
-                </screen>
+                </screen> It's important to use <emphasis>+=</emphasis> so it
+      will get appended to the standard file-list, not replace the standard
+      one.</para>
+    </section>
+  </chapter>
 
-It's important to use <emphasis>+=</emphasis> so it will get appended to the standard file-list, not replace the standard one.
-            </para>
-        </section>
-    </chapter>
+  <chapter id="chapter_getting_oe">
+    <title>Getting OpenEmbedded</title>
 
+    <section id="gettingoe_getting_bitbake">
+      <title>Getting <application>BitBake</application></title>
 
-    <chapter>
-        <title>Getting OpenEmbedded</title>
-        <section>
-            <title>Getting <application>BitBake</application></title>
-            <para>The required version of <application>BitBake</application> is changing rapidly. At the time of writing (15th of October 2006) <application>BitBake</application> 1.6.0 was required.</para>
-            <para>A safe method is to get <application>BitBake</application> from a stable (even mior number) Subversion branch.
-            <screen>
+      <para>The required version of <application>BitBake</application> is
+      changing rapidly. At the time of writing (15th of October 2006)
+      <application>BitBake</application> 1.6.0 was required.</para>
+
+      <para>A safe method is to get <application>BitBake</application> from a
+      stable (even mior number) Subversion branch. <screen>
 <command>svn</command> co http://svn.berlios.de/svnroot/repos/bitbake/branches/bitbake-1.6
 ...
 A   bitbake-1.6/classes/base.bbclass
 U   bitbake-1.6
 At revision 570.
-            </screen>
-            <application>BitBake</application> is checked out now; this completes the first and most critical dependency of OpenEmbedded. Issuing <command>svn</command> <command>up</command> in the <emphasis>bitbake-1.6</emphasis> directory will update <application>BitBake</application> to the latest stable version, but generally it is a good idea to stick with a specific known working version of <application>BitBake</application> until OpenEmbedded asks you to upgrade.
-            </para>
-        </section>
-
-        <section>
-            <title>Getting OpenEmbedded</title>
-            <para>
-The OpenEmbedded metadata has a high rate of development, so it's a good idea to stay up to date.
-You'll need monotone 0.28 to get the metadata and stay up to date. Monotone is available in most distributions and has binaries at <ulink url="http://venge.net/monotone/">Monotone homepage</ulink>.</para>
-<para> Next step is getting snapshot of database.
-
-<screen>
+            </screen> <application>BitBake</application> is checked out now;
+      this completes the first and most critical dependency of OpenEmbedded.
+      Issuing <command>svn</command> <command>up</command> in the
+      <emphasis>bitbake-1.6</emphasis> directory will update
+      <application>BitBake</application> to the latest stable version, but
+      generally it is a good idea to stick with a specific known working
+      version of <application>BitBake</application> until OpenEmbedded asks
+      you to upgrade.</para>
+    </section>
+
+    <section id="gettingoe_getting_oe">
+      <title>Getting OpenEmbedded</title>
+
+      <para>The OpenEmbedded metadata has a high rate of development, so it's
+      a good idea to stay up to date. You'll need monotone 0.28 to get the
+      metadata and stay up to date. Monotone is available in most
+      distributions and has binaries at <ulink
+      url="http://venge.net/monotone/">Monotone homepage</ulink>.</para>
+
+      <para>Next step is getting snapshot of database. <screen>
 wget http://openembedded.org/snapshots/OE.mtn.bz2 http://openembedded.org/snapshots/OE.mtn.bz2.md5
-</screen>
-
-Or if you have monotone 0.30 or later:
-
-<screen>
+</screen> Or if you have monotone 0.30 or later: <screen>
 wget http://www.openembedded.org/snapshots/OE-this-is-for-mtn-0.30.mtn.bz2 
 wget http://www.openembedded.org/snapshots/OE-this-is-for-mtn-0.30.mtn.bz2.md5
-</screen>
-
-Then verify integrity of snapshot by checking md5sum.
-
-<screen>
+</screen> Then verify integrity of snapshot by checking md5sum. <screen>
 cat OE.mtn.bz2.md5sum
 md5sum OE.mtn.bz2
-</screen>
+</screen> Then unpack database. <screen>
+bunzip OE.mtn.bz2
+</screen> Finally checkout the development branch. <screen>
+mtn --db=OE.mtn co -b org.openembedded.dev
+</screen></para>
+    </section>
 
-Then unpack database.
+    <section id="gettingoe_configuring_oe">
+      <title>Configuring OpenEmbedded</title>
 
-<screen>
-bunzip OE.mtn.bz2
-</screen>
+      <para>This section is a stub, help us by expanding it</para>
+    </section>
 
-Finally checkout the development branch.
+    <section id="gettingoe_building_software">
+      <title>Building Software</title>
 
-<screen>
-mtn --db=OE.mtn co -b org.openembedded.dev
-</screen>
+      <para>This section is a stub, help us by expanding it</para>
+    </section>
+  </chapter>
 
-           </para>
-        </section>
+  <chapter id="chapter_special_features">
+    <title>Special features</title>
 
-        <section>
-            <title>Configuring OpenEmbedded</title>
-            <para>This section is a stub, help us by expanding it</para>
-        </section>
+    <section id="special_debian_naming">
+      <title>Debian package naming <anchor id="debian" /></title>
 
-        <section>
-            <title>Building Software</title>
-            <para>This section is a stub, help us by expanding it</para>
-        </section>
-    </chapter>
+      <screen>INHERIT += "debian"</screen>
 
-    <chapter>
-        <title>Special features</title>
-        <section>
-            <title>Debian package naming <anchor id="debian" /></title>
-            <screen>INHERIT += "debian"</screen>
-            <para>Placing the above line into your <emphasis>${DISTRO}.conf</emphasis> or <emphasis>local.conf</emphasis> will trigger renaming of packages if they only ship one library. Imagine a package where the package name (<command>PN</command>) is foo and this packages ships a file named <command>libfoo.so.1.2.3</command>. Now this package will be renamed to <command>libfoo1</command> to follow the Debian package naming policy.</para>
-        </section>
+      <para>Placing the above line into your
+      <emphasis>${DISTRO}.conf</emphasis> or <emphasis>local.conf</emphasis>
+      will trigger renaming of packages if they only ship one library. Imagine
+      a package where the package name (<command>PN</command>) is foo and this
+      packages ships a file named <command>libfoo.so.1.2.3</command>. Now this
+      package will be renamed to <command>libfoo1</command> to follow the
+      Debian package naming policy.</para>
+    </section>
 
-        <section>
-            <title>Shared Library handling (shlibs) <anchor id="shlibs" /></title>
-            <para>Run-time Dependencies (<command>RDEPENDS</command>) will be added when packaging the software. They should only contain the minimal dependencies to run the program. OpenEmbedded will analyze each packaged binary and search for <command>SO_NEEDED</command> libraries. The libraries are absolutely required by the program then OpenEmbedded is searching for packages that installs these libraries. these packages are automatically added to the <command>RDEPENDS</command>. As a packager you don't need to worry about shared libraries anymore they will be added automatically.</para>
-            <remark>NOTE: This does not apply to plug-ins used by the program.</remark>
-        </section>
+    <section id="special_shlibs">
+      <title>Shared Library handling (shlibs) <anchor id="shlibs" /></title>
 
-        <section>
-            <title>BitBake Collections <anchor id="collections" /></title>
-            <para>This section is a stub, help us by expanding it</para>
-            <para>
-<screen>
+      <para>Run-time Dependencies (<command>RDEPENDS</command>) will be added
+      when packaging the software. They should only contain the minimal
+      dependencies to run the program. OpenEmbedded will analyze each packaged
+      binary and search for <command>SO_NEEDED</command> libraries. The
+      libraries are absolutely required by the program then OpenEmbedded is
+      searching for packages that installs these libraries. these packages are
+      automatically added to the <command>RDEPENDS</command>. As a packager
+      you don't need to worry about shared libraries anymore they will be
+      added automatically.</para>
+
+      <remark>NOTE: This does not apply to plug-ins used by the
+      program.</remark>
+    </section>
+
+    <section id="special_bitbake_collections">
+      <title>BitBake Collections <anchor id="collections" /></title>
+
+      <para>This section is a stub, help us by expanding it</para>
+
+      <para><screen>
 BBFILES := "${OEDIR}/openembedded/packages/*/*.bb ${LOCALDIR}/packages/*/*.bb"
 BBFILE_COLLECTIONS = "upstream local"
 BBFILE_PATTERN_upstream = "^${OEDIR}/openembedded/packages/"
 BBFILE_PATTERN_local = "^${LOCALDIR}/packages/"
 BBFILE_PRIORITY_upstream = "5"
 BBFILE_PRIORITY_local = "10"
-</screen>
-</para>
-        </section>
-
-        <section>
-            <title>Task-base <anchor id="task-base" /></title>
+</screen></para>
+    </section>
 
-<para>Task-base is new way of creating basic root filesystems. Instead of having each machine setting a ton of duplicate variables, this allow a machine to specify its features and <command>task-base</command> builds it a customised package based on what the machine needs along with what the distro supports.</para>
+    <section id="special_task_base">
+      <title>Task-base <anchor id="task-base" /></title>
 
-<para> To illustrate, the distro config file can say:
+      <para>Task-base is new way of creating basic root filesystems. Instead
+      of having each machine setting a ton of duplicate variables, this allow
+      a machine to specify its features and <command>task-base</command>
+      builds it a customised package based on what the machine needs along
+      with what the distro supports.</para>
 
-<screen>
+      <para>To illustrate, the distro config file can say: <screen>
 DISTRO_FEATURES = "nfs smbfs ipsec wifi ppp alsa bluetooth ext2 irda pcmcia usbgadget usbhost"
-</screen>
-
-and the machine config:
-
-<screen>
+</screen> and the machine config: <screen>
 MACHINE_FEATURES = "kernel26 apm alsa pcmcia bluetooth irda usbgadget"
-</screen>
-
-and the resulting <command>task-base</command> would support pcmcia but not usbhost.</para>
-
-<para>Task-base details exactly which options are either machine or distro settings (or need to be in both). Machine options are meant to reflect capabilities of the machine, distro options list things distribution maintainers might want to add or remove from their distros images.</para>
-        </section>
-        <section>
-            <title>Overrides <anchor id="overrides" /></title>
-            <para>This section is a stub, help us by expanding it</para>
-        </section>
-    </chapter>
-
-    <chapter>
-        <title>Common Use-cases/tasks</title>
-
-        <section>
-            <title>Creating a new Distribution</title>
-<para>
-Creating a new distribution is not complicated. Config need to be created
-in /conf/distro directory. What has to be inside?
-<itemizedlist>
-    <listitem><para><command>DISTRO_VERSION</command> so users will know which version of distribution they use.</para></listitem>
-    <listitem><para><command>DISTRO_TYPE</command> (release/debug) variable is used in some recipes to enable/disable some features - for example kernel output on screen for "debug" builds.</para></listitem>
-    <listitem><para>Type of libc used: will it be glibc (<command>TARGET_OS</command> = "linux") or uclibc (<command>TARGET_OS</command> = "linux-uclibc")?</para></listitem>
-    <listitem><para>Toolchain versions - for example gcc 3.4.4 based distro will have:
-            <screen>
+</screen> and the resulting <command>task-base</command> would support pcmcia
+      but not usbhost.</para>
+
+      <para>Task-base details exactly which options are either machine or
+      distro settings (or need to be in both). Machine options are meant to
+      reflect capabilities of the machine, distro options list things
+      distribution maintainers might want to add or remove from their distros
+      images.</para>
+    </section>
+
+    <section id="special_overrides">
+      <title>Overrides <anchor id="overrides" /></title>
+
+      <para>This section is a stub, help us by expanding it</para>
+    </section>
+  </chapter>
+
+  <chapter id="chapter_common_use_cases">
+    <title>Common Use-cases/tasks</title>
+
+    <section id="commonuse_new_distro">
+      <title>Creating a new Distribution</title>
+
+      <para>Creating a new distribution is not complicated. Config need to be
+      created in /conf/distro directory. What has to be inside? <itemizedlist>
+          <listitem>
+            <para><command>DISTRO_VERSION</command> so users will know which
+            version of distribution they use.</para>
+          </listitem>
+
+          <listitem>
+            <para><command>DISTRO_TYPE</command> (release/debug) variable is
+            used in some recipes to enable/disable some features - for example
+            kernel output on screen for "debug" builds.</para>
+          </listitem>
+
+          <listitem>
+            <para>Type of libc used: will it be glibc
+            (<command>TARGET_OS</command> = "linux") or uclibc
+            (<command>TARGET_OS</command> = "linux-uclibc")?</para>
+          </listitem>
+
+          <listitem>
+            <para>Toolchain versions - for example gcc 3.4.4 based distro will
+            have: <screen>
 PREFERRED_PROVIDERS += " virtual/${TARGET_PREFIX}gcc-initial:gcc-cross-initial"
 PREFERRED_PROVIDERS += " virtual/${TARGET_PREFIX}gcc:gcc-cross"
 PREFERRED_PROVIDERS += " virtual/${TARGET_PREFIX}g++:gcc-cross"
@@ -327,79 +435,115 @@ PREFERRED_VERSION_binutils-cross = "2.16"
 PREFERRED_VERSION_gcc = "3.4.4"
 PREFERRED_VERSION_gcc-cross = "3.4.4"
 PREFERRED_VERSION_gcc-initial-cross = "3.4.4"
-            </screen>
-    </para></listitem>
-    <listitem><para> <command>DISTRO_FEATURES</command> which describe which features distro has. More about it in <link linkend="task-base">task-base</link> section.</para></listitem>
-    <listitem><para>Versions of kernels used for supported devices:
-            <screen>
+            </screen></para>
+          </listitem>
+
+          <listitem>
+            <para><command>DISTRO_FEATURES</command> which describe which
+            features distro has. More about it in <link
+            linkend="task-base">task-base</link> section.</para>
+          </listitem>
+
+          <listitem>
+            <para>Versions of kernels used for supported devices: <screen>
 PREFERRED_VERSION_linux-omap1_omap5912osk ?= "2.6.18+git"
 PREFERRED_VERSION_linux-openzaurus ?= "2.6.17"
-            </screen>
-    </para></listitem>
-    <listitem><para>To get more stable build it is good to make use of sane-srcdates.inc file which contain working SRCDATE for many of floating recipes.
-            <screen>
+            </screen></para>
+          </listitem>
+
+          <listitem>
+            <para>To get more stable build it is good to make use of
+            sane-srcdates.inc file which contain working SRCDATE for many of
+            floating recipes. <screen>
 require conf/distro/include/sane-srcdates.inc
-            </screen>
-            It also should have global <command>SRCDATE</command> value set (format is ISO date: YYYYMMDD):
-            <screen>
+            </screen> It also should have global <command>SRCDATE</command>
+            value set (format is ISO date: YYYYMMDD): <screen>
 SRCDATE = "20061014"
-            </screen>
-    </para></listitem>
-</itemizedlist>
-</para>
-        </section>
+            </screen></para>
+          </listitem>
+        </itemizedlist></para>
+    </section>
 
-        <section>
-            <title>Adding a new Machine</title>
-<para>To be able to build for device OpenEmbedded have to know it, so machine config file need to be written. All those configs are stored in /conf/machine/ directory.</para>
+    <section id="commonuse_new_machine">
+      <title>Adding a new Machine</title>
 
-<para>As usual some variables are required:
-      <itemizedlist>
-          <listitem><para><command>TARGET_ARCH</command> which describe which CPU architecture does machine use.</para></listitem>
-          <listitem><para><command>MACHINE_FEATURES</command> which describe which features device has. More about it in <link linkend="task-base">task-base</link> section.</para></listitem>
-          <listitem><para><command>PREFERRED_PROVIDER_virtual/kernel</command> has to point into proper kernel recipe for this machine.</para></listitem>
-      </itemizedlist>
-</para>
-
-<para>
-Next kernel recipe needs to be added.
-</para>
-        </section>
+      <para>To be able to build for device OpenEmbedded have to know it, so
+      machine config file need to be written. All those configs are stored in
+      /conf/machine/ directory.</para>
 
-        <section>
-            <title>Adding a new Package</title>
-            <para>This section is a stub, help us by expanding it</para>
-        </section>
+      <para>As usual some variables are required: <itemizedlist>
+          <listitem>
+            <para><command>TARGET_ARCH</command> which describe which CPU
+            architecture does machine use.</para>
+          </listitem>
 
-        <section>
-            <title>Creating your own image</title>
-<para>
-    Creating own image is easy - only few variables needs to be set:
-    <itemizedlist>
-        <listitem><para><command>IMAGE_BASENAME</command> to give name for own image</para></listitem>
-        <listitem><para><command>IPKG_INSTALL</command> to give list of packages to install into image</para></listitem>
-        <listitem><para><command>RDEPENDS</command> to give list of packages which are needed to be build to create image</para></listitem>
-        <listitem><para><command>IMAGE_LINGUAS</command> is optional list of languages which has to be installed into image</para></listitem>
-    </itemizedlist>
-
-    Then adding of <emphasis>image_ipk</emphasis> class use:
-    <screen>
+          <listitem>
+            <para><command>MACHINE_FEATURES</command> which describe which
+            features device has. More about it in <link
+            linkend="task-base">task-base</link> section.</para>
+          </listitem>
+
+          <listitem>
+            <para><command>PREFERRED_PROVIDER_virtual/kernel</command> has to
+            point into proper kernel recipe for this machine.</para>
+          </listitem>
+        </itemizedlist></para>
+
+      <para>Next kernel recipe needs to be added.</para>
+    </section>
+
+    <section id="commonuse_new_package">
+      <title>Adding a new Package</title>
+
+      <para>This section is a stub, help us by expanding it</para>
+    </section>
+
+    <section id="commonuse_new_image">
+      <title>Creating your own image</title>
+
+      <para>Creating own image is easy - only few variables needs to be set:
+      <itemizedlist>
+          <listitem>
+            <para><command>IMAGE_BASENAME</command> to give name for own
+            image</para>
+          </listitem>
+
+          <listitem>
+            <para><command>IPKG_INSTALL</command> to give list of packages to
+            install into image</para>
+          </listitem>
+
+          <listitem>
+            <para><command>RDEPENDS</command> to give list of packages which
+            are needed to be build to create image</para>
+          </listitem>
+
+          <listitem>
+            <para><command>IMAGE_LINGUAS</command> is optional list of
+            languages which has to be installed into image</para>
+          </listitem>
+        </itemizedlist> Then adding of <emphasis>image_ipk</emphasis> class
+      use: <screen>
 inherit image_ipk
-</screen>
+</screen> And image recipe is ready for usage.</para>
+    </section>
 
-And image recipe is ready for usage.
-</para>
-        </section>
+    <section id="commonuse_prebuilt_toolchain">
+      <title>Using a prebuilt toolchain to create your packages</title>
 
-        <section>
-            <title>Using a prebuilt toolchain to create your packages</title>
-            <para>It might be necessary to integrate a prebuilt toolchain and other libraries but still be use
-OpenEmbedded to build packages. One of many approaches is shown and discussed here.</para>
-
-            <section>
-                <title>The toolchain</title>
-                <para>We assume the toolchain provides a C and C++ compiler, an assembler and other tools to build packages.  The list below shows a gcc 3.4.4 toolchain for ARM architectures using glibc. We assume that the toolchain is in your <command>PATH</command>.</para>
-<screen>
+      <para>It might be necessary to integrate a prebuilt toolchain and other
+      libraries but still be use OpenEmbedded to build packages. One of many
+      approaches is shown and discussed here.</para>
+
+      <section>
+        <title>The toolchain</title>
+
+        <para>We assume the toolchain provides a C and C++ compiler, an
+        assembler and other tools to build packages. The list below shows a
+        gcc 3.4.4 toolchain for ARM architectures using glibc. We assume that
+        the toolchain is in your <command>PATH</command>.</para>
+
+        <screen>
 <command>ls</command> pre-built/cross/bin
 
 arm-linux-g++
@@ -421,30 +565,47 @@ arm-linux-objcopy
 arm-linux-strip
 arm-linux-objdump
 </screen>
-            </section>
-            <section>
-                <title>The prebuilt libraries</title>
-                <para>We need the header files and the libraries itself. The following directory layout is assume.
-<command>PRE_BUILT</command> has two subdirectories one is called <emphasis>include</emphasis> and holds the header files and the other directory is called <emphasis>lib</emphasis> and holds the shared and static libraries. Additionally a Qt2 directory is present having a <emphasis>include</emphasis> and <emphasis>lib</emphasis> sub-directory.</para>
-                <screen>
+      </section>
+
+      <section>
+        <title>The prebuilt libraries</title>
+
+        <para>We need the header files and the libraries itself. The following
+        directory layout is assume. <command>PRE_BUILT</command> has two
+        subdirectories one is called <emphasis>include</emphasis> and holds
+        the header files and the other directory is called
+        <emphasis>lib</emphasis> and holds the shared and static libraries.
+        Additionally a Qt2 directory is present having a
+        <emphasis>include</emphasis> and <emphasis>lib</emphasis>
+        sub-directory.</para>
+
+        <screen>
 <command>ls</command> $PRE_BUILT
 include
 lib
 qt2
 </screen>
-            </section>
-
-            <section>
-                <title>Setting up OpenEmbedded</title>
-                <para>OpenEmbedded will be setup here. We assume that your machine and distribution is not part
-of OpenEmbedded and they will be created ad-hoc in the <emphasis>local.conf</emphasis> file. You will need to have
-<application>BitBake</application> and a current OpenEmbedded version available.
-                </para>
-
-                <section>
-                    <title>Sourcable script</title>
-                    <para>To ease the usage of OpenEmbedded we start by creating a source-able script. This is actually a small variation from the already seen script. We will name it <emphasis>build_source</emphasis> and you will need to source it.</para>
-                    <screen>
+      </section>
+
+      <section>
+        <title>Setting up OpenEmbedded</title>
+
+        <para>OpenEmbedded will be setup here. We assume that your machine and
+        distribution is not part of OpenEmbedded and they will be created
+        ad-hoc in the <emphasis>local.conf</emphasis> file. You will need to
+        have <application>BitBake</application> and a current OpenEmbedded
+        version available.</para>
+
+        <section>
+          <title>Sourcable script</title>
+
+          <para>To ease the usage of OpenEmbedded we start by creating a
+          source-able script. This is actually a small variation from the
+          already seen script. We will name it
+          <emphasis>build_source</emphasis> and you will need to source
+          it.</para>
+
+          <screen>
 BITBAKE_PATH=/where/is/bitbake/bin
 TOOLCHAIN=/where/is/toolchain/bin
 HOST_TOOLS=/where/is/hosttools/bin
@@ -454,14 +615,19 @@ export PATH=$BITBAKE_PATH:$TOOLCHAIN:$HOST_TOOLS:$PATH
 export OEDIR=$PWD
 export LOCALDIR=$PWD/secret-isv
                     </screen>
-                    <para>Use <command>source build_source</command> to source the script, use <command>env</command> to check that the variable where exported.</para>
-                </section>
 
-                <section>
-                    <title>Creating the local.conf</title>
-                    <para>We will configure OpenEmbedded now, it is very similar to what we have done above.</para>
+          <para>Use <command>source build_source</command> to source the
+          script, use <command>env</command> to check that the variable where
+          exported.</para>
+        </section>
+
+        <section>
+          <title>Creating the local.conf</title>
+
+          <para>We will configure OpenEmbedded now, it is very similar to what
+          we have done above.</para>
 
-                    <screen>
+          <screen>
 DL_DIR = "${OEDIR}/sources"
 BBFILES := "${OEDIR}/openembedded/packages/*/*.bb ${LOCALDIR}/packages/*/*.bb"
 BBFILE_COLLECTIONS = "upstream local"
@@ -471,9 +637,14 @@ BBFILE_PRIORITY_upstream = "5"
 BBFILE_PRIORITY_local = "10"
 BBMASK = ""
                     </screen>
-                    <para>${OEDIR}/openembedded will be a upstream release of OpenEmbedded. Above we have assumed it is in the current working directory. Additionally we have a ${LOCALDIR}, we combine these two directories as a special <link linkend="collections">BitBake Collection</link>.</para>
 
-                <screen>
+          <para>${OEDIR}/openembedded will be a upstream release of
+          OpenEmbedded. Above we have assumed it is in the current working
+          directory. Additionally we have a ${LOCALDIR}, we combine these two
+          directories as a special <link linkend="collections">BitBake
+          Collection</link>.</para>
+
+          <screen>
 #
 # machine stuff
 #
@@ -483,9 +654,11 @@ TARGET_CC_ARCH = "-mcpu=xscale -mtune=iwmmxt"
 TARGET_ARCH = "arm"
 PACKAGE_ARCH="xscale"
                 </screen>
-                <para>We tell OpenEmbedded that we build for the ARM platform and optimize for xscale and iwmmxt.</para>
 
-                <screen>
+          <para>We tell OpenEmbedded that we build for the ARM platform and
+          optimize for xscale and iwmmxt.</para>
+
+          <screen>
 INHERIT += " package_ipk debian"
 TARGET_OS  = "linux"
 TARGET_FPU = "soft"
@@ -494,9 +667,13 @@ DISTRO_NAME = "secret-distro"
 DISTRO_VERSION = "x.y.z"
 DISTRO_TYPE = "release"
                 </screen>
-                <para>Create a distribution ad-hoc as well. We tell OpenEmbedded that we build for linux and glibc using soft float as fpu. If your toolchain is a uclibc toolchain you will need to set <command>TARGET_OS</command> to linux-uclibc.</para>
 
-                <screen>
+          <para>Create a distribution ad-hoc as well. We tell OpenEmbedded
+          that we build for linux and glibc using soft float as fpu. If your
+          toolchain is a uclibc toolchain you will need to set
+          <command>TARGET_OS</command> to linux-uclibc.</para>
+
+          <screen>
 export CC  = "${CCACHE}arm-linux-gcc-3.4.4 ${HOST_CC_ARCH}"
 export CXX = "${CCACHE}arm-linux-g++ ${HOST_CC_ARCH}"
 export CPP = "arm-linux-gcc-3.4.4 -E"
@@ -506,9 +683,12 @@ export AS  = "arm-linux-as"
 export RANLIB  = "arm-linux-ranlib"
 export STRIP  = "arm-linux-strip"
                 </screen>
-                <para>The above variables replace the ones from <emphasis>bitbake.conf</emphasis>. This will make OpenEmbedded use the prebuilt toolchain.</para>
 
-                <screen>
+          <para>The above variables replace the ones from
+          <emphasis>bitbake.conf</emphasis>. This will make OpenEmbedded use
+          the prebuilt toolchain.</para>
+
+          <screen>
 #
 # point OE to the lib and include directory
 #
@@ -522,36 +702,48 @@ QPEDIR = "${PRE_BUILT}"
 palmtopdir = "/opt/Qtopia"
 palmqtdir  = "/opt/Qtopia"
                 </screen>
-                <para>We will add the <command>PRE_BUILT</command> libraries to the include and library paths. And the same is done for the special version of Qt we have in your <command>PRE_BUILT</command> directory.</para>
 
-                <screen>
+          <para>We will add the <command>PRE_BUILT</command> libraries to the
+          include and library paths. And the same is done for the special
+          version of Qt we have in your <command>PRE_BUILT</command>
+          directory.</para>
+
+          <screen>
 ASSUME_PROVIDED += " virtual/${TARGET_PREFIX}gcc "
 ASSUME_PROVIDED += " virtual/libc "
 ASSUME_PROVIDED += " virtual/qte "
 ASSUME_PROVIDED += " virtual/libqpe "
 ASSUME_PROVIDED += " libqpe-opie "
                 </screen>
-                <para>Now we have told <application>BitBake</application> that the C library, compiler and Qtopia is already provided.  These lines will avoid building binutils, gcc initial, glibc, gcc.</para>
 
+          <para>Now we have told <application>BitBake</application> that the C
+          library, compiler and Qtopia is already provided. These lines will
+          avoid building binutils, gcc initial, glibc, gcc.</para>
 
-                <screen>
+          <screen>
 <command>source</command> build_source
 <command>bitbake</command> your-killer-app
                 </screen>
-                <para>You should be able to create the packages you want to using the prebuilt toolchain now.</para>
 
-                </section>
-            </section>
+          <para>You should be able to create the packages you want to using
+          the prebuilt toolchain now.</para>
+        </section>
+      </section>
 
-            <section>
-                <title>Useful hints</title>
-                <para>If you have more prebuilt libraries you need to add additional <command>ASSUME_PROVIDED</command>
-lines to your <emphasis>local.conf</emphasis>. Using <command>bitbake -vvv PACKAGE</command> you can easily see the package names you could <command>ASSUME_PROVIDED</command> if you have some prebuilt.</para> 
-            </section>
+      <section>
+        <title>Useful hints</title>
 
-            <section>
-                <title>Issues with this approach</title>
-<screen>
+        <para>If you have more prebuilt libraries you need to add additional
+        <command>ASSUME_PROVIDED</command> lines to your
+        <emphasis>local.conf</emphasis>. Using <command>bitbake -vvv
+        PACKAGE</command> you can easily see the package names you could
+        <command>ASSUME_PROVIDED</command> if you have some prebuilt.</para>
+      </section>
+
+      <section>
+        <title>Issues with this approach</title>
+
+        <screen>
 NOTE: Couldn't find shared library provider for libqtopia.so.1
 NOTE: Couldn't find shared library provider for libqtopia2.so.2
 NOTE: Couldn't find shared library provider for libqpe.so.1
@@ -562,60 +754,119 @@ NOTE: Couldn't find shared library provider for libgcc_s.so.1
 NOTE: Couldn't find shared library provider for libc.so.6
 NOTE: Couldn't find shared library provider for libm.so.6
 </screen>
-                <para>OpenEmbedded tries to automatically add run-time dependencies (RDEPENDS) to the package. It uses the <emphasis><link linkend="shlibs">shlibs</link></emphasis> system to do add them, in this case it was not able to find packages providing these libraries as they are prebuilt. This means they will not be added to the RDEPENDS of the just created package. The result can be fatal. If you use OpenEmbedded to create images you will end up with a image without a libc being installed. This will lead to a fatal failure. To workaround this issue you could create a package for the metadata to install every needed library and use ${BOOTSTRAP_EXTRA_RDEPENDS} to make sure this package is installed when creating images.</para>
-            </section>
 
-        </section>
+        <para>OpenEmbedded tries to automatically add run-time dependencies
+        (RDEPENDS) to the package. It uses the <emphasis><link
+        linkend="shlibs">shlibs</link></emphasis> system to do add them, in
+        this case it was not able to find packages providing these libraries
+        as they are prebuilt. This means they will not be added to the
+        RDEPENDS of the just created package. The result can be fatal. If you
+        use OpenEmbedded to create images you will end up with a image without
+        a libc being installed. This will lead to a fatal failure. To
+        workaround this issue you could create a package for the metadata to
+        install every needed library and use ${BOOTSTRAP_EXTRA_RDEPENDS} to
+        make sure this package is installed when creating images.</para>
+      </section>
+    </section>
 
-        <section>
-            <title>Using a new package format</title>
-            <para>This section is a stub, help us by expanding it</para>
-        </section>
-    </chapter>
+    <section id="commonuse_new_package_format">
+      <title>Using a new package format</title>
 
-    <chapter>
-        <title>Comparing</title>
+      <para>This section is a stub, help us by expanding it</para>
+    </section>
+  </chapter>
 
-        <section>
-            <title>buildroot</title>
-            <para>Writing of <application>BitBake</application> recipes is more easy and more intuitive than writing Makefiles while providing higher flexibility. This allows you to tweak specific recipes for your very special needs and to add new recipes very fast. You can build toolchains, Software Distribution Kits (SDKs), complete Distributions or just single packages. The flexibility of OpenEmbedded allows you to reuse the once written recipes for many different purposes. OpenEmbedded provides everything buildroot will be able to provide. But in contrast to buildroot OpenEmbedded will allow you to achieve what you really want to achieve. You can add new package formats, new filesystems, new output formats easily. OpenEmbedded will suit your need.</para>
-        </section>
+  <chapter id="chapter_comparing">
+    <title>Comparing</title>
 
-        <section>
-            <title>crosstool</title>
-            <para>Crosstool allows to create toolchains for you. It can only create the initial toolchain for you. It will not compile other needed libraries or applications for you, it will not be able to track dependencies or to package them properly. OpenEmbedded supports all configurations crosstool supports. You can start to create toolchains with OpenEmbedded, then as your needs grow create a more complete SDK from already present base libraries and applications and if you recognize you need to have packages for the target you have them almost built already.</para>
-        </section>
+    <section id="comparing_buildroot">
+      <title>buildroot</title>
 
-        <section>
-            <title>handmade</title>
-            <para>Cross-compilation is a tough business. It is not that cross-compiling is hard itself but many people misuse the buildsystem they use to build their software. This will lead to a variety of issues you can run into. This can be failing tests on configuration because of executing cross compiled binaries or crashes at run-time due wrong sizes of basic types.  When utilizing OpenEmbedded you avoid searching for patches at many different places and will be able to get things done more quickly.  <application>OpenEmbedded</application> allows you to choose from a pool of ready to use software packages.</para>
-            <para>OpenEmbedded will create complete flashable images using different output formats and filesystems. This allows you to create complete and specialized distributions easily.</para>
-        </section>
-    </chapter>
-
-<!-- Bitbake usage chapter -->
-<!--    &chapter-usage; - this is not ready yet -->
-
-<!-- Bitbake recipies chapter -->
-    &chapter-recipes;
-
-<!-- Reference manual. Sorted alphabetically. All entries are pulled in from external files -->
-    <chapter>
-        <title>Reference</title>
-        &class-autotools;
-        &class-binconfig;
-        &dirs-install;
-        &dirs-staging;
-        &class-distutils;
-        &fakeroot;
-        &class-image_ipkg;
-        &image-types;
-        &class-pkgconfig;
-        &class-rootfs_ipkg;
-        &var-section;
-        &var-src-uri;
-        &class-update-alternatives;
-        &class-update-rcd;
-    </chapter>
-
-</book>
+      <para>Writing of <application>BitBake</application> recipes is more easy
+      and more intuitive than writing Makefiles while providing higher
+      flexibility. This allows you to tweak specific recipes for your very
+      special needs and to add new recipes very fast. You can build
+      toolchains, Software Distribution Kits (SDKs), complete Distributions or
+      just single packages. The flexibility of OpenEmbedded allows you to
+      reuse the once written recipes for many different purposes. OpenEmbedded
+      provides everything buildroot will be able to provide. But in contrast
+      to buildroot OpenEmbedded will allow you to achieve what you really want
+      to achieve. You can add new package formats, new filesystems, new output
+      formats easily. OpenEmbedded will suit your need.</para>
+    </section>
+
+    <section id="comparing_crosstool">
+      <title>crosstool</title>
+
+      <para>Crosstool allows to create toolchains for you. It can only create
+      the initial toolchain for you. It will not compile other needed
+      libraries or applications for you, it will not be able to track
+      dependencies or to package them properly. OpenEmbedded supports all
+      configurations crosstool supports. You can start to create toolchains
+      with OpenEmbedded, then as your needs grow create a more complete SDK
+      from already present base libraries and applications and if you
+      recognize you need to have packages for the target you have them almost
+      built already.</para>
+    </section>
+
+    <section id="comparing_handmade">
+      <title>handmade</title>
+
+      <para>Cross-compilation is a tough business. It is not that
+      cross-compiling is hard itself but many people misuse the buildsystem
+      they use to build their software. This will lead to a variety of issues
+      you can run into. This can be failing tests on configuration because of
+      executing cross compiled binaries or crashes at run-time due wrong sizes
+      of basic types. When utilizing OpenEmbedded you avoid searching for
+      patches at many different places and will be able to get things done
+      more quickly. <application>OpenEmbedded</application> allows you to
+      choose from a pool of ready to use software packages.</para>
+
+      <para>OpenEmbedded will create complete flashable images using different
+      output formats and filesystems. This allows you to create complete and
+      specialized distributions easily.</para>
+    </section>
+  </chapter>
+
+  <!-- Bitbake usage chapter -->
+
+  <!--    &chapter-usage; - this is not ready yet -->
+
+  <!-- Bitbake recipies chapter -->
+
+  &chapter-recipes;
+
+  <!-- Reference manual. Sorted alphabetically. All entries are pulled in from external files -->
+
+  <chapter id="chapter_reference">
+    <title>Reference</title>
+
+    &class-autotools;
+
+    &class-binconfig;
+
+    &dirs-install;
+
+    &dirs-staging;
+
+    &class-distutils;
+
+    &fakeroot;
+
+    &class-image_ipkg;
+
+    &image-types;
+
+    &class-pkgconfig;
+
+    &class-rootfs_ipkg;
+
+    &var-section;
+
+    &var-src-uri;
+
+    &class-update-alternatives;
+
+    &class-update-rcd;
+  </chapter>
+</book>
\ No newline at end of file