Bug#873456: Bug#879048: Bug#876075: Anchors are non-unique in the single-HTML version

[Sean Whitton]

Hello Bill,

On Sun, Jun 10 2018, Bill Allombert wrote:

> The policy-1.html has the nice property that it is easy to search the
> whole document.

Yes, this was actually the main reason I pushed to use singlehtml as the
default on the web mirrors when we switched to Sphinx.

People on their own computers can install the debian-policy package and
search policy.txt.gz with Emacs or zless or similar.

On Sun, Jun 10 2018, Bill Allombert wrote:

> Maybe it sound harsher than what I wanted to say.  I have no problem
> with policy-1.html to be dropped as a stop-gap measure. However this
> is not a good long term solution. If sphynx cannot do it then we
> should consider a better technology.

Indeed, it would be better to ship a quality policy-1.html than not ship
one.  However, I don't share your optimism that we will find a
technology that will generate a good policy-1.html without having
various other disadvantages when compared with Sphinx.

So while I agree that after dropping policy-1.html we should have a bug
"restore single file HTML format", I think it should be of wishlist
severity, because the only reasonable expectation is that we won't have
policy-1.html until Sphinx has better support for generating it.

(Also, the other bugs should be closed when policy-1.html is dropped
because they are strictly invalid when the policy-1.html file does not
exist in the package.  Instead, in the wishlist bug, we can note the
reasons for removal.)

-- 
Sean Whitton

Bug#873456: Bug#876075: Bug#879048: Bug#876075: Anchors are non-unique in the single-HTML version

[Bill Allombert]

On Sun, Jun 10, 2018 at 03:01:51PM +0200, Bill Allombert wrote:
> On Sun, Jun 10, 2018 at 01:37:11PM +0100, Sean Whitton wrote:
> > Hello all,
> > 
> > On Mon, Dec 25 2017, Russ Allbery wrote:
> > 
> > > I'm not sure where we landed with this, but it feels like the
> > > single-HTML output from Sphnix is kind of broken, and publishing that
> > > on the web site has caused various problems.  I'm not sure how to get
> > > to the multi-page version on www.debian.org, and indeed the anchors
> > > and table of contents in Policy are not working right now on the web
> > > site because of this problem.
> > >
> > > I feel like the single-page HTML version may have been a failed
> > > experiment, at least pending further work on Sphinx, and we should
> > > just publish the multi-page version.  What do other people think?
> > > (Adding debian-www for their opinion as well.)
> > >
> > > Not having working footnotes feels to me like kind of a showstopper.
> > 
> > It's been sixty days since I reported one of these bugs upstream and
> > there has been no response from upstream.  So I think it is time to undo
> > our failed experiment.
> > 
> > We have a choice between dropping policy-1.html altogether, or instead
> > switching the www.debian.org copy to use the multi-page version and not
> > modifying the debian-policy package.
> > 
> > We have three separate bugs (see Cc header) about the singlepage output:
> > the gap in quality between singlepage and multipage is rather wide.  So
> > I am favour of dropping policy-1.html altogether.  I just don't think
> > it's good enough to include in our package.  Further, now that
> > policy.txt.gz has proper section numbering again, it can replace a lot
> > of the uses that there were for policy-1.html.
> > 
> > Any objections to dropping singlepage html output completely, until a
> > future date at which Sphinx upstream has improved it?
> 
> If you do that, then do not close the bugs related to policy-1.html
> because they will still be valid, and report a bug 'policy-1.html is
> missing'.

Maybe it sound harsher than what I wanted to say.
I have no problem with policy-1.html to be dropped as a stop-gap
measure. However this is not a good long term solution. If sphynx cannot
do it then we should consider a better technology. 

Cheers,
-- 
Bill. 

Imagine a large red swirl here. 

Bug#876075: Bug#879048: Bug#876075: Anchors are non-unique in the single-HTML version

[Bill Allombert]

On Sun, Jun 10, 2018 at 01:37:11PM +0100, Sean Whitton wrote:
> Hello all,
> 
> On Mon, Dec 25 2017, Russ Allbery wrote:
> 
> > I'm not sure where we landed with this, but it feels like the
> > single-HTML output from Sphnix is kind of broken, and publishing that
> > on the web site has caused various problems.  I'm not sure how to get
> > to the multi-page version on www.debian.org, and indeed the anchors
> > and table of contents in Policy are not working right now on the web
> > site because of this problem.
> >
> > I feel like the single-page HTML version may have been a failed
> > experiment, at least pending further work on Sphinx, and we should
> > just publish the multi-page version.  What do other people think?
> > (Adding debian-www for their opinion as well.)
> >
> > Not having working footnotes feels to me like kind of a showstopper.
> 
> It's been sixty days since I reported one of these bugs upstream and
> there has been no response from upstream.  So I think it is time to undo
> our failed experiment.
> 
> We have a choice between dropping policy-1.html altogether, or instead
> switching the www.debian.org copy to use the multi-page version and not
> modifying the debian-policy package.
> 
> We have three separate bugs (see Cc header) about the singlepage output:
> the gap in quality between singlepage and multipage is rather wide.  So
> I am favour of dropping policy-1.html altogether.  I just don't think
> it's good enough to include in our package.  Further, now that
> policy.txt.gz has proper section numbering again, it can replace a lot
> of the uses that there were for policy-1.html.
> 
> Any objections to dropping singlepage html output completely, until a
> future date at which Sphinx upstream has improved it?

If you do that, then do not close the bugs related to policy-1.html
because they will still be valid, and report a bug 'policy-1.html is
missing'.

