sphinx: ref-manual links fixes and many other cleanups to import

(From yocto-docs rev: d079e418d5a81610e1f06a7a6ca45dd040c1402e)

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

1 files changed, 81 insertions, 48 deletions

diff --git a/documentation/ref-manual/faq.rst b/documentation/ref-manual/faq.rst
index e25f0b278c..04066e9202 100644
--- a/documentation/ref-manual/faq.rst
+++ b/documentation/ref-manual/faq.rst
@@ -4,9 +4,9 @@
 FAQ
 ***
 
-**Q:** How does Poky differ from `OpenEmbedded <&OE_HOME_URL;>`__?
+**Q:** How does Poky differ from `OpenEmbedded <http://www.openembedded.org/>`__?
 
-**A:** The term "`Poky <#>`__" refers to the specific reference build
+**A:** The term ``Poky`` refers to the specific reference build
 system that the Yocto Project provides. Poky is based on
 :term:`OpenEmbedded-Core (OE-Core)` and :term:`BitBake`. Thus, the
 generic term used here for the build system is the "OpenEmbedded build
@@ -44,11 +44,10 @@ steps on how to update your build tools.
 
 **A:** Support for an additional board is added by creating a Board
 Support Package (BSP) layer for it. For more information on how to
-create a BSP layer, see the "`Understanding and Creating
-Layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__"
-section in the Yocto Project Development Tasks Manual and the `Yocto
-Project Board Support Package (BSP) Developer's
-Guide <&YOCTO_DOCS_BSP_URL;>`__.
+create a BSP layer, see the
+":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`"
+section in the Yocto Project Development Tasks Manual and the
+:doc:`../bsp-guide/bsp-guide`.
 
 Usually, if the board is not completely exotic, adding support in the
 Yocto Project is fairly straightforward.
@@ -73,8 +72,8 @@ device.
 **Q:** How do I add my package to the Yocto Project?
 
 **A:** To add a package, you need to create a BitBake recipe. For
-information on how to create a BitBake recipe, see the "`Writing a New
-Recipe <&YOCTO_DOCS_DEV_URL;#new-recipe-writing-a-new-recipe>`__"
+information on how to create a BitBake recipe, see the
+":ref:`dev-manual/dev-manual-common-tasks:writing a new recipe`"
 section in the Yocto Project Development Tasks Manual.
 
 **Q:** Do I have to reflash my entire board with a new Yocto Project
@@ -126,12 +125,18 @@ file.
 
 Following is the applicable code for setting various proxy types in the
 ``.wgetrc`` file. By default, these settings are disabled with comments.
-To use them, remove the comments: # You can set the default proxies for
-Wget to use for http, https, and ftp. # They will override the value in
-the environment. #https_proxy = http://proxy.yoyodyne.com:18023/
-#http_proxy = http://proxy.yoyodyne.com:18023/ #ftp_proxy =
-http://proxy.yoyodyne.com:18023/ # If you do not want to use proxy at
-all, set this to off. #use_proxy = on The Yocto Project also includes a
+To use them, remove the comments: ::
+
+   # You can set the default proxies for Wget to use for http, https, and ftp.
+   # They will override the value in the environment.
+   #https_proxy = http://proxy.yoyodyne.com:18023/
+   #http_proxy = http://proxy.yoyodyne.com:18023/
+   #ftp_proxy = http://proxy.yoyodyne.com:18023/
+
+   # If you do not want to use proxy at all, set this to off.
+   #use_proxy = on
+
+The Yocto Project also includes a
 ``meta-poky/conf/site.conf.sample`` file that shows how to configure CVS
 and Git proxy servers if needed. For more information on setting up
 various proxy types and configuring proxy servers, see the
@@ -167,8 +172,12 @@ always been traced back to hardware or virtualization issues.
 **A:** If you get an error message that indicates GNU ``libiconv`` is
 not in use but ``iconv.h`` has been included from ``libiconv``, you need
 to check to see if you have a previously installed version of the header
-file in ``/usr/local/include``. #error GNU libiconv not in use but
-included iconv.h is from libiconv If you find a previously installed
+file in ``/usr/local/include``.
+::
+
+   #error GNU libiconv not in use but included iconv.h is from libiconv
+
+If you find a previously installed
 file, you should either uninstall it or temporarily rename it and try
 the build again.
 
@@ -189,20 +198,21 @@ and also any configuration information about how that package was
 configured and built.
 
 You can find more information on licensing in the
-"`Licensing <&YOCTO_DOCS_OM_URL;#licensing>`__" section in the Yocto
-Project Overview and Concepts Manual and also in the "`Maintaining Open
-Source License Compliance During Your Product's
-Lifecycle <&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle>`__"
+":ref:`overview-manual/overview-manual-development-environment:licensing`"
+section in the Yocto
+Project Overview and Concepts Manual and also in the
+":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`"
 section in the Yocto Project Development Tasks Manual.
 
 **Q:** How do I disable the cursor on my touchscreen device?
 
 **A:** You need to create a form factor file as described in the
