1 files changed, 69 insertions, 89 deletions

diff --git a/documentation/sdk-manual/working-projects.rst b/documentation/sdk-manual/working-projects.rst
index bddf00a7dc..4236bcec24 100644
--- a/documentation/sdk-manual/working-projects.rst
+++ b/documentation/sdk-manual/working-projects.rst
@@ -11,14 +11,15 @@ Autotools-Based Projects
 ========================
 
 Once you have a suitable :ref:`sdk-manual/intro:the cross-development toolchain`
-installed, it is very easy to develop a project using the `GNU
-Autotools-based <https://en.wikipedia.org/wiki/GNU_Build_System>`__
-workflow, which is outside of the :term:`OpenEmbedded Build System`.
+installed, it is very easy to develop a project using the :wikipedia:`GNU
+Autotools-based <GNU_Build_System>` workflow, which is outside of the
+:term:`OpenEmbedded Build System`.
 
 The following figure presents a simple Autotools workflow.
 
 .. image:: figures/sdk-autotools-flow.png
    :align: center
+   :width: 70%
 
 Follow these steps to create a simple Autotools-based "Hello World"
 project:
@@ -30,10 +31,9 @@ project:
    GNOME Developer
    site.
 
-1. *Create a Working Directory and Populate It:* Create a clean
+#. *Create a Working Directory and Populate It:* Create a clean
    directory for your project and then make that directory your working
-   location.
-   ::
+   location::
 
       $ mkdir $HOME/helloworld
       $ cd $HOME/helloworld
@@ -45,16 +45,14 @@ project:
    respectively.
 
    Use the following command to create an empty README file, which is
-   required by GNU Coding Standards:
-   ::
+   required by GNU Coding Standards::
 
       $ touch README
 
    Create the remaining
    three files as follows:
 
-   -  ``hello.c``:
-      ::
+   -  ``hello.c``::
 
          #include <stdio.h>
 
@@ -63,8 +61,7 @@ project:
                  printf("Hello World!\n");
              }
 
-   -  ``configure.ac``:
-      ::
+   -  ``configure.ac``::
 
          AC_INIT(hello,0.1)
          AM_INIT_AUTOMAKE([foreign])
@@ -72,13 +69,12 @@ project:
          AC_CONFIG_FILES(Makefile)
          AC_OUTPUT
 
-   -  ``Makefile.am``:
-      ::
+   -  ``Makefile.am``::
 
          bin_PROGRAMS = hello
          hello_SOURCES = hello.c
 
-2. *Source the Cross-Toolchain Environment Setup File:* As described
+#. *Source the Cross-Toolchain Environment Setup File:* As described
    earlier in the manual, installing the cross-toolchain creates a
    cross-toolchain environment setup script in the directory that the
    SDK was installed. Before you can use the tools to develop your
@@ -87,14 +83,17 @@ project:
    which is followed by the string "poky-linux". For this example, the
    command sources a script from the default SDK installation directory
    that uses the 32-bit Intel x86 Architecture and the &DISTRO; Yocto
-   Project release:
-   ::
+   Project release::
 
       $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
 
-3. *Create the configure Script:* Use the ``autoreconf`` command to
-   generate the ``configure`` script.
-   ::
+   Another example is sourcing the environment setup directly in a Yocto
+   build::
+
+      $ source tmp/deploy/images/qemux86-64/environment-setup-core2-64-poky-linux
+
+#. *Create the configure Script:* Use the ``autoreconf`` command to
+   generate the ``configure`` script::
 
       $ autoreconf
 
@@ -104,20 +103,16 @@ project:
 
    .. note::
 
-      If you get errors from
-      configure.ac
-      , which
-      autoreconf
+      If you get errors from ``configure.ac``, which ``autoreconf``
       runs, that indicate missing files, you can use the "-i" option,
       which ensures missing auxiliary files are copied to the build
       host.
 
-4. *Cross-Compile the Project:* This command compiles the project using
+#. *Cross-Compile the Project:* This command compiles the project using
    the cross-compiler. The
    :term:`CONFIGURE_FLAGS`
    environment variable provides the minimal arguments for GNU
-   configure:
-   ::
+   configure::
 
       $ ./configure ${CONFIGURE_FLAGS}
 
@@ -130,14 +125,12 @@ project:
    ``armv5te-poky-linux-gnueabi``. You will notice that the name of the
    script is ``environment-setup-armv5te-poky-linux-gnueabi``. Thus, the
    following command works to update your project and rebuild it using
-   the appropriate cross-toolchain tools:
-   ::
+   the appropriate cross-toolchain tools::
 
      $ ./configure --host=armv5te-poky-linux-gnueabi --with-libtool-sysroot=sysroot_dir
 
-5. *Make and Install the Project:* These two commands generate and
-   install the project into the destination directory:
-   ::
+#. *Make and Install the Project:* These two commands generate and
+   install the project into the destination directory::
 
       $ make
       $ make install DESTDIR=./tmp
@@ -146,22 +139,19 @@ project:
 
       To learn about environment variables established when you run the
       cross-toolchain environment setup script and how they are used or
-      overridden when the Makefile, see the "
-      Makefile-Based Projects
-      " section.
+      overridden by the Makefile, see the
+      :ref:`sdk-manual/working-projects:makefile-based projects` section.
 
    This next command is a simple way to verify the installation of your
    project. Running the command prints the architecture on which the
    binary file can run. This architecture should be the same
-   architecture that the installed cross-toolchain supports.
-   ::
+   architecture that the installed cross-toolchain supports::
 
       $ file ./tmp/usr/local/bin/hello
 
-6. *Execute Your Project:* To execute the project, you would need to run
+#. *Execute Your Project:* To execute the project, you would need to run
    it on your target hardware. If your target hardware happens to be
-   your build host, you could run the project as follows:
-   ::
+   your build host, you could run the project as follows::
 
       $ ./tmp/usr/local/bin/hello
 
@@ -181,23 +171,24 @@ variables and Makefile variables during development.
 
 .. image:: figures/sdk-makefile-flow.png
    :align: center
+   :width: 70%
 
 The main point of this section is to explain the following three cases
 regarding variable behavior:
 
--  *Case 1 - No Variables Set in the Makefile Map to Equivalent
+-  *Case 1 --- No Variables Set in the Makefile Map to Equivalent
    Environment Variables Set in the SDK Setup Script:* Because matching
    variables are not specifically set in the ``Makefile``, the variables
    retain their values based on the environment setup script.
 
--  *Case 2 - Variables Are Set in the Makefile that Map to Equivalent
+-  *Case 2 --- Variables Are Set in the Makefile that Map to Equivalent
    Environment Variables from the SDK Setup Script:* Specifically
    setting matching variables in the ``Makefile`` during the build
    results in the environment settings of the variables being
    overwritten. In this case, the variables you set in the ``Makefile``
    are used.
 
--  *Case 3 - Variables Are Set Using the Command Line that Map to
+-  *Case 3 --- Variables Are Set Using the Command Line that Map to
    Equivalent Environment Variables from the SDK Setup Script:*
    Executing the ``Makefile`` from the command line results in the
    environment variables being overwritten. In this case, the
@@ -206,10 +197,7 @@ regarding variable behavior:
 .. note::
 
    Regardless of how you set your variables, if you use the "-e" option
-   with
-   make
-   , the variables from the SDK setup script take precedence:
-   ::
+   with ``make``, the variables from the SDK setup script take precedence::
 
       $ make -e target
 
@@ -220,8 +208,7 @@ demonstrates these variable behaviors.
 In a new shell environment variables are not established for the SDK
 until you run the setup script. For example, the following commands show
 a null value for the compiler variable (i.e.
-:term:`CC`).
-::
+:term:`CC`)::
 
    $ echo ${CC}
 
@@ -231,8 +218,7 @@ Running the
 SDK setup script for a 64-bit build host and an i586-tuned target
 architecture for a ``core-image-sato`` image using the current &DISTRO;
 Yocto Project release and then echoing that variable shows the value
-established through the script:
-::
+established through the script::
 
    $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
    $ echo ${CC}
@@ -241,10 +227,9 @@ established through the script:
 To illustrate variable use, work through this simple "Hello World!"
 example:
 
-1. *Create a Working Directory and Populate It:* Create a clean
+#. *Create a Working Directory and Populate It:* Create a clean
    directory for your project and then make that directory your working
-   location.
-   ::
+   location::
 
       $ mkdir $HOME/helloworld
       $ cd $HOME/helloworld
@@ -257,8 +242,7 @@ example:
 
    Create the three files as follows:
 
