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

(From yocto-docs rev: 8e73d870e9dc2df416f5c5cf5b10ef552be0aa6d)

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

documentation/dev-manual/dev-manual-intro.rst

@@ -32,16 +32,14 @@ This manual provides the following:
 
 This manual does not provide the following:
 
--  Redundant Step-by-step Instructions: For example, the `Yocto Project
+-  Redundant Step-by-step Instructions: For example, the
-   Application Development and the Extensible Software Development Kit
+   :doc:`../sdk-manual/sdk-manual` manual contains detailed
-   (eSDK) <&YOCTO_DOCS_SDK_URL;>`__ manual contains detailed
    instructions on how to install an SDK, which is used to develop
    applications for target hardware.
 
 -  Reference or Conceptual Material: This type of material resides in an
    appropriate reference manual. For example, system variables are
-   documented in the `Yocto Project Reference
+   documented in the :doc`../ref-manual/ref-manual`.
-   Manual <&YOCTO_DOCS_REF_URL;>`__.
 
 -  Detailed Public Information Not Specific to the Yocto Project: For
    example, exhaustive information on how to use the Source Control
@@ -56,9 +54,8 @@ supplemental information is recommended for full comprehension. For
 introductory information on the Yocto Project, see the
 :yocto_home:`Yocto Project Website <>`. If you want to build an image with no
 knowledge of Yocto Project as a way of quickly testing it out, see the
-`Yocto Project Quick Build <&YOCTO_DOCS_BRIEF_URL;>`__ document.
+:doc:`../brief-yoctoprojectqs/brief-yoctoprojectqs` document.
 
 For a comprehensive list of links and other documentation, see the
-"`Links and Related
+":ref:`ref-manual/resources:links and related documentation`"
-Documentation <&YOCTO_DOCS_REF_URL;#resources-links-and-related-documentation>`__"
 section in the Yocto Project Reference Manual.

documentation/dev-manual/dev-manual-qemu.rst

@@ -50,8 +50,7 @@ available. Follow these general steps to run QEMU:
 
 1. *Install QEMU:* QEMU is made available with the Yocto Project a
    number of ways. One method is to install a Software Development Kit
-   (SDK). See "`The QEMU
+   (SDK). See ":ref:`sdk-manual/sdk-intro:the qemu emulator`" section in the
-   Emulator <&YOCTO_DOCS_SDK_URL;#the-qemu-emulator>`__" section in the
    Yocto Project Application Development and the Extensible Software
    Development Kit (eSDK) manual for information on how to install QEMU.
 
@@ -60,14 +59,18 @@ available. Follow these general steps to run QEMU:
 
    -  If you cloned the ``poky`` repository or you downloaded and
       unpacked a Yocto Project release tarball, you can source the build
-      environment script (i.e.
+      environment script (i.e. :ref:`structure-core-script`):
-      ````` <&YOCTO_DOCS_REF_URL;#structure-core-script>`__): $ cd
+      ::
-      ~/poky $ source oe-init-build-env
+
+         $ cd ~/poky
+         $ source oe-init-build-env
 
    -  If you installed a cross-toolchain, you can run the script that
       initializes the toolchain. For example, the following commands run
       the initialization script from the default ``poky_sdk`` directory:
-      . ~/poky_sdk/environment-setup-core2-64-poky-linux
+      ::
+
+         . ~/poky_sdk/environment-setup-core2-64-poky-linux
 
 3. *Ensure the Artifacts are in Place:* You need to be sure you have a
    pre-built kernel that will boot in QEMU. You also need the target
@@ -78,18 +81,21 @@ available. Follow these general steps to run QEMU:
       your :term:`Build Directory`.
 
    -  If you have not built an image, you can go to the
-      `machines/qemu <&YOCTO_MACHINES_DL_URL;>`__ area and download a
+      :yocto_dl:`machines/qemu <releases/yocto/yocto-3.1.2/machines/qemu/>` area and download a
       pre-built image that matches your architecture and can be run on
       QEMU.
 
-   See the "`Extracting the Root
+   See the ":ref:`sdk-manual/sdk-appendix-obtain:extracting the root filesystem`"
-   Filesystem <&YOCTO_DOCS_SDK_URL;#sdk-extracting-the-root-filesystem>`__"
    section in the Yocto Project Application Development and the
    Extensible Software Development Kit (eSDK) manual for information on
    how to extract a root filesystem.
 
-4. *Run QEMU:* The basic ``runqemu`` command syntax is as follows: $
+4. *Run QEMU:* The basic ``runqemu`` command syntax is as follows:
-   runqemu [option ] [...] Based on what you provide on the command
+   ::
+
+      $ runqemu [option ] [...]
+
+   Based on what you provide on the command
    line, ``runqemu`` does a good job of figuring out what you are trying
    to do. For example, by default, QEMU looks for the most recently
    built image according to the timestamp when it needs to look for an
@@ -113,30 +119,40 @@ available. Follow these general steps to run QEMU:
          and uses the most recently built image according to the
          timestamp.
 
