1. Forum
  2. Usenet
  3. LINUX.DEBIAN.POLICY

  • Bug#872893: debian-policy: Chapters, sections, appendices and numbering

    From Guillem Jover@21:1/5 to All on Tue Aug 22 12:20:01 2017
    XPost: linux.debian.bugs.dist

    Package: debian-policy
    Version: 4.1.0.0

    Hi!

    At least on the PDF output, the section numbers are wrong, as there
    are now two chapters that include the old sections.

    The appendices are also not easily distinguishable from the other
    sections as they also use numbers intead of say letters.

    Thanks,
    Guillem

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Sean Whitton@21:1/5 to Guillem Jover on Tue Aug 22 20:50:02 2017
    XPost: linux.debian.bugs.dist

    control: tag -1 +moreinfo

    Hello Guillem,

    On Tue, Aug 22 2017, Guillem Jover wrote:

    At least on the PDF output, the section numbers are wrong, as there
    are now two chapters that include the old sections.

    Could you explain "two chapters that include the old sections", please?
    Or just say which sections are wrong.

    We tried hard to avoid this, so it's definitely a bug.

    The appendices are also not easily distinguishable from the other
    sections as they also use numbers intead of say letters.

    This is a limitation of Sphinx. We aren't going to fix it unless a new
    feature arrives from upstream.

    --
    Sean Whitton

    --=-=-Content-Type: application/pgp-signature; name="signature.asc"

    -----BEGIN PGP SIGNATURE-----

    iQIzBAEBCgAdFiEEm5FwB64DDjbk/CSLaVt65L8GYkAFAlmcbYAACgkQaVt65L8G YkCiohAAlNCBi9PN3pjNo2BVVjm2e0sQ0n6r1dnSqD0JI4rbqPqhIzjfA+Jz8UAR sY9fxdP4Y1Wek0DpTQS8ftO4Y3iFbxLGcN6/jMskq1BkD+RdRKT7+wzzy4PP7pQO OnVdnMNf+OZ2KQQZBmKPUKfbumkyOPLO9A65m72bGnfDLsVZMI+IoErMrxW01S2z WlUnfEBw1QgfSJ5uy754l8bM9nVEoc7cg6dL3U7uMlsGWR8mRRDU1Y1gzdSr8Zsz XuTtwKPRLHhAIR/mzjOemBN4oE3ysh8yiaVzLl+PGe8zkWa2TXISu1pf5l45xGCn WpNJsRnL1wWERp8Hk6cJpZq9NC1xRdofPCqV7P7PLYwEDbGUWZJYgzcSqyud4is4 uDdanm8/fAx+JuOhs+TecOItZzLNTmBIh7n02QCQ3vRbsokybIQEiDLq2v2SQvwK ZbWRDGs/+Frwtk5J8m8YzDBElHhaeGYMwTUijgPmNB14M18SlNB40kUFqiNrvr0t 3EAiGO874TJxRF+1486ed+zrgIkRysGUcRmQsxkMslCaOVQXzn9LoTVxc0CsmT6i Ule7JtVIHfKELLw1n6/ILy6UpV3b3PwmQCDa03AiXNrxJ5DN5Qnj6XgbP2UCzV/Z 7oLQrhhM0EMWoVYm+xPf8+Fq0rYxnDMJtF6VpkUy6hMTp6jQz1k=Ylq/
    -----END PGP SIGNATURE-----

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Guillem Jover@21:1/5 to Sean Whitton on Tue Aug 22 23:20:01 2017
    XPost: linux.debian.bugs.dist

    Control: tag -1 - moreinfo

    Hi!

    On Tue, 2017-08-22 at 10:44:32 -0700, Sean Whitton wrote:
    On Tue, Aug 22 2017, Guillem Jover wrote:
    At least on the PDF output, the section numbers are wrong, as there
    are now two chapters that include the old sections.

    Could you explain "two chapters that include the old sections", please?
    Or just say which sections are wrong.

    We tried hard to avoid this, so it's definitely a bug.

    Take section «10.9.1. The use of dpkg-statoverride», this is correct
    on the HTML output and info file, on the PDF it's a section w/o a
    number inside §2.10.9. I've not checked the EPUB file.

    The appendices are also not easily distinguishable from the other
    sections as they also use numbers intead of say letters.

    This is a limitation of Sphinx. We aren't going to fix it unless a new feature arrives from upstream.

    Well, that's unfortunate. :( And I've just noticed on the info files
    it's just worse as they do not get their section numbers reset so
    they keep incrementing from the last chapter index. For example
    «Binary packages (…)» used to be appendix B, now it's 2, but on the
    info file it's 14.

    Thanks,
    Guillem

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Russ Allbery@21:1/5 to Guillem Jover on Wed Aug 23 04:20:01 2017
    XPost: linux.debian.bugs.dist

    Guillem Jover <[email protected]> writes:
    On Tue, 2017-08-22 at 10:44:32 -0700, Sean Whitton wrote:

    Could you explain "two chapters that include the old sections", please?
    Or just say which sections are wrong.

    We tried hard to avoid this, so it's definitely a bug.

    Take section «10.9.1. The use of dpkg-statoverride», this is correct on
    the HTML output and info file, on the PDF it's a section w/o a number
    inside §2.10.9. I've not checked the EPUB file.

    Yeah, Sphinx is doing something really weird with how it does section numbering. It's counting the top-level document as having three sections
    and embedding the contents in section "2" and pushing everything down.
    This is the same problem the info documentation is having.

    I'll take a look and try to figure out some solution.

    --
    Russ Allbery ([email protected]) <http://www.eyrie.org/~eagle/>

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Sean Whitton@21:1/5 to Guillem Jover on Wed Aug 23 03:40:01 2017
    XPost: linux.debian.bugs.dist

    On Tue, Aug 22 2017, Guillem Jover wrote:

    Take section «10.9.1. The use of dpkg-statoverride», this is correct
    on the HTML output and info file, on the PDF it's a section w/o a
    number inside §2.10.9. I've not checked the EPUB file.

    Thanks!

    And I've just noticed on the info files it's just worse as they do not
    get their section numbers reset so they keep incrementing from the
    last chapter index. For example «Binary packages (…)» used to be
    appendix B, now it's 2, but on the info file it's 14.

    Okay, that sounds like a bug -- thanks.

    --
    Sean Whitton

    --=-=-Content-Type: application/pgp-signature; name="signature.asc"

    -----BEGIN PGP SIGNATURE-----

    iQIzBAEBCgAdFiEEm5FwB64DDjbk/CSLaVt65L8GYkAFAlmczAAACgkQaVt65L8G YkB+GQ//UkQ5bxcl0qip/N2wFAYm0O5QKsrxF71z4DfApV5Xej78loh255cxROYP 1FV8Wbx3Pex5E/iwcZQjHsEFLWTaC0oM/6zIuhxTtc2bJGfNHmX0sh/jKK/WamkV 29YrGUvSWhQ0Ulq7VwX3a2Ha8+wsqiY2b4QYmhfhI/0cQ2W5cbWjK4eaOPCUb0w9 I4BcqT3/qH2MOK7WP8K4JLckj5FXzMvtTov+81UmT2fwBskGjioTQf8D4RM/F+Ty CAsyMudmi4pvOEmed40eAlZlraXVAJ4evsT/uZAOHXBJQEK/axRg2nutP2KMtRZ/ iDATSKdc8YCizWMAjsg/5rCS2zMaWaU7sJBvKuVT8UM013ElOLKtHHNkToyQLCiu 2k7AeDcymE8yAvTZ/AEO3NlEsn3pnH05QWYQiwB53vkk8UU6Tr0LT6vDt/SqaNFP Qqk1eugSQxKxMFxY0QhqX6jQaE6Rn/tGJ11PJJpUl0b0QRoLkhGeCbQFiZ9jCBDn g9kNWqx8FPYJFUKSwZP5qIkW65FYL6f/HTE4gXhkAIA4HPrsddhvIV1ePonSSlY9 CGvhSrg+gUtM13t9kOCzauhnyVMSXIhTkO/ZjEwkW7xrf5PTW91CedwKshWEIjNz xHP7v0VGlZ9d+tatkRE/MkxQOL5+JPAQIMm/RKo3VbbOtMcPrOI=ZiEH
    -----END PGP SIGNATURE-----

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Russ Allbery@21:1/5 to Guillem Jover on Wed Aug 23 08:10:01 2017
    XPost: linux.debian.bugs.dist

    Guillem Jover <[email protected]> writes:

    Well, that's unfortunate. :( And I've just noticed on the info files
    it's just worse as they do not get their section numbers reset so
    they keep incrementing from the last chapter index. For example
    «Binary packages (…)» used to be appendix B, now it's 2, but on the
    info file it's 14.

    Yeah, both the info and PDF documentation have that issue, but HTML
    doesn't. I haven't looked at epub, but it's probably just the HTML output
    in another form.

    --
    Russ Allbery ([email protected]) <http://www.eyrie.org/~eagle/>

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Russ Allbery@21:1/5 to Guillem Jover on Wed Aug 23 08:20:01 2017
    XPost: linux.debian.bugs.dist

    Control: tags -1 pending

    Guillem Jover <[email protected]> writes:

    The appendices are also not easily distinguishable from the other
    sections as they also use numbers intead of say letters.

    This is https://github.com/sphinx-doc/sphinx/issues/2502. I'm going to
    close out this specific bug number against Policy by fixing the numbering
    and nesting for the main chapters, since I think the appendix numbering is liveable, but we'll definitely fix this if some solution materializes.

    --
    Russ Allbery ([email protected]) <http://www.eyrie.org/~eagle/>

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)