[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Bug#40706: [AMENDMENT 17/7/99] /usr/share/doc vs. /usr/doc transition

retitle 40706 [AMENDMENT 17/7/99] /usr/share/doc vs. /usr/doc transition

    PROPOSAL: Easing the transition from `/usr/doc' to `/usr/share/doc'

                  Manoj Srivastava <srivasta@debian.org>
                             $Revision: 1.3 $


Copyright Notice

     Copyright © 1998 by Manoj Srivastava.

     You are given permission to redistribute this document and/or modify
     it under the terms of the GNU General Public License as published by
     the Free Software Foundation; either version 2, or (at your option)
     any later version.

     On Debian GNU/Linux systems, the complete text of the GNU General
     Public License can be found in `</usr/share/common-licenses/GPL>'.


1. Introduction, and Administrivia

1.1. Deadline for tabling the discussion

     I decided to use the suggested _usual_ period of two weeks for this
     proposal. Therefore, this proposal needs to be acted upon before July
     31th, 1999.

1.2. People Seconding the Proposal

     The following people have seconded the proposal so far, and there has
     been one objection.

     1.   Joey Hess <joey@kitenet.net>

     2.   Darren O. Benham <gecko@debian.org>

     3.   Roland Rosenfeld <roland@spinnaker.de>

     The person who objected was Santiago Vila <sanvila@unex.es>


2. Need for a mechanism to ease the change

     Now that we have formally decided to adopt the FHS, we need to ensure
     the transition is as smooth as we can make it. We can not just mandate
     that the distribution migrate to the new standard, and expect to leave
     it at that, since the unit of updates in the distribution is the
     package, and FHS conformance thus has to be achieved package by
     package. There is also the consideratiuon that evolutionalry changes
     are less dangerous, and easier to stage, than revolutionary changes,
     which tend to be a tad more messy.

     Some of the constraints are:

        * The transition may take a long time, going by previous
          transitions, and not all packages are upgraded anywhere near

          I think that expecting _*all*_ packages to have moved before we
          release potato is futile, unless we do not plan on releasing
          potato for 18 months or so. We *_cannot_* expect to get FHS
          compliance in place by potato.

        * We should not break backwards compatibility during the transition
          period. This is a quality of implementation issue

          During the transition, we need to provide backwards
          compatibility, firstly for programs ike `dwww', and `dhelp', and
          also for our users who have gotten used to looking under a single
          dir (`/usr/doc/') for docs (`/usr/doc/`package''). During the
          transition, the documentation could be in in two places, and that
          is not good


3. Proposed solution

     I propose that there be a syymlink from /usr/doc/package =>
     /usr/share/doc/package, managed by the package itself. Since there is
     some concern that the packaging system does not deal well with
     replacing a directory with a symbolic link, it is suggested that the
     link be manipulated in the maintainer scripts postinst and postrm.

          	  Postinst install:
          if [ -d /usr/doc ]; then
            if [ ! -e /usr/doc/$package ]; then
              (cd /usr/doc;
               if [ -d ../share/doc/$package ]; then
                  ln -s ../share/doc/$package $package ;

          postrm remove:
          if [ -d /usr/doc ]; then
            if [ -L /usr/doc/$package ]; then
              rm /usr/doc/$package ;

     This is how it works:

     1.   Policy 3.X mandates that packages that move the docs to
          /usr/share/doc must provide a compatibility symlink in /usr/doc.
          This shall allow packages to incrementally move to policy 3.X,
          while providing compatibility with older systems.
          (/usr/doc/package symlink is handled by package)

     2.   At a later date, another policy (say, 4.X) shall ask for packages
          to no longer provide the link. We can do this when we are sure
          the time for the links is gone, and the transitions is over.

     I understand that the forest of symlinks is ugly, but it is
     technically sound, it maintains backwards compatibility, it allows
     incremental compliance to FHS, and caters to a hybrid system. I submit
     that aesthetics takes a back seat to functionality.

     To the objection that it shall cause package to be modified twice, I
     say that

        * This is a complex transition, and may require this to meet the
          constraints of tehsituation

        * One modification of the packages is required anyway for comliance
          with the FHS.

        * The second modification, namely, the removal of the symbolic
          link, shall be well into the future, and added to a future policy
          change. It is concievable that the packages may need to change
          for policy updates in any case.


     PROPOSAL: Easing the transition from `/usr/doc' to `/usr/share/doc'
     Manoj Srivastava <srivasta@debian.org>
     $Revision: 1.3 $

 "If you don't make money off of it, it had better be either a
 religious experience or a hobby." Lance Cooper
Manoj Srivastava   <srivasta@debian.org>  <http://www.debian.org/%7Esrivasta/>
Key C7261095 fingerprint = CB D9 F4 12 68 07 E4 05  CC 2D 27 12 1D F5 E8 6E

Reply to: