Move commands and specifier_syntax details to subsections

Author: jaimergp

peps/pep-0804.rst

@@ -612,7 +612,7 @@ Each entry in this list is defined as a dictionary with these fields:
 
 .. list-table::
     :header-rows: 1
-    :widths: 25 25 50
+    :widths: 25 15 60
 
     * - Field
       - Type
@@ -622,71 +622,78 @@ Each entry in this list is defined as a dictionary with these fields:
       - Short identifier for this package manager (usually the command name).
     * - ``commands`` (required)
       - ``dict``
-      - Commands used to install or query the given package(s). Only two keys
-        are allowed: ``install`` (to generate install instructions) and ``query`` (to
-        check whether a given package is already installed). Their value is a dictionary
-        with:
+      - Commands used to install or query the given package(s). See subsection
+        below for more details.
+    * - ``specifier_syntax`` (required)
+      - ``dict``
+      - Mapping of allowed PEP440 version specifiers to the syntax used in this
+        package manager. See subsection below for more details.
 
-        - a required key ``command`` that takes a list of strings
-          (as expected by ``subprocess.run``).
+``commands``
+""""""""""""
 
-        - an optional ``requires_elevation`` boolean (``False`` by default)
-          to indicate whether the command must run with elevated permissions
-          (e.g. administrator on Windows, superuser on Linux and macOS).
+Only two keys are allowed: ``install`` (to generate install instructions) and
+``query`` (to check whether a given package is already installed). Their value
+is a dictionary with:
 
-        - an enum ``multiple_specifiers`` that determines whether the command
-          accepts multiple package specifiers at the same time, taking one of:
+- a required key ``command`` that takes a list of strings (as expected by
+  ``subprocess.run``).
 
-          - ``always``, default in ``install``.
+- an optional ``requires_elevation`` boolean (``False`` by default) to indicate
+  whether the command must run with elevated permissions (e.g. administrator on
+  Windows, superuser on Linux and macOS).
 
-          - ``name-only``, the command only accepts multiple specifiers if they do
-            not contain version constraints.
+- an enum ``multiple_specifiers`` that determines whether the command accepts
+  multiple package specifiers at the same time, taking one of:
 
-          - ``never``, default in ``query``.
+  - ``always``, default in ``install``.
 
-        Exactly one of the ``command`` items MUST be the ``{}`` placeholder,
-        which will be replaced by the mapped package specifier(s). The
-        ``install`` command SHOULD support the placeholder being replaced by
-        multiple specifiers, ``query`` MUST only receive a single specifier
-        per command.
-    * - ``specifier_syntax`` (required)
-      - ``dict``
-      - Mapping of allowed PEP440 version specifiers to the syntax used in this
-        package manager. Three top-level keys are expected and required:
-
-        - ``name_only`` MUST take a list of strings as the syntax used for specifiers
-          that do not contain any version information; it MUST include the placeholder
-          ``{name}``.
-
-        - ``exact_version`` MUST be ``None`` or a list of strings that describe
-          the syntax used for specifiers that only express exact version
-          constraints; in the latter case, the placeholders ``{name}``
-          and ``{version}`` MUST be present in at least one of the strings
-          (although not necessary the same string for both).
-
-        - ``version_ranges`` MUST be ``None`` or a dictionary with the
-          following required keys:
-
-          - the key ``syntax`` takes a list of strings where at least one MUST
-            include the ``{ranges}`` placeholder (to be replaced by the
-            maybe-joined version constraints, as determined by the value of
-            ``and``). They MAY also include the ``{name}`` placeholder.
-
-          - the keys ``equal``, ``greater_than``, ``greater_than_equal``,
-            ``less_than``, and ``less_than_equal`` take a string
-            if the operator is supported, ``None`` otherwise. In the former case,
-            the value MUST include the ``{version}`` placeholder, and MAY include
-            ``{name}``.
-
-          - the key ``and`` takes a string used to join multiple version
-            constraints in a single token, or ``None`` if only a single
-            constraint can be used per token. In the latter case, the different
-            constraints will be "exploded" into several tokens using the
-            ``syntax`` template.
-
-          When ``exact_version`` or ``version_ranges`` are set to ``None``, it
-          indicates that the respective types of specifiers are not supported
-          by the package manager.
+  - ``name-only``, the command only accepts multiple specifiers if they do not
+    contain version constraints.
+
+  - ``never``, default in ``query``.
+
+Exactly one of the ``command`` items MUST be the ``{}`` placeholder, which will
+be replaced by the mapped package specifier(s). The ``install`` command SHOULD
+support the placeholder being replaced by multiple specifiers, ``query`` MUST
+only receive a single specifier per command.
+
+``specifier_syntax``
+""""""""""""""""""""
+
+Three top-level keys are expected and required:
+
+- ``name_only`` MUST take a list of strings as the syntax used for specifiers
+  that do not contain any version information; it MUST include the placeholder
+  ``{name}``.
+
+- ``exact_version`` MUST be ``None`` or a list of strings that describe the
+  syntax used for specifiers that only express exact version constraints; in
+  the latter case, the placeholders ``{name}`` and ``{version}`` MUST be
+  present in at least one of the strings (although not necessary the same
+  string for both).
+
+- ``version_ranges`` MUST be ``None`` or a dictionary with the following
+  required keys:
+
+  - the key ``syntax`` takes a list of strings where at least one MUST include
+    the ``{ranges}`` placeholder (to be replaced by the maybe-joined version
+    constraints, as determined by the value of ``and``). They MAY also include
+    the ``{name}`` placeholder.
+
+  - the keys ``equal``, ``greater_than``, ``greater_than_equal``,
+    ``less_than``, and ``less_than_equal`` take a string if the operator is
+    supported, ``None`` otherwise. In the former case, the value MUST include
+    the ``{version}`` placeholder, and MAY include ``{name}``.
+
+  - the key ``and`` takes a string used to join multiple version constraints in
+    a single token, or ``None`` if only a single constraint can be used per
+    token. In the latter case, the different constraints will be "exploded"
+    into several tokens using the ``syntax`` template.
+
+  When ``exact_version`` or ``version_ranges`` are set to ``None``, it
+  indicates that the respective types of specifiers are not supported by the
+  package manager.
 
 
 Examples