docs: ref-manual: indentation, links and highlights fixes

Reviewed-by: Nicolas Dechesne <nicolas.dechesne@linaro.org> (From yocto-docs rev: 27f6527882d22f20641882018ca5b8a7a30092ae) Signed-off-by: Quentin Schulz <foss@0leil.net> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org> (cherry picked from commit f5688a74cd9d100dee270edb9a33c02015cfabda) Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
2026-06-02 13:29:49 +00:00 · 2020-10-05 20:37:23 +02:00
parent 017be0a956
commit e8feec005b
26 changed files with 509 additions and 837 deletions
@@ -4,7 +4,7 @@
 FAQ
 ***
-**Q:** How does Poky differ from `OpenEmbedded <http://www.openembedded.org/>`__?
+**Q:** How does Poky differ from :oe_home:`OpenEmbedded <>`?
 **A:** The term ``Poky`` refers to the specific reference build
 system that the Yocto Project provides. Poky is based on
@@ -21,9 +21,9 @@ Can I still use the Yocto Project?
 **A:** You can get the required tools on your host development system a
 couple different ways (i.e. building a tarball or downloading a
-tarball). See the "`Required Git, tar, Python and gcc
+tarball). See the
-Versions <#required-git-tar-python-and-gcc-versions>`__" section for
+":ref:`ref-manual/ref-system-requirements:required git, tar, python and gcc versions`"
-steps on how to update your build tools.
+section for steps on how to update your build tools.
 **Q:** How can you claim Poky / OpenEmbedded-Core is stable?
@@ -370,7 +370,7 @@ redirect requests through proxy servers.
 **A:** Yes - you can easily do this. When you use BitBake to build an
 image, all the build output goes into the directory created when you run
 the build environment setup script (i.e.
-````` <#structure-core-script>`__). By default, this :term:`Build Directory`
+:ref:`structure-core-script`). By default, this :term:`Build Directory`
 is named ``build`` but can be named
 anything you want.
@@ -414,7 +414,14 @@ that program is never installed directly to the build machine's root
 file system. Consequently, the build system uses paths within the Build
 Directory for ``DESTDIR``, ``bindir`` and related variables. To better
 understand this, consider the following two paths where the first is
-relatively normal and the second is not: ::
+relatively normal and the second is not:
 .. note::
   Due to these lengthy examples, the paths are artificially broken
   across lines for readability.
 ::
   /home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/
      1.2.8-r0/sysroot-destdir/usr/bin
@@ -423,11 +430,6 @@ relatively normal and the second is not: ::
      zlib-native/1.2.8-r0/sysroot-destdir/home/maxtothemax/poky-bootchart2/
      build/tmp/sysroots/x86_64-linux/usr/bin
 .. note::
   Due to these lengthy examples, the paths are artificially broken
   across lines for readability.
 Even if the paths look unusual,
 they both are correct - the first for a target and the second for a
 native recipe. These paths are a consequence of the ``DESTDIR``
@@ -121,11 +121,11 @@ further details.
 IMAGE_FEATURES
 ~~~~~~~~~~~~~~
-Image recipes that previously included "apps-console-core" in
+Image recipes that previously included ``apps-console-core`` in
-:term:`IMAGE_FEATURES` should now include "splash"
+:term:`IMAGE_FEATURES` should now include ``splash``
 instead to enable the boot-up splash screen. Retaining
-"apps-console-core" will still include the splash screen but generates a
+``apps-console-core`` will still include the splash screen but generates a
-warning. The "apps-x11-core" and "apps-x11-games" ``IMAGE_FEATURES``
+warning. The ``apps-x11-core`` and ``apps-x11-games`` ``IMAGE_FEATURES``
 features have been removed.
 .. _migration-1.3-removed-recipes:
@@ -173,7 +173,7 @@ the OpenEmbedded community layers such as ``meta-oe`` and
 ``meta-gnome``. For the remainder, you can now find them in the
 ``meta-extras`` repository, which is in the
 :yocto_git:`Source Repositories <>` at
-http://git.yoctoproject.org/cgit/cgit.cgi/meta-extras/.
+:yocto_git:`/cgit/cgit.cgi/meta-extras/`.
 .. _1.3-linux-kernel-naming:
@@ -61,7 +61,7 @@ Differences include the following:
   the :term:`MACHINEOVERRIDES` or
   :term:`DISTROOVERRIDES` variables, as
   appropriate. For more related changes, see the
-   "`Variables <#migration-1.4-variables>`__" section.
+   ":ref:`ref-manual/migration-1.4:variables`" section.
 .. _migration-1.4-proxies-and-fetching-source:
@@ -124,8 +124,8 @@ The following variables have changed:
   :term:`SRC_URI`. If you have a recipe that relied upon
   these directories, which would be unusual, then you will need to add
   the appropriate paths within the recipe or, alternatively, rearrange
-   the files. The most common locations are still covered by ``${BP}``,
+   the files. The most common locations are still covered by ``${``\ :term:`BP`\ ``}``,
-   ``${BPN}``, and "files", which all remain in the default value of
+   ``${``\ :term:`BPN`\ ``}``, and "files", which all remain in the default value of
   :term:`FILESPATH`.
 .. _migration-target-package-management-with-rpm:
@@ -25,8 +25,8 @@ If the Linux distribution you are using on your build host does not
 provide packages for these, you can install and use the Buildtools
 tarball, which provides an SDK-like environment containing them.
-For more information on this requirement, see the "`Required Git, tar,
+For more information on this requirement, see the
-Python and gcc Versions <#required-git-tar-python-and-gcc-versions>`__"
+":ref:`ref-manual/ref-system-requirements:required git, tar, python and gcc versions`"
 section.
 .. _migration-1.5-atom-pc-bsp:
@@ -41,9 +41,8 @@ all x86 hardware, but it will run on a wider range of systems than the
 .. note::
-   Additionally, a
+   Additionally, a ``genericx86-64`` BSP has been added for 64-bit Atom
-   genericx86-64
+   systems.
   BSP has been added for 64-bit Atom systems.
 .. _migration-1.5-bitbake:
@@ -96,7 +95,7 @@ The following changes have been made to the package QA checks:
   this file within :ref:`ref-tasks-install` if "make
   install" is installing it.
-  If you are using the buildhistory class, the check for the package
+-  If you are using the ``buildhistory`` class, the check for the package
   version going backwards is now controlled using a standard QA check.
   Thus, if you have customized your ``ERROR_QA`` or ``WARN_QA`` values
   and still wish to have this check performed, you should add
@@ -299,7 +298,7 @@ Removed and Renamed Recipes
 -  ``libtool-nativesdk`` has been renamed to ``nativesdk-libtool``.
 -  ``tinylogin`` has been removed. It has been replaced by a suid
-   portion of Busybox. See the "`BusyBox <#migration-1.5-busybox>`__"
+   portion of Busybox. See the "`BusyBox <#busybox>`__"
   section for more information.
 -  ``external-python-tarball`` has been renamed to
@@ -345,8 +344,7 @@ Following is a list of short entries describing other changes:
 -  ``libpam``: Deny all services for the ``OTHER`` entries.
 -  ``image.bbclass``: Move ``runtime_mapping_rename`` to avoid conflict
-   with ``multilib``. See
+   with ``multilib``. See :yocto_bugs:`YOCTO #4993 </show_bug.cgi?id=4993>`
   `YOCTO #4993 <https://bugzilla.yoctoproject.org/show_bug.cgi?id=4993>`_
   in Bugzilla for more information.
 -  ``linux-dtb``: Use kernel build system to generate the ``dtb`` files.
@@ -53,9 +53,12 @@ Matching Branch Requirement for Git Fetching
 When fetching source from a Git repository using
 :term:`SRC_URI`, BitBake will now validate the
 :term:`SRCREV` value against the branch. You can specify
-the branch using the following form: SRC_URI =
+the branch using the following form:
-"git://server.name/repository;branch=branchname" If you do not specify a
+::
-branch, BitBake looks in the default "master" branch.
+
      SRC_URI = "git://server.name/repository;branch=branchname"
 If you do not specify a branch, BitBake looks in the default "master" branch.
 Alternatively, if you need to bypass this check (e.g. if you are
 fetching a revision corresponding to a tag that is not on any branch),
@@ -123,8 +126,7 @@ Changes to Variables
 --------------------
 The following variables have changed. For information on the
-OpenEmbedded build system variables, see the "`Variables
+OpenEmbedded build system variables, see the ":doc:`ref-variables`" Chapter.
 Glossary <#ref-variables-glos>`__" Chapter.
 .. _migration-1.6-variable-changes-TMPDIR:
@@ -254,11 +256,8 @@ default. The following additional lines are needed in your
 .. note::
-   The default
+   The default ``local.conf`` contains these statements. Consequently, if you
-   local.conf
+   are building a headless system and using a default ``local.conf``
   contains these statements. Consequently, if you are building a
   headless system and using a default
   local.conf
   file, you will need comment these two lines out.
 .. _migration-1.6-core-image-basic:
@@ -412,6 +411,6 @@ The previous reference BSPs for the ``beagleboard`` and
 ``routerstationpro`` machines are still available in a new
 ``meta-yocto-bsp-old`` layer in the
 :yocto_git:`Source Repositories <>` at
-http://git.yoctoproject.org/cgit/cgit.cgi/meta-yocto-bsp-old/.
+:yocto_git:`/cgit/cgit.cgi/meta-yocto-bsp-old/`.
@@ -31,9 +31,9 @@ version required on the
 build host is now 1.7.8 because the ``--list`` option is now required by
 BitBake's Git fetcher. As always, if your host distribution does not
 provide a version of Git that meets this requirement, you can use the
-``buildtools-tarball`` that does. See the "`Required Git, tar, Python
+``buildtools-tarball`` that does. See the
-and gcc Versions <#required-git-tar-python-and-gcc-versions>`__" section
+":ref:`ref-manual/ref-system-requirements:required git, tar, python and gcc versions`"
-for more information.
+section for more information.
 .. _migration-1.7-autotools-class-changes:
@@ -157,7 +157,7 @@ The following changes have occurred to the QA check process:
   added in order to verify that file dependencies are satisfied (e.g.
   package contains a script requiring ``/bin/bash``) and build-time
   dependencies are declared, respectively. For more information, please
-   see the "`QA Error and Warning Messages <#ref-qa-checks>`__" chapter.
+   see the ":doc:`ref-qa-checks`" chapter.
 -  Package QA checks are now performed during a new
   :ref:`ref-tasks-package_qa` task rather than being
@@ -202,9 +202,7 @@ The following recipes have been removed:
   for version 3.17 has been added.
 -  ``eglibc`` has been removed in favor of ``glibc``. See the
-   "```eglibc 2.19`` Replaced with
+   ":ref:`migration-1.7-glibc-replaces-eglibc`" section for more information.
   ``glibc 2.20`` <#migration-1.7-glibc-replaces-eglibc>`__" section for
   more information.
 .. _migration-1.7-miscellaneous-changes:
@@ -96,8 +96,8 @@ changes in behavior exist:
      $ bitbake -e
-  ``d.delVar('``\ VARNAME\ ``')`` and
+-  ``d.delVar('VARNAME')`` and
-   ``d.setVar('``\ VARNAME\ ``', None)`` result in the variable and all
+   ``d.setVar('VARNAME', None)`` result in the variable and all
   of its overrides being cleared out. Before the change, only the
   non-overridden values were cleared.
@@ -9,7 +9,7 @@ Project 2.1 Release from the prior release.
 Variable Expansion in Python Functions
 --------------------------------------
-Variable expressions, such as ``${``\ VARNAME\ ``}`` no longer expand
+Variable expressions, such as ``${VARNAME}`` no longer expand
 automatically within Python functions. Suppressing expansion was done to
 allow Python functions to construct shell scripts or other code for
 situations in which you do not want such expressions expanded. For any
@@ -125,7 +125,7 @@ Image Generation is Now Split Out from Filesystem Generation
 Previously, for image recipes the :ref:`ref-tasks-rootfs`
 task assembled the filesystem and then from that filesystem generated
 images. With this Yocto Project release, image generation is split into
-separate ```do_image_*`` <#ref-tasks-image>`__ tasks for clarity both in
+separate :ref:`ref-tasks-image` tasks for clarity both in
 operation and in the code.
 For most cases, this change does not present any problems. However, if
@@ -133,7 +133,7 @@ you have made customizations that directly modify the ``do_rootfs`` task
 or that mention ``do_rootfs``, you might need to update those changes.
 In particular, if you had added any tasks after ``do_rootfs``, you
 should make edits so that those tasks are after the
-```do_image_complete`` <#ref-tasks-image-complete>`__ task rather than
+:ref:`ref-tasks-image-complete` task rather than
 after ``do_rootfs`` so that the your added tasks run at the correct
 time.
@@ -180,7 +180,7 @@ The following recipes have been removed in the 2.1 release:
 -  ``python-pygtk``: Recipe became obsolete.
 -  ``adt-installer``: Recipe became obsolete. See the "`ADT
-   Removed <#migration-2.1-adt-removed>`__" section for more
+   Removed <#adt-removed>`__" section for more
   information.
 .. _migration-2.1-class-changes:
@@ -287,7 +287,9 @@ The following changes have been made for the Poky distribution:
   option specified on the configure command line either because it is
   not a supported option for the configure script or because static
   libraries are needed should set the following variable:
-   DISABLE_STATIC = ""
+   ::
      DISABLE_STATIC = ""
 -  The separate ``poky-tiny`` distribution now uses the musl C library
   instead of a heavily pared down ``glibc``. Using musl results in a
@@ -357,10 +359,9 @@ These additional changes exist:
 -  The minimum Git version has been increased to 1.8.3.1. If your host
   distribution does not provide a sufficiently recent version, you can
-   install the buildtools, which will provide it. See the "`Required
+   install the buildtools, which will provide it. See the
-   Git, tar, Python and gcc
+   :ref:`ref-manual/ref-system-requirements:required git, tar, python and gcc versions`
-   Versions <#required-git-tar-python-and-gcc-versions>`__" section for
+   section for more information on the buildtools tarball.
   more information on the buildtools tarball.
 -  The buggy and incomplete support for the RPM version 4 package
   manager has been removed. The well-tested and maintained support for
@@ -376,8 +377,9 @@ These additional changes exist:
      base-passwd
      shadow
      update-alternatives
      run-postinsts
-   run-postinsts With the Yocto Project 2.1 release, these packages are
+   With the Yocto Project 2.1 release, these packages are
   only removed if "read-only-rootfs" is in ``IMAGE_FEATURES``, since
   they might still be needed for a read-write image even in the absence
   of a package manager (e.g. if users need to be added, modified, or
@@ -16,8 +16,7 @@ the minimum kernel version is 3.19.
 .. note::
-   For x86 and x86_64, you can reset
+   For x86 and x86_64, you can reset :term:`OLDEST_KERNEL`
   OLDEST_KERNEL
   to anything down to 2.6.32 if desired.
 .. _migration-2.2-staging-directories-in-sysroot-simplified:
@@ -79,7 +78,9 @@ particular areas of interest:
  - the syntax for octal values changed
-  - the ``iter*()`` functions changed name \* iterators now return views, not lists
+  - the ``iter*()`` functions changed name
  - iterators now return views, not lists
  - changed names for Python modules
@@ -224,9 +225,7 @@ follows and run ``runqemu``:
 .. note::
-   For command-line syntax, use
+   For command-line syntax, use ``runqemu help``.
   runqemu help
   .
 ::
@@ -369,7 +368,7 @@ The following recipes have been removed:
 -  ``sato-icon-theme``: Became obsolete.
 -  ``swabber-native``: Swabber has been removed. See the `entry on
-   Swabber <#migration-2.2-swabber-has-been-removed>`__.
+   Swabber <#swabber-has-been-removed>`__.
 -  ``tslib``: No longer needed and has been moved to ``meta-oe``.
@@ -395,7 +394,7 @@ The following classes have been removed:
 -  ``sip``: Mostly unused.
 -  ``swabber``: See the `entry on
-   Swabber <#migration-2.2-swabber-has-been-removed>`__.
+   Swabber <#swabber-has-been-removed>`__.
 .. _migration-2.2-minor-packaging-changes:
@@ -76,9 +76,7 @@ Consider the following:
 .. note::
   You can find more information on how recipe-specific sysroots work in
-   the "
+   the ":ref:`ref-classes-staging`" section.
   staging.bbclass
   " section.
 .. _migration-2.3-path-variable:
@@ -104,9 +102,8 @@ value.
 .. note::
   PATH
-   is not sanitized in the same way within
+   is not sanitized in the same way within ``devshell``.
-   devshell
+   If it were, you would have difficulty running host tools for
   . If it were, you would have difficulty running host tools for
   development and debugging within the shell.
 .. _migration-2.3-scripts:
@@ -240,10 +237,8 @@ to substitute a GPLv2 version of a GPLv3 recipe, then you must add the
 .. note::
-   You can find
+   You can ``find meta-gplv2`` layer in the OpenEmbedded layer index at
-   meta-gplv2
+   https://layers.openembedded.org/layerindex/branch/master/layer/meta-gplv2/.
   layer in the OpenEmbedded layer index at
   .
 These relocated GPLv2 recipes do not receive the same level of
 maintenance as other core recipes. The recipes do not get security fixes
@@ -316,8 +311,7 @@ The following package management changes took place:
 -  Signing of remote package feeds using ``PACKAGE_FEED_SIGN`` is not
   currently supported. This issue will be fully addressed in a future
-   Yocto Project release. See `defect
+   Yocto Project release. See :yocto_bugs:`defect 11209 </show_bug.cgi?id=11209>`
   11209 <https://bugzilla.yoctoproject.org/show_bug.cgi?id=11209>`__
   for more information on a solution to package feed signing with RPM
   in the Yocto Project 2.3 release.
@@ -329,8 +323,7 @@ The following package management changes took place:
   .. note::
      For further details on this change, see the
-      commit message
+      :yocto_git:`commit message </cgit/cgit.cgi/poky/commit/?id=f4d4f99cfbc2396e49c1613a7d237b9e57f06f81>`.
      .
 .. _migration-2.3-removed-recipes:
@@ -372,9 +365,9 @@ The following changes have been made to Wic:
 .. note::
-   For more information on Wic, see the "
+   For more information on Wic, see the
-   Creating Partitioned Images Using Wic
+   ":ref:`dev-manual/dev-manual-common-tasks:creating partitioned images using wic`"
-   " section in the Yocto Project Development Tasks Manual.
+   section in the Yocto Project Development Tasks Manual.
 -  *Default Output Directory Changed:* Wic's default output directory is
   now the current directory by default instead of the unusual
@@ -410,8 +403,8 @@ The following QA checks have changed:
   warning, you need to address missing runtime dependencies.
   For additional information, see the
-   :ref:`insane <ref-classes-insane>` class and the "`Errors and
+   :ref:`insane <ref-classes-insane>` class and the
-   Warnings <#qa-errors-and-warnings>`__" section.
+   ":ref:`ref-manual/ref-qa-checks:errors and warnings`" section.
 .. _migration-2.3-miscellaneous-changes:
@@ -179,8 +179,8 @@ or ::
 The earlier build-time provides behavior was a quirk of the
 way the Python manifest file was created. For more information on this
-change please see `this
+change please see :yocto_git:`this commit
-commit <http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=8d94b9db221d1def42f091b991903faa2d1651ce>`__.
+</cgit/cgit.cgi/poky/commit/?id=8d94b9db221d1def42f091b991903faa2d1651ce>`.
 .. _migration-2.5-miscellaneous-changes:
@@ -110,7 +110,7 @@ upon the older ``*proto`` recipes need to be changed to depend on the
 newer ``xorgproto`` recipe instead.
 For names of recipes removed because of this repository change, see the
-`Removed Recipes <#migration-2.6-removed-recipes>`__ section.
+`Removed Recipes <#removed-recipes>`__ section.
 .. _migration-2.6-distutils-distutils3-fetching-dependencies:
@@ -128,18 +128,9 @@ missing from :term:`DEPENDS`).
 .. note::
   This change affects classes beyond just the two mentioned (i.e.
-   distutils
+   ``distutils`` and ``distutils3``). Any recipe that inherits ``distutils*``
-   and
+   classes are affected. For example, the ``setuptools`` and ``setuptools3``
-   distutils3
+   recipes are affected since they inherit the ``distutils*`` classes.
   ). Any recipe that inherits
   distutils\*
   classes are affected. For example, the
   setuptools
   and
   setuptools3
   recipes are affected since they inherit the
   distutils\*
   classes.
 Fetching these types of dependencies that are not provided in the
 sysroot negatively affects the ability to reproduce builds. This type of
@@ -178,13 +169,13 @@ The following changes have been made:
 -  Several variables have changed names for consistency:
   ::
-      Old Variable                  Name New Variable Name
+      Old Variable Name             New Variable Name
      ========================================================
-      KERNEL_IMAGE_BASE_NAME        :term:`KERNEL_IMAGE_NAME`
+      KERNEL_IMAGE_BASE_NAME        KERNEL_IMAGE_NAME
-      KERNEL_IMAGE_SYMLINK_NAME     :term:`KERNEL_IMAGE_LINK_NAME`
+      KERNEL_IMAGE_SYMLINK_NAME     KERNEL_IMAGE_LINK_NAME
-      MODULE_TARBALL_BASE_NAME      :term:`MODULE_TARBALL_NAME`
+      MODULE_TARBALL_BASE_NAME      MODULE_TARBALL_NAME
-      MODULE_TARBALL_SYMLINK_NAME   :term:`MODULE_TARBALL_LINK_NAME`
+      MODULE_TARBALL_SYMLINK_NAME   MODULE_TARBALL_LINK_NAME
-      INITRAMFS_BASE_NAME           :term:`INITRAMFS_NAME`
+      INITRAMFS_BASE_NAME           INITRAMFS_NAME
 -  The ``MODULE_IMAGE_BASE_NAME`` variable has been removed. The module
   tarball name is now controlled directly with the
@@ -233,11 +224,9 @@ you replace all instances of ``SERIAL_CONSOLE`` with
 .. note::
-   The only difference in usage is that
+   The only difference in usage is that ``SERIAL_CONSOLES``
   SERIAL_CONSOLES
   expects entries to be separated using semicolons as compared to
-   SERIAL_CONSOLE
+   ``SERIAL_CONSOLE``, which expects spaces.
   , which expects spaces.
 .. _migration-2.6-poky-sets-unknown-configure-option-to-qa-error:
@@ -263,9 +252,7 @@ The following changes have occurred:
   .. note::
-      The
+      The ``virtclass-multilib-`` overrides for multilib are still valid.
      virtclass-multilib-
      overrides for multilib are still valid.
 -  The ``forcevariable`` Override Now Has a Higher Priority Than
   ``libc`` Overrides: The ``forcevariable`` override is documented to
@@ -447,14 +434,8 @@ The following miscellaneous changes occurred:
   .. note::
-      genericx86
+      ``genericx86`` and ``genericx86-64`` retain ``kernel-modules`` as part of
-      and
+      the ``RRECOMMENDS`` variable setting.
      genericx86-64
      retain
      kernel-modules
      as part of the
      RRECOMMENDS
      variable setting.
 -  The ``LGPLv2_WHITELIST_GPL-3.0`` variable has been removed. If you
   are setting this variable in your configuration, set or append it to
@@ -197,8 +197,7 @@ The following BitBake changes have occurred.
 -  The arguments passed to functions used with
   :term:`bitbake:BB_HASHCHECK_FUNCTION`
   have changed. If you are using your own custom hash check function,
-   see
+   see :yocto_git:`/cgit/cgit.cgi/poky/commit/?id=40a5e193c4ba45c928fccd899415ea56b5417725`
   http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=40a5e193c4ba45c928fccd899415ea56b5417725
   for details.
 -  Task specifications in ``BB_TASKDEPDATA`` and class implementations
@@ -47,7 +47,7 @@ splitting out of debug symbols during packaging).
   even if the recipes do not produce architecture-specific output.
   Configuring such recipes for all architectures causes the
-   ```do_package_write_*`` tasks to
+   ``do_package_write_*`` tasks to
   have different signatures for the machines with different tunings.
   Additionally, unnecessary rebuilds occur every time an image for a
   different ``MACHINE`` is built even when the recipe never changes.
@@ -164,24 +164,18 @@ example use for this class.
   For RPMs and other packages that do not contain a subdirectory, you
   should specify an appropriate fetcher parameter to point to the
-   subdirectory. For example, if BitBake is using the Git fetcher (
+   subdirectory. For example, if BitBake is using the Git fetcher (``git://``),
-   git://
+   the "subpath" parameter limits the checkout to a specific subpath
-   ), the "subpath" parameter limits the checkout to a specific subpath
+   of the tree. Here is an example where ``${BP}`` is used so that the files
-   of the tree. Here is an example where
+   are extracted into the subdirectory expected by the default value of
-   ${BP}
+   ``S``:
   is used so that the files are extracted into the subdirectory
   expected by the default value of
   S
   :
   ::
           SRC_URI = "git://example.com/downloads/somepackage.rpm;subpath=${BP}"
-   See the "
+   See the ":ref:`bitbake-user-manual/bitbake-user-manual-fetching:fetchers`" section in the BitBake User Manual for
-   Fetchers
+   more information on supported BitBake Fetchers.
   " section in the BitBake User Manual for more information on
   supported BitBake Fetchers.
 .. _ref-classes-binconfig:
@@ -736,11 +730,8 @@ introspection. This functionality is only enabled if the
 .. note::
   This functionality is backfilled by default and, if not applicable,
-   should be disabled through
+   should be disabled through ``DISTRO_FEATURES_BACKFILL_CONSIDERED`` or
-   DISTRO_FEATURES_BACKFILL_CONSIDERED
+   ``MACHINE_FEATURES_BACKFILL_CONSIDERED``, respectively.
   or
   MACHINE_FEATURES_BACKFILL_CONSIDERED
   , respectively.
 .. _ref-classes-grub-efi:
@@ -969,9 +960,8 @@ The ``image_types`` class also handles conversion and compression of images.
 .. note::
   To build a VMware VMDK image, you need to add "wic.vmdk" to
-   IMAGE_FSTYPES
+   ``IMAGE_FSTYPES``. This would also be similar for Virtual Box Virtual Disk
-   . This would also be similar for Virtual Box Virtual Disk Image
+   Image ("vdi") and QEMU Copy On Write Version 2 ("qcow2") images.
   ("vdi") and QEMU Copy On Write Version 2 ("qcow2") images.
 .. _ref-classes-image-live:
@@ -1032,9 +1022,8 @@ You can configure the sanity checks so that specific test failures
 either raise a warning or an error message. Typically, failures for new
 tests generate a warning. Subsequent failures for the same test would
 then generate an error message once the metadata is in a known and good
-condition. See the "`QA Error and Warning Messages <#ref-qa-checks>`__"
+condition. See the ":doc:`ref-qa-checks`" Chapter for a list of all the warning
-Chapter for a list of all the warning and error messages you might
+and error messages you might encounter using a default configuration.
 encounter using a default configuration.
 Use the :term:`WARN_QA` and
 :term:`ERROR_QA` variables to control the behavior of
@@ -1275,9 +1264,9 @@ The following list shows the tests you can list with the ``WARN_QA`` and
 -  ``textrel:`` Checks for ELF binaries that contain relocations in
   their ``.text`` sections, which can result in a performance impact at