-   -  ``main.c``:
-      ::
+   -  ``main.c``::
 
          #include "module.h"
          void sample_func();
@@ -268,14 +252,12 @@ example:
              return 0;
          }
 
-   -  ``module.h``:
-      ::
+   -  ``module.h``::
 
          #include <stdio.h>
          void sample_func();
 
-   -  ``module.c``:
-      ::
+   -  ``module.c``::
 
          #include "module.h"
          void sample_func()
@@ -284,7 +266,7 @@ example:
              printf("\n");
          }
 
-2. *Source the Cross-Toolchain Environment Setup File:* As described
+#. *Source the Cross-Toolchain Environment Setup File:* As described
    earlier in the manual, installing the cross-toolchain creates a
    cross-toolchain environment setup script in the directory that the
    SDK was installed. Before you can use the tools to develop your
@@ -293,35 +275,37 @@ example:
    which is followed by the string "poky-linux". For this example, the
    command sources a script from the default SDK installation directory
    that uses the 32-bit Intel x86 Architecture and the &DISTRO_NAME; Yocto
-   Project release:
-   ::
+   Project release::
 
       $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
 
-3. *Create the Makefile:* For this example, the Makefile contains
-   two lines that can be used to set the ``CC`` variable. One line is
+   Another example is sourcing the environment setup directly in a Yocto
+   build::
+
+      $ source tmp/deploy/images/qemux86-64/environment-setup-core2-64-poky-linux
+
+#. *Create the Makefile:* For this example, the Makefile contains
+   two lines that can be used to set the :term:`CC` variable. One line is
    identical to the value that is set when you run the SDK environment
-   setup script, and the other line sets ``CC`` to "gcc", the default
-   GNU compiler on the build host:
-   ::
+   setup script, and the other line sets :term:`CC` to "gcc", the default
+   GNU compiler on the build host::
 
       # CC=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux
       # CC="gcc"
       all: main.o module.o
-        ${CC} main.o module.o -o target_bin
+        ${CC} main.o module.o -o target_bin
       main.o: main.c module.h
-        ${CC} -I . -c main.c
-      module.o: module.c
-        module.h ${CC} -I . -c module.c
+        ${CC} -I . -c main.c
+      module.o: module.c module.h
+        ${CC} -I . -c module.c
       clean:
-        rm -rf *.o
-        rm target_bin
+        rm -rf *.o
+        rm target_bin
 
-4. *Make the Project:* Use the ``make`` command to create the binary
+#. *Make the Project:* Use the ``make`` command to create the binary
    output file. Because variables are commented out in the Makefile, the
-   value used for ``CC`` is the value set when the SDK environment setup
-   file was run:
-   ::
+   value used for :term:`CC` is the value set when the SDK environment setup
+   file was run::
 
       $ make
       i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
@@ -329,13 +313,12 @@ example:
       i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin
 
    From the results of the previous command, you can see that
-   the compiler used was the compiler established through the ``CC``
+   the compiler used was the compiler established through the :term:`CC`
    variable defined in the setup script.
 
-   You can override the ``CC`` environment variable with the same
+   You can override the :term:`CC` environment variable with the same
    variable as set from the Makefile by uncommenting the line in the
-   Makefile and running ``make`` again.
-   ::
+   Makefile and running ``make`` again::
 
       $ make clean
       rm -rf *.o
@@ -356,8 +339,7 @@ example:
    variable as part of the command line. Go into the Makefile and
    re-insert the comment character so that running ``make`` uses the
    established SDK compiler. However, when you run ``make``, use a
-   command-line argument to set ``CC`` to "gcc":
-   ::
+   command-line argument to set :term:`CC` to "gcc"::
 
       $ make clean
       rm -rf *.o
@@ -381,8 +363,7 @@ example:
    environment variable.
 
    In this last case, edit Makefile again to use the "gcc" compiler but
-   then use the "-e" option on the ``make`` command line:
-   ::
+   then use the "-e" option on the ``make`` command line::
 
       $ make clean
       rm -rf *.o
@@ -406,9 +387,8 @@ example:
    use the SDK environment variables regardless of the values in the
    Makefile.
 
-5. *Execute Your Project:* To execute the project (i.e. ``target_bin``),
-   use the following command:
-   ::
+#. *Execute Your Project:* To execute the project (i.e. ``target_bin``),
+   use the following command::
 
       $ ./target_bin
       Hello World!