-      $ runqemu qemux86-64
+      ::
+
+        $ runqemu qemux86-64
 
    -  This example produces the exact same results as the previous
       example. This command, however, specifically provides the image
-      and root filesystem type. $ runqemu qemux86-64 core-image-minimal
+      and root filesystem type.
-      ext4
+      ::
+
+         $ runqemu qemux86-64 core-image-minimal ext4
 
    -  This example specifies to boot an initial RAM disk image and to
       enable audio in QEMU. For this case, ``runqemu`` set the internal
       variable ``FSTYPE`` to "cpio.gz". Also, for audio to be enabled,
       an appropriate driver must be installed (see the previous
-      description for the ``audio`` option for more information). $
+      description for the ``audio`` option for more information).
-      runqemu qemux86-64 ramfs audio
+      ::
+
+         $ runqemu qemux86-64 ramfs audio
 
    -  This example does not provide enough information for QEMU to
       launch. While the command does provide a root filesystem type, it
-      must also minimally provide a MACHINE, KERNEL, or VM option. $
+      must also minimally provide a MACHINE, KERNEL, or VM option.
-      runqemu ext4
+      ::
+
+         $ runqemu ext4
 
    -  This example specifies to boot a virtual machine image
       (``.wic.vmdk`` file). From the ``.wic.vmdk``, ``runqemu``
       determines the QEMU architecture (MACHINE) to be "qemux86-64" and
-      the root filesystem type to be "vmdk". $ runqemu
+      the root filesystem type to be "vmdk".
-      /home/scott-lenovo/vm/core-image-minimal-qemux86-64.wic.vmdk
+      ::
+
+         $ runqemu /home/scott-lenovo/vm/core-image-minimal-qemux86-64.wic.vmdk
 
 Switching Between Consoles
 ==========================
@@ -191,15 +207,19 @@ using an NFS server.
    The ``runqemu-extract-sdk`` takes a root filesystem tarball and
    extracts it into a location that you specify. Here is an example that
    takes a file system and extracts it to a directory named
-   ``test-nfs``: runqemu-extract-sdk
+   ``test-nfs``:
-   ./tmp/deploy/images/qemux86-64/core-image-sato-qemux86-64.tar.bz2
+   ::
-   test-nfs
+
+      runqemu-extract-sdk ./tmp/deploy/images/qemux86-64/core-image-sato-qemux86-64.tar.bz2 test-nfs
 
 2. *Start QEMU:* Once you have extracted the file system, you can run
    ``runqemu`` normally with the additional location of the file system.
    You can then also make changes to the files within ``./test-nfs`` and
    see those changes appear in the image in real time. Here is an
-   example using the ``qemux86`` image: runqemu qemux86-64 ./test-nfs
+   example using the ``qemux86`` image:
+   ::
+
+      runqemu qemux86-64 ./test-nfs
 
 .. note::
 
@@ -297,38 +317,57 @@ present, the toolchain is also automatically used.
 QEMU Command-Line Syntax
 ========================
 
-The basic ``runqemu`` command syntax is as follows: $ runqemu [option ]
+The basic ``runqemu`` command syntax is as follows:
-[...] Based on what you provide on the command line, ``runqemu`` does a
+::
+
+   $ runqemu [option ] [...]
+
+Based on what you provide on the command line, ``runqemu`` does a
 good job of figuring out what you are trying to do. For example, by
 default, QEMU looks for the most recently built image according to the
 timestamp when it needs to look for an image. Minimally, through the use
 of options, you must provide either a machine name, a virtual machine
 image (``*wic.vmdk``), or a kernel image (``*.bin``).
 
