Policy for /usr/doc/<pkg-name>-doc

[Rafael Laboissiere <rafael@icp.inpg.fr>]

I just realized that there is no uniformity in Debian as regards the
place for package additional documentation.  The Debian Policy is not
clear on this issue:

<quote>
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/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.
</quote>

When a new package <pkg-name>-doc is created, where should it put the
files, in /usr/doc/<pkg-name> or in /usr/doc/<pkg-name>-doc?  My
preference is to put it in /usr/doc/<pkg-name>, but as my preference is
not necessarily good taste, I wrote a small script to check what the
packages *-doc packages in slink do.  The results are at the end of this
post.  It appears that there is a preference for /usr/doc/<pkg-name>-doc
(65%).

Should the Debian Policy state which is the prefered behavior?

--
Rafael Laboissiere, Debian developer.


===========================================================================
[ WARNING: I did not check this results by hand, they were generated
  automaticaly by a script, so errors may exist.]

Packages that put additional documentation under /usr/doc/<pkg-name>

    aegis-doc     felt-doc      kbackup-doc    pact-doc       wine-doc    
    apache-doc    gwm-doc       libhdf4g-doc   plplot-doc     xcin-doc    
    bind-doc      hugs-doc      lprng-doc      python-doc     xconq-doc   
    cook-doc      hylafax-doc   musixtex-doc   swig-doc       xntp3-doc   
    dotfile-doc   ilu-doc       nas-doc        the-doc        xv-doc      


Packages that put additional documentation under /usr/doc/<pkg-name>-doc

    angband-doc   icon-doc      libpwdb-doc    povray-doc     vis5d-doc  
    crossfire-doc ivtools-doc   m4-doc         ptx-doc        vnc-doc       
    diff-doc      lapack-doc    make-doc       qt-doc         wdiff-doc     
    docbook-doc   lclint-doc    mesa-doc       r5rs-doc       wordnet-doc   
    dstool-doc    libc6-doc     msql-doc       recode-doc     wxftp-doc     
    dstooltk-doc  libforms-doc  mysql-doc      samba-doc      xfig-doc      
    exim-doc      libggi-doc    netcdf-doc     scilab-doc     zephyr-doc    
    flex-doc      libgtk-doc    octave-doc     snns-doc                     
    gettext-doc   libmpeg-doc   php3-doc       solid-doc                 
    glut-doc      libpam-doc    postgresql-doc tetex-doc