1 files changed, 64 insertions, 46 deletions

diff --git a/documentation/ref-manual/ref-structure.rst b/documentation/ref-manual/ref-structure.rst
index 1efb81414f..48a443331b 100644
--- a/documentation/ref-manual/ref-structure.rst
+++ b/documentation/ref-manual/ref-structure.rst
@@ -11,8 +11,8 @@ describes the Source Directory and gives information about those files
 and directories.
 
 For information on how to establish a local Source Directory on your
-development system, see the "`Locating Yocto Project Source
-Files <&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files>`__"
+development system, see the
+":ref:`dev-manual/dev-manual-start:locating yocto project source files`"
 section in the Yocto Project Development Tasks Manual.
 
 .. note::
@@ -42,7 +42,7 @@ itself; consequently, most users do not need to worry about BitBake.
 
 When you run the ``bitbake`` command, the main BitBake executable (which
 resides in the ``bitbake/bin/`` directory) starts. Sourcing the
-environment setup script (i.e. ````` <#structure-core-script>`__) places
+environment setup script (i.e. :ref:`structure-core-script`) places
 the ``scripts/`` and ``bitbake/bin/`` directories (in that order) into
 the shell's ``PATH`` environment variable.
 
@@ -59,14 +59,14 @@ generated by the OpenEmbedded build system in its standard configuration
 where the source tree is combined with the output. The :term:`Build Directory`
 is created initially when you ``source``
 the OpenEmbedded build environment setup script (i.e.
-````` <#structure-core-script>`__).
+:ref:`structure-core-script`).
 
 It is also possible to place output and configuration files in a
 directory separate from the :term:`Source Directory` by
 providing a directory name when you ``source`` the setup script. For
 information on separating output from your local Source Directory files
 (commonly described as an "out of tree" build), see the
-"````` <#structure-core-script>`__" section.
+":ref:`structure-core-script`" section.
 
 .. _handbook:
 
@@ -103,9 +103,8 @@ metadata to define the Poky reference distribution.
 -------------------
 
 This directory contains the Yocto Project reference hardware Board
-Support Packages (BSPs). For more information on BSPs, see the `Yocto
-Project Board Support Package (BSP) Developer's
-Guide <&YOCTO_DOCS_BSP_URL;>`__.
+Support Packages (BSPs). For more information on BSPs, see the
+:doc:`../bsp-guide/bsp-guide`.
 
 .. _structure-meta-selftest:
 
@@ -131,7 +130,7 @@ This directory contains template recipes for BSP and kernel development.
 
 This directory contains various integration scripts that implement extra
 functionality in the Yocto Project environment (e.g. QEMU scripts). The
-````` <#structure-core-script>`__ script prepends this directory to the
+:ref:`structure-core-script` script prepends this directory to the
 shell's ``PATH`` environment variable.
 
 The ``scripts`` directory has useful scripts that assist in contributing
@@ -154,18 +153,30 @@ When you run this script, your Yocto Project environment is set up, a
 :term:`Build Directory` is created, your working
 directory becomes the Build Directory, and you are presented with some
 simple suggestions as to what to do next, including a list of some
-possible targets to build. Here is an example: $ source
-oe-init-build-env ### Shell environment set up for builds. ### You can
-now run 'bitbake <target>' Common targets are: core-image-minimal
-core-image-sato meta-toolchain meta-ide-support You can also run
-generated qemu images with a command like 'runqemu qemux86-64' The
-default output of the ``oe-init-build-env`` script is from the
+possible targets to build. Here is an example:
+::
+
+   $ source oe-init-build-env
+
+   ### Shell environment set up for builds. ###
+
+   You can now run 'bitbake <target>'
+
+   Common targets are:
+       core-image-minimal
+       core-image-sato
+       meta-toolchain
+       meta-ide-support
+
+   You can also run generated qemu images with a command like 'runqemu qemux86-64'
+
+The default output of the ``oe-init-build-env`` script is from the
 ``conf-notes.txt`` file, which is found in the ``meta-poky`` directory
 within the :term:`Source Directory`. If you design a
 custom distribution, you can include your own version of this
 configuration file to mention the targets defined by your distribution.
