Bug#912059: debian-policy: please increase ToC depth (for Lintian's benefit)

[Colin Watson <cjwatson@debian.org>]

Package: debian-policy
Version: 4.2.1.3
Severity: normal
Tags: patch

I recently noticed some outdated links generated by Lintian, which led
me to look into how they're generated.  Lintian has a script
(private/refresh-manual-refs) to grab references from the tables of
contents of various Debian documents, which it then uses in some of its
tags.  That currently has a hack for the main Policy document, dating
from last year:

    'policy' => [
        '/usr/share/doc/debian-policy/policy.html/index.html',
        'https://www.debian.org/doc/debian-policy/',
        # $index_re would match the Policy's TOC and work otherwise, but
        # the TOC is generated only up to 3 levels deep as of 4.1.1.1, and
        # we want refs to all levels.
        qr{
              <(h[2-5])>\s*
              ([A-Z]|[A-Z]?[\d\.]+?)
              \.?\s+
              ([\w\s[:punct:]]+?)
              <a\s(?:[^>]*?)\bhref="([^"]+)".+?</a>
              </\1>
        }x,
        [['_ignored'], ['section'], ['title'], ['url']]
    ],

But this doesn't actually work at the moment: when I run this script it
loses all the policy entries from the output file.  There is some
support for extracting additional subsection references from other
files, but it would take some effort to get this to work for policy,
because the order of fields in the regex would need to be a bit
different when parsing the primary index versus when parsing individual
ch-* files.

I think it would be much simpler to just increase the Policy ToC's
section depth.  That would seem generally slightly more useful (there
isn't so much noise at the fourth level that it would make the ToC
substantially harder to read), and would relieve Lintian from having to
do this hack.

(See also #912055, a similar problem in doc-base.)

diff --git a/policy/index.rst b/policy/index.rst
index aa3fecd..b38e8c3 100644
--- a/policy/index.rst
+++ b/policy/index.rst
@@ -12,7 +12,7 @@ that each package must satisfy to be included in the distribution.
 This is Debian Policy version |policy_version|, released on |policy_date|.
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 4
    :numbered:
    
    ch-scope
@@ -31,7 +31,7 @@ This is Debian Policy version |policy_version|, released on |policy_date|.
 .. toctree::
    :caption: Appendices
    :name: appendix
-   :maxdepth: 3
+   :maxdepth: 4
    :numbered:
 
    ap-pkg-scope

Thanks,

-- 
Colin Watson                                       [cjwatson@debian.org]