Bug#45561: PROPOSAL] tech-ctte: /usr/share/doc

[Roland Rosenfeld <roland@debian.org>]

On Fri, 24 Sep 1999, Joey Hess wrote:

> I think someone needs to write a policy diff. It can use how
> debhelper does things as the reccomended method, without metioning
> debhelper.

The days go by, we want to freeze potato soon, but no policy change is 
visible.  But we should hurry up, because there are many packages
available which use /usr/share/doc without creating a symlink and some 
of the maintainers don't change this until the policy is changed :-(

So I tried to produce a diff against policy.sgml (3.0.1.1), based on
your proposal.  Please don't flame me because of my bad English or
something like this but simply improve my first try.

Maybe we can use this as a basis for 3.0.2 or 3.1.0, which should be
distributed as soon as possible, because some packages have to be
changed accordingly before freezing potato.

Here's a little entry for upgrading-checklist:

  - /usr/doc/<package> has to be a symlink pointing to
    /usr/share/doc/<package>.  This symlink has to be maintained by
    postinst and prerm, because dpkg will cause problems otherwise.
    Create/remote the symlinks using debhelper or see section
    "6.4. Accessing the documentation" for more information.

Ciao

        Roland

-- 
 * roland@spinnaker.de * http://www.spinnaker.de/ *
 PGP: 1024/DD08DD6D   2D E7 CC DE D5 8D 78 BE  3C A0 A4 F1 4B 09 CE AF

--- -	Wed Sep 29 17:59:06 1999
+++ policy.sgml	Wed Sep 29 17:58:32 1999
@@ -2722,7 +2722,11 @@
 		
 	      <p>
 		Html documents for a package are stored in
-		/usr/share/doc/<var>package</var> and can be referred to as
+		<tt>/usr/share/doc/<var>package</var></tt> but should
+		be accessed via symlinks as
+		<tt>/usr/doc/<var>package</var></tt><footnote> for
+		backward compatibility, see <ref
+		id="usrdoc"></footnote> and can be referred to as
 		<example>
 		  http://localhost/doc/&lt;package&gt;/&lt;filename&gt;
 		</example></p></item>
@@ -3131,7 +3135,43 @@
 	  the instructions for building and installing the package, of
 	  course!</p>
       </sect>
-      
+
+      <sect id="usrdoc">
+	<heading>Accessing the documentation</heading>
+
+	<p>
+	  Former Debian releases placed all additional documentation
+	  in <tt>/usr/doc/<var>package</var></tt>.  To realize a
+	  smooth migration to
+	  <tt>/usr/share/doc/<var>package</var></tt>, each package
+	  must maintain a symlink <tt>/usr/doc/<var>package</var></tt>
+	  that points to the new location of its documentation in
+	  <tt>/usr/share/doc/<var>package</var></tt><footnote>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.</footnote>.
+	  The symlink must be created when the package is installed;
+	  it cannot be contained in the package itself due to problems
+	  with <prgn>dpkg</prgn>. One reasonable way to accomplish
+	  this is to put the following in the package's
+	  <prgn>postinst</prgn>:
+          <example>
+  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
+          </example>
+          And the following in the package's <prgn>prerm</prgn>:
+          <example>
+  if [ \( "$1" = "upgrade" -o "$1" = "remove" \) 
+       -a -L /usr/doc/#PACKAGE# ]; then
+        rm -f /usr/doc/#PACKAGE#
+  fi
+          </example>
+
+
       <sect>
 	<heading>Preferred documentation formats</heading>