manuals: simplify references to classes

Now that .bbclass is removed from class section titles.
We can now have, for example, :ref:`ref-classes-insane`
instead of :ref:`insane <ref-classes-insane>`.

Then, when necessary, rework paragraphs so that they
have lines of even length, not exceeding 80 characters.

(From yocto-docs rev: e76190e3be78c1e483bec0469f1e437dbf8f3791)

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Suggested-by: Quentin Schulz <foss+yocto@0leil.net>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 37 insertions, 48 deletions

diff --git a/documentation/dev-manual/new-recipe.rst b/documentation/dev-manual/new-recipe.rst
index 3adebf2746..4751f64b7e 100644
--- a/documentation/dev-manual/new-recipe.rst
+++ b/documentation/dev-manual/new-recipe.rst
@@ -565,7 +565,7 @@ your software is built:
    need to modify the configuration.
 
    When using Autotools, your recipe needs to inherit the
-   :ref:`autotools <ref-classes-autotools>` class and it does not have to
+   :ref:`ref-classes-autotools` class and it does not have to
    contain a :ref:`ref-tasks-configure` task. However, you might still want to
    make some adjustments. For example, you can set :term:`EXTRA_OECONF` or
    :term:`PACKAGECONFIG_CONFARGS` to pass any needed configure options that
@@ -576,7 +576,7 @@ your software is built:
    need to modify the configuration.
 
    When you use CMake, your recipe needs to inherit the
-   :ref:`cmake <ref-classes-cmake>` class and it does not have to contain a
+   :ref:`ref-classes-cmake` class and it does not have to contain a
    :ref:`ref-tasks-configure` task. You can make some adjustments by setting
    :term:`EXTRA_OECMAKE` to pass any needed configure options that are
    specific to the recipe.
@@ -712,7 +712,7 @@ Here are some common issues that cause failures.
    ":ref:`dev-manual/debugging:debugging parallel make races`" section.
 
 -  *Improper host path usage:* This failure applies to recipes building
-   for the target or ":ref:`nativesdk <ref-classes-nativesdk>`" only. The
+   for the target or ":ref:`ref-classes-nativesdk`" only. The
    failure occurs when the compilation process uses improper headers,
    libraries, or other files from the host system when cross-compiling for
    the target.
@@ -807,14 +807,13 @@ installed correctly.
       re-execute :ref:`ref-tasks-install` if needed.
 
    -  ``oe_runmake install``, which can be run directly or can be run
-      indirectly by the
-      :ref:`autotools <ref-classes-autotools>` and
-      :ref:`cmake <ref-classes-cmake>` classes,
-      runs ``make install`` in parallel. Sometimes, a Makefile can have
-      missing dependencies between targets that can result in race
-      conditions. If you experience intermittent failures during
-      :ref:`ref-tasks-install`, you might be able to work around them by disabling
-      parallel Makefile installs by adding the following to the recipe::
+      indirectly by the :ref:`ref-classes-autotools` and
+      :ref:`ref-classes-cmake` classes, runs ``make install`` in parallel.
+      Sometimes, a Makefile can have missing dependencies between targets that
+      can result in race conditions. If you experience intermittent failures
+      during :ref:`ref-tasks-install`, you might be able to work around them by
+      disabling parallel Makefile installs by adding the following to the
+      recipe::
 
          PARALLEL_MAKEINST = ""
 
@@ -854,7 +853,7 @@ different ways:
    shutdown of all other programs.
 
    To enable a service using SysVinit, your recipe needs to inherit the
-   :ref:`update-rc.d <ref-classes-update-rc.d>` class. The class helps
+   :ref:`ref-classes-update-rc.d` class. The class helps
    facilitate safely installing the package on the target.
 
    You will need to set the
@@ -870,7 +869,7 @@ different ways:
    https://freedesktop.org/wiki/Software/systemd/.
 
    To enable a service using systemd, your recipe needs to inherit the
-   :ref:`systemd <ref-classes-systemd>` class. See the ``systemd.bbclass`` file
+   :ref:`ref-classes-systemd` class. See the ``systemd.bbclass`` file
    located in your :term:`Source Directory` section for more information.
 
 Packaging
@@ -886,14 +885,12 @@ take. The following list describes the process:
    other logical components that should be split out. The :ref:`ref-tasks-package`
    task ensures that files are split up and packaged correctly.
 
--  *Running QA Checks*: The
-   :ref:`insane <ref-classes-insane>` class adds a
+-  *Running QA Checks*: The :ref:`ref-classes-insane` class adds a
    step to the package generation process so that output quality
    assurance checks are generated by the OpenEmbedded build system. This
    step performs a range of checks to be sure the build's output is free
    of common problems that show up during runtime. For information on
-   these checks, see the
-   :ref:`insane <ref-classes-insane>` class and
+   these checks, see the :ref:`ref-classes-insane` class and
    the ":ref:`ref-manual/qa-checks:qa error and warning messages`"
    chapter in the Yocto Project Reference Manual.
 
