Bug#40706: /usr/share/doc vs. /usr/doc

[Roland Rosenfeld <roland@spinnaker.de>]

Package: debian-policy
Version: 3.0.0.0
Severity: important

debian-policy 3.0.0.0 is now out and mentions to use
/usr/share/doc/<package> instead of /usr/doc/<package>.

This is principally the right way (according to FHS), but we cannot
recompile all packages now but we need a smooth way from one directory 
to the other.

We need an official way (noted in the policy or at least in
upgrading-checklist) to migrate from /usr/doc to /usr/share/doc,
otherwise the package maintainers will distribute the document files
between the two directories and users have to search both directories
to find the correct location of the files and web servers are no
longer able to detect the documentation as
http://localhost/doc/<package>.

So please let us handle this question with high priority, before there 
are packages uploaded, with documentation which cannot be found as
/usr/doc/<package>.


I don't have an optimal solution for this question, but the following
seems to do the job:

- New packages should use /usr/share/doc/<package> and create a
  symlink /usr/doc/<package> pointing to /usr/share/doc/<package>.
- The symlink allows us to access every documentation as
  /usr/doc/<package> in the transitional period.
- After the transitional period (when every package places its
  documentation under /usr/share/doc/<package>), we can find every
  package documentation as /usr/share/doc/<package>.
- At this time we can begin removing the symlinks when new packages
  are uploaded.


I would like to hear of better methods for a smooth transition, but I
did not see any better solution yet (other ideas intend to tell the
web sever to search both directories, but this doesn't help the user
who is searching the correct directory).

Ciao

        Roland

-- 
 * roland@spinnaker.de * http://www.spinnaker.de/ *
 PGP: 1024/DD08DD6D   2D E7 CC DE D5 8D 78 BE  3C A0 A4 F1 4B 09 CE AF