Bug#69311: PROPOSAL] Finishing the /usr/doc -> /usr/share/doc transition.

[Adrian Bunk <bunk@fs.tum.de>]

On Sun, 20 Aug 2000, Chris Waters wrote:

> I think an addendum is needed to this proposal -- if any package *has*
> had symlinks in /usr/doc, then it needs to clean them up in its
> install scripts, now, and possibly forever.
> 
> This is one of the reasons I objected to the symlinks in the first
> place -- now a *whole* bunch of packages are going to have to carry
> extra cruft for an indefinite period of time -- but since we went
> ahead and implemented the symlinks, we damn well better be willing to
> pay the price.
> 
> Without such an addendum, I object to this proposal.  With it, I will 
> second.  Personally, I think one of the people who crammed the symlink
> idea through should be forced to do the work of creating the proper   
> patches to policy (and maybe to debhelper).  Santiago and I (in a rare
> point of agreement) tried to prevent this mess.  We failed, but we
> shouldn't be forced to clean it up now.


Current policy says:

     Former Debian releases placed all additional documentation in
     `/usr/doc/<package>'.  To realize a smooth migration to
     `/usr/share/doc/<package>', each package must maintain a symlink
     `/usr/doc/<package>' that points to the new location of its
     documentation in `/usr/share/doc/<package>'[1].  The symlink must be
     created when the package is installed; it cannot be contained in the
     package itself due to problems with `dpkg'.  One reasonable way to
     accomplish this is to put the following in the package's `postinst':

            if [ "$1" = "configure" ]; then
                  if [ -d /usr/doc -a ! -e /usr/doc/#PACKAGE# \
                      -a -d /usr/share/doc/#PACKAGE# ]; then
                          ln -sf ../share/doc/#PACKAGE# /usr/doc/#PACKAGE#
                  fi
            fi

     And the following in the package's `prerm':

            if [ \( "$1" = "upgrade" -o "$1" = "remove" \) \
                 -a -L /usr/doc/#PACKAGE# ]; then
                  rm -f /usr/doc/#PACKAGE#
            fi



That means it's already a bug if a package doesn't remove this link in
it's prerm. (And lintian gives you a warning if you forget this.) If
policy is changed and the symlink is no longer necessary you can simply
remove these statements from the postinst and the prerm and the package
doesn't has to carry any "extra cruft" in the future.


> cheers


cu,
Adrian

-- 
A "No" uttered from deepest conviction is better and greater than a
"Yes" merely uttered to please, or what is worse, to avoid trouble.
                -- Mahatma Ghandi