Warning: This page is seriously outdated since it predates dpkg-maintscript-helper symlink_to_dir/dir_to_symlink. Nowadays you would just create debian/mlterm-im-ibus.maintscript:
dir_to_symlink /usr/share/doc/mlterm-im-ibus mlterm-common 3.1.2-1.1~
This page is meant to describe how to address the problem "missing copyright file" as meant here. The cause is that dpkg refuses to replace a directory with a symlink or vice versa (this behaviour is wanted for unrelated reasons).
If you want to replace a directory with a symlink, you may let a preinst script remove the directory before dpkg creates the symbolic link. Example from the mlterm package:
1 #!/bin/sh 2 set -e 3 4 case "$1" in 5 install|upgrade) 6 # dpkg does not replace directories by symlinks or vice versa. 7 if dpkg --compare-versions "$2" lt "3.1.2-1.1" ; then 8 rm -rf /usr/share/doc/mlterm-im-ibus || true 9 fi 10 ;; 11 abort-upgrade) 12 ;; 13 *) 14 echo "preinst called with unknown argument \`$1'" >&2 15 exit 1 16 ;; 17 esac 18 19 #DEBHELPER# 20 21 exit 0
The other obvious solution is not to use symlinks at all. Symbolic links created by any previous version must then be removed by a preinst script. In case you did replace a symlink with a directory in version 1, but are adding the preinst script a posteriori in version 3, a system with version 2 may still contain a symlink (because dpkg did ignore your changes in a normal upgrade path) or not (because the user did try version 3 then downgrade). You should then remove any existing symlink, whatever the upgraded version, as done here.