-See the "`Creating a Custom Template Configuration
-Directory <&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory>`__"
+See the
+":ref:`dev-manual/dev-manual-common-tasks:creating a custom template configuration directory`"
 section in the Yocto Project Development Tasks Manual for more
 information.
 
@@ -175,11 +186,14 @@ you provide a Build Directory argument when you ``source`` the script,
 you direct the OpenEmbedded build system to create a Build Directory of
 your choice. For example, the following command creates a Build
 Directory named ``mybuilds/`` that is outside of the :term:`Source Directory`:
-$ source OE_INIT_FILE ~/mybuilds The
-OpenEmbedded build system uses the template configuration files, which
+::
+
+   $ source OE_INIT_FILE ~/mybuilds
+
+The OpenEmbedded build system uses the template configuration files, which
 are found by default in the ``meta-poky/conf/`` directory in the Source
-Directory. See the "`Creating a Custom Template Configuration
-Directory <&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory>`__"
+Directory. See the
+":ref:`dev-manual/dev-manual-common-tasks:creating a custom template configuration directory`"
 section in the Yocto Project Development Tasks Manual for more
 information.
 
@@ -207,7 +221,7 @@ The Build Directory - ``build/``
 
 The OpenEmbedded build system creates the :term:`Build Directory`
 when you run the build environment setup
-script ````` <#structure-core-script>`__. If you do not give the Build
+script :ref:`structure-core-script`. If you do not give the Build
 Directory a specific name when you run the setup script, the name
 defaults to ``build/``.
 
@@ -223,8 +237,7 @@ The OpenEmbedded build system creates this directory when you enable
 build history via the ``buildhistory`` class file. The directory
 organizes build information into image, packages, and SDK
 subdirectories. For information on the build history feature, see the
-"`Maintaining Build Output
-Quality <&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality>`__"
+":ref:`dev-manual/dev-manual-common-tasks:maintaining build output quality`"
 section in the Yocto Project Development Tasks Manual.
 
 .. _structure-build-conf-local.conf:
@@ -248,7 +261,7 @@ which you want to access downloaded files (``DL_DIR``).
 If ``local.conf`` is not present when you start the build, the
 OpenEmbedded build system creates it from ``local.conf.sample`` when you
 ``source`` the top-level build environment setup script
-````` <#structure-core-script>`__.
+:ref:`structure-core-script`.
 
 The source ``local.conf.sample`` file used depends on the
 ``$TEMPLATECONF`` script variable, which defaults to ``meta-poky/conf/``
@@ -258,7 +271,11 @@ environment. Because the script variable points to the source of the
 ``local.conf.sample`` file, this implies that you can configure your
 build environment from any layer by setting the variable in the
 top-level build environment setup script as follows:
-TEMPLATECONF=your_layer/conf Once the build process gets the sample
+::
+
+   TEMPLATECONF=your_layer/conf
+
+Once the build process gets the sample
 file, it uses ``sed`` to substitute final
 ``${``\ :term:`OEROOT`\ ``}`` values for all
 ``##OEROOT##`` values.
@@ -283,7 +300,7 @@ file, it uses ``sed`` to substitute final
 ----------------------------
 
 This configuration file defines
-`layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__,
+:ref:`layers <dev-manual/dev-manual-common-tasks:understanding and creating layers>`,
 which are directory trees, traversed (or walked) by BitBake. The
 ``bblayers.conf`` file uses the :term:`BBLAYERS`
 variable to list the layers BitBake tries to find.
@@ -291,7 +308,7 @@ variable to list the layers BitBake tries to find.
 If ``bblayers.conf`` is not present when you start the build, the
 OpenEmbedded build system creates it from ``bblayers.conf.sample`` when
 you ``source`` the top-level build environment setup script (i.e.
-````` <#structure-core-script>`__).
+:ref:`structure-core-script`).
 
 As with the ``local.conf`` file, the source ``bblayers.conf.sample``
 file used depends on the ``$TEMPLATECONF`` script variable, which