-Following is the command-line help output for the ``runqemu`` command: $
+Following is the command-line help output for the ``runqemu`` command:
-runqemu --help Usage: you can run this script with any valid combination
+::
-of the following environment variables (in any order): KERNEL - the
+
-kernel image file to use ROOTFS - the rootfs image file or nfsroot
+   $ runqemu --help
-directory to use MACHINE - the machine name (optional, autodetected from
+
-KERNEL filename if unspecified) Simplified QEMU command-line options can
+   Usage: you can run this script with any valid combination
-be passed with: nographic - disable video console serial - enable a
+   of the following environment variables (in any order):
-serial console on /dev/ttyS0 slirp - enable user networking, no root
+     KERNEL - the kernel image file to use
-privileges is required kvm - enable KVM when running x86/x86_64
+     ROOTFS - the rootfs image file or nfsroot directory to use
-(VT-capable CPU required) kvm-vhost - enable KVM with vhost when running
+     MACHINE - the machine name (optional, autodetected from KERNEL filename if unspecified)
-x86/x86_64 (VT-capable CPU required) publicvnc - enable a VNC server
+     Simplified QEMU command-line options can be passed with:
-open to all hosts audio - enable audio [*/]ovmf\* - OVMF firmware file
+       nographic - disable video console
-or base name for booting with UEFI tcpserial=<port> - specify tcp serial
+       serial - enable a serial console on /dev/ttyS0
-port number biosdir=<dir> - specify custom bios dir
+       slirp - enable user networking, no root privileges is required
-biosfilename=<filename> - specify bios filename qemuparams=<xyz> -
+       kvm - enable KVM when running x86/x86_64 (VT-capable CPU required)
-specify custom parameters to QEMU bootparams=<xyz> - specify custom
+       kvm-vhost - enable KVM with vhost when running x86/x86_64 (VT-capable CPU required)
-kernel parameters during boot help, -h, --help: print this text
+       publicvnc - enable a VNC server open to all hosts
-Examples: runqemu runqemu qemuarm runqemu tmp/deploy/images/qemuarm
+       audio - enable audio
-runqemu tmp/deploy/images/qemux86/<qemuboot.conf> runqemu qemux86-64
+       [*/]ovmf* - OVMF firmware file or base name for booting with UEFI
-core-image-sato ext4 runqemu qemux86-64 wic-image-minimal wic runqemu
+     tcpserial=<port> - specify tcp serial port number
-path/to/bzImage-qemux86.bin path/to/nfsrootdir/ serial runqemu qemux86
+     biosdir=<dir> - specify custom bios dir
-iso/hddimg/wic.vmdk/wic.qcow2/wic.vdi/ramfs/cpio.gz... runqemu qemux86
+     biosfilename=<filename> - specify bios filename
-qemuparams="-m 256" runqemu qemux86 bootparams="psplash=false" runqemu
+     qemuparams=<xyz> - specify custom parameters to QEMU
-path/to/<image>-<machine>.wic runqemu path/to/<image>-<machine>.wic.vmdk
+     bootparams=<xyz> - specify custom kernel parameters during boot
+     help, -h, --help: print this text
+
+   Examples:
+     runqemu
+     runqemu qemuarm
+     runqemu tmp/deploy/images/qemuarm
+     runqemu tmp/deploy/images/qemux86/<qemuboot.conf>
+     runqemu qemux86-64 core-image-sato ext4
+     runqemu qemux86-64 wic-image-minimal wic
+     runqemu path/to/bzImage-qemux86.bin path/to/nfsrootdir/ serial
+     runqemu qemux86 iso/hddimg/wic.vmdk/wic.qcow2/wic.vdi/ramfs/cpio.gz...
+     runqemu qemux86 qemuparams="-m 256"
+     runqemu qemux86 bootparams="psplash=false"
+     runqemu path/to/<image>-<machine>.wic
+     runqemu path/to/<image>-<machine>.wic.vmdk
 
 .. _qemu-dev-runqemu-command-line-options:
 

documentation/dev-manual/dev-manual-start.rst

@@ -5,9 +5,9 @@ Setting Up to Use the Yocto Project
 ***********************************
 
 This chapter provides guidance on how to prepare to use the Yocto
-Project. You can learn about creating a team environment that develops
+Project. You can learn about creating a team environment to develop
-using the Yocto Project, how to set up a `build
+using the Yocto Project, how to set up a :ref:`build
-host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__, how to locate
+host <dev-manual/dev-manual-start:preparing the build host>`, how to locate
 Yocto Project source repositories, and how to create local Git
 repositories.
 
@@ -79,8 +79,9 @@ particular working environment and set of practices.
     configuration files, classes, and so forth) and any software you are
     developing under the control of an SCM system that is compatible
     with the OpenEmbedded build system is advisable. Of all of the SCMs
-    supported by BitBake, the Yocto Project team strongly recommends
+    supported by BitBake, the Yocto Project team strongly recommends using
-    using `Git <&YOCTO_DOCS_OM_URL;#git>`__. Git is a distributed system
+    :ref:`overview-manual/overview-manual-development-environment:git`.
+    Git is a distributed system
     that is easy to back up, allows you to work remotely, and then
     connects back to the infrastructure.
 
@@ -171,8 +172,8 @@ particular working environment and set of practices.
 
     -  Highlights when commits break the build.
 
-    -  Populates an `sstate
+    -  Populates an :ref:`sstate
-       cache <&YOCTO_DOCS_OM_URL;#shared-state-cache>`__ from which
+       cache <overview-manual/overview-manual-concepts:shared state cache>` from which
        developers can pull rather than requiring local builds.
 
     -  Allows commit hook triggers, which trigger builds when commits
@@ -226,20 +227,17 @@ particular working environment and set of practices.
     some best practices exist within the Yocto Project development
     environment. Consider the following:
 
-    -  Use `Git <&YOCTO_DOCS_OM_URL;#git>`__ as the source control
+    -  Use :ref:`overview-manual/overview-manual-development-environment:git` as the source control
        system.
 
     -  Maintain your Metadata in layers that make sense for your
