sphinx: import docs

The Yocto Project docs was migrated from Docbook to Sphinx in YP
 3.2. This 3.1 is an LTS release, and since 3.1 docs are 'close to'
 the docs in 3.2, we agreed to backport sphinx docs onto 3.1.

This first patch brings all changes done in 3.2 until:
7f64574f7 README: include detailed information about sphinx

There are other changes after this commit, but they will be
 selectively backported in individual patches.

This patch was generated with the following command:

git cherry-pick -n \
 $(git log --reverse --oneline \
 ac352ad7f95db7eeacb53c2778caa31800bd7c26..7f64574f7 \
| cut -f1 -d' ')

The following commits were applies in the dunfell docs, but not in
master, so they were first reverted (and squashed into this change). A
commit will reintroduce the content from these patches in the Sphinx
files in a followup patch.

069c27574 Documenation: Prepared for the 3.1.1 release
bd140f0f9 Documentation: Add 3.1.1 version updates missing from previous commit
17cc71a8f Documenation: Prepared for the 3.1.2 release
1a69e2c02 Documenation: Prepared for the 3.1.3 release
8910ac1c7 Documenation: Prepared for the 3.1.4 release

(From yocto-docs rev: c25fe058b88b893b0d146f3ed27320b47cdec236)

Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 63 insertions, 4 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index e9ce182a59..247f6abfd4 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1,6 +1,7 @@
 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
 [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
 
 <chapter id='extendpoky'>
 
@@ -3189,7 +3190,7 @@
                         building an image.
                         </para></listitem>
                     <listitem><para>
-                        <filename>virtual/mesa</filename>:
+                        <filename>virtual/libgbm</filename>:
                         Provides <filename>gbm.pc</filename>.
                         </para></listitem>
                     <listitem><para>
@@ -8383,7 +8384,7 @@
                                 If you see the following error, you need to
                                 update or create a
                                 <filename>~/.mtoolsrc</filename> file and
-                                be sure to have the line “mtools_skip_check=1“
+                                be sure to have the line "mtools_skip_check=1"
                                 in the file.
                                 Then, run the Wic command again:
                                 <literallayout class='monospaced'>
@@ -9057,6 +9058,9 @@
                 <listitem><para>
                     <link linkend='creating-node-package-manager-npm-packages'>Creating node package manager (NPM) packages</link>
                     </para></listitem>
+                <listitem><para>
+                    <link linkend='adding-custom-metadata-to-packages'>Adding custom metadata to packages</link>
+                    </para></listitem>
             </itemizedlist>
         </para>
 
@@ -9833,7 +9837,7 @@
                         <listitem><para>
                             Select the desired package format as follows:
                             <literallayout class='monospaced'>
-     PACKAGE_CLASSES ?= “package_<replaceable>packageformat</replaceable>”
+     PACKAGE_CLASSES ?= "package_<replaceable>packageformat</replaceable>"
                             </literallayout>
                             where <replaceable>packageformat</replaceable>
                             can be "ipk", "rpm", "deb", or "tar" which are the
@@ -10761,6 +10765,61 @@
                 </para>
             </section>
         </section>
+
+        <section id='adding-custom-metadata-to-packages'>
+            <title>Adding custom metadata to packages</title>
+
+            <para>
+                The variable <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ADD_METADATA'><filename>PACKAGE_ADD_METADATA</filename></ulink>
+                can be used to add additional metadata to packages. This is
+                reflected in the package control/spec file. To take the ipk
+                format for example, the CONTROL file stored inside would
+                contain the additional metadata as additional lines.
+            </para>
+
+            <para>
+                The variable can be used in multiple ways, including using
+                suffixes to set it for a specific package type and/or package.
+                Note that the order of precedence is the same as this list:
+                <itemizedlist>
+                    <listitem><para>
+                        <filename>PACKAGE_ADD_METADATA_&lt;PKGTYPE&gt;_&lt;PN&gt;</filename>
+                    </para></listitem>
+                    <listitem><para>
+                        <filename>PACKAGE_ADD_METADATA_&lt;PKGTYPE&gt;</filename>
+                    </para></listitem>
+                    <listitem><para>
+                        <filename>PACKAGE_ADD_METADATA_&lt;PN&gt;</filename>
+                    </para></listitem>
+                    <listitem><para>
+                        <filename>PACKAGE_ADD_METADATA</filename>
+                    </para></listitem>
+                </itemizedlist>
+                &lt;PKGTYPE&gt; is a parameter and expected to be a
+                distinct name of specific package type:
+                <itemizedlist>
+                    <listitem><para>IPK for .ipk packages</para></listitem>
+                    <listitem><para>DEB for .deb packages</para></listitem>
+                    <listitem><para>RPM for .rpm packages</para></listitem>
+                </itemizedlist>
+                &lt;PN&gt; is a parameter and expected to be a package name.
+            </para>
+
+            <para>
+                The variable can contain multiple [one-line] metadata fields
+                separated by the literal sequence '\n'. The separator can be
+                redefined using the variable flag <filename>separator</filename>.
+            </para>
+
+            <para>
+                The following is an example that adds two custom fields for
+                ipk packages:
+                <literallayout class='monospaced'>
+    PACKAGE_ADD_METADATA_IPK = "Vendor: CustomIpk\nGroup: Applications/Spreadsheets"
+                </literallayout>
+            </para>
+        </section>
+
     </section>
 
     <section id='efficiently-fetching-source-files-during-a-build'>
@@ -14134,7 +14193,7 @@
                         <filename>local.conf</filename> file or in an image
                         recipe:
                         <literallayout class='monospaced'>
-     IMAGE_INSTALL_append = “ gdbserver"
+     IMAGE_INSTALL_append = " gdbserver"
                         </literallayout>
                         The change makes sure the <filename>gdbserver</filename>
                         package is included.