From cf2169b351000b04f46270fcb3a9234ffa44b7c5 Mon Sep 17 00:00:00 2001
From: Scott Rifenbark <srifenbark@gmail.com>
Date: Tue, 20 Jun 2017 14:24:30 -0700
Subject: dev-manual, ref-manual: Re-wrote the intros

Fixes [YOCTO #11630]

I updated both the introductory sections of the ref-manual and the
dev-manual.  These need to work more tightly with the projected
YP documentation set.

(From yocto-docs rev: 6a28537d03fad8a53198edc7f9a6229f4e58e551)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
---
 documentation/ref-manual/introduction.xml | 173 +++++++-----------------------
 1 file changed, 41 insertions(+), 132 deletions(-)

(limited to 'documentation/ref-manual/introduction.xml')

diff --git a/documentation/ref-manual/introduction.xml b/documentation/ref-manual/introduction.xml
index aab0eaa9e0..98b3ca828c 100644
--- a/documentation/ref-manual/introduction.xml
+++ b/documentation/ref-manual/introduction.xml
@@ -12,29 +12,25 @@
         Welcome to the Yocto Project Reference Manual.
         This manual provides reference information for the current release
         of the Yocto Project.
-        The Yocto Project is an open-source collaboration project focused
-        on embedded Linux developers.
-        Amongst other things, the Yocto Project uses the OpenEmbedded build
-        system, which is based on the Poky project, to construct complete
-        Linux images.
+        This manual is best used after you have an understanding
+        of the basics of the Yocto Project.
+        The manual is neither meant to be read as a starting point to the
+        Yocto Project nor read from start to finish.
+        Use this manual to find concepts, variable definitions, class
+        descriptions, and so forth as needed during the course of using
+        the Yocto Project.
     </para>
 
     <para>
-        This reference manual is best used after you have an understanding
-        of the basics of the Yocto Project.
-        The manual is not meant to be read as a starting point to the
-        Yocto Project.
-        Use this manual to find concepts, variable definitions, class
-        descriptions, and so forth.
-        The manual augments working with the Yocto Project during application
-        and kernel development.
+        For introductory information on the Yocto Project, see the
+        <ulink url='&YOCTO_HOME_URL;/ecosystem/yocto-project-backgrounders'>Yocto Project Backgrounders</ulink>
+        on the
+        <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>.
     </para>
 
     <para>
-        The Yocto Project Reference Manual does not provide "how-to",
-        task-oriented information.
-        You can find complete introductory and getting started information
-        on the Yocto Project by reading the
+        You can find an introductory to using the Yocto Project by working
+        through the
         <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
         You can find "how-to" information in the
         <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Manual</ulink>.
@@ -47,124 +43,37 @@
     </para>
 </section>
 
-<!--
-<section id='intro-manualoverview'>
-    <title>Documentation Overview</title>
+<section id='ref-yp-intro'>
+    <title>Yocto Project Introduction</title>
+
     <para>
-        This reference manual consists of the following:
-        <itemizedlist>
-            <listitem><para>
-                <emphasis>
-                <link linkend='usingpoky'>Using the Yocto Project</link>:
-                </emphasis>
-                Provides an overview of the components that make up the Yocto
-                Project followed by information about debugging images created
-                in the Yocto Project.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>
-                <link linkend='closer-look'>A Closer Look at the Yocto Project Development Environment</link>:
-                </emphasis>
-                Provides a more detailed look at the Yocto Project development
-                environment within the context of development.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>
-                <link linkend='technical-details'>Technical Details</link>:
-                </emphasis>
-                Describes fundamental Yocto Project components as well as an
-                explanation behind how the Yocto Project uses shared state
-                (sstate) cache to speed build time.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>
-                <link linkend='migration'>Migrating to a Newer Yocto Project Release</link>:
-                </emphasis>
-                Describes release-specific information that helps you move from
-                one Yocto Project Release to another.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>
-                <link linkend='ref-structure'>Directory Structure</link>:
-                </emphasis> Describes the
-                <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
-                created either by unpacking a released Yocto Project tarball on
-                your host development system, or by cloning the upstream
-                <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink>
-                Git repository.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>
-                <link linkend='ref-classes'>Classes</link>:
-                </emphasis>
-                Describes the classes used in the Yocto Project.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>
-                <link linkend='ref-tasks'>Tasks</link>:
-                </emphasis>
-                Describes the tasks defined by the OpenEmbedded build system.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>
-                <link linkend='ref-devtool-reference'><filename>devtool</filename> Quick Reference</link>:
-                </emphasis>
-                Provides a quick reference for the <filename>devtool</filename>
-                command.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>
-                <link linkend='ref-qa-checks'>QA Error and Warning Messages</link>:
-                </emphasis>
-                Lists and describes QA warning and error messages.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>
-                <link linkend='ref-images'>Images</link>:
-                </emphasis>
-                Describes the standard images that the Yocto Project supports.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>
-                <link linkend='ref-features'>Features</link>:
-                </emphasis>
-                Describes mechanisms for creating distribution, machine, and
-                image features during the build process using the OpenEmbedded
-                build system.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>
-                <link linkend='ref-variables-glos'>Variables Glossary</link>:
-                </emphasis>
-                Presents most variables used by the OpenEmbedded build system,
-                which uses BitBake.
-                Entries describe the function of the variable and how to
-                apply them.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>
-                <link linkend='ref-varlocality'>Variable Context</link>:
-                </emphasis>
-                Provides variable locality or context.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>
-                <link linkend='faq'>FAQ</link>:
-                </emphasis>
-                Provides answers for commonly asked questions in the Yocto
-                Project development environment.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>
-                <link linkend='resources'>Contributions and Additional Information</link>:
-                </emphasis>
-                Provides an overview of methods by which you can
-                contribute to and participate in the Yocto Project.
-                </para></listitem>
-        </itemizedlist>
+        The Yocto Project is an open-source collaboration project whose
+        focus is for developers of embedded Linux systems.
+        Among other things, the Yocto Project uses a build host based
+        on the OpenEmbedded (OE) project, which uses the
+        <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
+        tool, to construct complete Linux images.
+        The BitBake and OE components are combined together to form
+        a reference build host, historically known as
+        <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink>
+        (<emphasis>Pah</emphasis>-kee).
+    </para>
+
+    <para>
+        By default, using the Yocto Project creates a Poky distribution.
+        However, you can create your own distribution by providing key
+        <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>.
+        A good example is Angstrom, which has had a distribution
+        based on the Yocto Project since its inception.
+        Other examples include commercial distributions like
+        <ulink url='https://www.yoctoproject.org/organization/wind-river-systems'>Wind River Linux</ulink>,
+        <ulink url='https://www.yoctoproject.org/organization/mentor-graphics'>Mentor Embedded Linux</ulink>,
+        <ulink url='https://www.yoctoproject.org/organization/enea-ab'>ENEA Linux</ulink>
+        and <ulink url='https://www.yoctoproject.org/ecosystem/member-organizations'>others</ulink>.
+        See the "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-your-own-distribution'>Creating Your Own Distribution</ulink>"
+        section in the Yocto Project Development Manual for more information.
     </para>
 </section>
--->
 
 <section id='intro-requirements'>
 <title>System Requirements</title>
-- 
cgit v1.2.3-54-g00ecf