Re: New policy locations for docs

[Roland Rosenfeld <roland@spinnaker.de>]

Mike Markley <mike@markley.org> wrote:

> OK, I'm looking at the policy manual and while I do see the
> /usr/share/doc thing, I don't see any mention of symlinks to
> /usr/doc either way. Are we allowed to symlink
> /usr/share/doc/package to /usr/doc/package?

No, it's strictly forbidden.  You should link /usr/doc/package to
/usr/share/doc/package in postinst (and remove it in prerm).

Please have a look at policy 3.1, which is in Incoming at the moment:

5.5. Web servers and applications
---------------------------------
[...]
     2.   Access to html documents

          Html documents for a package are stored in
          `/usr/share/doc/<package>' but should be accessed via symlinks as
          `/usr/doc/<package>'[1] and can be referred to as

                          http://localhost/doc/<package>/<filename>

          [1]  for backward compatibility, see Section 6.4, `Accessing the
               documentation'
[...]

6.4. Accessing the documentation
--------------------------------

     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

     [1]  These symlinks will be removed in the future, but they have to be
          there for compatibility reasons until all packages have moved and
          the policy is changed accordingly.

Tschoeeee

        Roland

-- 
 * roland@spinnaker.de * http://www.spinnaker.de/ *