-       situation. See the "`The Yocto Project Layer
+       situation. See the ":ref:`overview-manual/overview-manual-yp-intro:the yocto project layer model`"
-       Model <&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model>`__"
        section in the Yocto Project Overview and Concepts Manual and the
-       "`Understanding and Creating
+       ":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`"
-       Layers <#understanding-and-creating-layers>`__" section for more
+       section for more information on layers.
-       information on layers.
 
     -  Separate the project's Metadata and code by using separate Git
-       repositories. See the "`Yocto Project Source
+       repositories. See the ":ref:`overview-manual/overview-manual-development-environment:yocto project source repositories`"
-       Repositories <&YOCTO_DOCS_OM_URL;#yocto-project-repositories>`__"
        section in the Yocto Project Overview and Concepts Manual for
        information on these repositories. See the "`Locating Yocto
        Project Source Files <#locating-yocto-project-source-files>`__"
@@ -258,15 +256,16 @@ particular working environment and set of practices.
     -  The Yocto Project community encourages you to send patches to the
        project to fix bugs or add features. If you do submit patches,
        follow the project commit guidelines for writing good commit
-       messages. See the "`Submitting a Change to the Yocto
+       messages. See the
-       Project <#how-to-submit-a-change>`__" section.
+       ":ref:`dev-manual/dev-manual-common-tasks:submitting a change to the yocto project`"
+       section.
 
     -  Send changes to the core sooner than later as others are likely
        to run into the same issues. For some guidance on mailing lists
-       to use, see the list in the "`Submitting a Change to the Yocto
+       to use, see the list in the
-       Project <#how-to-submit-a-change>`__" section. For a description
+       ":ref:`dev-manual/dev-manual-common-tasks:submitting a change to the yocto project`"
-       of the available mailing lists, see the "`Mailing
+       section. For a description
-       Lists <&YOCTO_DOCS_REF_URL;#resources-mailinglist>`__" section in
+       of the available mailing lists, see the ":ref:`resources-mailinglist`" section in
        the Yocto Project Reference Manual.
 
 .. _dev-preparing-the-build-host:
@@ -275,7 +274,7 @@ Preparing the Build Host
 ========================
 
 This section provides procedures to set up a system to be used as your
-`build host <&YOCTO_DOCS_REF_URL;#hardware-build-system-term>`__ for
+:term:`Build Host` for
 development using the Yocto Project. Your build host can be a native
 Linux machine (recommended), it can be a machine (Linux, Mac, or
 Windows) that uses `CROPS <https://github.com/crops/poky-container>`__,
@@ -297,15 +296,11 @@ are necessary depending on what you want to accomplish. See the
 following references for information on how to prepare for Board Support
 Package (BSP) development and kernel development:
 
--  *BSP Development:* See the "`Preparing Your Build Host to Work With
+-  *BSP Development:* See the ":ref:`bsp-guide/bsp:preparing your build host to work with bsp layers`"
-   BSP
-   Layers <&YOCTO_DOCS_BSP_URL;#preparing-your-build-host-to-work-with-bsp-layers>`__"
    section in the Yocto Project Board Support Package (BSP) Developer's
    Guide.
 
--  *Kernel Development:* See the "`Preparing the Build Host to Work on
+-  *Kernel Development:* See the ":ref:`kernel-dev/kernel-dev-common:preparing the build host to work on the kernel`"
-   the
-   Kernel <&YOCTO_DOCS_KERNEL_DEV_URL;#preparing-the-build-host-to-work-on-the-kernel>`__"
    section in the Yocto Project Linux Kernel Development Manual.
 
 Setting Up a Native Linux Host
@@ -319,8 +314,8 @@ Project Build Host:
    a recent release of Fedora, openSUSE, Debian, Ubuntu, RHEL or CentOS
    as these releases are frequently tested against the Yocto Project and
    officially supported. For a list of the distributions under
-   validation and their status, see the "`Supported Linux
+   validation and their status, see the ":ref:`Supported Linux
-   Distributions <&YOCTO_DOCS_REF_URL;#detailed-supported-distros>`__"
+   Distributions <detailed-supported-distros>`"
    section in the Yocto Project Reference Manual and the wiki page at
    :yocto_wiki:`Distribution Support </wiki/Distribution_Support>`.
 
@@ -341,9 +336,8 @@ Project Build Host:
 
    If your build host does not meet any of these three listed version
    requirements, you can take steps to prepare the system so that you
-   can still use the Yocto Project. See the "`Required Git, tar, Python
+   can still use the Yocto Project. See the
-   and gcc
+   ":ref:`ref-manual/ref-system-requirements:required git, tar, python and gcc versions`"
-   Versions <&YOCTO_DOCS_REF_URL;#required-git-tar-python-and-gcc-versions>`__"
    section in the Yocto Project Reference Manual for information.
 
 4. *Install Development Host Packages:* Required development host
@@ -351,23 +345,19 @@ Project Build Host:
    with the Yocto Project. Collectively, the number of required packages
    is large if you want to be able to cover all cases.
 