-   runtime. See the explanation for the
+   runtime. See the explanation for the ``ELF binary`` message in
-   ```ELF binary`` <#qa-issue-textrel>`__ message for more information
+   ":doc:`ref-qa-checks`" for more information regarding runtime performance
-   regarding runtime performance issues.
+   issues.
 -  ``unlisted-pkg-lics:`` Checks that all declared licenses applying
   for a package are also declared on the recipe level (i.e. any license
@@ -1627,8 +1616,8 @@ section in the Yocto Project Development Tasks Manual.
 ==================
 The ``native`` class provides common functionality for recipes that
-build tools to run on the `build host <#hardware-build-system-term>`__
+build tools to run on the :term:`Build Host` (i.e. tools that use the compiler
-(i.e. tools that use the compiler or other tools from the build host).
+or other tools from the build host).
 You can create a recipe that builds tools that run natively on the host
 a couple different ways:
@@ -1726,8 +1715,7 @@ package manager (NPM) <https://en.wikipedia.org/wiki/Npm_(software)>`__.
 .. note::
-   Currently, recipes inheriting this class must use the
+   Currently, recipes inheriting this class must use the ``npm://``
   npm://
   fetcher to have dependencies fetched and packaged automatically.
 For information on how to create NPM packages, see the
@@ -1831,9 +1819,9 @@ consider some further things about using RPM:
 You can find additional information on the effects of the package class
 at these two Yocto Project mailing list links:
-  https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html
+-  :yocto_lists:`/pipermail/poky/2011-May/006362.html`
-  https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html
+-  :yocto_lists:`/pipermail/poky/2011-May/006363.html`
 .. _ref-classes-package_deb:
@@ -1892,16 +1880,8 @@ variable in the ``local.conf`` file.
 .. note::
-   You cannot specify the
+   You cannot specify the ``package_tar`` class first using the
-   package_tar
+   ``PACKAGE_CLASSES`` variable. You must use ``.deb``, ``.ipk``, or ``.rpm``
   class first using the
   PACKAGE_CLASSES
   variable. You must use
   .deb
   ,
   .ipk
   , or
   .rpm
   file formats for your image or SDK.
 .. _ref-classes-packagedata:
@@ -2066,9 +2046,7 @@ The ``prexport`` class provides functionality for exporting
 .. note::
   This class is not intended to be used directly. Rather, it is enabled
-   when using "
+   when using "``bitbake-prserv-tool export``".
   bitbake-prserv-tool export
   ".
 .. _ref-classes-primport:
@@ -2081,9 +2059,7 @@ The ``primport`` class provides functionality for importing
 .. note::
   This class is not intended to be used directly. Rather, it is enabled
-   when using "
+   when using "``bitbake-prserv-tool import``".
   bitbake-prserv-tool import
   ".
 .. _ref-classes-prserv:
@@ -2202,9 +2178,7 @@ override the removal by setting ``REMOVE_LIBTOOL_LA`` to "0" as follows:
 .. note::
-   The
+   The ``remove-libtool`` class is not enabled by default.
   remove-libtool
   class is not enabled by default.
 .. _ref-classes-report-error:
@@ -2440,13 +2414,12 @@ stages:
   .. note::
      Additionally, a recipe can customize the files further by
-      declaring a processing function in the
+      declaring a processing function in the ``SYSROOT_PREPROCESS_FUNCS``
      SYSROOT_PREPROCESS_FUNCS
      variable.
   A shared state (sstate) object is built from these files and the
   files are placed into a subdirectory of
-   ```tmp/sysroots-components/`` <#structure-build-tmp-sysroots-components>`__.
+   :ref:`structure-build-tmp-sysroots-components`.
   The files are scanned for hardcoded paths to the original
   installation location. If the location is found in text files, the
   hardcoded locations are replaced by tokens and a list of the files
@@ -2595,13 +2568,8 @@ internal class and is not intended to be used directly.
 .. note::
-   The
+   The ``systemd-boot`` class is a result from merging the ``gummiboot`` class
-   systemd-boot
+   used in previous Yocto Project releases with the ``systemd`` project.
   class is a result from merging the
   gummiboot
   class used in previous Yocto Project releases with the
   systemd
   project.
 Set the :term:`EFI_PROVIDER` variable to
 "systemd-boot" to use this class. Doing so creates a standalone EFI
@@ -2645,13 +2613,9 @@ steps to set up the environment.
 .. note::
-   Best practices include using
+   Best practices include using :term:`IMAGE_CLASSES` rather than
-   IMAGE_CLASSES
+   :term:`INHERIT` to inherit the ``testimage`` class for automated image
-   rather than
+   testing.
   INHERIT
   to inherit the
   testimage
   class for automated image testing.
 The tests are commands that run on the target system over ``ssh``. Each
 test is written in Python and makes use of the ``unittest`` module.
@@ -2684,13 +2648,9 @@ using the following:
 .. note::
-   Best practices include using
+   Best practices include using :term:`IMAGE_CLASSES` rather than
-   IMAGE_CLASSES
+   :term:`INHERIT` to inherit the ``testsdk`` class for automated SDK
-   rather than
+   testing.
   INHERIT
   to inherit the
   testsdk
   class for automated SDK testing.
 .. _ref-classes-texinfo:
@@ -2707,11 +2667,8 @@ host system.
 .. note::
   If you want to use the Texinfo recipe shipped with the build system,
-   you can remove "texinfo-native" from
+   you can remove "texinfo-native" from :term:`ASSUME_PROVIDED` and makeinfo
-   ASSUME_PROVIDED
+   from :term:`SANITY_REQUIRED_UTILITIES`.
   and makeinfo from
   SANITY_REQUIRED_UTILITIES
   .
 .. _ref-classes-tinderclient:
@@ -2834,10 +2791,8 @@ file.
 .. note::
-   You can use the
+   You can use the ``update-alternatives`` command directly in your recipes.
-   update-alternatives
+   However, this class simplifies things in most cases.
   command directly in your recipes. However, this class simplifies
   things in most cases.
 .. _ref-classes-update-rc.d:
@@ -2903,18 +2858,10 @@ additional information.
 .. note::
-   You do not use the
+   You do not use the ``useradd-staticids`` class directly. You either enable
-   useradd-staticids
+   or disable the class by setting the ``USERADDEXTENSION`` variable. If you
-   class directly. You either enable or disable the class by setting the
+   enable or disable the class in a configured system, :term:`TMPDIR` might
-   USERADDEXTENSION
+   contain incorrect ``uid`` and ``gid`` values. Deleting the ``TMPDIR``
   variable. If you enable or disable the class in a configured system,
   TMPDIR
   might contain incorrect
   uid
   and
   gid
   values. Deleting the
   TMPDIR
   directory will correct this condition.
 .. _ref-classes-utility-tasks:
@@ -131,7 +131,7 @@ The following figure shows the workspace structure:
   :align: center
   :scale: 70%
-::
+.. code-block:: none
   attic - A directory created if devtool believes it must preserve
           anything when you run "devtool reset".  For example, if you
@@ -223,7 +223,7 @@ specify these options when using the ``devtool add`` command:
 .. note::
   If you prefer to use the latest revision every time the recipe is
-   built, use the options --autorev or -a.
+   built, use the options ``--autorev`` or ``-a``.
 .. _devtool-extracting-the-source-for-an-existing-recipe:
@@ -261,7 +261,7 @@ Modifying an Existing Recipe
 Use the ``devtool modify`` command to begin modifying the source of an
 existing recipe. This command is very similar to the
-```add`` <#devtool-adding-a-new-recipe-to-the-workspace>`__ command
+:ref:`add <devtool-adding-a-new-recipe-to-the-workspace>` command
 except that it does not physically create the recipe in the workspace
 layer because the recipe already exists in an another layer.
@@ -303,7 +303,7 @@ Updating a Recipe
 Use the ``devtool update-recipe`` command to update your recipe with
 patches that reflect changes you make to the source files. For example,
 if you know you are going to work on some code, you could first use the
-```devtool modify`` <#devtool-modifying-a-recipe>`__ command to extract
+:ref:`devtool modify <devtool-modifying-a-recipe>` command to extract
 the code and set up the workspace. After which, you could modify,
 compile, and test the code.
@@ -386,15 +386,21 @@ satisfied.
 .. note::
   When a reason for not upgrading displays, the reason is usually
-   written into the recipe using the RECIPE_NO_UPDATE_REASON
+   written into the recipe using the ``RECIPE_NO_UPDATE_REASON``
-   variable. See the base-passwd.bb recipe for an example.
+   variable. See the
   :yocto_git:`base-passwd.bb </cgit/cgit.cgi/poky/tree/meta/recipes-core/base-passwd/base-passwd_3.5.29.bb>`
   recipe for an example.
 ::
-   $ devtool check-upgrade-status ...
+   $ devtool check-upgrade-status
   ...
   NOTE: acpid 2.0.30 2.0.31 Ross Burton <ross.burton@intel.com>
   NOTE: u-boot-fw-utils 2018.11 2019.01 Marek Vasut <marek.vasut@gmail.com> d3689267f92c5956e09cc7d1baa4700141662bff
-   NOTE: u-boot-tools 2018.11 2019.01 Marek Vasut <marek.vasut@gmail.com> d3689267f92c5956e09cc7d1baa4700141662bff . . .
+   NOTE: u-boot-tools 2018.11 2019.01 Marek Vasut <marek.vasut@gmail.com> d3689267f92c5956e09cc7d1baa4700141662bff
   .
   .
   .
   NOTE: base-passwd 3.5.29 3.5.45 Anuj Mittal <anuj.mittal@intel.com> cannot be updated due to: Version 3.5.38 requires cdebconf for update-passwd utility
   NOTE: busybox 1.29.2 1.30.0 Andrej Valek <andrej.valek@siemens.com>
   NOTE: dbus-test 1.12.10 1.12.12 Chen Qi <Qi.Chen@windriver.com>
@@ -607,8 +613,8 @@ Following is sample output after using
 to create and add the ``mtr_0.86.bb`` recipe to the ``workspace`` directory:
 ::
-   $ devtool status mtr
+   $ devtool status
-   :/home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb)
+   mtr:/home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb)
   $
 .. _devtool-search-for-available-target-recipes:
@@ -229,11 +229,8 @@ The following image features are available for all images:
   .. note::
-      To make the
+      To make the ``/var/log`` directory on the target persistent, use the
-      /var/log
+      :term:`VOLATILE_LOG_DIR` variable by setting it to "no".
      directory on the target persistent, use the
      VOLATILE_LOG_DIR
      variable by setting it to "no".
 -  *ptest-pkgs:* Installs ptest packages for all ptest-enabled recipes.
@@ -16,8 +16,7 @@ image you want.
   the GNU Affero General Public License Version 3 (AGPL-3.0) components
   is only supported for minimal and base images. Furthermore, if you
   are going to build an image using non-GPLv3 and similarly licensed
-   components, you must make the following changes in the
+   components, you must make the following changes in the ``local.conf``
   local.conf
   file before using the BitBake command to build the minimal or base
   image:
   ::
@@ -55,15 +55,14 @@ must also provide one of the ``--ondrive``, ``--ondisk``, or
 .. note::
   The mount program must understand the PARTUUID syntax you use with
-   --use-uuid
+   ``--use-uuid`` and non-root *mountpoint*, including swap. The busybox
-   and non-root
+   versions of these application are currently excluded.
   mountpoint
   , including swap. The busybox versions of these application are
   currently excluded.
 Here is an example that uses "/" as the mountpoint. The command uses
-``--ondisk`` to force the partition onto the ``sdb`` disk: part /
+``--ondisk`` to force the partition onto the ``sdb`` disk:
--source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024
+::
      part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024
 Here is a list that describes other supported options you can use with
 the ``part`` and ``partition`` commands:
@@ -454,9 +454,8 @@ Errors and Warnings
      Disabling stripping here does not mean that the final packaged
      binaries will be unstripped. Once the OpenEmbedded build system
-      splits out debug symbols to the
+      splits out debug symbols to the ``-dbg`` package, it will then
-      -dbg
+      strip the symbols from the binaries.
      package, it will then strip the symbols from the binaries.
@@ -64,7 +64,7 @@ codename are likely to be compatible and thus work together.
 Releases are given a nominal release version as well but the codename is
 used in repositories for this reason. You can find information on Yocto
 Project releases and codenames at
-https://wiki.yoctoproject.org/wiki/Releases.
+:yocto_wiki:`/wiki/Releases`.
 Stable Release Process
 ======================
@@ -94,7 +94,7 @@ Community LTS trees and branches exist where community members share
 patches for older releases. However, these types of patches do not go
 through the same release process as do point releases. You can find more
 information about stable branch maintenance at
-https://wiki.yoctoproject.org/wiki/Stable_branch_maintenance.
+:yocto_wiki:`/wiki/Stable_branch_maintenance`.
 Testing and Quality Assurance
 =============================
@@ -145,18 +145,16 @@ consists of the following pieces:
   .. note::
-      Running
+      Running ``oe-selftest`` requires host packages beyond the "Essential"
-      oe-selftest
+      grouping. See the :ref:`ref-manual/ref-system-requirements:required packages for the build host`
-      requires host packages beyond the "Essential" grouping. See the "
+      section for more information.
      Required Packages for the Build Host
      " section for more information.
 Originally, much of this testing was done manually. However, significant
 effort has been made to automate the tests so that more people can use
 them and the Yocto Project development team can run them faster and more
 efficiently.
-The Yocto Project's main Autobuilder (https://autobuilder.yoctoproject.org/)
+The Yocto Project's main Autobuilder (&YOCTO_AB_URL;)
 publicly tests each Yocto Project release's code in the
 :term:`OpenEmbedded-Core (OE-Core)`, Poky, and BitBake repositories. The testing
 occurs for both the current state of the "master" branch and also for
@@ -282,17 +282,10 @@ file, it uses ``sed`` to substitute final
 .. note::
-   You can see how the
+   You can see how the ``TEMPLATECONF`` variable is used by looking at the
-   TEMPLATECONF
+   ``scripts/oe-setup-builddir``` script in the :term:`Source Directory`.
-   variable is used by looking at the
+   You can find the Yocto Project version of the ``local.conf.sample`` file in
-   scripts/oe-setup-builddir
+   the ``meta-poky/conf`` directory.
   script in the
   Source Directory
   . You can find the Yocto Project version of the
   local.conf.sample
   file in the
   meta-poky/conf
   directory.
 .. _structure-build-conf-bblayers.conf:
@@ -327,16 +320,9 @@ Once the build process gets the sample file, it uses ``sed`` to substitute final
 .. note::
-   You can see how the
+   You can see how the ``TEMPLATECONF`` variable ``scripts/oe-setup-builddir``
-   TEMPLATECONF
+   script in the :term:`Source Directory`. You can find the Yocto Project
-   variable
+   version of the ``bblayers.conf.sample`` file in the ``meta-poky/conf/``
   scripts/oe-setup-builddir
   script in the
   Source Directory
   . You can find the Yocto Project version of the
   bblayers.conf.sample
   file in the
   meta-poky/conf/
   directory.
 .. _structure-build-conf-sanity_info:
@@ -531,19 +517,16 @@ should be automatic, and recipes should not directly reference
 Previous versions of the OpenEmbedded build system used to create a
 global shared sysroot per machine along with a native sysroot. Beginning
-with the DISTRO version of the Yocto Project, sysroots exist in
+with the 2.3 version of the Yocto Project, sysroots exist in
 recipe-specific :term:`WORKDIR` directories. Thus, the
 ``build/tmp/sysroots/`` directory is unused.
 .. note::
-   The
+   The ``build/tmp/sysroots/`` directory can still be populated using the
-   build/tmp/sysroots/
+   ``bitbake build-sysroots`` command and can be used for compatibility in some
-   directory can still be populated using the
+   cases. However, in general it is not recommended to populate this directory.
-   bitbake build-sysroots
+   Individual recipe-specific sysroots should be used.
   command and can be used for compatibility in some cases. However, in
   general it is not recommended to populate this directory. Individual
   recipe-specific sysroots should be used.
 .. _structure-build-tmp-stamps:
@@ -554,8 +537,11 @@ This directory holds information that BitBake uses for accounting
 purposes to track what tasks have run and when they have run. The
 directory is sub-divided by architecture, package name, and version.
 Following is an example:
-stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do Although
+::
-the files in the directory are empty of data, BitBake uses the filenames
+
      stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do
 Although 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
@@ -613,13 +599,12 @@ install" places its output that is then split into sub-packages within
 The recipe work directory - ``${WORKDIR}``.
 As described earlier in the
-"```build/tmp/sysroots/`` <#structure-build-tmp-sysroots>`__" section,
+":ref:`structure-build-tmp-sysroots`" section,
-beginning with the DISTRO release of the Yocto Project, the OpenEmbedded
+beginning with the 2.3 release of the Yocto Project, the OpenEmbedded
 build system builds each recipe in its own work directory (i.e.
 :term:`WORKDIR`). The path to the work directory is
 constructed using the architecture of the given build (e.g.
-:term:`TUNE_PKGARCH`,
+:term:`TUNE_PKGARCH`, :term:`MACHINE_ARCH`, or "allarch"), the recipe
 :term:`MACHINE_ARCH`, or "allarch"), the recipe
 name, and the version of the recipe (i.e.
 :term:`PE`\ ``:``\ :term:`PV`\ ``-``\ :term:`PR`).
@@ -27,9 +27,7 @@ and conceptual information in the :doc:`../overview-manual/overview-manual`.
 .. note::
   For more information about the Yocto Project Documentation set, see
-   the "
+   the :ref:`ref-manual/resources:links and related documentation` section.
   Links and Related Documentation
   " section.
 .. _detailed-supported-distros:
@@ -95,8 +93,8 @@ distributions:
      compatible but not officially supported nor validated with
      WSLv2, if you still decide to use WSL please upgrade to WSLv2.
-   -  If you encounter problems, please go to `Yocto Project
+   -  If you encounter problems, please go to :yocto_bugs:`Yocto Project
-      Bugzilla <http://bugzilla.yoctoproject.org>`__ and submit a bug. We are
+      Bugzilla <>` and submit a bug. We are
      interested in hearing about your experience. For information on
      how to submit a bug, see the Yocto Project
      :yocto_wiki:`Bugzilla wiki page </wiki/Bugzilla_Configuration_and_Bug_Tracking>`
@@ -181,8 +179,11 @@ supported openSUSE Linux distribution:
      $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL;
 -  *Documentation:* Packages needed if you are going to build out the
-   Yocto Project documentation manuals: $ sudo zypper install dblatex
+   Yocto Project documentation manuals:
-   xmlto
+   ::
      $ sudo zypper install dblatex xmlto
 CentOS-7 Packages
 -----------------
@@ -283,7 +284,7 @@ installer and automatically installs the tools for you:
      $ cd poky
      $ scripts/install-buildtools --without-extended-buildtools \
-        --base-url https://downloads.yoctoproject.org/releases/yocto \
+        --base-url &YOCTO_DL_URL;/releases/yocto \
        --release yocto-&DISTRO; \
        --installer-version &DISTRO;
@@ -344,7 +345,7 @@ of the two methods by which you can get these tools:
   During execution, a prompt appears that allows you to choose the
   installation directory. For example, you could choose the following:
-   /home/your-username/buildtools
+   ``/home/your-username/buildtools``
 3. Source the tools environment setup script by using a command like the
   following:
@@ -392,12 +393,8 @@ installer:
   .. note::
-      The
+      The :term:`SDKMACHINE` variable in your ``local.conf`` file determines
-      SDKMACHINE
+      whether you build tools for a 32-bit or 64-bit system.
      variable in your
      local.conf
      file determines whether you build tools for a 32-bit or 64-bit
      system.
   Once the build completes, you can find the ``.sh`` file that installs
   the tools in the ``tmp/deploy/sdk`` subdirectory of the
@@ -421,7 +418,7 @@ installer:
   During execution, a prompt appears that allows you to choose the
   installation directory. For example, you could choose the following:
-   /home/your_username/buildtools
+   ``/home/your_username/buildtools``
 5. Source the tools environment setup script by using a command like the
   following:
@@ -87,33 +87,30 @@ output from ``${DEPLOYDIR}`` to ``${DEPLOY_DIR_IMAGE}``.
 .. note::
-   Do not write the output directly to
+   Do not write the output directly to ``${DEPLOY_DIR_IMAGE}``, as this causes
-   ${DEPLOY_DIR_IMAGE}
+   the sstate mechanism to malfunction.
   , as this causes the sstate mechanism to malfunction.
 The ``do_deploy`` task is not added as a task by default and
 consequently needs to be added manually. If you want the task to run
 after :ref:`ref-tasks-compile`, you can add it by doing
-the following: addtask deploy after do_compile Adding ``do_deploy``
+the following:
-after other tasks works the same way.
+::
      addtask deploy after do_compile
 Adding ``do_deploy`` after other tasks works the same way.
 .. note::
-   You do not need to add
+   You do not need to add ``before do_build`` to the ``addtask`` command
-   before do_build
+   (though it is harmless), because the ``base`` class contains the following:
   to the
   addtask
   command (though it is harmless), because the
   base
   class contains the following:
   ::
           do_build[recrdeptask] += "do_deploy"
-   See the "
+   See the ":ref:`bitbake-user-manual/bitbake-user-manual-execution:dependencies`"
-   Dependencies
+   section in the BitBake User Manual for more information.
   " section in the BitBake User Manual for more information.
 If the ``do_deploy`` task re-executes, any previous output is removed
 (i.e. "cleaned").
@@ -298,10 +295,8 @@ to locate and apply patch files to the source code.
 .. note::
-   The build system uses the
+   The build system uses the :term:`FILESPATH` variable to determine the
-   FILESPATH
+   default set of directories when searching for patches.
   variable to determine the default set of directories when searching
   for patches.
 Patch files, by default, are ``*.patch`` and ``*.diff`` files created
 and kept in a subdirectory of the directory holding the recipe file. For
@@ -322,13 +317,8 @@ and patch files needed to build the package.
 .. note::
-   In the case for the
+   In the case for the ``bluez5_5.48.bb`` recipe, the ``SRC_URI`` statements
-   bluez5_5.48.bb
+   are from an include file ``bluez5.inc``.
   recipe, the
   SRC_URI
   statements are from an include file
   bluez5.inc
   .
 As mentioned earlier, the build system treats files whose file types are
 ``.patch`` and ``.diff`` as patch files. However, you can use the
@@ -356,7 +346,7 @@ the patch phase, you can use the "apply=no" parameter with the
 In the
 previous example, assuming all the files in the directory holding the
 patch files end with either ``.patch`` or ``.diff``, every file would be
-applied as a patch by default except for the patch_file5 patch.
+applied as a patch by default except for the ``patch_file5`` patch.
 You can find out more about the patching process in the
 ":ref:`patching-dev-environment`" section in
@@ -561,11 +551,9 @@ scratch is guaranteed.
 .. note::
-   The
+   The ``do_cleansstate`` task cannot remove sstate from a remote sstate
-   do_cleansstate
+   mirror. If you need to build a target from scratch using remote mirrors, use
-   task cannot remove sstate from a remote sstate mirror. If you need to
+   the "-f" option as follows:
   build a target from scratch using remote mirrors, use the "-f" option
   as follows:
   ::
      $ bitbake -f -c do_cleansstate target
@@ -609,14 +597,9 @@ Creates or updates the index in the `:ref:`package-feeds-dev-environment` area.
 .. note::
-   This task is not triggered with the
+   This task is not triggered with the ``bitbake -c`` command-line option as
-   bitbake -c
+   are the other tasks in this section. Because this task is specifically for
-   command-line option as are the other tasks in this section. Because
+   the ``package-index`` recipe, you run it using ``bitbake package-index``.
   this task is specifically for the
   package-index
   recipe, you run it using
   bitbake package-index
   .
 Image-Related Tasks
 ===================
@@ -101,12 +101,12 @@ universal, the list includes them just in case:
      .. note::
-         By default, the Build Directory contains :term:`TMPDIR` , which is a
+         By default, the Build Directory contains :term:`TMPDIR`, which is a
-         temporary directory the build system uses for its work. TMPDIR cannot
+         temporary directory the build system uses for its work. ``TMPDIR`` cannot
         be under NFS. Thus, by default, the Build Directory cannot be under
         NFS. However, if you need the Build Directory to be under NFS, you can
-         set this up by setting TMPDIR in your local.conf file to use a local
+         set this up by setting ``TMPDIR`` in your ``local.conf`` file to use a local
-         drive. Doing so effectively separates TMPDIR from TOPDIR , which is the
+         drive. Doing so effectively separates ``TMPDIR`` from :term:`TOPDIR`, which is the
         Build Directory.
   Build Host
@@ -232,7 +232,7 @@ universal, the list includes them just in case:
      core set of recipes.
      You can see the Metadata in the ``meta`` directory of the Yocto
-      Project :yocto_git:`Source Repositories <>`.
+      Project :yocto_git:`Source Repositories </cgit/cgit.cgi/poky>`.
   OpenEmbedded Build System
      The build system specific to the Yocto
@@ -246,9 +246,7 @@ universal, the list includes them just in case:
      .. note::
-         For some historical information about Poky, see the
+         For some historical information about Poky, see the :term:`Poky` term.
         Poky
         term.
   Package
      In the context of the Yocto Project, this term refers to a
@@ -258,10 +256,9 @@ universal, the list includes them just in case:
      It is worth noting that the term "package" can, in general, have
      subtle meanings. For example, the packages referred to in the
-      "`Required Packages for the Build
+      ":ref:`ref-manual/ref-system-requirements:required packages for the build host`"
-      Host <#required-packages-for-the-build-host>`__" section are compiled
+      section are compiled binaries that, when installed, add functionality to
-      binaries that, when installed, add functionality to your Linux
+      your Linux distribution.
      distribution.
      Another point worth noting is that historically within the Yocto
      Project, recipes were referred to as packages - thus, the existence
@@ -65,27 +65,27 @@ and announcements. To subscribe to one of the following mailing lists,
 click on the appropriate URL in the following list and follow the
 instructions:
-  https://lists.yoctoproject.org/g/yocto - General Yocto Project
+-  :yocto_lists:`/g/yocto` - General Yocto Project
   discussion mailing list.
-  https://lists.openembedded.org/g/openembedded-core - Discussion mailing
+-  :oe_lists:`/g/openembedded-core` - Discussion mailing
   list about OpenEmbedded-Core (the core metadata).
-  https://lists.openembedded.org/g/openembedded-devel - Discussion
+-  :oe_lists:`/g/openembedded-devel` - Discussion
   mailing list about OpenEmbedded.
-  https://lists.openembedded.org/g/bitbake-devel - Discussion mailing
+-  :oe_lists:`/g/bitbake-devel` - Discussion mailing
   list about the :term:`BitBake` build tool.
-  https://lists.yoctoproject.org/g/poky - Discussion mailing list
+-  :yocto_lists:`/g/poky` - Discussion mailing list
-   about `Poky <#poky>`__.
+   about :term:`Poky`.
-  https://lists.yoctoproject.org/g/yocto-announce - Mailing list to
+-  :yocto_lists:`/g/yocto-announce` - Mailing list to
   receive official Yocto Project release and milestone announcements.
 For more Yocto Project-related mailing lists, see the
-Yocto Project Website
+:yocto_home:`Yocto Project Website <>`.
-.
+
 .. _resources-irc:
 Internet Relay Chat (IRC)
@@ -113,12 +113,12 @@ Here is a list of resources you might find helpful:
   planning, release engineering, QA & automation, a reference site map,
   and other resources related to the Yocto Project.
-  `OpenEmbedded <http://www.openembedded.org/>`__\ *:* The build system used by the
+-  :oe_home:`OpenEmbedded <>`\ *:* The build system used by the
   Yocto Project. This project is the upstream, generic, embedded
   distribution from which the Yocto Project derives its build system
   (Poky) and to which it contributes.
-  `BitBake <http://www.openembedded.org/wiki/BitBake>`__\ *:* The tool
+-  :oe_home:`BitBake </wiki/BitBake>`\ *:* The tool
   used to process metadata.
 -  :doc:`BitBake User Manual <bitbake:index>`\ *:* A comprehensive
@@ -155,7 +155,7 @@ Here is a list of resources you might find helpful:
   manual provides reference material such as variable, task, and class
   descriptions.
-  `Yocto Project Mega-Manual <https://docs.yoctoproject.org/singleindex.html>`__\ *:* This manual
+-  :yocto_docs:`Yocto Project Mega-Manual </singleindex.html>`\ *:* This manual
   is simply a single HTML file comprised of the bulk of the Yocto
   Project manuals. The Mega-Manual primarily exists as a vehicle by
   which you can easily search for phrases and terms used in the Yocto
@@ -180,7 +180,7 @@ Here is a list of resources you might find helpful:
   the Yocto Project website and click on the "RELEASE INFORMATION" link
   for the appropriate release.
-  `Bugzilla <https://bugzilla.yoctoproject.org>`__\ *:* The bug tracking application
+-  :yocto_bugs:`Bugzilla <>`\ *:* The bug tracking application
   the Yocto Project uses. If you find problems with the Yocto Project,
   you should report them using this application.