• Bug#877337: www.debian.org: Switch back to single page version of Polic

    From Sean Whitton@21:1/5 to All on Sat Sep 30 18:40:01 2017
    XPost: linux.debian.bugs.dist, linux.debian.www

    --x2752jeciuulah5d
    Content-Type: text/plain; charset=us-ascii
    Content-Disposition: inline
    Content-Transfer-Encoding: quoted-printable

    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

    --x2752jeciuulah5d
    Content-Type: text/x-diff; charset=us-ascii
    Content-Disposition: attachment; filename="0001-Publish-single-page-version-of-Debian-Policy-Manual.patch"
    Content-Transfer-Encoding: quoted-printable

    From dcb0c69aa246e8076f79d6838cd7eec34d57b815 Mon Sep 17 00:00:00 2001
    From: Sean Whitton <spwhitton@spwhitton.name>
    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
  • From Paul Wise@21:1/5 to All on Tue Oct 3 04:30:01 2017
    XPost: linux.debian.bugs.dist, linux.debian.www

    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

    -----BEGIN PGP SIGNATURE-----

    iQIzBAABCgAdFiEEYQsotVz8/kXqG1Y7MRa6Xp/6aaMFAlnS9J4ACgkQMRa6Xp/6 aaMQqRAAoiR/9qCikx5k8zSVthP/NcI6wo2yttPGnzO89aFx2eBWur8sUcKQl0Z9 jN1BF/pvrTz2TB8uvLYmwhuyHAmFNNPbE4EZeQ8623qCQzqzPAarn/VwjrZlhUL0 2I4Y05J8xn2cQI5Ge1zqKhJYsNLJHZHrNYJYHb7iPaNskkp5diFWI0DaVfKLJSAO EDrpxNgVaRX2/wyvy6HbHCWtiyHgLuTjYG79IsqS4ORUP3bAa2UtBAyNPjB3sCW1 UXNnVdfu429FL6qcN5uJsqic4n0uyxsCyMqv+suhD0YbkgASKupX/wrotIfgstL9 Pk6aP+BHNcM8mWeYkz+YDyQ2ow9CA1fbX7QLnZrRNR4He5mtI6Vh89LtAAHwobPS QCVEJ601GAdA2ZkZpyThemGxiaN3ZYW/QORxtV7/dC5CMofLLQ6CoQJk86moF/oL DXfPrRpV2Yfyub8YCNnRih46krAWp6f6uxEyvNPT+qwjHTnq3Sf0UjrN44/vzOgw Rlg1nj1HzAkoKXakyAwuKTnVftjlDOs09Tm87CHA7VECE6ThIZDGRmJP4r/AXx5b EHqnQOgpl5FgJIrYbrstWqJUoOcDh2zI9SmJP0J7CsO6e/kDseNmDut8xdB4WxRS VR2JqXuAafeaGwNKf5To5W1DXnlEuJxnK5FEhPB3meyxkxePT/4=
    =8xJa
    -----END PGP SIGNATURE-----

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Paul Wise@21:1/5 to Sean Whitton on Wed Oct 4 06:00:01 2017
    XPost: linux.debian.bugs.dist, linux.debian.www

    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
    <link> 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

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Sean Whitton@21:1/5 to Paul Wise on Wed Oct 4 05:50:01 2017
    XPost: linux.debian.bugs.dist, linux.debian.www

    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
    <link> tags will point to policy.html/, so they would break again if policy-1.html were copied within that directory. Given #

    --
    Sean Whitton

    --=-=-Content-Type: application/pgp-signature; name="signature.asc"

    -----BEGIN PGP SIGNATURE-----

    iQIzBAEBCgAdFiEEm5FwB64DDjbk/CSLaVt65L8GYkAFAlnUWHgACgkQaVt65L8G YkB1qA//by7NVZ9NAcCveNkRJkZ+3N2B5vRgLfJlbVHWK8UuFLgZJEv/tXbCXeM6 NNMGPx7kOttb/X7PGqxfjDLT6mUrEKjMVypJpk6TG3q6WeoMgwBynuiSrRw5BwH4 r6bXFr50rjqb/x5u1i0kVKoaZyZV53UupPfj5bDAivCglVNzGFKm8moRmURDbGMd Q26Ant543gH9TXxkWGussGwOJ5BiS+4JW0aD4JU67hdzb336+O2Omj22kG+hj5B5 I2U4BThl4afZdY5AT4H0XFX7q9oLnIVAiZanUFndBwsQsQmb+tw+Fjk2KayQHHx0 5nWpIYltf6jD/YvEIF3KgoYybFJm3zeyb+tGRkr3tu6qNq6Yk2EaAbx12JnMOOAD OJerqItS6xiBTDouUjVOgkr3LYW6hEUw3YmYATykfhpXaIUZGKPMAoM2ml8EHIJb JM+GLAgldp2bW4gTCUu1G3fug6ACSQIBprUtM2P3pE/IrKK02hbBxXLvBw5yQIqt /sUHO3jXJdTCKm3ezXaE0z6vDIEHRH3ZUtHPah8zNktqhtjIjjz3qtkZPQw6UTZ+ 00MXqXPAOvTYmxYr8XKBIAmxx+ZTeBsUJQ6NWDivldrLtmr5smQ4MGtZDubQscXh kN/YGMaNGeoE2yJd/DokbNEISIVmJ3w8kGWzDDL4A7olSW2BWUI=4HOX
    -----END PGP SIGNATURE-----

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)