Bug#872895: debian-policy: Split html for policy lost

[Guillem Jover]

On Tue, 2017-08-22 at 17:26:32 -0700, Sean Whitton wrote:
> On Tue, Aug 22 2017, Guillem Jover wrote:
> > I guess there are two problems here, one is indeed completely losing
> > the multi-page rendering from the package. The other is the default
> > change in the web site. IMO the best solution, and what is customary,
> > is to present both (or more) rendering and let the user select:
> >
> >   [HTML one-page] [HTML multi-page] [PDF] [EPUB]
> 
> So you'd like https://www.debian.org/doc/debian-policy/ to be a menu?

No,  which already
contains such menu. I'd rather see no change to the default and just
see the multi-page one added as an additional "format", so that we do
not break links etc. It's very common, and it's been so for people to
post URLs to the multi-page URLs BTW. I think having to add lots of
redirects would be counter-producive.

Thanks,
Guillem

Bug#872895: debian-policy: Split html for policy lost

[Russ Allbery]

Control: tags -1 pending

Guillem Jover  writes:

> This version has lost the distinction between a single policy html and
> the one with different files per chapter. This will break links.

Okay, I think this is fixed in Git and Policy should now ship both the
single-file and the multi-file versions in the same directories they were
in before the conversion to reStructuredText.  The multi-file version is
in policy.html and the single-file version is policy-1.html.

This also required adding _static and _images to the top-level of the
usr/share/doc directory because single-file from Sphinx isn't strictly
single file (and we have images now), but I think it should all work.  The
tricky part will be on the debian-www side in copying things over.  I'll
give them a warning that more changes are coming.

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

Bug#872895: debian-policy: Split html for policy lost

[Sean Whitton]

control: retitle -1 Include multi-page HTML in package
^ see below for explanation

Hello,

On Tue, Aug 22 2017, Mattia Rizzolo wrote:

> On Tue, Aug 22, 2017 at 12:10:36PM -0700, Sean Whitton wrote:
>> - it would be nice to include the multi-page rendering in the package
>
> More than nice, please.  I don't really deal with huge single-page
> documents.  Besides you wrote:
>> The single page output is much more useful to casual readers wanting
>> to look something up
> I deem this completely subjective, please don't assume such assertion as
> facts.  Also, I don't consider myself a "causual reader" and when I want
> to read something up I know what's the name of the paragrah, pick it
> from the index and then head to the relevant, single page.

Right, indeed, you're not a casual reader, and we would expect you to
have the Debian package installed.  I think the web version should be
tailored for people coming from outside the project who don't know that
such a package exists.  For them, it's easier to have a single page.

This is subjective but that doesn't preclude me making a judgement about
what most people would prefer, based on my experience.

>> - since we're publishing only the single-page version on
>> www.debian.org, we need to rewrite the links
>
> Please do publish both.

On Tue, Aug 22 2017, Guillem Jover wrote:

> I guess there are two problems here, one is indeed completely losing
> the multi-page rendering from the package. The other is the default
> change in the web site. IMO the best solution, and what is customary,
> is to present both (or more) rendering and let the user select:
>
>   [HTML one-page] [HTML multi-page] [PDF] [EPUB]

So you'd like https://www.debian.org/doc/debian-policy/ to be a menu?

I think that those who want this should file a bug against
www.debian.org.  It's not really in our purview, since we don't maintain
the script that maintains the /doc/ directory.  Hence I'm retitling this
bug to the part that is the policy editors' responsibility.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#872895: debian-policy: Split html for policy lost

[Guillem Jover]

Hi!

On Tue, 2017-08-22 at 11:09:37 -0700, Jonathan Nieder wrote:
> Sean Whitton wrote:
> > On Tue, Aug 22 2017, Guillem Jover wrote:
> >> This version has lost the distinction between a single policy html and
> >> the one with different files per chapter. This will break links.
> >
> > This was intentional.  The single page output is much more useful to
> > casual readers wanting to look something up.

When I want to search for something in an on-line document I also
select the single-page document if it's available. Otherwise when I
want to navigate the document or read specific parts, I find the
multi-page way more pleasant and clear, because each chapter is
contained so I know how much there is to finish it, and scrolling or
using say the Ini/End key take you to the expected boundaries, and
it tends to have a global and intrapage TOCs to go to specific parts.

> I don't completely understand.  The old rendering had both single page
> and multi-page versions.  If I understand what you're saying, it is a
> reason that the single-page version is useful, but why does that
> preclude also providing the multi-page rendering?

I guess there are two problems here, one is indeed completely losing
the multi-page rendering from the package. The other is the default
change in the web site. IMO the best solution, and what is customary,
is to present both (or more) rendering and let the user select:

  [HTML one-page] [HTML multi-page] [PDF] [EPUB]

Thanks,
Guillem

Bug#872895: debian-policy: Split html for policy lost

[Mattia Rizzolo]

On Tue, Aug 22, 2017 at 12:10:36PM -0700, Sean Whitton wrote:
> - it would be nice to include the multi-page rendering in the package

More than nice, please.  I don't really deal with huge single-page
documents.  Besides you wrote:
> The single page output is much more useful to casual readers wanting
> to look something up
I deem this completely subjective, please don't assume such assertion as
facts.  Also, I don't consider myself a "causual reader" and when I want
to read something up I know what's the name of the paragrah, pick it
from the index and then head to the relevant, single page.

> - since we're publishing only the single-page version on www.debian.org,
>   we need to rewrite the links

Please do publish both.

-- 
regards,
Mattia Rizzolo

GPG Key: 66AE 2B4A FCCF 3F52 DA18  4D18 4B04 3FCD B944 4540  .''`.
more about me:  https://mapreri.org : :'  :
Launchpad user: https://launchpad.net/~mapreri  `. `'`
Debian QA page: https://qa.debian.org/developer.php?login=mattia  `-


signature.asc
Description: PGP signature

Bug#872895: debian-policy: Split html for policy lost

[Sean Whitton]

Hello Jonathan,

On Tue, Aug 22 2017, Jonathan Nieder wrote:

> I don't completely understand.  The old rendering had both single page
> and multi-page versions.  If I understand what you're saying, it is a
> reason that the single-page version is useful, but why does that
> preclude also providing the multi-page rendering?

Ah, sorry, I think there are two bugs here:

- it would be nice to include the multi-page rendering in the package

- since we're publishing only the single-page version on www.debian.org,
  we need to rewrite the links

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#872895: debian-policy: Split html for policy lost

[Jonathan Nieder]

Hi,

Sean Whitton wrote:
> On Tue, Aug 22 2017, Guillem Jover wrote:

>> This version has lost the distinction between a single policy html and
>> the one with different files per chapter. This will break links.
>
> This was intentional.  The single page output is much more useful to
> casual readers wanting to look something up.

I don't completely understand.  The old rendering had both single page
and multi-page versions.  If I understand what you're saying, it is a
reason that the single-page version is useful, but why does that
preclude also providing the multi-page rendering?

Thanks,
Jonathan

Bug#872895: debian-policy: Split html for policy lost

[Sean Whitton]

Hello Guillem,

On Tue, Aug 22 2017, Guillem Jover wrote:

> This version has lost the distinction between a single policy html and
> the one with different files per chapter. This will break links.

This was intentional.  The single page output is much more useful to
casual readers wanting to look something up.

I think that maybe we should reassign this bug to www.debian.org to
request rewriting of the old URIs?

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#872895: debian-policy: Split html for policy lost

[Guillem Jover]

Package: debian-policy
Version: 4.1.0.0

Hi!

This version has lost the distinction between a single policy html and
the one with different files per chapter. This will break links.

Thanks,
Guillem