-   For lists of required packages for all scenarios, see the "`Required
+   For lists of required packages for all scenarios, see the
-   Packages for the Build
+   ":ref:`ref-manual/ref-system-requirements:required packages for the build host`"
-   Host <&YOCTO_DOCS_REF_URL;#required-packages-for-the-build-host>`__"
    section in the Yocto Project Reference Manual.
 
 Once you have completed the previous steps, you are ready to continue
 using a given development path on your native Linux machine. If you are
-going to use BitBake, see the "`Cloning the ``poky``
+going to use BitBake, see the
-Repository <#cloning-the-poky-repository>`__" section. If you are going
+":ref:`dev-manual/dev-manual-start:cloning the \`\`poky\`\` repository`"
-to use the Extensible SDK, see the "`Using the Extensible
+section. If you are going
-SDK <&YOCTO_DOCS_SDK_URL;#sdk-extensible>`__" Chapter in the Yocto
+to use the Extensible SDK, see the ":doc:`../sdk-manual/sdk-extensible`" Chapter in the Yocto
 Project Application Development and the Extensible Software Development
-Kit (eSDK) manual. If you want to work on the kernel, see the `Yocto
+Kit (eSDK) manual. If you want to work on the kernel, see the :doc:`../kernel-dev/kernel-dev`. If you are going to use
-Project Linux Kernel Development
+Toaster, see the ":doc:`../toaster-manual/toaster-manual-setup-and-use`"
-Manual <&YOCTO_DOCS_KERNEL_DEV_URL;>`__. If you are going to use
-Toaster, see the "`Setting Up and Using
-Toaster <&YOCTO_DOCS_TOAST_URL;#toaster-manual-setup-and-use>`__"
 section in the Toaster User Manual.
 
 .. _setting-up-to-use-crops:
@@ -465,12 +455,11 @@ Once you have a container set up, everything is in place to develop just
 as if you were running on a native Linux machine. If you are going to
 use the Poky container, see the "`Cloning the ``poky``
 Repository <#cloning-the-poky-repository>`__" section. If you are going
-to use the Extensible SDK container, see the "`Using the Extensible
+to use the Extensible SDK container, see the
-SDK <&YOCTO_DOCS_SDK_URL;#sdk-extensible>`__" Chapter in the Yocto
+":doc:`../sdk-manual/sdk-extensible`" Chapter in the Yocto
 Project Application Development and the Extensible Software Development
 Kit (eSDK) manual. If you are going to use the Toaster container, see
-the "`Setting Up and Using
+the ":doc:`../toaster-manual/toaster-manual-setup-and-use`"
-Toaster <&YOCTO_DOCS_TOAST_URL;#toaster-manual-setup-and-use>`__"
 section in the Toaster User Manual.
 
 .. _setting-up-to-use-wsl:
@@ -490,8 +479,14 @@ your Yocto Project build host:
 1. *Make sure your Windows 10 machine is capable of running WSLv2:*
    WSLv2 is only available for Windows 10 builds > 18917. To check which
    build version you are running, you may open a command prompt on
-   Windows and execute the command "ver". C:\Users\myuser> ver Microsoft
+   Windows and execute the command "ver".
-   Windows [Version 10.0.19041.153] If your build is capable of running
+   ::
+
+      C:\Users\myuser> ver
+
+      Microsoft Windows [Version 10.0.19041.153]
+
+   If your build is capable of running
    WSLv2 you may continue, for more information on this subject or
    instructions on how to upgrade to WSLv2 visit `Windows 10
    WSLv2 <https://docs.microsoft.com/en-us/windows/wsl/wsl2-install>`__
@@ -507,8 +502,14 @@ your Yocto Project build host:
    distribution.
 
 3. *Check your Linux distribution is using WSLv2:* Open a Windows
-   PowerShell and run: C:\WINDOWS\system32> wsl -l -v NAME STATE VERSION
+   PowerShell and run:
-   \*Ubuntu Running 2 Note the version column which says the WSL version
+   ::
+
+      C:\WINDOWS\system32> wsl -l -v
+      NAME    STATE   VERSION
+      *Ubuntu Running 2
+
+   Note the version column which says the WSL version
    being used by your distribution, on compatible systems, this can be
    changed back at any point in time.
 
@@ -529,25 +530,35 @@ your Yocto Project build host:
 
    1. *Find the location of your VHDX file:* First you need to find the
       distro app package directory, to achieve this open a Windows
-      Powershell as Administrator and run: C:\WINDOWS\system32>
+      Powershell as Administrator and run:
-      Get-AppxPackage -Name "*Ubuntu*" \| Select PackageFamilyName
+      ::
-      PackageFamilyName -----------------
+
-      CanonicalGroupLimited.UbuntuonWindows_79abcdefgh You should now
+         C:\WINDOWS\system32> Get-AppxPackage -Name "*Ubuntu*" | Select PackageFamilyName
+         PackageFamilyName
+         -----------------
+         CanonicalGroupLimited.UbuntuonWindows_79abcdefgh
+
+
+      You should now
       replace the PackageFamilyName and your user on the following path
       to find your VHDX file:
