Bug#877337: www.debian.org: Switch back to single page version of Policy Manual

[Sean Whitton]

Hello,

On Fri, Dec 01 2017, Sean Whitton wrote:

> How about renaming index.html to policy.html and policy-1.html to
> index.html on the web mirrors?

Sorry, this was a stupid suggestion and won't work.  There are
references to index.html in the chapters.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#877337: www.debian.org: Switch back to single page version of Policy Manual

[Sean Whitton]

Hello Laura,

On Fri, Dec 01 2017, Laura Arjona Reina wrote:

> My proposal is to clarify, at the top of the document, what the user gets, and
> where are the other formats. In particular, add this paragraph (or something
> similar) right after "This is Debian Policy version 4.1.2.0, released on
> 2017-11-30.":
>
> ---
> This is Debian Policy version 4.1.2.0, released on 2017-11-30.
>
> This document is also available from the Debian web mirrors at
> https://www.debian.org/doc/debian-policy/ in several formats:
> * single page HTML (at [policy-1.html],
> https://www.debian.org/doc/debian-policy/ redirects to this),
> * HTML splitted in chapters
> ([https://www.debian.org/doc/debian-policy/index.html]),
> * electronic book ([policy.epub]) and printable format ([policy.pdf]),
> * plain text (without section numbering) ([policy.txt]).
> ---

I don't think this really answers my concern that it is confusing for
/debian-policy/ and /debian-policy/index.html not to be the same page.

How about renaming index.html to policy.html and policy-1.html to
index.html on the web mirrors?

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#877337: www.debian.org: Switch back to single page version of Policy Manual

[Laura Arjona Reina]

Hello

El 04/10/17 a las 05:50, Paul Wise escribió:
> On Wed, Oct 4, 2017 at 11:41 AM, Sean Whitton wrote:
> 
>> - installing the policy.html/ dir as 
>> https://www.debian.org/doc/debian-policy/;
>> - copying policy-1.html into that dir; and
>> - telling Apache to serve policy-1.html as the directory index?
> 
> Correct.
> 
>> I'm a little worried people could be very confused (why is
>> debian-policy/index.html different from debian-policy/?!  is there some
>> cache refresh needed somewhere?) but I don't object.
> 
> Hmm, I'm not sure what to do about that.

My proposal is to clarify, at the top of the document, what the user gets, and
where are the other formats. In particular, add this paragraph (or something
similar) right after "This is Debian Policy version 4.1.2.0, released on
2017-11-30.":

---
This is Debian Policy version 4.1.2.0, released on 2017-11-30.

This document is also available from the Debian web mirrors at
https://www.debian.org/doc/debian-policy/ in several formats:
* single page HTML (at [policy-1.html],
https://www.debian.org/doc/debian-policy/ redirects to this),
* HTML splitted in chapters
([https://www.debian.org/doc/debian-policy/index.html]),
* electronic book ([policy.epub]) and printable format ([policy.pdf]),
* plain text (without section numbering) ([policy.txt]).
---

and then change the "New versions of this document" to the following:


New versions of this document

This manual is distributed via the Debian package debian-policy.

Policy changes between versions of this document are described in the [Upgrading
checklist](relative_link) which is also available as a standalone copy in the
debian-policy package and the [corresponding chapter in HTML
version](https://www.debian.org/doc/debian-policy/document-upgrading-checklist).


If this proposal is accepted, I'm happy to provide patches against debian-policy
to implement this. In the website version we would include both the single html
and the splitted in chapters html, and then, also fix the bug #877367
(www.debian.org: Please consider adding redirects for old Policy
chapters/appendices) without the need of adding redirects.

What do you think?

Cheers
-- 
Laura Arjona Reina
https://wiki.debian.org/LauraArjona

Bug#877337: www.debian.org: Switch back to single page version of Policy Manual

[Paul Wise]

On Wed, Oct 4, 2017 at 11:41 AM, Sean Whitton wrote:

> - installing the policy.html/ dir as 
> https://www.debian.org/doc/debian-policy/;
> - copying policy-1.html into that dir; and
> - telling Apache to serve policy-1.html as the directory index?

Correct.

> I'm a little worried people could be very confused (why is
> debian-policy/index.html different from debian-policy/?!  is there some
> cache refresh needed somewhere?) but I don't object.

Hmm, I'm not sure what to do about that.

> I'm about to upload a fix for that, though, following your advice, the
>  tags will point to policy.html/, so they would break again if
> policy-1.html were copied within that directory.

You could use symlinks in the package instead to avoid that.

-- 
bye,
pabs

https://wiki.debian.org/PaulWise

Bug#877337: www.debian.org: Switch back to single page version of Policy Manual

[Sean Whitton]

Hello Paul,

On Tue, Oct 03 2017, Paul Wise wrote:

> I propose to do it by placing both versions of the document into the
> same directory and then setting the DocumentIndex Apache configuration
> option to prefer the single page document over the multi-page one.

You mean

- installing the policy.html/ dir as https://www.debian.org/doc/debian-policy/;
- copying policy-1.html into that dir; and
- telling Apache to serve policy-1.html as the directory index?

I'm a little worried people could be very confused (why is
debian-policy/index.html different from debian-policy/?!  is there some
cache refresh needed somewhere?) but I don't object.

> The only problem with this is #877573 but that also affects offline
> readers of Debian Policy anyway so it needs to be fixed anyway.

I'm about to upload a fix for that, though, following your advice, the
 tags will point to policy.html/, so they would break again if
policy-1.html were copied within that directory.  Given #

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#877337: www.debian.org: Switch back to single page version of Policy Manual

[Paul Wise]

On Sat, 30 Sep 2017 09:33:52 -0700 Sean Whitton wrote:

> We (the active Policy Team members) think that the single page version
> is more suitable for Debian's web mirrors.  This is because it is more
> useful for newcomers: with the single page version, it is possible to
> use your browser's search function to search across the entire document.
> More experienced users, who want the multi-page version, probably have
> the debian-policy package installed locally.

I wonder if we could accommodate both categories of Debian Policy
readers instead of dropping support for more experienced readers?

I propose to do it by placing both versions of the document into the
same directory and then setting the DocumentIndex Apache configuration
option to prefer the single page document over the multi-page one.

The advantage of this is that we accommodate folks who prefer the
existing multi-page document and no existing URL will break but that by
default new users will get the single-page version.

The only problem with this is #877573 but that also affects offline
readers of Debian Policy anyway so it needs to be fixed anyway.

I have verified with diffoscope that the _static and _images
directories are identical between the two documents.

If there are no objections to this then I can do the changes needed.

-- 
bye,
pabs

https://wiki.debian.org/PaulWise


signature.asc
Description: This is a digitally signed message part

Bug#877337: www.debian.org: Switch back to single page version of Policy Manual

[Sean Whitton]

Hello Laura,

On Sun, Oct 01 2017, Laura Arjona Reina wrote:

> I've applied your patch, and also reviewed our mvhtml_sphinx()
> function and adapted it to copy the 1-page manual and the _static and
> _images files only.
>
> (If in the future the package carries translations, we'll need to
> readapt this function to take care about the translations, too).
>
> After running the last website build,
> https://www.debian.org/doc/debian-policy seems to show the correct
> info.
>
> Since the old files were still there, I've logged in
> www-master.debian.org and removed them manually (together with some
> other .gz files of old versions of debian-policy). I believe that
> these changes will be visible in the next website build (the old files
> will be removed from mirrors too).

Many thanks for all your work on this today.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#877337: www.debian.org: Switch back to single page version of Policy Manual

[Laura Arjona Reina]

Hello Sean

El 30/09/17 a las 18:33, Sean Whitton escribió:
> 
> Please revert this, so the single page version is published on our web
> mirrors.  Here is a patch (against [1]; unfortunately, I'm not in a
> position to test it).  I'd appreciate it if this change could be made
> quickly, to avoid URLs to the multi page version ending up in too many
> mailing list posts/other documents.

I've applied your patch, and also reviewed our mvhtml_sphinx() function and
adapted it to copy the 1-page manual and the _static and _images files only.

(If in the future the package carries translations, we'll need to readapt this
function to take care about the translations, too).

After running the last website build, https://www.debian.org/doc/debian-policy
seems to show the correct info.

Since the old files were still there, I've logged in www-master.debian.org and
removed them manually (together with some other .gz files of old versions of
debian-policy). I believe that these changes will be visible in the next website
build (the old files will be removed from mirrors too).

I leave this bug open for the case further action is needed; if everything goes
well I'll close the bug in some days.

Best regards
-- 
Laura Arjona Reina
https://wiki.debian.org/LauraArjona

Bug#877337: www.debian.org: Switch back to single page version of Policy Manual

[Sean Whitton]

Package: www.debian.org
Severity: normal
Tags: patch

Hello www-team,

One of the improvements for which we switched Debian Policy to build
with Sphinx was the ability to output the Policy Manual as a single HTML
page.  Previously, it was only possible to output the Policy Manual as a
number of interlinked HTML pages.

We (the active Policy Team members) think that the single page version
is more suitable for Debian's web mirrors.  This is because it is more
useful for newcomers: with the single page version, it is possible to
use your browser's search function to search across the entire document.
More experienced users, who want the multi-page version, probably have
the debian-policy package installed locally.

When we uploaded Policy 4.1.0.0, this had the effect of switching the
version of the Policy Manual published on the web mirrors from
multi-page to single page.  But this was because we screwed up the
installed paths (see #872895).  With Policy 4.1.1.0, we've fixed the
paths, and so the version of the Policy Manual published on the web
mirrors has reverted to the multi-page version.

Please revert this, so the single page version is published on our web
mirrors.  Here is a patch (against [1]; unfortunately, I'm not in a
position to test it).  I'd appreciate it if this change could be made
quickly, to avoid URLs to the multi page version ending up in too many
mailing list posts/other documents.

@@ -392,7 +392,8 @@ echo -n "Installing documents:"
 # Debian Policy Manual
 unpack debian-policy
 mvdocs debian-policy usr/share/doc/debian-policy NO en / policy
-mvhtml_sphinx debian-policy usr/share/doc/debian-policy/policy.html NO en /
+mvhtml_sphinx debian-policy usr/share/doc/debian-policy/policy-1.html NO 
en /
+mv -f $webdocdir/debian-policy/policy-1.html 
$webdocdir/debian-policy/index.html
 
 mvdocs fhs usr/share/doc/debian-policy/fhs NO en packaging-manuals/ fhs-2.3
 mvhtml fhs usr/share/doc/debian-policy/fhs NO en packaging-manuals/ fhs-2.3

[1]  https://anonscm.debian.org/cgit/debwww/cron.git/tree/parts/7doc

-- 
Sean Whitton
From dcb0c69aa246e8076f79d6838cd7eec34d57b815 Mon Sep 17 00:00:00 2001
From: Sean Whitton 
Date: Sat, 30 Sep 2017 09:33:08 -0700
Subject: [PATCH] Publish single page version of Debian Policy Manual

---
 parts/7doc | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/parts/7doc b/parts/7doc
index 4917094..8905599 100755
--- a/parts/7doc
+++ b/parts/7doc
@@ -392,7 +392,8 @@ echo -n "Installing documents:"
 # Debian Policy Manual
 unpack debian-policy
 mvdocs debian-policy usr/share/doc/debian-policy NO en / policy
-mvhtml_sphinx debian-policy usr/share/doc/debian-policy/policy.html NO en /
+mvhtml_sphinx debian-policy usr/share/doc/debian-policy/policy-1.html NO en /
+mv -f $webdocdir/debian-policy/policy-1.html $webdocdir/debian-policy/index.html
 
 mvdocs fhs usr/share/doc/debian-policy/fhs NO en packaging-manuals/ fhs-2.3
 mvhtml fhs usr/share/doc/debian-policy/fhs NO en packaging-manuals/ fhs-2.3
-- 
2.14.1



signature.asc
Description: PGP signature