@@ -301,10 +318,12 @@ building from the OpenEmbedded-Core environment. Because the script
 variable points to the source of the ``bblayers.conf.sample`` file, this
 implies that you can base your build from any layer by setting the
 variable in the top-level build environment setup script as follows:
-TEMPLATECONF=your_layer/conf Once the build process gets the sample
-file, it uses ``sed`` to substitute final
-``${``\ :term:`OEROOT`\ ``}`` values for all
-``##OEROOT##`` values.
+::
+
+   TEMPLATECONF=your_layer/conf
+
+Once the build process gets the sample file, it uses ``sed`` to substitute final
+``${``\ :term:`OEROOT`\ ``}`` values for all ``##OEROOT##`` values.
 
 .. note::
 
@@ -395,9 +414,8 @@ This directory contains any "end result" output from the OpenEmbedded
 build process. The :term:`DEPLOY_DIR` variable points
 to this directory. For more detail on the contents of the ``deploy``
 directory, see the
-"`Images <&YOCTO_DOCS_OM_URL;#images-dev-environment>`__" and
-"`Application Development
-SDK <&YOCTO_DOCS_OM_URL;#sdk-dev-environment>`__" sections in the Yocto
+":ref:`images-dev-environment`" and
+":ref:`sdk-dev-environment`" sections in the Yocto
 Project Overview and Concepts Manual.
 
 .. _structure-build-tmp-deploy-deb:
@@ -434,9 +452,8 @@ This directory receives package licensing information. For example, the
 directory contains sub-directories for ``bash``, ``busybox``, and
 ``glibc`` (among others) that in turn contain appropriate ``COPYING``
 license files with other licensing information. For information on
-licensing, see the "`Maintaining Open Source License Compliance During
-Your Product's
-Lifecycle <&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle>`__"
+licensing, see the
+":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`"
 section in the Yocto Project Development Tasks Manual.
 
 .. _structure-build-tmp-deploy-images:
@@ -461,8 +478,11 @@ image again.
 If you do accidentally delete files here, you will need to force them to
 be re-created. In order to do that, you will need to know the target
 that produced them. For example, these commands rebuild and re-create
-the kernel files: $ bitbake -c clean virtual/kernel $ bitbake
-virtual/kernel
+the kernel files:
+::
+
+   $ bitbake -c clean virtual/kernel
+   $ bitbake virtual/kernel
 
 .. _structure-build-tmp-deploy-sdk:
 
@@ -472,8 +492,7 @@ virtual/kernel
 The OpenEmbedded build system creates this directory to hold toolchain
 installer scripts which, when executed, install the sysroot that matches
 your target hardware. You can find out more about these installers in
-the "`Building an SDK
-Installer <&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer>`__"
+the ":ref:`sdk-manual/sdk-appendix-obtain:building an sdk installer`"
 section in the Yocto Project Application Development and the Extensible
 Software Development Kit (eSDK) manual.
 
@@ -540,8 +559,8 @@ the files in the directory are empty of data, BitBake uses the filenames
 and timestamps for tracking purposes.
 
 For information on how BitBake uses stamp files to determine if a task
-should be rerun, see the "`Stamp Files and the Rerunning of
-Tasks <&YOCTO_DOCS_OM_URL;#stamp-files-and-the-rerunning-of-tasks>`__"
+should be rerun, see the
+":ref:`overview-manual/overview-manual-concepts:stamp files and the rerunning of tasks`"
 section in the Yocto Project Overview and Concepts Manual.
 
 .. _structure-build-tmp-log:
@@ -573,8 +592,7 @@ built within the Yocto Project. For this package, a work directory of
 ``tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+<.....>``, referred
 to as the ``WORKDIR``, is created. Within this directory, the source is
 unpacked to ``linux-qemux86-standard-build`` and then patched by Quilt.
-(See the "`Using Quilt in Your
-Workflow <&YOCTO_DOCS_DEV_URL;#using-a-quilt-workflow>`__" section in
+(See the ":ref:`using-a-quilt-workflow`" section in
 the Yocto Project Development Tasks Manual for more information.) Within
 the ``linux-qemux86-standard-build`` directory, standard Quilt
 directories ``linux-3.0/patches`` and ``linux-3.0/.pc`` are created, and