-      ``C:\Users\user\AppData\Local\Packages\PackageFamilyName\LocalState\``
+      ::
-      For example: ls
+
-      C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\\
+          ls C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\
-      Mode LastWriteTime Length Name -a---- 3/14/2020 9:52 PM
+          Mode                 LastWriteTime         Length Name
-      57418973184 ext4.vhdx Your VHDX file path is:
+          -a----         3/14/2020   9:52 PM    57418973184 ext4.vhdx
+
+      Your VHDX file path is:
       ``C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx``
 
    2. *Optimize your VHDX file:* Open a Windows Powershell as
       Administrator to optimize your VHDX file, shutting down WSL first:
-      C:\WINDOWS\system32> wsl --shutdown C:\WINDOWS\system32>
+      ::
-      optimize-vhd -Path
+
-      C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx
+         C:\WINDOWS\system32> wsl --shutdown
-      -Mode full A progress bar should be shown while optimizing the
+         C:\WINDOWS\system32> optimize-vhd -Path C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\ext4.vhdx -Mode full
+
+      A progress bar should be shown while optimizing the
       VHDX file, and storage should now be reflected correctly on the
       Windows Explorer.
 
@@ -565,12 +576,10 @@ your Yocto Project build host:
 
 Once you have WSLv2 set up, everything is in place to develop just as if
 you were running on a native Linux machine. If you are going to use the
-Extensible SDK container, see the "`Using the Extensible
+Extensible SDK container, see the ":doc:`../sdk-manual/sdk-extensible`" Chapter in the Yocto
-SDK <&YOCTO_DOCS_SDK_URL;#sdk-extensible>`__" Chapter in the Yocto
 Project Application Development and the Extensible Software Development
 Kit (eSDK) manual. If you are going to use the Toaster container, see
-the "`Setting Up and Using
+the ":doc:`../toaster-manual/toaster-manual-setup-and-use`"
-Toaster <&YOCTO_DOCS_TOAST_URL;#toaster-manual-setup-and-use>`__"
 section in the Toaster User Manual.
 
 Locating Yocto Project Source Files
@@ -582,19 +591,17 @@ files you'll need to work with the Yocto Project.
 .. note::
 
    -  For concepts and introductory information about Git as it is used
-      in the Yocto Project, see the "`Git <&YOCTO_DOCS_OM_URL;#git>`__"
+      in the Yocto Project, see the ":ref:`overview-manual/overview-manual-development-environment:git`"
       section in the Yocto Project Overview and Concepts Manual.
 
-   -  For concepts on Yocto Project source repositories, see the "`Yocto
+   -  For concepts on Yocto Project source repositories, see the
-      Project Source
+      ":ref:`overview-manual/overview-manual-development-environment:yocto project source repositories`"
-      Repositories <&YOCTO_DOCS_OM_URL;#yocto-project-repositories>`__"
       section in the Yocto Project Overview and Concepts Manual."
 
 Accessing Source Repositories
 -----------------------------
 
-Working from a copy of the upstream Yocto Project `Source
+Working from a copy of the upstream :ref:`dev-manual/dev-manual-start:accessing source repositories` is the
-Repositories <&YOCTO_DOCS_OM_URL;#source-repositories>`__ is the
 preferred method for obtaining and using a Yocto Project release. You
 can view the Yocto Project Source Repositories at
 :yocto_git:`/`. In particular, you can find the ``poky``
@@ -611,8 +618,7 @@ Use the following procedure to locate the latest upstream copy of the
    interested (e.g. ``poky``).
 
 3. *Find the URL Used to Clone the Repository:* At the bottom of the
-   page, note the URL used to
+   page, note the URL used to clone that repository
-   `clone <&YOCTO_DOCS_OM_URL;#git-commands-clone>`__ that repository
    (e.g. :yocto_git:`/git/poky`).
 
    .. note::
@@ -658,9 +664,9 @@ Follow these steps to locate and download a particular tarball:
    are interested (e.g. ``yocto``).
 
 3. *Find the Tarball:* Drill down to find the associated tarball. For
