Bug#872944: #872944 www.debian.org: Remove JavaScript from Policy Manual published on web mirrors

[Sean Whitton]

Hello,

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.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#872944: #872944 www.debian.org: Remove JavaScript from Policy Manual published on web mirrors

[Holger Levsen]

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.


-- 
cheers,
Holger

 ⢀⣴⠾⠻⢶⣦⠀
 ⣾⠁⢠⠒⠀⣿⡁  holger@(debian|reproducible-builds|layer-acht).org
 ⢿⡄⠘⠷⠚⠋⠀  OpenPGP: B8BF54137B09D35CF026FE9D 091AB856069AAA1C
 ⠈⠳⣄

Another end of the world is possible.


signature.asc
Description: PGP signature

Bug#872944: #872944 www.debian.org: Remove JavaScript from Policy Manual published on web mirrors

[Thomas Lange]

Currently we have a working solution using js and providing multi page
html. That's a good solution which is already available.


> I did not go deeper into this scenario, I just found 
> https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=877337
> which includes a forward-backword-forward dance switching multiple
> times between multi-page and single-page html variant requests.
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.

-- 
regards Thomas

Bug#872944: #872944 www.debian.org: Remove JavaScript from Policy Manual published on web mirrors

[Holger Wansing]

Hi,

Bill Allombert  wrote (Wed, 10 Apr 2024 
22:24:20 +0200):
> On Wed, Apr 10, 2024 at 09:33:50PM +0200, Holger Wansing wrote:
> > Hello www team and debian-policy editor team,
> > 
> > Note: apparently we have no alternative beside js, if we want full-text 
> > search for html output (single-page html could be a possible way, but 
> > that output format has been disabled due to various other issues).
> 
> Sorry, but why is this so hard to generate a single-page html ?
> debiandoc could do it. Using the browser intra-page search is always much
> easier/faster that using a search box.

I did not go deeper into this scenario, I just found 
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=877337
which includes a forward-backword-forward dance switching multiple
times between multi-page and single-page html variant requests.


Holger


-- 
Holger Wansing 
PGP-Fingerprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076

Bug#872944: #872944 www.debian.org: Remove JavaScript from Policy Manual published on web mirrors

[Bill Allombert]

On Wed, Apr 10, 2024 at 09:33:50PM +0200, Holger Wansing wrote:
> Hello www team and debian-policy editor team,
> 
> Note: apparently we have no alternative beside js, if we want full-text 
> search for html output (single-page html could be a possible way, but 
> that output format has been disabled due to various other issues).

Sorry, but why is this so hard to generate a single-page html ?
debiandoc could do it. Using the browser intra-page search is always much
easier/faster that using a search box.

Cheers,
Bill.

Bug#872944: #872944 www.debian.org: Remove JavaScript from Policy Manual published on web mirrors

[Thomas Lange]

> On Wed, 10 Apr 2024 21:33:50 +0200, Holger Wansing  
> said:


> The second javascript functionality is the full-text search.

> Please note, that I made use of javascript by intend, despite of this bug 
> requesting to remove all js functionality.
Hi holger,

in the past we tried to avoid javascript, but that's long time ago
(like 7 years) and nowadays I see no reason to do web pages without it
if we loose functionality.

So please go ahead and use js. I think the search function is very important.

I think it's important not to load js code on our pages from an
external URL, but to provide it from our web servers (selfhosted).

> Please note, that this decision is not only for debian-policy, but for
> all sphinx-based manuals on Debian website.
> (I hope we don't make different decisions on this question for the 
> various manuals we have. That would make the implentation once again
> more difficult.)
All sphinx-based manuals can use js from my point of view. There's no
reason to handle some manuals differently.


> What should be done now?
Close the bug that request to remove all js functionality (#876241).

-- 
regards Thomas

Bug#872944: #872944 www.debian.org: Remove JavaScript from Policy Manual published on web mirrors

[Holger Wansing]

Hello www team and debian-policy editor team,


in-line with activating the new html theme on our website I also
worked on the javascript front:

to make the html theme work on small screens (smartphones) the readthedocs.org
theme relies on javascript functionality, to display a sidebar with the table
of content only, when the device is in landscape direction resp. when the 
burger button is pressed.

The second javascript functionality is the full-text search.

I made all needed changings, to get the above functions work and they are doing 
fine now. See 

Please note, that I made use of javascript by intend, despite of this bug 
requesting to remove all js functionality.
This is because I wanted to find out,  what we need (aka which javascript 
packages) to make all the above mentioned functions work. 
Since I lack the skills to value this simply by studying source code and 
reading documentation, I had to test this in live to be sure.

The outcome of this is:
we need content of the javascript packages "libjs-sphinxdoc" and "libjs-jquery" 
existing in the manuals' path, to accomplish the above goals.

We need to decide now, if we want these functionality, when they require 
those javascript packages. 
Or if we skip such functionality.

Note: apparently we have no alternative beside js, if we want full-text 
search for html output (single-page html could be a possible way, but 
that output format has been disabled due to various other issues).

And being able to show/hide the sidebar on smartphones is a great benefit
when screen size is limited.


There are requests to not use js, but it has also been mentioned, that it
may be worth it enabling js, because of the relatively reduced amount of js 
use in sphinxdoc / jquery.
Note: I'm lacking skills to inspect source code, which other functions are
integrated in the doctools.js / jquery.js / searchtools.js / sphinx-highlight.js
scripts resp. what the functions I find there are doing exactly! 
Maybe someone can make a statement here?

I would like to mention another point:
it's a Browser functionality for decades to have the possibility to disable
use of JavaScript. So people who want to avoid any risk due to js, can or
will most probably have JavaScript disabled in the Browser settings anyway.


Please note, that this decision is not only for debian-policy, but for
all sphinx-based manuals on Debian website.
(I hope we don't make different decisions on this question for the 
various manuals we have. That would make the implentation once again
more difficult.)



What should be done now?


Holger