The policy-1.html has the nice property that it is easy to search the
whole document.

Cheers,
-- 
Bill. 

Imagine a large red swirl here. 

Bug#879048: Bug#876075: Anchors are non-unique in the single-HTML version

[Sean Whitton]

Hello all,

On Mon, Dec 25 2017, Russ Allbery wrote:

> I'm not sure where we landed with this, but it feels like the
> single-HTML output from Sphnix is kind of broken, and publishing that
> on the web site has caused various problems.  I'm not sure how to get
> to the multi-page version on www.debian.org, and indeed the anchors
> and table of contents in Policy are not working right now on the web
> site because of this problem.
>
> I feel like the single-page HTML version may have been a failed
> experiment, at least pending further work on Sphinx, and we should
> just publish the multi-page version.  What do other people think?
> (Adding debian-www for their opinion as well.)
>
> Not having working footnotes feels to me like kind of a showstopper.

It's been sixty days since I reported one of these bugs upstream and
there has been no response from upstream.  So I think it is time to undo
our failed experiment.

We have a choice between dropping policy-1.html altogether, or instead
switching the www.debian.org copy to use the multi-page version and not
modifying the debian-policy package.

We have three separate bugs (see Cc header) about the singlepage output:
the gap in quality between singlepage and multipage is rather wide.  So
I am favour of dropping policy-1.html altogether.  I just don't think
it's good enough to include in our package.  Further, now that
policy.txt.gz has proper section numbering again, it can replace a lot
of the uses that there were for policy-1.html.

Any objections to dropping singlepage html output completely, until a
future date at which Sphinx upstream has improved it?

-- 
Sean Whitton

Bug#876075: Anchors are non-unique in the single-HTML version

[Sean Whitton]

Hello,

On Mon, Dec 25 2017, Russ Allbery wrote:

> I'm not sure where we landed with this, but it feels like the
> single-HTML output from Sphnix is kind of broken, and publishing that
> on the web site has caused various problems.  I'm not sure how to get
> to the multi-page version on www.debian.org, and indeed the anchors
> and table of contents in Policy are not working right now on the web
> site because of this problem.
>
> I feel like the single-page HTML version may have been a failed
> experiment, at least pending further work on Sphinx, and we should
> just publish the multi-page version.  What do other people think?
> (Adding debian-www for their opinion as well.)
>
> Not having working footnotes feels to me like kind of a showstopper.

Ah, I hadn't realised that this was an upstream bug.  I agree that it's
a showstopper.

Do you recall if we've already reported this upstream, Russ?  If not, I
would suggest we report it upstream and set ourselves a deadline; if the
bug is not fixed by that date, we abandon singlehtml on our mirrors.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#876075: Anchors are non-unique in the single-HTML version

[Russ Allbery]

Andrey Rahmatullin  writes:

> Package: debian-policy
> Version: 4.1.0.0
> Severity: normal

> https://www.debian.org/doc/debian-policy/#version
> https://www.debian.org/doc/debian-policy/index.html#introduction

> etc.

> This breaks the ToC.

More troublingly, this also breaks all the footnotes.  We can fix the
headings by explicitly setting an anchor, but I don't think the footnotes
are fixable without fixing things in Sphinx.

I'm not sure where we landed with this, but it feels like the single-HTML
output from Sphnix is kind of broken, and publishing that on the web site
has caused various problems.  I'm not sure how to get to the multi-page
version on www.debian.org, and indeed the anchors and table of contents in
Policy are not working right now on the web site because of this problem.

I feel like the single-page HTML version may have been a failed
experiment, at least pending further work on Sphinx, and we should just
publish the multi-page version.  What do other people think?  (Adding
debian-www for their opinion as well.)

Not having working footnotes feels to me like kind of a showstopper.

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

Bug#876075: Anchors are non-unique in the single-HTML version

[Andrey Rahmatullin]

On Mon, Sep 18, 2017 at 01:45:10PM +0500, Andrey Rahmatullin wrote:
> Package: debian-policy
> Version: 4.1.0.0
> Severity: normal
> 
> https://www.debian.org/doc/debian-policy/#version
> https://www.debian.org/doc/debian-policy/index.html#introduction
> 
> etc.
> 
> This breaks the ToC.
It also make impossible to link to such sections.

-- 
WBR, wRAR


signature.asc
Description: PGP signature

Bug#876075: Anchors are non-unique in the single-HTML version

[Andrey Rahmatullin]

Package: debian-policy
Version: 4.1.0.0
Severity: normal

https://www.debian.org/doc/debian-policy/#version
https://www.debian.org/doc/debian-policy/index.html#introduction

etc.

This breaks the ToC.



-- System Information:
Debian Release: buster/sid
  APT prefers unstable-debug
  APT policy: (500, 'unstable-debug'), (500, 'testing-debug'), (500, 
'unstable'), (500, 'testing'), (101, 'experimental')
Architecture: amd64 (x86_64)
Foreign Architectures: i386

Kernel: Linux 4.13.0-trunk-amd64 (SMP w/4 CPU cores)
Locale: LANG=ru_RU.UTF-8, LC_CTYPE=ru_RU.UTF-8 (charmap=UTF-8), LANGUAGE= 
(charmap=UTF-8)
Shell: /bin/sh linked to /usr/bin/dash
Init: systemd (via /run/systemd/system)

Versions of packages debian-policy depends on:
ii  libjs-sphinxdoc  1.6.3-2

debian-policy recommends no packages.

Versions of packages debian-policy suggests:
ii  doc-base  0.10.7

-- no debconf information