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

[Russ Allbery]

Control: tags -1 pending

Guillem Jover  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 (r...@debian.org)   

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

[Russ Allbery]

Guillem Jover  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 (r...@debian.org)   

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

[Russ Allbery]

Guillem Jover  writes:

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

I think I've fixed this.  For reference, the first problem was the
headings in the top-level document for the abstract and the license.  When
I fixed that, Sphinx got a bit more confused, but adding the document
title with the highest-level heading (as documented in the Sphinx docs)
seems to have cleaned that up.

The license got appended to the end of the upgrading checklist if it was
just at the end of the top-level index, so I made it a separate appendix.
The alternative was to put it in front of the main text, and that seemed
awkward.

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

This unfortunately really doesn't seem to be fixable in Sphinx right now,
which is frustrating.  :(  But it's more incentive to get rid of the
packaging manual appendices, which are basically long-standing technical
debt, and incorporate that material directly into Policy.  That leaves the
process and the upgrading checklist, which I think could be just left as a
final section of the document.

-- 
Russ Allbery (r...@debian.org)   

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

[Russ Allbery]

Guillem Jover  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 (r...@debian.org)   

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

[Sean Whitton]

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


signature.asc
Description: PGP signature

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

[Guillem Jover]

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

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

[Sean Whitton]

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


signature.asc
Description: PGP signature

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

[Guillem Jover]

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