-   example, click on ``yocto-DISTRO`` to view files associated with the
+   example, click on ``yocto-&DISTRO;`` to view files associated with the
-   Yocto Project DISTRO release (e.g.
+   Yocto Project &DISTRO; release (e.g.
-   ``poky-DISTRO_NAME_NO_CAP-POKYVERSION.tar.bz2``, which is the
+   ``&YOCTO_POKY;.tar.bz2``, which is the
    released Poky tarball).
 
 4. *Download the Tarball:* Click the tarball to download and save a
@@ -691,8 +697,7 @@ Releases <#accessing-index-of-releases>`__" section.
 
 3. *Select a Yocto Project Release:* Use the menu next to "RELEASE" to
    display and choose a recent or past supported Yocto Project release
-   (e.g. DISTRO_NAME_NO_CAP, DISTRO_NAME_NO_CAP_MINUS_ONE, and so
+   (e.g. &DISTRO_NAME_NO_CAP;, &DISTRO_NAME_NO_CAP_MINUS_ONE;, and so forth).
-   forth).
 
    .. note::
 
@@ -711,7 +716,7 @@ Accessing Nightly Builds
 ------------------------
 
 Yocto Project maintains an area for nightly builds that contains tarball
-releases at ` <&YOCTO_AB_NIGHTLY_URL;>`__. These builds include Yocto
+releases at https://autobuilder.yocto.io//pub/nightly/. These builds include Yocto
 Project releases ("poky"), toolchains, and builds for supported
 machines.
 
@@ -719,7 +724,7 @@ Should you ever want to access a nightly build of a particular Yocto
 Project component, use the following procedure:
 
 1. *Locate the Index of Nightly Builds:* Open a browser and go to
-   ` <&YOCTO_AB_NIGHTLY_URL;>`__ to access the Nightly Builds.
+   https://autobuilder.yocto.io//pub/nightly/ to access the Nightly Builds.
 
 2. *Select a Date:* Click on the date in which you are interested. If
    you want the latest builds, use "CURRENT".
@@ -739,11 +744,10 @@ Cloning and Checking Out Branches
 To use the Yocto Project for development, you need a release locally
 installed on your development system. This locally installed set of
 files is referred to as the :term:`Source Directory`
- in the Yocto
+in the Yocto Project documentation.
-Project documentation.
 
 The preferred method of creating your Source Directory is by using
-`Git <&YOCTO_DOCS_OM_URL;#git>`__ to clone a local copy of the upstream
+:ref:`overview-manual/overview-manual-development-environment:git` to clone a local copy of the upstream
 ``poky`` repository. Working from a cloned copy of the upstream
 repository allows you to contribute back into the Yocto Project or to
 simply work with the latest software on a development branch. Because
@@ -756,19 +760,26 @@ Cloning the ``poky`` Repository
 -------------------------------
 
 Follow these steps to create a local version of the upstream
-```poky`` <&YOCTO_DOCS_REF_URL;#poky>`__ Git repository.
+:term:`Poky` Git repository.
 
 1. *Set Your Directory:* Change your working directory to where you want
    to create your local copy of ``poky``.
 
 2. *Clone the Repository:* The following example command clones the
    ``poky`` repository and uses the default name "poky" for your local
-   repository: $ git clone git://git.yoctoproject.org/poky Cloning into
+   repository:
-   'poky'... remote: Counting objects: 432160, done. remote: Compressing
+   ::
-   objects: 100% (102056/102056), done. remote: Total 432160 (delta
+
-   323116), reused 432037 (delta 323000) Receiving objects: 100%
+      $ git clone git://git.yoctoproject.org/poky
-   (432160/432160), 153.81 MiB \| 8.54 MiB/s, done. Resolving deltas:
+      Cloning into 'poky'...
-   100% (323116/323116), done. Checking connectivity... done. Unless you
+      remote: Counting objects: 432160, done.
+      remote: Compressing objects: 100% (102056/102056), done.
+      remote: Total 432160 (delta 323116), reused 432037 (delta 323000)
+      Receiving objects: 100% (432160/432160), 153.81 MiB | 8.54 MiB/s, done.
+      Resolving deltas: 100% (323116/323116), done.
+      Checking connectivity... done.
+
+   Unless you
    specify a specific development branch or tag name, Git clones the
    "master" branch, which results in a snapshot of the latest
    development changes for "master". For information on how to check out
@@ -779,13 +790,21 @@ Follow these steps to create a local version of the upstream
 
    Once the local repository is created, you can change to that
    directory and check its status. Here, the single "master" branch
-   exists on your system and by default, it is checked out: $ cd ~/poky
+   exists on your system and by default, it is checked out:
-   $ git status On branch master Your branch is up-to-date with
+   ::
-   'origin/master'. nothing to commit, working directory clean $ git
+
-   branch \* master Your local repository of poky is identical to the
+      $ cd ~/poky
+      $ git status
+      On branch master
+      Your branch is up-to-date with 'origin/master'.
+      nothing to commit, working directory clean
+      $ git branch
+      * master
+
+   Your local repository of poky is identical to the
    upstream poky repository at the time from which it was cloned. As you
    work with the local branch, you can periodically use the
-   ``git pull DASHDASHrebase`` command to be sure you are up-to-date
+   ``git pull --rebase`` command to be sure you are up-to-date
    with the upstream branch.
 
 Checking Out by Branch in Poky
@@ -809,28 +828,48 @@ and then specifically check out that development branch.
    copy of poky, see the "`Cloning the ``poky``
    Repository <#cloning-the-poky-repository>`__" section.
 
-2. *Determine Existing Branch Names:* $ git branch -a \* master
+2. *Determine Existing Branch Names:*
-   remotes/origin/1.1_M1 remotes/origin/1.1_M2 remotes/origin/1.1_M3
+   ::
-   remotes/origin/1.1_M4 remotes/origin/1.2_M1 remotes/origin/1.2_M2
+
-   remotes/origin/1.2_M3 . . . remotes/origin/thud
+      $ git branch -a
-   remotes/origin/thud-next remotes/origin/warrior
+      * master
-   remotes/origin/warrior-next remotes/origin/zeus
+      remotes/origin/1.1_M1
-   remotes/origin/zeus-next ... and so on ...
+      remotes/origin/1.1_M2
+      remotes/origin/1.1_M3
+      remotes/origin/1.1_M4
+      remotes/origin/1.2_M1
+      remotes/origin/1.2_M2
+      remotes/origin/1.2_M3
+      . . .
+      remotes/origin/thud
+      remotes/origin/thud-next
+      remotes/origin/warrior
+      remotes/origin/warrior-next
+      remotes/origin/zeus
+      remotes/origin/zeus-next
+      ... and so on ...
 
 3. *Check out the Branch:* Check out the development branch in which you
    want to work. For example, to access the files for the Yocto Project
-   DISTRO Release (DISTRO_NAME), use the following command: $ git
+   &DISTRO; Release (&DISTRO_NAME;), use the following command:
-   checkout -b DISTRO_NAME_NO_CAP origin/DISTRO_NAME_NO_CAP Branch
+   ::
-   DISTRO_NAME_NO_CAP set up to track remote branch DISTRO_NAME_NO_CAP
+
-   from origin. Switched to a new branch 'DISTRO_NAME_NO_CAP' The
+      $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
-   previous command checks out the "DISTRO_NAME_NO_CAP" development
+      Branch &DISTRO_NAME; set up to track remote branch &DISTRO_NAME; from origin.
+      Switched to a new branch '&DISTRO_NAME;'
+
+   The previous command checks out the "&DISTRO_NAME;" development
    branch and reports that the branch is tracking the upstream
-   "origin/DISTRO_NAME_NO_CAP" branch.
+   "origin/&DISTRO_NAME;" branch.
 
    The following command displays the branches that are now part of your
    local poky repository. The asterisk character indicates the branch
-   that is currently checked out for work: $ git branch master \*
+   that is currently checked out for work:
-   DISTRO_NAME_NO_CAP
+   ::
+
+      $ git branch
+        master *
+        &DISTRO_NAME;
 
 .. _checkout-out-by-tag-in-poky:
 
@@ -854,20 +893,48 @@ similar to checking out by branch name except you use tag names.
    Repository <#cloning-the-poky-repository>`__" section.
 
 2. *Fetch the Tag Names:* To checkout the branch based on a tag name,
-   you need to fetch the upstream tags into your local repository: $ git
+   you need to fetch the upstream tags into your local repository:
-   fetch --tags $
+   ::
 
-3. *List the Tag Names:* You can list the tag names now: $ git tag
+      $ git fetch --tags
-   1.1_M1.final 1.1_M1.rc1 1.1_M1.rc2 1.1_M2.final 1.1_M2.rc1 . . .
+      $
-   yocto-2.5 yocto-2.5.1 yocto-2.5.2 yocto-2.5.3 yocto-2.6 yocto-2.6.1
-   yocto-2.6.2 yocto-2.7 yocto_1.5_M5.rc8
 
-4. *Check out the Branch:* $ git checkout tags/DISTRO_REL_TAG -b
+3. *List the Tag Names:* You can list the tag names now:
-   my_yocto_DISTRO Switched to a new branch 'my_yocto_DISTRO' $ git
+   ::
-   branch master \* my_yocto_DISTRO The previous command creates and
+
-   checks out a local branch named "my_yocto_DISTRO", which is based on
+      $ git tag
+      1.1_M1.final
+      1.1_M1.rc1
+      1.1_M1.rc2
+      1.1_M2.final
+      1.1_M2.rc1
+         .
+         .
+         .
+      yocto-2.5
+      yocto-2.5.1
+      yocto-2.5.2
+      yocto-2.5.3
+      yocto-2.6
+      yocto-2.6.1
+      yocto-2.6.2
+      yocto-2.7
+      yocto_1.5_M5.rc8
+
+
+4. *Check out the Branch:*
+   ::
+
+      $ git checkout tags/yocto-&DISTRO; -b my_yocto_&DISTRO;
+      Switched to a new branch 'my_yocto_&DISTRO;'
+      $ git branch
+        master
+      * my_yocto_&DISTRO;
+
+   The previous command creates and
+   checks out a local branch named "my_yocto_&DISTRO;", which is based on
    the commit in the upstream poky repository that has the same tag. In
    this example, the files you have available locally as a result of the
-   ``checkout`` command are a snapshot of the "DISTRO_NAME_NO_CAP"
+   ``checkout`` command are a snapshot of the "&DISTRO_NAME_NO_CAP;"
-   development branch at the point where Yocto Project DISTRO was
+   development branch at the point where Yocto Project &DISTRO; was
    released.