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.