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)

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)

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)

XPost: linux.debian.bugs.dist

Guillem Jover <guillem@debian.org> 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 (rra@debian.org) <http://www.eyrie.org/~eagle/>

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

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)

XPost: linux.debian.bugs.dist

Guillem Jover <guillem@debian.org> 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 (rra@debian.org) <http://www.eyrie.org/~eagle/>

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

XPost: linux.debian.bugs.dist

Control: tags -1 pending

Guillem Jover <guillem@debian.org> 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 (rra@debian.org) <http://www.eyrie.org/~eagle/>

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