sphinx: sdk-manual: Various URL, code block and other fixes to imported data

(From yocto-docs rev: 12f5e9cb36409b813ffef9242ce9a042f08acf69)

Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

6 files changed, 623 insertions, 282 deletions

diff --git a/documentation/sdk-manual/sdk-appendix-customizing.rst b/documentation/sdk-manual/sdk-appendix-customizing.rst
index 3bb6ef3a19..7743e3c004 100644
--- a/documentation/sdk-manual/sdk-appendix-customizing.rst
+++ b/documentation/sdk-manual/sdk-appendix-customizing.rst
@@ -18,8 +18,7 @@ build system applies them against ``local.conf`` and ``auto.conf``:
 
 -  Variables whose values start with "/" are excluded since the
    assumption is that those values are paths that are likely to be
-   specific to the `build
-   host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__.
+   specific to the :term:`Build Host`.
 
 -  Variables listed in
    :term:`SDK_LOCAL_CONF_BLACKLIST`
@@ -57,8 +56,8 @@ OpenEmbedded build system used to create the SDK.
 Adjusting the Extensible SDK to Suit Your Build Host's Setup
 ============================================================
 
-In most cases, the extensible SDK defaults should work with your `build
-host's <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__ setup.
+In most cases, the extensible SDK defaults should work with your :term:`Build
+Host`'s setup.
 However, some cases exist for which you might consider making
 adjustments:
 
@@ -87,8 +86,8 @@ adjustments:
    opposed to being called explicitly), then you need to do one of the
    following:
 
-   -  After ensuring the tasks are `shared
-      state <&YOCTO_DOCS_OM_URL;#shared-state-cache>`__ tasks (i.e. the
+   -  After ensuring the tasks are :ref:`shared
+      state <overview-manual/overview-manual-concepts:shared state cache>` tasks (i.e. the
       output of the task is saved to and can be restored from the shared
       state cache) or ensuring the tasks are able to be produced quickly
       from a task that is a shared state task, add the task name to the
@@ -124,7 +123,7 @@ adjustments:
 
 -  If your OpenEmbedded build system setup uses a different environment
    setup script other than
-   ````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__, then you must
+   :ref:`structure-core-script`, then you must
    set
    :term:`OE_INIT_ENV_SCRIPT`
    to point to the environment setup script you use.
@@ -152,8 +151,10 @@ from the :term:`DISTRO` variable.
 The
 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
 class defines the default value of the ``SDK_TITLE`` variable as
-follows: SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or
-d.getVar('DISTRO')} SDK"
+follows:
+::
+
+   SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
 
 While several ways exist to change this variable, an efficient method is
 to set the variable in your distribution's configuration file. Doing so
@@ -163,7 +164,10 @@ an example, assume you have your own layer for your distribution named
 does the default "poky" distribution. If so, you could update the
 ``SDK_TITLE`` variable in the
 ``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following
-form: SDK_TITLE = "your_title"
+form:
+::
+
+   SDK_TITLE = "your_title"
 
 Providing Updates to the Extensible SDK After Installation
 ==========================================================
@@ -193,8 +197,12 @@ the installed SDKs to update the installed SDKs by using the
 3. Build the extensible SDK normally (i.e., use the
    ``bitbake -c populate_sdk_ext`` imagename command).
 
-4. Publish the SDK using the following command: $ oe-publish-sdk
-   some_path/sdk-installer.sh path_to_shared_http_directory You must
+4. Publish the SDK using the following command:
+   ::
+
+      $ oe-publish-sdk some_path/sdk-installer.sh path_to_shared_http_directory
+
+   You must
    repeat this step each time you rebuild the SDK with changes that you
    want to make available through the update mechanism.
 
@@ -213,7 +221,12 @@ installation directory for the SDK is based on the
 :term:`SDKEXTPATH` variables from
 within the
 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
-class as follows: SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" You can
+class as follows:
+::
+
+   SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"
+
+You can
 change this default installation directory by specifically setting the
 ``SDKEXTPATH`` variable.
 
@@ -226,7 +239,10 @@ assume you have your own layer for your distribution named
 does the default "poky" distribution. If so, you could update the
 ``SDKEXTPATH`` variable in the
 ``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following
-form: SDKEXTPATH = "some_path_for_your_installed_sdk"
+form:
+::
+
+   SDKEXTPATH = "some_path_for_your_installed_sdk"
 
 After building your installer, running it prompts the user for
 acceptance of the some_path_for_your_installed_sdk directory as the
@@ -260,8 +276,11 @@ source, you need to do a number of things:
 3. Set the appropriate configuration so that the produced SDK knows how
    to find the configuration. The variable you need to set is
    :term:`SSTATE_MIRRORS`:
-   SSTATE_MIRRORS = "file://.\*
-   http://example.com/some_path/sstate-cache/PATH" You can set the
+   ::
+
+      SSTATE_MIRRORS = "file://.* http://example.com/some_path/sstate-cache/PATH"
+
+   You can set the
    ``SSTATE_MIRRORS`` variable in two different places:
 
    -  If the mirror value you are setting is appropriate to be set for
@@ -271,8 +290,10 @@ source, you need to do a number of things:
       side, and its contents will not interfere with the build), then
       you can set the variable in your ``local.conf`` or custom distro
       configuration file. You can then "whitelist" the variable through
-      to the SDK by adding the following: SDK_LOCAL_CONF_WHITELIST =
-      "SSTATE_MIRRORS"
+      to the SDK by adding the following:
+      ::
+
+         SDK_LOCAL_CONF_WHITELIST = "SSTATE_MIRRORS"
 
    -  Alternatively, if you just want to set the ``SSTATE_MIRRORS``
       variable's value for the SDK alone, create a
@@ -296,7 +317,11 @@ This bundling can lead to an SDK installer file that is a Gigabyte or
 more in size. If the size of this file causes a problem, you can build
 an SDK that has just enough in it to install and provide access to the
 ``devtool command`` by setting the following in your configuration:
-SDK_EXT_TYPE = "minimal" Setting
+::
+
+   SDK_EXT_TYPE = "minimal"
+
+Setting
 :term:`SDK_EXT_TYPE` to
 "minimal" produces an SDK installer that is around 35 Mbytes in size,
 which downloads and installs quickly. You need to realize, though, that
@@ -314,9 +339,12 @@ information enables the ``devtool search`` command to return useful
 results.
 
 To facilitate this wider range of information, you would need to set the
-following: SDK_INCLUDE_PKGDATA = "1" See the
-:term:`SDK_INCLUDE_PKGDATA`
-variable for additional information.
+following:
+::
+
+   SDK_INCLUDE_PKGDATA = "1"
+
+See the :term:`SDK_INCLUDE_PKGDATA` variable for additional information.
 
 Setting the ``SDK_INCLUDE_PKGDATA`` variable as shown causes the "world"
 target to be built so that information for all of the recipes included
diff --git a/documentation/sdk-manual/sdk-appendix-obtain.rst b/documentation/sdk-manual/sdk-appendix-obtain.rst
index ed460c78ea..ffaed9deef 100644
--- a/documentation/sdk-manual/sdk-appendix-obtain.rst
+++ b/documentation/sdk-manual/sdk-appendix-obtain.rst
@@ -17,10 +17,10 @@ and then run the script to hand-install the toolchain.
 Follow these steps to locate and hand-install the toolchain:
 
 1. *Go to the Installers Directory:* Go to
-   ` <&YOCTO_TOOLCHAIN_DL_URL;>`__
+   :yocto_dl:`releases/yocto/yocto-3.1.2/toolchain/`
 
 2. *Open the Folder for Your Build Host:* Open the folder that matches
-   your `build host <&YOCTO_DOCS_REF_URL;#build-system-term>`__ (i.e.
+   your :term:`Build Host` (i.e.
    ``i686`` for 32-bit machines or ``x86_64`` for 64-bit machines).
 
 3. *Locate and Download the SDK Installer:* You need to find and
@@ -28,14 +28,29 @@ Follow these steps to locate and hand-install the toolchain:
    hardware, and image type.
 
    The installer files (``*.sh``) follow this naming convention:
-   poky-glibc-host_system-core-image-type-arch-toolchain[-ext]-release.sh
-   Where: host_system is a string representing your development system:
-   "i686" or "x86_64" type is a string representing the image: "sato" or
-   "minimal" arch is a string representing the target architecture:
-   "aarch64", "armv5e", "core2-64", "coretexa8hf-neon", "i586",
-   "mips32r2", "mips64", or "ppc7400" release is the version of Yocto
-   Project. NOTE: The standard SDK installer does not have the "-ext"
-   string as part of the filename. The toolchains provided by the Yocto
+   ::
+
+      poky-glibc-host_system-core-image-type-arch-toolchain[-ext]-release.sh
+
+      Where:
+          host_system is a string representing your development system:
+                 "i686" or "x86_64"
+
+          type is a string representing the image:
+                "sato" or "minimal"
+
+          arch is a string representing the target architecture:
+                 "aarch64", "armv5e", "core2-64", "coretexa8hf-neon", "i586", "mips32r2",
+                 "mips64", or "ppc7400"
+
+          release is the version of Yocto Project.
+
+          NOTE:
+             The standard SDK installer does not have the "-ext" string as
+             part of the filename.
+
+
+   The toolchains provided by the Yocto
    Project are based off of the ``core-image-sato`` and
    ``core-image-minimal`` images and contain libraries appropriate for
    developing against those images.
@@ -43,12 +58,17 @@ Follow these steps to locate and hand-install the toolchain:
    For example, if your build host is a 64-bit x86 system and you need
    an extended SDK for a 64-bit core2 target, go into the ``x86_64``
    folder and download the following installer:
-   poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh
+   ::
+
+      poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh
 
 4. *Run the Installer:* Be sure you have execution privileges and run
    the installer. Following is an example from the ``Downloads``
-   directory: $
-   ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh
+   directory:
+   ::
+
+      $ ~/Downloads/poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh
+
    During execution of the script, you choose the root location for the
    toolchain. See the "`Installed Standard SDK Directory
    Structure <#sdk-installed-standard-sdk-directory-structure>`__"
@@ -63,8 +83,7 @@ As an alternative to locating and downloading an SDK installer, you can
 build the SDK installer. Follow these steps:
 
 1. *Set Up the Build Environment:* Be sure you are set up to use BitBake
-   in a shell. See the "`Preparing the Build
-   Host <&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host>`__" section
+   in a shell. See the ":ref:`dev-manual/dev-manual-start:preparing the build host`" section
    in the Yocto Project Development Tasks Manual for information on how
    to get a build host ready that is either a native Linux machine or a
    machine that uses CROPS.
@@ -72,21 +91,23 @@ build the SDK installer. Follow these steps:
 2. *Clone the ``poky`` Repository:* You need to have a local copy of the
    Yocto Project :term:`Source Directory`
    (i.e. a local
-   ``poky`` repository). See the "`Cloning the ``poky``
-   Repository <&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository>`__" and
-   possibly the "`Checking Out by Branch in
-   Poky <&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky>`__" and
-   "`Checking Out by Tag in
-   Poky <&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky>`__" sections
+   ``poky`` repository). See the ":ref:`dev-manual/dev-manual-start:cloning the \`\`poky\`\` repository`" and
+   possibly the ":ref:`dev-manual/dev-manual-start:checking out by branch in poky`" and
+   ":ref:`checkout-out-by-tag-in-poky`" sections
    all in the Yocto Project Development Tasks Manual for information on
    how to clone the ``poky`` repository and check out the appropriate
    branch for your work.
 
 3. *Initialize the Build Environment:* While in the root directory of
    the Source Directory (i.e. ``poky``), run the
-   ````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__ environment
+   :ref:`structure-core-script` environment
    setup script to define the OpenEmbedded build environment on your
-   build host. $ source OE_INIT_FILE Among other things, the script
+   build host.
+   ::
+
+      $ source oe-init-build-env
+
+   Among other things, the script
    creates the :term:`Build Directory`,
    which is
    ``build`` in this case and is located in the Source Directory. After
@@ -119,13 +140,17 @@ build the SDK installer. Follow these steps:
               The extensible SDK can currently only be built for the same architecture as the machine being built on - SDK_ARCH is
               set to i686 (likely via setting SDKMACHINE) which is different from the architecture of the build machine (x86_64).
               Unable to continue.
-                             
+
 
 6. *Build the SDK Installer:* To build the SDK installer for a standard
    SDK and populate the SDK image, use the following command form. Be
    sure to replace image with an image (e.g. "core-image-sato"): $
    bitbake image -c populate_sdk You can do the same for the extensible
-   SDK using this command form: $ bitbake image -c populate_sdk_ext
+   SDK using this command form:
+   ::
+
+      $ bitbake image -c populate_sdk_ext
+
    These commands produce an SDK installer that contains the sysroot
    that matches your target root filesystem.
 
@@ -147,9 +172,12 @@ build the SDK installer. Follow these steps:
          libc-staticdev"
 
 7. *Run the Installer:* You can now run the SDK installer from
-   ``tmp/deploy/sdk`` in the Build Directory. Following is an example: $
-   cd ~/poky/build/tmp/deploy/sdk $
-   ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh
+   ``tmp/deploy/sdk`` in the Build Directory. Following is an example:
+   ::
+
+      $ cd ~/poky/build/tmp/deploy/sdk
+      $ ./poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-DISTRO.sh
+
    During execution of the script, you choose the root location for the
    toolchain. See the "`Installed Standard SDK Directory
    Structure <#sdk-installed-standard-sdk-directory-structure>`__"
@@ -176,7 +204,7 @@ Follow these steps to extract the root filesystem:
    Image File:* You need to find and download the root filesystem image
    file that is appropriate for your target system. These files are kept
    in machine-specific folders in the
-   :yocto_dl:`Index of Releases <releases/yocto/yocto-&DISTRO;/machines/>`
+   :yocto_dl:`Index of Releases <releases/yocto/yocto-3.1.2/machines/>`
    in the "machines" directory.
 
    The machine-specific folders of the "machines" directory contain
@@ -185,22 +213,32 @@ Follow these steps to extract the root filesystem:
    which you can use with QEMU directly.
 
    The pre-built root filesystem image files follow these naming
-   conventions: core-image-profile-arch.tar.bz2 Where: profile is the
-   filesystem image's profile: lsb, lsb-dev, lsb-sdk, minimal,
-   minimal-dev, minimal-initramfs, sato, sato-dev, sato-sdk,
-   sato-sdk-ptest. For information on these types of image profiles, see
-   the ":ref:`ref-manual/ref-images:Images`" chapter in the
-   Yocto Project Reference Manual. arch is a string representing the
-   target architecture: beaglebone-yocto, beaglebone-yocto-lsb,
-   edgerouter, edgerouter-lsb, genericx86, genericx86-64,
-   genericx86-64-lsb, genericx86-lsb and qemu*. The root filesystems
+   conventions:
+   ::
+
+      core-image-profile-arch.tar.bz2
+
+      Where:
+          profile is the filesystem image's profile:
+                    lsb, lsb-dev, lsb-sdk, minimal, minimal-dev, minimal-initramfs,
+                    sato, sato-dev, sato-sdk, sato-sdk-ptest. For information on
+                    these types of image profiles, see the "Images" chapter in
+                    the Yocto Project Reference Manual.
+
+          arch is a string representing the target architecture:
+                    beaglebone-yocto, beaglebone-yocto-lsb, edgerouter, edgerouter-lsb,
+                    genericx86, genericx86-64, genericx86-64-lsb, genericx86-lsb and qemu*.
+
+   The root filesystems
    provided by the Yocto Project are based off of the
    ``core-image-sato`` and ``core-image-minimal`` images.
 
    For example, if you plan on using a BeagleBone device as your target
    hardware and your image is a ``core-image-sato-sdk`` image, you can
    download the following file:
-   core-image-sato-sdk-beaglebone-yocto.tar.bz2
+   ::
+
+      core-image-sato-sdk-beaglebone-yocto.tar.bz2
 
 2. *Initialize the Cross-Development Environment:* You must ``source``
    the cross-development environment setup script to establish necessary
@@ -210,21 +248,24 @@ Follow these steps to extract the root filesystem:
    installed the toolchain (e.g. ``poky_sdk``).
 
    Following is an example based on the toolchain installed in the
-   "`Locating Pre-Built SDK
-   Installers <#sdk-locating-pre-built-sdk-installers>`__" section: $
-   source ~/poky_sdk/environment-setup-core2-64-poky-linux
+   ":ref:`sdk-locating-pre-built-sdk-installers`" section:
+   ::
+
+      $ source ~/poky_sdk/environment-setup-core2-64-poky-linux
 
 3. *Extract the Root Filesystem:* Use the ``runqemu-extract-sdk``
    command and provide the root filesystem image.
 
    Following is an example command that extracts the root filesystem
    from a previously built root filesystem image that was downloaded
-   from the `Index of Releases <&YOCTO_DOCS_OM_URL;#index-downloads>`__.
+   from the :yocto_dl:`Index of Releases <releases/yocto/yocto-3.1.2/machines/>`.
    This command extracts the root filesystem into the ``core2-64-sato``
-   directory: $ runqemu-extract-sdk
-   ~/Downloads/core-image-sato-sdk-beaglebone-yocto.tar.bz2
-   ~/beaglebone-sato You could now point to the target sysroot at
-   ``beablebone-sato``.
+   directory:
+   ::
+
+      $ runqemu-extract-sdk ~/Downloads/core-image-sato-sdk-beaglebone-yocto.tar.bz2 ~/beaglebone-sato
+
+   You could now point to the target sysroot at ``beablebone-sato``.
 
 Installed Standard SDK Directory Structure
 ==========================================
@@ -246,7 +287,7 @@ Within the figure, italicized text is used to indicate replaceable
 portions of the file or directory name. For example, install_dir/version
 is the directory where the SDK is installed. By default, this directory
 is ``/opt/poky/``. And, version represents the specific snapshot of the
-SDK (e.g. ````). Furthermore, target represents the target architecture
+SDK (e.g. 3.1.2). Furthermore, target represents the target architecture
 (e.g. ``i586``) and host represents the development system's
 architecture (e.g. ``x86_64``). Thus, the complete names of the two
 directories within the ``sysroots`` could be ``i586-poky-linux`` and
diff --git a/documentation/sdk-manual/sdk-extensible.rst b/documentation/sdk-manual/sdk-extensible.rst
index 5836bd8549..1ad5c46bea 100644
--- a/documentation/sdk-manual/sdk-extensible.rst
+++ b/documentation/sdk-manual/sdk-extensible.rst
@@ -45,14 +45,13 @@ functionality.
 Installing the Extensible SDK
 =============================
 
-The first thing you need to do is install the SDK on your `Build
-Host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__ by running the
-``*.sh`` installation script.
+The first thing you need to do is install the SDK on your :term:`Build
+Host` by running the ``*.sh`` installation script.
 
 You can download a tarball installer, which includes the pre-built
 toolchain, the ``runqemu`` script, the internal build system,
 ``devtool``, and support files from the appropriate
-`toolchain <&YOCTO_TOOLCHAIN_DL_URL;>`__ directory within the Index of
+:yocto_dl:`toolchain <releases/yocto/yocto-3.1.2/toolchain/>` directory within the Index of
 Releases. Toolchains are available for several 32-bit and 64-bit
 architectures with the ``x86_64`` directories, respectively. The
 toolchains the Yocto Project provides are based off the
@@ -64,17 +63,33 @@ representing the host system appears first in the filename and then is
 immediately followed by a string representing the target architecture.
 An extensible SDK has the string "-ext" as part of the name. Following
 is the general form:
-poky-glibc-host_system-image_type-arch-toolchain-ext-release_version.sh
-Where: host_system is a string representing your development system:
-i686 or x86_64. image_type is the image for which the SDK was built:
-core-image-sato or core-image-minimal arch is a string representing the
-tuned target architecture: aarch64, armv5e, core2-64, i586, mips32r2,
-mips64, ppc7400, or cortexa8hf-neon release_version is a string
-representing the release number of the Yocto Project: DISTRO,
-DISTRO+snapshot For example, the following SDK installer is for a 64-bit
+::
+
+   poky-glibc-host_system-image_type-arch-toolchain-ext-release_version.sh
+
+   Where:
+       host_system is a string representing your development system:
+
+                  i686 or x86_64.
+
+       image_type is the image for which the SDK was built:
+
+                  core-image-sato or core-image-minimal
+
+       arch is a string representing the tuned target architecture:
+
+                  aarch64, armv5e, core2-64, i586, mips32r2, mips64, ppc7400, or cortexa8hf-neon
+
+       release_version is a string representing the release number of the Yocto Project:
+
+                  3.1.2, 3.1.2+snapshot
+
+For example, the following SDK installer is for a 64-bit
 development host system and a i586-tuned target architecture based off
 the SDK for ``core-image-sato`` and using the current DISTRO snapshot:
-poky-glibc-x86_64-core-image-sato-i586-toolchain-ext-DISTRO.sh
+::
+
+   poky-glibc-x86_64-core-image-sato-i586-toolchain-ext-DISTRO.sh
 
 .. note::
 
@@ -102,28 +117,26 @@ architecture. The example assumes the SDK installer is located in
    that case, set up the proper permissions in the directory and run the
    installer again.
 
-$
-./Downloads/poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.5.sh
-Poky (Yocto Project Reference Distro) Extensible SDK installer version
-2.5
-==========================================================================
-Enter target directory for SDK (default: ~/poky_sdk): You are about to
-install the SDK to "/home/scottrif/poky_sdk". Proceed [Y/n]? Y
-Extracting SDK..............done Setting it up... Extracting
-buildtools... Preparing build system... Parsing recipes: 100%
-\|##################################################################\|
-Time: 0:00:52 Initialising tasks: 100%
-\|###############################################################\|
-Time: 0:00:00 Checking sstate mirror object availability: 100%
-\|#######################################\| Time: 0:00:00 Loading cache:
-100%
-\|####################################################################\|
-Time: 0:00:00 Initialising tasks: 100%
-\|###############################################################\|
-Time: 0:00:00 done SDK has been successfully set up and is ready to be
-used. Each time you wish to use the SDK in a new shell session, you need
-to source the environment setup script e.g. $ .
-/home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux
+::
+
+   $ ./Downloads/poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.5.sh
+   Poky (Yocto Project Reference Distro) Extensible SDK installer version 2.5
+   ==========================================================================
+   Enter target directory for SDK (default: ~/poky_sdk):
+   You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed [Y/n]? Y
+   Extracting SDK..............done
+   Setting it up...
+   Extracting buildtools...
+   Preparing build system...
+   Parsing recipes: 100% |##################################################################| Time: 0:00:52
+   Initialising tasks: 100% |###############################################################| Time: 0:00:00
+   Checking sstate mirror object availability: 100% |#######################################| Time: 0:00:00
+   Loading cache: 100% |####################################################################| Time: 0:00:00
+   Initialising tasks: 100% |###############################################################| Time: 0:00:00
+   done
+   SDK has been successfully set up and is ready to be used.
+   Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
+    $ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux
 
 .. _sdk-running-the-extensible-sdk-environment-setup-script:
 
@@ -142,10 +155,14 @@ begin with the string "``environment-setup``" and include as part of
 their name the tuned target architecture. As an example, the following
 commands set the working directory to where the SDK was installed and
 then source the environment setup script. In this example, the setup
-script is for an IA-based target machine using i586 tuning: $ cd
-/home/scottrif/poky_sdk $ source environment-setup-core2-64-poky-linux
-SDK environment now set up; additionally you may now run devtool to
-perform development tasks. Run devtool --help for further details.
+script is for an IA-based target machine using i586 tuning:
+::
+
+   $ cd /home/scottrif/poky_sdk
+   $ source environment-setup-core2-64-poky-linux
+   SDK environment now set up; additionally you may now run devtool to perform development tasks.
+   Run devtool --help for further details.
+
 Running the setup script defines many environment variables needed in
 order to use the SDK (e.g. ``PATH``,
 :term:`CC`,
@@ -172,7 +189,7 @@ system.
    part of an image built using the build system.
 
 The ``devtool`` command line is organized similarly to
-`Git <&YOCTO_DOCS_OM_URL;#git>`__ in that it has a number of
+:ref:`overview-manual/overview-manual-development-environment:git` in that it has a number of
 sub-commands for each function. You can run ``devtool --help`` to see
 all the commands.
 
@@ -188,12 +205,12 @@ all the commands.
 Three ``devtool`` subcommands exist that provide entry-points into
 development:
 
--  *``devtool add``*: Assists in adding new software to be built.
+-  *devtool add*: Assists in adding new software to be built.
 
--  *``devtool modify``*: Sets up an environment to enable you to modify
+-  *devtool modify*: Sets up an environment to enable you to modify
    the source of an existing component.
 
--  *``devtool upgrade``*: Updates an existing recipe so that you can
+-  *devtool upgrade*: Updates an existing recipe so that you can
    build it for an updated set of source files.
 
 As with the build system, "recipes" represent software packages within
@@ -248,8 +265,12 @@ command:
       to be extracted. In this situation, the source code is extracted
       to the default workspace - you do not want the files in some
       specific location outside of the workspace. Thus, everything you
-      need will be located in the workspace: $ devtool add recipe
-      fetchuri With this command, ``devtool`` extracts the upstream
+      need will be located in the workspace:
+      ::
+
+         $ devtool add recipe fetchuri
+
+      With this command, ``devtool`` extracts the upstream
       source files into a local Git repository within the ``sources``
       folder. The command then creates a recipe named recipe and a
       corresponding append file in the workspace. If you do not provide
@@ -269,7 +290,12 @@ command:
       Furthermore, the first positional argument srctree in this case
       identifies where the ``devtool add`` command will locate the
       extracted code outside of the workspace. You need to specify an
-      empty directory: $ devtool add recipe srctree fetchuri In summary,
+      empty directory:
+      ::
+
+         $ devtool add recipe srctree fetchuri
+
+      In summary,
       the source code is pulled from fetchuri and extracted into the
       location defined by srctree as a local Git repository.
 
@@ -281,7 +307,11 @@ command:
       ``devtool`` workspace.
 
       The following command provides a new recipe name and identifies
-      the existing source tree location: $ devtool add recipe srctree
+      the existing source tree location:
+      ::
+
+         $ devtool add recipe srctree
+
       The command examines the source code and creates a recipe named
       recipe for the code and places the recipe into the workspace.
 
@@ -294,7 +324,12 @@ command:
 
 2. *Edit the Recipe*: You can use ``devtool edit-recipe`` to open up the
    editor as defined by the ``$EDITOR`` environment variable and modify
-   the file: $ devtool edit-recipe recipe From within the editor, you
+   the file:
+   ::
+
+      $ devtool edit-recipe recipe
+
+   From within the editor, you
    can make modifications to the recipe that take affect when you build
    it later.
 
@@ -302,13 +337,18 @@ command:
    depends on what you are going to do with the new code.
 
    If you need to eventually move the build output to the target
-   hardware, use the following ``devtool`` command: $ devtool build
-   recipe
+   hardware, use the following ``devtool`` command:
+   :;
+
+      $ devtool build recipe
 
    On the other hand, if you want an image to contain the recipe's
    packages from the workspace for immediate deployment onto a device
    (e.g. for testing purposes), you can use the ``devtool build-image``
-   command: $ devtool build-image image
+   command:
+   ::
+
+      $ devtool build-image image
 
 4. *Deploy the Build Output*: When you use the ``devtool build`` command
    to build out your recipe, you probably want to see if the resulting
@@ -336,7 +376,10 @@ command:
    creates any patches corresponding to commits in the local Git
    repository, moves the new recipe to a more permanent layer, and then
    resets the recipe so that the recipe is built normally rather than
-   from the workspace. $ devtool finish recipe layer
+   from the workspace.
+   ::
+
+      $ devtool finish recipe layer
 
    .. note::
 
@@ -401,7 +444,12 @@ command:
       outside the workspace (i.e. ``meta-``\ layername).
 
       The following command identifies the recipe and, by default,
-      extracts the source files: $ devtool modify recipe Once
+      extracts the source files:
+      ::
+
+         $ devtool modify recipe
+
+      Once
       ``devtool``\ locates the recipe, ``devtool`` uses the recipe's
       :term:`SRC_URI` statements to
       locate the source code and any local patch files from other
@@ -435,7 +483,10 @@ command:
       The following command tells ``devtool`` the recipe with which to
       work and, in this case, identifies a local area for the extracted
       source files that exists outside of the default ``devtool``
-      workspace: $ devtool modify recipe srctree
+      workspace:
+      ::
+
+         $ devtool modify recipe srctree
 
       .. note::
 
@@ -466,7 +517,10 @@ command:
       The following command tells ``devtool`` the recipe with which to
       work, uses the "-n" option to indicate source does not need to be
       extracted, and uses srctree to point to the previously extracted
-      source files: $ devtool modify -n recipe srctree
+      source files:
+      ::
+
+         $ devtool modify -n recipe srctree
 
       If an ``oe-local-files`` subdirectory happens to exist and it
       contains non-patch files, the files are used. However, if the
@@ -487,8 +541,10 @@ command:
    depends on what you are going to do with the new code.
 
    If you need to eventually move the build output to the target
-   hardware, use the following ``devtool`` command: $ devtool build
-   recipe
+   hardware, use the following ``devtool`` command:
+   ::
+
+      $ devtool build recipe
 
    On the other hand, if you want an image to contain the recipe's
    packages from the workspace for immediate deployment onto a device
@@ -509,8 +565,12 @@ command:
       development machine.
 
    You can deploy your build output to that target hardware by using the
-   ``devtool deploy-target`` command: $ devtool deploy-target recipe
-   target The target is a live target machine running as an SSH server.
+   ``devtool deploy-target`` command:
+   ::
+
+      $ devtool deploy-target recipe target
+
+   The target is a live target machine running as an SSH server.
 
    You can, of course, use other methods to deploy the image you built
    using the ``devtool build-image`` command to actual hardware.
@@ -522,8 +582,10 @@ command:
    repository, updates the recipe to point to them (or creates a
    ``.bbappend`` file to do so, depending on the specified destination
    layer), and then resets the recipe so that the recipe is built
-   normally rather than from the workspace. $ devtool finish recipe
-   layer
+   normally rather than from the workspace.
+   ::
+
+      $ devtool finish recipe layer
 
    .. note::
 
@@ -600,8 +662,12 @@ The following diagram shows the common development flow used with the
    A common situation is where third-party software has undergone a
    revision so that it has been upgraded. The recipe you have access to
    is likely in your own layer. Thus, you need to upgrade the recipe to
-   use the newer version of the software: $ devtool upgrade -V version
-   recipe By default, the ``devtool upgrade`` command extracts source
+   use the newer version of the software:
+   ::
+
+      $ devtool upgrade -V version recipe
+
+   By default, the ``devtool upgrade`` command extracts source
    code into the ``sources`` directory in the
    :ref:`devtool-the-workspace-layer-structure`.
    If you want the code extracted to any other location, you need to
@@ -648,13 +714,18 @@ The following diagram shows the common development flow used with the
    depends on what you are going to do with the new code.
 
    If you need to eventually move the build output to the target
-   hardware, use the following ``devtool`` command: $ devtool build
-   recipe
+   hardware, use the following ``devtool`` command:
+   ::
+
+      $ devtool build recipe
 
    On the other hand, if you want an image to contain the recipe's
    packages from the workspace for immediate deployment onto a device
    (e.g. for testing purposes), you can use the ``devtool build-image``
-   command: $ devtool build-image image
+   command:
+   ::
+
+      $ devtool build-image image
 
 4. *Deploy the Build Output*: When you use the ``devtool build`` command
    or ``bitbake`` to build your recipe, you probably want to see if the
@@ -690,8 +761,10 @@ The following diagram shows the common development flow used with the
 
    If you specify a destination layer that is the same as the original
    source, then the old version of the recipe and associated files are
-   removed prior to adding the new version. $ devtool finish recipe
-   layer
+   removed prior to adding the new version.
+   ::
+
+      $ devtool finish recipe layer
 
    .. note::
 
@@ -770,8 +843,12 @@ name and version, just the name, or just the version as part of the
 command line.
 
 Sometimes the name or version determined from the source tree might be
-incorrect. For such a case, you must reset the recipe: $ devtool reset
--n recipename After running the ``devtool reset`` command, you need to
+incorrect. For such a case, you must reset the recipe:
+::
+
+   $ devtool reset -n recipename
+
+After running the ``devtool reset`` command, you need to
 run ``devtool add`` again and provide the name or the version.
 
 .. _sdk-dependency-detection-and-mapping:
@@ -793,8 +870,10 @@ the ``DEPENDS`` variable in the original recipe to include the new
 recipe.
 
 If you need to add runtime dependencies, you can do so by adding the
-following to your recipe: RDEPENDS_${PN} += "dependency1 dependency2
-..."
+following to your recipe:
+::
+
+   RDEPENDS_${PN} += "dependency1 dependency2 ..."
 
 .. note::
 
@@ -881,7 +960,11 @@ mind:
    :term:`EXTRA_OEMAKE` or
    :term:`PACKAGECONFIG_CONFARGS`
    within the recipe. Here is an example using ``EXTRA_OEMAKE``:
-   EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'" In the above example,
+   ::
+
+      EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'"
+
+   In the above example,
    single quotes are used around the variable settings as the values are
    likely to contain spaces because required default options are passed
    to the compiler.
@@ -903,8 +986,8 @@ mind:
 Adding Native Tools
 -------------------
 
-Often, you need to build additional tools that run on the `build
-host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__ as opposed to
+Often, you need to build additional tools that run on the :term:`Build
+Host` as opposed to
 the target. You should indicate this requirement by using one of the
 following methods when you run ``devtool add``:
 
@@ -935,8 +1018,12 @@ You can use the ``devtool add`` command two different ways to add
 Node.js modules: 1) Through ``npm`` and, 2) from a repository or local
 source.
 
-Use the following form to add Node.js modules through ``npm``: $ devtool
-add "npm://registry.npmjs.org;name=forever;version=0.15.1" The name and
+Use the following form to add Node.js modules through ``npm``:
+::
+
+   $ devtool add "npm://registry.npmjs.org;name=forever;version=0.15.1"
+
+The name and
 version parameters are mandatory. Lockdown and shrinkwrap files are
 generated and pointed to by the recipe in order to freeze the version
 that is fetched for the dependencies according to the first time. This
@@ -956,8 +1043,12 @@ these behaviors ensure the reproducibility and integrity of the build.
 
 As mentioned earlier, you can also add Node.js modules directly from a
 repository or local source tree. To add modules this way, use
-``devtool add`` in the following form: $ devtool add
-https://github.com/diversario/node-ssdp In this example, ``devtool``
+``devtool add`` in the following form:
+::
+
+   $ devtool add https://github.com/diversario/node-ssdp
+
+In this example, ``devtool``
 fetches the specified Git repository, detects the code as Node.js code,
 fetches dependencies using ``npm``, and sets
 :term:`SRC_URI` accordingly.
@@ -984,7 +1075,7 @@ build progresses as follows:
 
 For recipes in the workspace, fetching and unpacking is disabled as the
 source tree has already been prepared and is persistent. Each of these
-build steps is defined as a function (task), usually with a "do_" prefix
+build steps is defined as a function (task), usually with a "do\_" prefix
 (e.g. :ref:`ref-tasks-fetch`,
 :ref:`ref-tasks-unpack`, and so
 forth). These functions are typically shell scripts but can instead be
@@ -1069,8 +1160,8 @@ reference.
 Sharing Files Between Recipes
 -----------------------------
 
-Recipes often need to use files provided by other recipes on the `build
-host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__. For example,
+Recipes often need to use files provided by other recipes on the
+:term:`Build Host`. For example,
 an application linking to a common library needs access to the library
 itself and its associated headers. The way this access is accomplished
 within the extensible SDK is through the sysroot. One sysroot exists per
@@ -1142,11 +1233,19 @@ need to restore the original files that existed prior to running the
 ``devtool deploy-target`` command. Because the ``devtool deploy-target``
 command backs up any files it overwrites, you can use the
 ``devtool undeploy-target`` command to restore those files and remove
-any other files the recipe deployed. Consider the following example: $
-devtool undeploy-target lighttpd root@192.168.7.2 If you have deployed
+any other files the recipe deployed. Consider the following example:
+::
+
+   $ devtool undeploy-target lighttpd root@192.168.7.2
+
+If you have deployed
 multiple applications, you can remove them all using the "-a" option
-thus restoring the target device to its original state: $ devtool
-undeploy-target -a root@192.168.7.2 Information about files deployed to
+thus restoring the target device to its original state:
+::
+
+   $ devtool undeploy-target -a root@192.168.7.2
+
+Information about files deployed to
 the target as well as any backed up files are stored on the target
 itself. This storage, of course, requires some additional space on the
 target machine.
@@ -1175,14 +1274,26 @@ populated on-demand. Sometimes you must explicitly install extra items
 into the SDK. If you need these extra items, you can first search for
 the items using the ``devtool search`` command. For example, suppose you
 need to link to libGL but you are not sure which recipe provides libGL.
-You can use the following command to find out: $ devtool search libGL
-mesa A free implementation of the OpenGL API Once you know the recipe
-(i.e. ``mesa`` in this example), you can install it: $ devtool
-sdk-install mesa By default, the ``devtool sdk-install`` command assumes
+You can use the following command to find out:
+::
+
+   $ devtool search libGL mesa
+
+A free implementation of the OpenGL API Once you know the recipe
+(i.e. ``mesa`` in this example), you can install it:
+::
+
+   $ devtool sdk-install mesa
+
+By default, the ``devtool sdk-install`` command assumes
 the item is available in pre-built form from your SDK provider. If the
 item is not available and it is acceptable to build the item from
-source, you can add the "-s" option as follows: $ devtool sdk-install -s
-mesa It is important to remember that building the item from source
+source, you can add the "-s" option as follows:
+::
+
+   $ devtool sdk-install -s mesa
+
+It is important to remember that building the item from source
 takes significantly longer than installing the pre-built artifact. Also,
 if no recipe exists for the item you want to add to the SDK, you must
 instead add the item using the ``devtool add`` command.
@@ -1196,8 +1307,12 @@ If you are working with an installed extensible SDK that gets
 occasionally updated (e.g. a third-party SDK), then you will need to
 manually "pull down" the updates into the installed SDK.
 
-To update your installed SDK, use ``devtool`` as follows: $ devtool
-sdk-update The previous command assumes your SDK provider has set the
+To update your installed SDK, use ``devtool`` as follows:
+::
+
+   $ devtool sdk-update
+
+The previous command assumes your SDK provider has set the
 default update URL for you through the
 :term:`SDK_UPDATE_URL`
 variable as described in the "`Providing Updates to the Extensible SDK
diff --git a/documentation/sdk-manual/sdk-intro.rst b/documentation/sdk-manual/sdk-intro.rst
index 215889f390..2e01cf1365 100644
--- a/documentation/sdk-manual/sdk-intro.rst
+++ b/documentation/sdk-manual/sdk-intro.rst
@@ -6,8 +6,8 @@ Introduction
 
 .. _sdk-manual-intro:
 
-Introduction
-============
+eSDK Introduction
+=================
 
 Welcome to the Yocto Project Application Development and the Extensible
 Software Development Kit (eSDK) manual. This manual provides information
@@ -109,18 +109,23 @@ when considering which to build:
 :term:`SDK_EXT_TYPE` is "full"
 or
 :term:`SDK_INCLUDE_TOOLCHAIN`
-is "1", which is the default. \*\* Sysroot is managed through the use of
+is "1", which is the default.
+
+\*\* Sysroot is managed through the use of
 ``devtool``. Thus, it is less likely that you will corrupt your SDK
-sysroot when you try to add additional libraries. \**\* You can add
+sysroot when you try to add additional libraries.
+
+\*\*\* You can add
 runtime package management to the standard SDK but it is not supported
-by default. \***\* You must build and make the shared state available to
+by default.
+
+\*\*\*\* You must build and make the shared state available to
 extensible SDK users for "packages" you want to enable users to install.
 
 The Cross-Development Toolchain
 -------------------------------
 
-The `Cross-Development
-Toolchain <&YOCTO_DOCS_REF_URL;#cross-development-toolchain>`__ consists
+The :term:`Cross-Development Toolchain` consists
 of a cross-compiler, cross-linker, and cross-debugger that are used to
 develop user-space applications for targeted hardware. Additionally, for
 an extensible SDK, the toolchain also has built-in ``devtool``
@@ -190,7 +195,7 @@ You just need to follow these general steps:
    root filesystem images.
 
    If you are going to develop your application on hardware, go to the
-   ```machines`` <&YOCTO_MACHINES_DL_URL;>`__ download area and choose a
+   :yocto_dl:`machines <releases/yocto/yocto-3.1.2/machines/>` download area and choose a
    target machine area from which to download the kernel image and root
    filesystem. This download area could have several files in it that
    support development using actual hardware. For example, the area
@@ -200,7 +205,7 @@ You just need to follow these general steps:
 
    If you are going to develop your application and then run and test it
    using the QEMU emulator, go to the
-   ```machines/qemu`` <&YOCTO_QEMU_DL_URL;>`__ download area. From this
+   :yocto_dl:`machines/qemu <releases/yocto/yocto-3.1.2/machines/qemu>` download area. From this
    area, go down into the directory for your target architecture (e.g.
    ``qemux86_64`` for an Intel-based 64-bit architecture). Download the
    kernel, root filesystem, and any other files you need for your
@@ -217,8 +222,7 @@ You just need to follow these general steps:
    tools to develop your application. If you need to separately install
    and use the QEMU emulator, you can go to `QEMU Home
    Page <http://wiki.qemu.org/Main_Page>`__ to download and learn about
-   the emulator. See the "`Using the Quick EMUlator
-   (QEMU) <&YOCTO_DOCS_DEV_URL;#dev-manual-qemu>`__" chapter in the
+   the emulator. See the ":doc:`../dev-manual/dev-manual-qemu`" chapter in the
    Yocto Project Development Tasks Manual for information on using QEMU
    within the Yocto Project.
 
diff --git a/documentation/sdk-manual/sdk-using.rst b/documentation/sdk-manual/sdk-using.rst
index b240f9174a..cd57f07eeb 100644
--- a/documentation/sdk-manual/sdk-using.rst
+++ b/documentation/sdk-manual/sdk-using.rst
@@ -42,13 +42,12 @@ Structure <#sdk-installed-standard-sdk-directory-structure>`__" section.
 Installing the SDK
 ==================
 
-The first thing you need to do is install the SDK on your `Build
-Host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__ by running the
-``*.sh`` installation script.
+The first thing you need to do is install the SDK on your :term:`Build
+Host` by running the ``*.sh`` installation script.
 
 You can download a tarball installer, which includes the pre-built
 toolchain, the ``runqemu`` script, and support files from the
-appropriate `toolchain <&YOCTO_TOOLCHAIN_DL_URL;>`__ directory within
+appropriate :yocto_dl:`toolchain <releases/yocto/yocto-3.1.2/toolchain/>` directory within
 the Index of Releases. Toolchains are available for several 32-bit and
 64-bit architectures with the ``x86_64`` directories, respectively. The
 toolchains the Yocto Project provides are based off the
@@ -58,17 +57,33 @@ libraries appropriate for developing against that image.
 The names of the tarball installer scripts are such that a string
 representing the host system appears first in the filename and then is
 immediately followed by a string representing the target architecture.
-poky-glibc-host_system-image_type-arch-toolchain-release_version.sh
-Where: host_system is a string representing your development system:
-i686 or x86_64. image_type is the image for which the SDK was built:
-core-image-minimal or core-image-sato. arch is a string representing the
-tuned target architecture: aarch64, armv5e, core2-64, i586, mips32r2,
-mips64, ppc7400, or cortexa8hf-neon. release_version is a string
-representing the release number of the Yocto Project: DISTRO,
-DISTRO+snapshot For example, the following SDK installer is for a 64-bit
+::
+
+   poky-glibc-host_system-image_type-arch-toolchain-release_version.sh
+
+   Where:
+       host_system is a string representing your development system:
+
+                  i686 or x86_64.
+
+       image_type is the image for which the SDK was built:
+
+                  core-image-minimal or core-image-sato.
+
+       arch is a string representing the tuned target architecture:
+
+                  aarch64, armv5e, core2-64, i586, mips32r2, mips64, ppc7400, or cortexa8hf-neon.
+
+       release_version is a string representing the release number of the Yocto Project:
+
+                  3.1.2, 3.1.2+snapshot
+
+For example, the following SDK installer is for a 64-bit
 development host system and a i586-tuned target architecture based off
 the SDK for ``core-image-sato`` and using the current DISTRO snapshot:
-poky-glibc-x86_64-core-image-sato-i586-toolchain-DISTRO.sh
+::
+
+   poky-glibc-x86_64-core-image-sato-i586-toolchain-DISTRO.sh
 
 .. note::
 
@@ -96,16 +111,18 @@ architecture. The example assumes the SDK installer is located in
    that case, set up the proper permissions in the directory and run the
    installer again.
 
-$ ./Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-DISTRO.sh
-Poky (Yocto Project Reference Distro) SDK installer version DISTRO
-=============================================================== Enter
-target directory for SDK (default: /opt/poky/DISTRO): You are about to
-install the SDK to "/opt/poky/DISTRO". Proceed [Y/n]? Y Extracting
-SDK........................................
-..............................done Setting it up...done SDK has been
-successfully set up and is ready to be used. Each time you wish to use
-the SDK in a new shell session, you need to source the environment setup
-script e.g. $ . /opt/poky/DISTRO/environment-setup-i586-poky-linux
+::
+
+   $ ./Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-3.1.2.sh
+   Poky (Yocto Project Reference Distro) SDK installer version 3.1.2
+   ===============================================================
+   Enter target directory for SDK (default: /opt/poky/3.1.2):
+   You are about to install the SDK to "/opt/poky/3.1.2". Proceed [Y/n]? Y
+   Extracting SDK........................................ ..............................done
+   Setting it up...done
+   SDK has been successfully set up and is ready to be used.
+   Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
+    $ . /opt/poky/3.1.2/environment-setup-i586-poky-linux
 
 Again, reference the "`Installed Standard SDK Directory
 Structure <#sdk-installed-standard-sdk-directory-structure>`__" section
@@ -120,7 +137,7 @@ Running the SDK Environment Setup Script
 Once you have the SDK installed, you must run the SDK environment setup
 script before you can actually use the SDK. This setup script resides in
 the directory you chose when you installed the SDK, which is either the
-default ``/opt/poky/DISTRO`` directory or the directory you chose during
+default ``/opt/poky/3.1.2`` directory or the directory you chose during
 installation.
 
 Before running the script, be sure it is the one that matches the
@@ -129,8 +146,12 @@ begin with the string "``environment-setup``" and include as part of
 their name the tuned target architecture. As an example, the following
 commands set the working directory to where the SDK was installed and
 then source the environment setup script. In this example, the setup
-script is for an IA-based target machine using i586 tuning: $ source
-/opt/poky/DISTRO/environment-setup-i586-poky-linux When you run the
+script is for an IA-based target machine using i586 tuning:
+::
+
+   $ source /opt/poky/3.1.2/environment-setup-i586-poky-linux
+
+When you run the
 setup script, the same environment variables are defined as are when you
 run the setup script for an extensible SDK. See the "`Running the
 Extensible SDK Environment Setup
diff --git a/documentation/sdk-manual/sdk-working-projects.rst b/documentation/sdk-manual/sdk-working-projects.rst
index df216175c9..2c20a1ec57 100644
--- a/documentation/sdk-manual/sdk-working-projects.rst
+++ b/documentation/sdk-manual/sdk-working-projects.rst
@@ -10,8 +10,7 @@ projects.
 Autotools-Based Projects
 ========================
 
-Once you have a suitable `cross-development
-toolchain <&YOCTO_DOCS_REF_URL;#cross-development-toolchain>`__
+Once you have a suitable :ref:`sdk-manual/sdk-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`.
@@ -33,24 +32,51 @@ project:
 
 1. *Create a Working Directory and Populate It:* Create a clean
    directory for your project and then make that directory your working
-   location. $ mkdir $HOME/helloworld $ cd $HOME/helloworld After
-   setting up the directory, populate it with files needed for the flow.
+   location.
+   ::
+
+      $ mkdir $HOME/helloworld
+      $ cd $HOME/helloworld
+
+   After setting up the directory, populate it with files needed for the flow.
    You need a project source file, a file to help with configuration,
    and a file to help create the Makefile, and a README file:
    ``hello.c``, ``configure.ac``, ``Makefile.am``, and ``README``,
    respectively.
 
    Use the following command to create an empty README file, which is
-   required by GNU Coding Standards: $ touch README Create the remaining
+   required by GNU Coding Standards:
+   ::
+
+      $ touch README
+
+   Create the remaining
    three files as follows:
 
-   -  *``hello.c``:* #include <stdio.h> main() { printf("Hello
-      World!\n"); }
+   -  ``hello.c``:
+      ::
+
+         #include <stdio.h>
 
-   -  *``configure.ac``:* AC_INIT(hello,0.1) AM_INIT_AUTOMAKE([foreign])
-      AC_PROG_CC AC_CONFIG_FILES(Makefile) AC_OUTPUT
+         main()
+             {
+                 printf("Hello World!\n");
+             }
 
-   -  *``Makefile.am``:* bin_PROGRAMS = hello hello_SOURCES = hello.c
+   -  ``configure.ac``:
+      ::
+
+         AC_INIT(hello,0.1)
+         AM_INIT_AUTOMAKE([foreign])
+         AC_PROG_CC
+         AC_CONFIG_FILES(Makefile)
+         AC_OUTPUT
+
+   -  ``Makefile.am``:
+      ::
+
+         bin_PROGRAMS = hello
+         hello_SOURCES = hello.c
 
 2. *Source the Cross-Toolchain Environment Setup File:* As described
    earlier in the manual, installing the cross-toolchain creates a
@@ -60,12 +86,19 @@ project:
    the string "environment-setup" and contains the machine architecture,
    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: $ source
-   /opt/poky/DISTRO/environment-setup-i586-poky-linux
+   that uses the 32-bit Intel x86 Architecture and the 3.1.2 Yocto
+   Project release:
+   ::
+
+      $ source /opt/poky/3.1.2/environment-setup-i586-poky-linux
 
-3. *Create the ``configure`` Script:* Use the ``autoreconf`` command to
-   generate the ``configure`` script. $ autoreconf The ``autoreconf``
+3. *Create the configure Script:* Use the ``autoreconf`` command to
+   generate the ``configure`` script.
+   ::
+
+      $ autoreconf
+
+   The ``autoreconf``
    tool takes care of running the other Autotools such as ``aclocal``,
    ``autoconf``, and ``automake``.
 
@@ -83,7 +116,12 @@ project:
    the cross-compiler. The
    :term:`CONFIGURE_FLAGS`
    environment variable provides the minimal arguments for GNU
-   configure: $ ./configure ${CONFIGURE_FLAGS} For an Autotools-based
+   configure:
+   ::
+
+      $ ./configure ${CONFIGURE_FLAGS}
+
+   For an Autotools-based
    project, you can use the cross-toolchain by just passing the
    appropriate host option to ``configure.sh``. The host option you use
    is derived from the name of the environment setup script found in the
@@ -92,12 +130,17 @@ 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: $ ./configure
-   --host=armv5te-poky-linux-gnueabi --with-libtool-sysroot=sysroot_dir
+   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 $ make
-   install DESTDIR=./tmp
+   install the project into the destination directory:
+   ::
+
+      $ make
+      $ make install DESTDIR=./tmp
 
    .. note::
 
@@ -110,14 +153,19 @@ project:
    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. $ file
-   ./tmp/usr/local/bin/hello
+   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
    it on your target hardware. If your target hardware happens to be
-   your build host, you could run the project as follows: $
-   ./tmp/usr/local/bin/hello As expected, the project displays the
-   "Hello World!" message.
+   your build host, you could run the project as follows:
+   ::
+
+      $ ./tmp/usr/local/bin/hello
+
+   As expected, the project displays the "Hello World!" message.
 
 Makefile-Based Projects
 =======================
@@ -137,7 +185,7 @@ variables and Makefile variables during development.
 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.
@@ -163,8 +211,8 @@ regarding variable behavior:
    , the variables from the SDK setup script take precedence:
    ::
 
-           $ make -e target
-                      
+      $ make -e target
+
 
 The remainder of this section presents a simple Makefile example that
 demonstrates these variable behaviors.
@@ -172,21 +220,36 @@ 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`). $ echo ${CC} $ Running the
+:term:`CC`).
+::
+
+   $ echo ${CC}
+
+   $
+
+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
+architecture for a ``core-image-sato`` image using the current 3.1.2
 Yocto Project release and then echoing that variable shows the value
-established through the script: $ source
-/opt/poky/DISTRO/environment-setup-i586-poky-linux $ echo ${CC}
-i586-poky-linux-gcc -m32 -march=i586
---sysroot=/opt/poky/2.5/sysroots/i586-poky-linux
+established through the script:
+::
+
+   $ source /opt/poky/3.1.2/environment-setup-i586-poky-linux
+   $ echo ${CC}
+   i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/3.1.2/sysroots/i586-poky-linux
 
 To illustrate variable use, work through this simple "Hello World!"
 example:
 
 1. *Create a Working Directory and Populate It:* Create a clean
    directory for your project and then make that directory your working
-   location. $ mkdir $HOME/helloworld $ cd $HOME/helloworld After
+   location.
+   ::
+
+      $ mkdir $HOME/helloworld
+      $ cd $HOME/helloworld
+
+   After
    setting up the directory, populate it with files needed for the flow.
    You need a ``main.c`` file from which you call your function, a
    ``module.h`` file to contain headers, and a ``module.c`` that defines
@@ -194,13 +257,32 @@ example:
 
    Create the three files as follows:
 
-   -  *``main.c``:* #include "module.h" void sample_func(); int main() {
-      sample_func(); return 0; }
+   -  ``main.c``:
+      ::
+
+         #include "module.h"
+         void sample_func();
+         int main()
+         {
+             sample_func();
+             return 0;
+         }
+
+   -  ``module.h``:
+      ::
 
-   -  *``module.h``:* #include <stdio.h> void sample_func();
+         #include <stdio.h>
+         void sample_func();
 
-   -  *``module.c``:* #include "module.h" void sample_func() {
-      printf("Hello World!"); printf("\n"); }
+   -  ``module.c``:
+      ::
+
+         #include "module.h"
+         void sample_func()
+         {
+             printf("Hello World!");
+             printf("\n");
+         }
 
 2. *Source the Cross-Toolchain Environment Setup File:* As described
    earlier in the manual, installing the cross-toolchain creates a
@@ -211,38 +293,62 @@ 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: $ source
-   /opt/poky/DISTRO/environment-setup-i586-poky-linux
+   Project release:
+   ::
+
+      $ source /opt/poky/DISTRO/environment-setup-i586-poky-linux
 
-3. *Create the ``Makefile``:* For this example, the Makefile contains
+3. *Create the Makefile:* For this example, the Makefile contains
    two lines that can be used to set the ``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: # 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
-   main.o: main.c module.h ${CC} -I . -c main.c module.o: module.c
-   module.h ${CC} -I . -c module.c clean: rm -rf \*.o rm target_bin
+   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
+      main.o: main.c module.h
+        ${CC} -I . -c main.c
+      module.o: module.c
+        module.h ${CC} -I . -c module.c
+      clean:
+        rm -rf *.o
+        rm target_bin
 
 4. *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: $ make i586-poky-linux-gcc -m32 -march=i586
-   --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
-   i586-poky-linux-gcc -m32 -march=i586
-   --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
-   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
+   file was run:
+   ::
+
+      $ make
+      i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
+      i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
+      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``
    variable defined in the setup script.
 
    You can override the ``CC`` environment variable with the same
    variable as set from the Makefile by uncommenting the line in the
-   Makefile and running ``make`` again. $ make clean rm -rf \*.o rm
-   target_bin # # Edit the Makefile by uncommenting the line that sets
-   CC to "gcc" # $ make gcc -I . -c main.c gcc -I . -c module.c gcc
-   main.o module.o -o target_bin As shown in the previous example, the
+   Makefile and running ``make`` again.
+   ::
+
+      $ make clean
+      rm -rf *.o
+      rm target_bin
+      #
+      # Edit the Makefile by uncommenting the line that sets CC to "gcc"
+      #
+      $ make
+      gcc -I . -c main.c
+      gcc -I . -c module.c
+      gcc main.o module.o -o target_bin
+
+   As shown in the previous example, the
    cross-toolchain compiler is not used. Rather, the default compiler is
    used.
 
@@ -250,36 +356,62 @@ 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": $ make clean rm -rf
-   \*.o rm target_bin # # Edit the Makefile to comment out the line
-   setting CC to "gcc" # $ make i586-poky-linux-gcc -m32 -march=i586
-   --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
-   i586-poky-linux-gcc -m32 -march=i586
-   --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
-   i586-poky-linux-gcc -m32 -march=i586
-   --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o
-   target_bin $ make clean rm -rf \*.o rm target_bin $ make CC="gcc" gcc
-   -I . -c main.c gcc -I . -c module.c gcc main.o module.o -o target_bin
+   command-line argument to set ``CC`` to "gcc":
+   ::
+
+      $ make clean
+      rm -rf *.o
+      rm target_bin
+      #
+      # Edit the Makefile to comment out the line setting CC to "gcc"
+      #
+      $ make
+      i586-poky-linux-gcc  -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
+      i586-poky-linux-gcc  -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
+      i586-poky-linux-gcc  -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin
+      $ make clean
+      rm -rf *.o
+      rm target_bin
+      $ make CC="gcc"
+      gcc -I . -c main.c
+      gcc -I . -c module.c
+      gcc main.o module.o -o target_bin
+
    In the previous case, the command-line argument overrides the SDK
    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: $ make clean
-   rm -rf \*.o rm target_bin # # Edit the Makefile to use "gcc" # $ make
-   gcc -I . -c main.c gcc -I . -c module.c gcc main.o module.o -o
-   target_bin $ make clean rm -rf \*.o rm target_bin $ make -e
-   i586-poky-linux-gcc -m32 -march=i586
-   --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
-   i586-poky-linux-gcc -m32 -march=i586
-   --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
-   i586-poky-linux-gcc -m32 -march=i586
-   --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o
-   target_bin In the previous case, the "-e" option forces ``make`` to
+   then use the "-e" option on the ``make`` command line:
+   ::
+
+      $ make clean
+      rm -rf *.o
+      rm target_bin
+      #
+      # Edit the Makefile to use "gcc"
+      #
+      $ make
+      gcc -I . -c main.c
+      gcc -I . -c module.c
+      gcc main.o module.o -o target_bin
+      $ make clean
+      rm -rf *.o
+      rm target_bin
+      $ make -e
+      i586-poky-linux-gcc  -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c main.c
+      i586-poky-linux-gcc  -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux -I . -c module.c
+      i586-poky-linux-gcc  -m32 -march=i586 --sysroot=/opt/poky/2.5/sysroots/i586-poky-linux main.o module.o -o target_bin
+
+   In the previous case, the "-e" option forces ``make`` to
    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: $ ./target_bin Hello World!
+   use the following command:
+   ::
+
+      $ ./target_bin
+      Hello World!
 
    .. note::