Re: Bug#62378: Redundant directory and package name

[Nicolás Lichtmaier <nick@debian.org>]

>  >> At present, it's pretty random. I would like a consistent answer to make
>  >> its way into policy, but there are lots of different cases, and I don't
>  >> think a simple "foo-doc installs stuff into /usr/share/doc/foo" is the
>  >> best answer. One must also consider that some doc package are actually
>  >> (at least partially) info files and man pages. 
> 
>  Nicolás> Perhaps we can't find an answer to every question, but at
>  Nicolás> least we could regulate how the easy cases are handled. It's
>  Nicolás> better to settle with a partial solution that cover many
>  Nicolás> cases than to live for ever in kaos.. =)
> 
> 	If you can come up with a quantification of what constitutes
>  an easy case, and gather the difficult cases already provided in this
>  thread as known exceptions, and come up with a wording for the easy
>  case handling, we may be getting somewhere. 

6.3 Additional documentation 

Any additional documentation that comes with the package can be installed at
the discretion of the package maintainer. Text documentation should be
installed in a directory /usr/share/doc/package, where package is the name
of the package, and compressed with gzip -9 unless it is small.

If a package comes with large amounts of documentation which many users of
the package will not require you should create a separate binary package to
contain it, so that it does not take up disk space on the machines of users
who do not need or want it installed. >>>>If a package is just a spinoff of
another, and provides documentation that the users fully associate with the
package, the maintainer may choose to put that documentation under that
package's docs directory, i.e. tool-doc may put files under
/usr/doc/tool.<<<<<

It is often a good idea to put text information files (READMEs, changelogs,
and so forth) that come with the source package in /usr/share/doc/package in
the binary package. However, you don't need to install the instructions for
building and installing the package, of course!

> 	And policy can't punt on /usr/doc symlinks, really, since
>  policy is what mandates them in the first place.

 The sumlinks issue is not being handled properly even now. The policy
should be amended to say something like this:


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[12]. The symlink must
be created when >>> any package that provides at least one file in that
documentation directory <<< 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

 [Good, the first packae installed creates the link, but this...]

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

 [ should be changed to this...]

The following in the package's prerm: 

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


And the following in the package's postrm: 

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

 [So the last package of the group being removed remove the link.]

 [I'm sure I'm missing many cases here... I know, but something can be worked
out...]