Re: single-page html of debian-policy to be revived?
On Sat, Apr 27, 2024 at 10:15:19AM +0100, Sean Whitton wrote: > Hello, > > On Mon 15 Apr 2024 at 09:59am GMT, Holger Levsen wrote: > > > On Sun, Apr 14, 2024 at 08:43:51PM +0800, Sean Whitton wrote: > >> ... but if dev-ref is already shipping both, maybe singlepage is indeed > >> usable these days ... > > > > I think it is. > > > >> > Could the Policy Editors team check, if everything is fine now, and if > >> > this should be published again? > >> > At least there is still an issue with the footnotes, there are 16 > >> > occurrences > >> > of #id1 for example... (search for "[1]" in policy-1.html). > >> Hrm. That seems like a pretty serious problem :\ > > > > I wouldnt call it serious. annoying yes, maybe. > > > >> Holger L., did you know about this issue? > >> Did you decide it was worth publishing anyway? > > > > yes. > > > > https://www.debian.org/doc/manuals/developers-reference/pkgs.en.html#how-could-installing-a-package-into-testing-possibly-break-other-packages > > or (single page) > > https://www.debian.org/doc/manuals/developers-reference/developers-reference.en.html#how-could-installing-a-package-into-testing-possibly-break-other-packages > > both show four footnotes, right where they belong, it's just that > > each foot note is numbered and that [1] or [2] or whatever is > > a link, pointing to a wrong place. > > > > I agree it's a bug, but I do think it's a pretty harmless one. > > Thanks. I'd be grateful for some feedback from other regular Policy > contributors. My view is that any issue with single-page is much more likely to be fixed if we use it than if we do not. I note that the links from the text to the footnotes are correct, it is only the backlink from the footnotes to the text which are wrong. I consider this minor. Cheers, -- Bill. Imagine a large red swirl here.
Re: single-page html of debian-policy to be revived?
Hello, On Mon 15 Apr 2024 at 09:59am GMT, Holger Levsen wrote: > On Sun, Apr 14, 2024 at 08:43:51PM +0800, Sean Whitton wrote: >> ... but if dev-ref is already shipping both, maybe singlepage is indeed >> usable these days ... > > I think it is. > >> > Could the Policy Editors team check, if everything is fine now, and if >> > this should be published again? >> > At least there is still an issue with the footnotes, there are 16 >> > occurrences >> > of #id1 for example... (search for "[1]" in policy-1.html). >> Hrm. That seems like a pretty serious problem :\ > > I wouldnt call it serious. annoying yes, maybe. > >> Holger L., did you know about this issue? >> Did you decide it was worth publishing anyway? > > yes. > > https://www.debian.org/doc/manuals/developers-reference/pkgs.en.html#how-could-installing-a-package-into-testing-possibly-break-other-packages > or (single page) > https://www.debian.org/doc/manuals/developers-reference/developers-reference.en.html#how-could-installing-a-package-into-testing-possibly-break-other-packages > both show four footnotes, right where they belong, it's just that > each foot note is numbered and that [1] or [2] or whatever is > a link, pointing to a wrong place. > > I agree it's a bug, but I do think it's a pretty harmless one. Thanks. I'd be grateful for some feedback from other regular Policy contributors. -- Sean Whitton signature.asc Description: PGP signature
Re: single-page html of debian-policy to be revived?
On Sun, Apr 14, 2024 at 08:43:51PM +0800, Sean Whitton wrote: > ... but if dev-ref is already shipping both, maybe singlepage is indeed > usable these days ... I think it is. > > Could the Policy Editors team check, if everything is fine now, and if > > this should be published again? > > At least there is still an issue with the footnotes, there are 16 > > occurrences > > of #id1 for example... (search for "[1]" in policy-1.html). > Hrm. That seems like a pretty serious problem :\ I wouldnt call it serious. annoying yes, maybe. > Holger L., did you know about this issue? > Did you decide it was worth publishing anyway? yes. https://www.debian.org/doc/manuals/developers-reference/pkgs.en.html#how-could-installing-a-package-into-testing-possibly-break-other-packages or (single page) https://www.debian.org/doc/manuals/developers-reference/developers-reference.en.html#how-could-installing-a-package-into-testing-possibly-break-other-packages both show four footnotes, right where they belong, it's just that each foot note is numbered and that [1] or [2] or whatever is a link, pointing to a wrong place. I agree it's a bug, but I do think it's a pretty harmless one. -- cheers, Holger ⢀⣴⠾⠻⢶⣦⠀ ⣾⠁⢠⠒⠀⣿⡁ holger@(debian|reproducible-builds|layer-acht).org ⢿⡄⠘⠷⠚⠋⠀ OpenPGP: B8BF54137B09D35CF026FE9D 091AB856069AAA1C ⠈⠳⣄ "Any fool can know. The point is to understand." - A. Einstein signature.asc Description: PGP signature
Re: single-page html of debian-policy to be revived?
Hello, On Sun 14 Apr 2024 at 01:57pm +02, Holger Wansing wrote: > 1. > Currently, the package does not ship this version. So this would have to > be re-added there. The changelog for 4.2.0.0 says * Stop installing policy-1.html because Sphinx's singlehtml output is too buggy at present (Closes: #873456, #876075, #879048). See also #877367. Thanks to Paul Wise for switching the web mirrors away from policy-1.html. I had forgotten about this. It seems that the first thing to do would be to determine if the issues discussed in those bugs still exist. > 2. > There are pro's and con's for both the single-page and multi-page variants. > Thus the only possible way IMO is to ship both via www.d.o. > The developers-refererence also ships both already, so it would be consistent > there. ... but if dev-ref is already shipping both, maybe singlepage is indeed usable these days ... > Could the Policy Editors team check, if everything is fine now, and if > this should be published again? > At least there is still an issue with the footnotes, there are 16 occurrences > of #id1 for example... (search for "[1]" in policy-1.html). Hrm. That seems like a pretty serious problem :\ Holger L., did you know about this issue? Did you decide it was worth publishing anyway? -- Sean Whitton signature.asc Description: PGP signature
single-page html of debian-policy to be revived?
Hi, Sean Whitton wrote (Sun, 14 Apr 2024 12:27:34 +0800): > On Thu 11 Apr 2024 at 08:32am GMT, Holger Levsen wrote: > > > On Thu, Apr 11, 2024 at 09:18:06AM +0200, Thomas Lange wrote: > >> A single page html may be an additional option but there's already the > >> single page txt version and the PDF. That's sufficient and I see no > >> need in providing more formats of this manual. > >> > >> Therefore we can close this and I will close 877337. > > > > fwiw, I disagree with this conclusion. single page txt and pdf versions > > are no replacements for single page html. > > I agree, and still think we should be publishing the single page version. 1. Currently, the package does not ship this version. So this would have to be re-added there. 2. There are pro's and con's for both the single-page and multi-page variants. Thus the only possible way IMO is to ship both via www.d.o. The developers-refererence also ships both already, so it would be consistent there. To make the existing mechanism work, which finds both variants on the web mirrors via webwml, the single-page html file needs to be named debian-policy.html: https://salsa.debian.org/webmaster-team/webwml/-/blob/master/english/doc/devel-manuals.defs?ref_type=heads That needs to be dealed with in the package, just renaming the file does not work, since it would break all the internal links. (Don't know how it worked in the past on the website with the file being named policy-1.html though.) 3. There were several bugs (e.g. #873456, #876075, #879048) with the single-page html version. Are they known to be solved now? Sphinx has received much development in the past 7 years, so there may be a chance to have them fixed ... (?) To get an idea of where we stand, I have built latest version of debian-policy with re-activated singlehtml variant (build via sbuild, so with latest Sphinx version), made the copy-and-rename dance which happens on wolkenstein for publication on www.d.o and pushed the result at https://people.debian.org/~holgerw/debian-policy-with-singlehtml/ The multi-page html is found via https://people.debian.org/~holgerw/debian-policy-with-singlehtml/debian-policy/index.html while single-page html is at https://people.debian.org/~holgerw/debian-policy-with-singlehtml/debian-policy/policy-1.html Could the Policy Editors team check, if everything is fine now, and if this should be published again? At least there is still an issue with the footnotes, there are 16 occurrences of #id1 for example... (search for "[1]" in policy-1.html). So long Holger -- Holger Wansing PGP-Fingerprint: 496A C6E8 1442 4B34 8508 3529 59F1 87CA 156E B076