-"`Miscellaneous BSP-Specific Recipe
-Files <&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes>`__" section in
+":ref:`bsp-filelayout-misc-recipes`" section in
 the Yocto Project Board Support Packages (BSP) Developer's Guide. Set
 the ``HAVE_TOUCHSCREEN`` variable equal to one as follows:
-HAVE_TOUCHSCREEN=1
+::
+
+   HAVE_TOUCHSCREEN=1
 
 **Q:** How do I make sure connected network interfaces are brought up by
 default?
@@ -210,14 +220,14 @@ default?
 **A:** The default interfaces file provided by the netbase recipe does
 not automatically bring up network interfaces. Therefore, you will need
 to add a BSP-specific netbase that includes an interfaces file. See the
-"`Miscellaneous BSP-Specific Recipe
-Files <&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes>`__" section in
+":ref:`bsp-filelayout-misc-recipes`" section in
 the Yocto Project Board Support Packages (BSP) Developer's Guide for
 information on creating these types of miscellaneous recipe files.
 
-For example, add the following files to your layer:
-meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces
-meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend
+For example, add the following files to your layer: ::
+
+   meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces
+   meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend
 
 **Q:** How do I create images with more free space?
 
@@ -260,7 +270,7 @@ controls which ``tcmode-*.inc`` file to include from the
 The default value of ``TCMODE`` is "default", which tells the
 OpenEmbedded build system to use its internally built toolchain (i.e.
 ``tcmode-default.inc``). However, other patterns are accepted. In
-particular, "external-*" refers to external toolchains. One example is
+particular, "external-\*" refers to external toolchains. One example is
 the Sourcery G++ Toolchain. The support for this toolchain resides in
 the separate ``meta-sourcery`` layer at
 http://github.com/MentorEmbedded/meta-sourcery/.
@@ -290,11 +300,13 @@ fail.
 
 As an example, you could add a specific server for the build system to
 attempt before any others by adding something like the following to the
-``local.conf`` configuration file: PREMIRRORS_prepend = "\\ git://.*/.\*
-http://www.yoctoproject.org/sources/ \\n \\ ftp://.*/.\*
-http://www.yoctoproject.org/sources/ \\n \\ http://.*/.\*
-http://www.yoctoproject.org/sources/ \\n \\ https://.*/.\*
-http://www.yoctoproject.org/sources/ \\n"
+``local.conf`` configuration file: ::
+
+   PREMIRRORS_prepend = "\
+       git://.*/.* http://www.yoctoproject.org/sources/ \n \
+       ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
+       http://.*/.* http://www.yoctoproject.org/sources/ \n \
+       https://.*/.* http://www.yoctoproject.org/sources/ \n"
 
 These changes cause the build system to intercept Git, FTP, HTTP, and
 HTTPS requests and direct them to the ``http://`` sources mirror. You
@@ -302,25 +314,43 @@ can use ``file://`` URLs to point to local directories or network shares
 as well.
 
 Aside from the previous technique, these options also exist:
-BB_NO_NETWORK = "1" This statement tells BitBake to issue an error
+::
+
+   BB_NO_NETWORK = "1"
+
+This statement tells BitBake to issue an error
 instead of trying to access the Internet. This technique is useful if
 you want to ensure code builds only from local sources.
 
-Here is another technique: BB_FETCH_PREMIRRORONLY = "1" This statement
+Here is another technique:
+::
+
+   BB_FETCH_PREMIRRORONLY = "1"
+
+This statement
 limits the build system to pulling source from the ``PREMIRRORS`` only.
 Again, this technique is useful for reproducing builds.
 
-Here is another technique: BB_GENERATE_MIRROR_TARBALLS = "1" This
+Here is another technique:
+::
+
+   BB_GENERATE_MIRROR_TARBALLS = "1"
+
+This
 statement tells the build system to generate mirror tarballs. This
 technique is useful if you want to create a mirror server. If not,
 however, the technique can simply waste time during the build.
 
 Finally, consider an example where you are behind an HTTP-only firewall.
 You could make the following changes to the ``local.conf`` configuration
-file as long as the ``PREMIRRORS`` server is current: PREMIRRORS_prepend
-= "\\ ftp://.*/.\* http://www.yoctoproject.org/sources/ \\n \\
-http://.*/.\* http://www.yoctoproject.org/sources/ \\n \\ https://.*/.\*
-http://www.yoctoproject.org/sources/ \\n" BB_FETCH_PREMIRRORONLY = "1"
+file as long as the ``PREMIRRORS`` server is current: ::
+
+   PREMIRRORS_prepend = "\
+       ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
+       http://.*/.* http://www.yoctoproject.org/sources/ \n \
+       https://.*/.* http://www.yoctoproject.org/sources/ \n"
+   BB_FETCH_PREMIRRORONLY = "1"
+
 These changes would cause the build system to successfully fetch source
 over HTTP and any network accesses to anything other than the
 ``PREMIRRORS`` would fail.
@@ -384,18 +414,21 @@ 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: ::
+
+   /home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/
+      1.2.8-r0/sysroot-destdir/usr/bin
+
+   /home/maxtothemax/poky-bootchart2/build/tmp/work/x86_64-linux/
+      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.
 
-/home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/
-1.2.8-r0/sysroot-destdir/usr/bin
-/home/maxtothemax/poky-bootchart2/build/tmp/work/x86_64-linux/
-zlib-native/1.2.8-r0/sysroot-destdir/home/maxtothemax/poky-bootchart2/
-build/tmp/sysroots/x86_64-linux/usr/bin Even if the paths look unusual,
+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``
 mechanism and while they appear strange, they are correct and in