Bug#999566: debian-policy: highlight source code examples

[Stéphane Blondon <stephane.blondon@gmail.com>]

Source: debian-policy
Version: 4.6.0.1
Severity: minor
Tags: patch
X-Debbugs-Cc: stephane@bearkhof.lan

Dear Maintainer,


it's easier to read highlighted code so the patch uses the highlight
sphinx feature on some of the code examples.
The patch is available at
https://salsa.debian.org/sblondon/policy/-/tree/highlight-debian-control

Should I add a "Control: tag -1 + patch"? I doubt about that because
the patch does not change the policy content.


diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst
index 4fa0d60..02445e4 100644
--- a/policy/ch-controlfields.rst
+++ b/policy/ch-controlfields.rst
@@ -656,7 +656,7 @@ description of the binary package, consisting of
two parts, the synopsis
or the short description, and the long description. It is a multiline
field with the following format:

[-::-]{+.. code-block:: debcontrol+}

    Description: single line synopsis
     extended description over several lines
@@ -757,7 +757,7 @@ values ``low``, ``medium``, ``high``,
``emergency``, or ``critical``
[#]_ (not case-sensitive) followed by an optional commentary
(separated by a space) which is usually in parentheses. For example:

[-::-]{+.. code-block:: debcontrol+}

    Urgency: low (HIGH for users of diversions)

@@ -986,7 +986,9 @@ repository where the Debian source package is developed.
    is specified, it defaults to ``.`` (the top level of the indicated
    repository and branch).

    For [-example::-]{+example:+}

{+    .. code-block:: debcontrol+}

        Vcs-Git: https://example.org/repo -b debian [p/package]

@@ -1198,13 +1200,13 @@ where the letter ``S`` is used in Debian
source control files and where
For example, if the main source information control file contains the
field

[-::-]{+.. code-block:: debcontrol+}

    XBS-Comment: I stand between the candle and the star.

then the binary and Debian source control files will contain the field

[-::-]{+.. code-block:: debcontrol+}

    Comment: I stand between the candle and the star.

diff --git a/policy/ch-source.rst b/policy/ch-source.rst
index 9f11a36..3a06e91 100644
--- a/policy/ch-source.rst
+++ b/policy/ch-source.rst
@@ -561,7 +561,7 @@ The following makefile snippet is an example of
how one may implement
the build options; you will probably have to massage this example in
order to make it work for your package.

[-::-]{+.. code-block:: Makefile+}

    CFLAGS = -Wall -g
    INSTALL = install
@@ -619,7 +619,9 @@ variables without the caller having to explicitly
request any
preservation.

The following are examples of valid gain root commands (in syntax of
sh), assuming the tools used are available and properly
[-configured::-]{+configured:+}

{+.. code-block:: sh+}

  # Command "sudo", with arguments "-nE" and "--"
  export DEB_GAIN_ROOT_CMD='sudo -nE --'