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
thanks
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
simultaneously.
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 ;
fi
)
fi
fi
postrm remove:
if [ -d /usr/doc ]; then
if [ -L /usr/doc/$package ]; then
rm /usr/doc/$package ;
fi
fi
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: