Bug#906949: Clarify documentation location in a Python2-less distribution

[Ian Jackson <ijackson@chiark.greenend.org.uk>]

Simon McVittie writes ("Re: Bug#906949: Clarify documentation location in a Python2-less distribution"):
> On Thu, 23 Aug 2018 at 15:43:06 +0100, Ian Jackson wrote:
> > There are two reasons for the standardised paths in /usr/share/doc:
> >  1. So that the user can find the right documentation.
> >  2. So that you avoid clashes with other packagkes.
> > 
> > Not moving the docs about assists 1.  As does providing a link
> > /usr/share/doc/python3-foo -> python-foo.
> 
> It would be non-Policy-compliant for python3-foo to have a symlink
> /usr/share/doc/python3-foo -> python-foo unless it Depends on
> python-foo (= ${binary:Version}), because python3-foo is required to
> contain or provide a corresponding /usr/share/doc/python3-foo/copyright
> and .../changelog.Debian.gz.

I think you have misunderstood me.  I am suggesting that, when python2
package is dropped, the python3 package would ship both
  /usr/share/doc/python-foo
  /usr/share/doc/python3-foo
and one would be a symlink to the other.

There would have to be some care taken to make the upgrade smooth.

> Similarly, you can't do that unless python3-foo Conflicts: python-foo,
> which seems like overly-aggressive deprecation :-)

We would need to get around that, indeed.  By managing the link in
maintainer scripts.

> Symlinks *inside* the per-package documentation directory are OK though,
> for example /usr/share/doc/python3-foo/html -> ../python-foo/html, or
> perhaps more realistically
> /usr/share/doc/python{,3}-foo/html -> ../python-foo-doc/html,
> which is how this works in src:dbus-python for example.

That would be another possibility.

Ian.

-- 
Ian Jackson <ijackson@chiark.greenend.org.uk>   These opinions are my own.

If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
a private address which bypasses my fierce spamfilter.