@@ -934,8 +931,7 @@ take. The following list describes the process:
    On the other hand, if the recipe produces packages that do not
    contain anything specific to the target machine or architecture at
    all (e.g. recipes that simply package script files or configuration
-   files), you should use the
-   :ref:`allarch <ref-classes-allarch>` class to
+   files), you should use the :ref:`ref-classes-allarch` class to
    do this for you by adding this to your recipe::
 
       inherit allarch
@@ -1002,18 +998,16 @@ same functionality, you can use a virtual provider (i.e. ``virtual/*``)
 as a placeholder for the actual provider. The actual provider is
 determined at build-time.
 
-A common scenario where a virtual provider is used would be for the
-kernel recipe. Suppose you have three kernel recipes whose
-:term:`PN` values map to ``kernel-big``,
-``kernel-mid``, and ``kernel-small``. Furthermore, each of these recipes
-in some way uses a :term:`PROVIDES`
-statement that essentially identifies itself as being able to provide
-``virtual/kernel``. Here is one way through the
-:ref:`kernel <ref-classes-kernel>` class::
+A common scenario where a virtual provider is used would be for the kernel
+recipe. Suppose you have three kernel recipes whose :term:`PN` values map to
+``kernel-big``, ``kernel-mid``, and ``kernel-small``. Furthermore, each of
+these recipes in some way uses a :term:`PROVIDES` statement that essentially
+identifies itself as being able to provide ``virtual/kernel``. Here is one way
+through the :ref:`ref-classes-kernel` class::
 
    PROVIDES += "virtual/kernel"
 
-Any recipe that inherits the :ref:`kernel <ref-classes-kernel>` class is
+Any recipe that inherits the :ref:`ref-classes-kernel` class is
 going to utilize a :term:`PROVIDES` statement that identifies that recipe as
 being able to provide the ``virtual/kernel`` item.
 
@@ -1223,7 +1217,7 @@ Autotooled Package
 
 Applications that use Autotools such as ``autoconf`` and ``automake``
 require a recipe that has a source archive listed in :term:`SRC_URI` and
-also inherit the :ref:`autotools <ref-classes-autotools>` class,
+also inherit the :ref:`ref-classes-autotools` class,
 which contains the definitions of all the steps needed to build an
 Autotool-based application. The result of the build is automatically
 packaged. And, if the application uses NLS for localization, packages
@@ -1353,24 +1347,19 @@ could lead to compatibility problems with ABI in the future. However,
 sometimes you have no choice.
 
 The easiest solution is to create a recipe that uses the
-:ref:`bin_package <ref-classes-bin-package>` class
-and to be sure that you are using default locations for build artifacts.
-In most cases, the :ref:`bin_package <ref-classes-bin-package>` class handles "skipping" the
-configure and compile steps as well as sets things up to grab packages
-from the appropriate area. In particular, this class sets ``noexec`` on
-both the :ref:`ref-tasks-configure`
-and :ref:`ref-tasks-compile` tasks,
-sets ``FILES:${PN}`` to "/" so that it picks up all files, and sets up a
-:ref:`ref-tasks-install` task, which
-effectively copies all files from ``${S}`` to ``${D}``. The
-:ref:`bin_package <ref-classes-bin-package>` class works well when the files extracted into ``${S}``
-are already laid out in the way they should be laid out on the target.
-For more information on these variables, see the
-:term:`FILES`,
-:term:`PN`,
-:term:`S`, and
-:term:`D` variables in the Yocto Project
-Reference Manual's variable glossary.
+:ref:`ref-classes-bin-package` class and to be sure that you are using default
+locations for build artifacts.  In most cases, the
+:ref:`ref-classes-bin-package` class handles "skipping" the configure and
+compile steps as well as sets things up to grab packages from the appropriate
+area. In particular, this class sets ``noexec`` on both the
+:ref:`ref-tasks-configure` and :ref:`ref-tasks-compile` tasks, sets
+``FILES:${PN}`` to "/" so that it picks up all files, and sets up a
+:ref:`ref-tasks-install` task, which effectively copies all files from ``${S}``
+to ``${D}``. The :ref:`ref-classes-bin-package` class works well when the files
+extracted into ``${S}`` are already laid out in the way they should be laid out
+on the target. For more information on these variables, see the :term:`FILES`,
+:term:`PN`, :term:`S`, and :term:`D` variables in the Yocto Project Reference
+Manual's variable glossary.
 
 .. note::
 
@@ -1388,7 +1377,7 @@ Reference Manual's variable glossary.
       section in the Yocto Project Overview and Concepts Manual for more
       information.
 
-If you cannot use the :ref:`bin_package <ref-classes-bin-package>` class, you need to be sure you are
+If you cannot use the :ref:`ref-classes-bin-package` class, you need to be sure you are
 doing the following:
 
 -  Create a recipe where the