Bug#925200: doc-base-file-references-missing-file: false positive and missing warning when symlinks are involved
Package: lintian
Version: 2.11.0
Severity: normal
Requested action for /usr/share/lintian/checks/menus.pm:
========================================================
* add feature to "delink" to follow relative symlink
--> /usr/share/lintian/checks/menus.pm around line 566-592
relative symlink needs to be converted to absolute one before
doing the path matching
* add sanity check for the file path to be usr/share/doc/*
or /usr/share/info/*.
--> /usr/share/lintian/checks/menus.pm before line 353
add file path matching rule and produce error message as
needed.
(I am not a good Perl user ... so no patch for now.)
Problem:
========
Currently, lintian warns like:
E: debian-reference-en: doc-base-file-references-missing-file debian-reference-en:9 /usr/share/doc/debian-reference/docs/debian-reference.en.txt.gz
E: debian-reference-en: doc-base-file-references-missing-file debian-reference-en:12 /usr/share/doc/debian-reference/docs/index.en.html
E: debian-reference-en: doc-base-file-references-missing-file debian-reference-en:13 /usr/share/doc/debian-reference/docs/*.en.html
These are false positive error messages.
libreoffice-help-en-us and similar packages also suffer this bug and set
up overrides for now. So this is not-so-isolated case and this lintian
error may lure people in wrong direction as I explain below. So it's
worth fixing.
Error analysis:
===============
For the above debian-refgerence-en case, "docs" is a relative symlink
generated by dh_link which generates symlinks that comply with Debian
policy - absolute when policy says they should be absolute, and relative
links with as short a path as possible. It will also create any
subdirectories it needs to put the symlinks in.
Actual files are located in places outside of /usr/share/doc/ such as
/usr/share/debian-reference/index.en.html This is in accordance with
Policy 12.3. Additional documentation:
| Packages must not require the existence of any files in /usr/share/doc/
| in order to function. [6] Any files that are used or read by programs
| but are also useful as stand alone documentation should be installed
| elsewhere, such as under /usr/share/package/, and then included via
| symbolic links in /usr/share/doc/package.
So this lintian error is false positive.
As I see the source of lintian, /usr/share/lintian/checks/menus.pm has
code to normalize symlinks as "delink".
Apparently, this only normalize the absolute path symlink case.
So updating this code to handle the relative path symlink is needed.
In addition to this, this bug may have lured people to wrong packaging
practices and that's need to be addressed. People could avoid this
lintian error by listing actual file paths without symlink in it such as
/usr/share/debian-reference/index.en.html in the doc-base configuration
file (debian/<package>.doc-base). This is very bad move. Policy "9.10.
Registering Documents using doc-base" instructs us "Please refer to the
documentation that comes with the doc-base package for information and
details." and in "2.3.2.2. Format sections" of the documentation that
comes with the doc-base package clearly prohibits such move.
| Except for the Info format the files referred in both Index and Files
| fields should be placed somewhere under the /usr/share/doc hierarchy. If
| for some reason it's not possible, then the registering package should
| provide a symbolic link pointing from the above hierarchy to the real
| files and register its documentation through the link, allowing
| doc-base, dhelp, or dwww packages to actually handle the documentation.
| Of course, files in the Info format should be located in the
| /usr/share/info directory.
So lintian should check if the listed file path starts as /usr/share/doc
or /usr/share/info before checking the existence of target file.
Note for normalize relative symlink:
====================================
Line 566 needs to be updated as:
# In the loop below we split $file into two parts on each '/' until
# there's no remaining slashes. We try substituting the first part with
# corresponding symlink and if it succeeds, we start the procedure from
# beginning.
#
# Example1:
# Let $all_links{"/a/b"} == "/d", and $file == "/a/b/c"
# Then 0) $p1 == "", $p2 == "/a/b/c"
# 1) $p1 == "/a", $p2 == "/b/c"
# 2) $p1 == "/a/b", $p2 == "/c" ; substitute "/d" for "/a/b"
# 3) $p1 == "", $p2 == "/d/c"
# 4) $p1 == "/d", $p2 == "/c"
# 5) $p1 == "/d/c", $p2 == ""
#
# Example2: (this needs to be added)
# Let $all_links{"/a/b"} == "../../d", and $file == "/a/b/c"
# Then 0) $p1 == "", $p2 == "/a/b/c"
# 1) $p1 == "/a", $p2 == "/b/c"
# 2) $p1 == "/a/b", $p2 == "/c" ; add "../../d" to "/a/b"
# 3) $p1 == "/a/b/../../d", $p2 == "/c"; normalize
# 4) $p1 == "/d", $p2 == "/c"
# 5) $p1 == "/d/c", $p2 == ""
#
# Note that the algorithm supposes, that
# i) $all_links{$X} != $X for each $X
# ii) both keys and values of %all_links start with '/'
-- System Information:
Debian Release: buster/sid
APT prefers testing
APT policy: (500, 'testing'), (10, 'unstable')
Architecture: amd64 (x86_64)
Kernel: Linux 4.19.0-2-amd64 (SMP w/4 CPU cores)
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8), LANGUAGE=en_US.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled
Versions of packages lintian depends on:
ii binutils 2.31.1-15
ii bzip2 1.0.6-9
ii diffstat 1.62-1
ii dpkg 1.19.5
ii dpkg-dev 1.19.5
ii file 1:5.35-4
ii gettext 0.19.8.1-9
ii gpg 2.2.12-1
ii intltool-debian 0.35.0+20060710.5
ii libapt-pkg-perl 0.1.34+b1
ii libarchive-zip-perl 1.64-1
ii libcapture-tiny-perl 0.48-1
ii libcgi-pm-perl 4.40-1
ii libclass-accessor-perl 0.51-1
ii libclone-perl 0.41-1+b1
pn libdigest-sha-perl <none>
ii libdpkg-perl 1.19.5
ii libemail-valid-perl 1.202-1
ii libfile-basedir-perl 0.08-1
ii libio-async-perl 0.72-1
ii libipc-run-perl 20180523.0-1
ii liblist-moreutils-perl 0.416-1+b4
ii libparse-debianchangelog-perl 1.2.0-13
ii libpath-tiny-perl 0.108-1
ii libtext-levenshtein-perl 0.13-1
ii libtimedate-perl 2.3000-2
ii libtry-tiny-perl 0.30-1
ii liburi-perl 1.76-1
ii libxml-simple-perl 2.25-1
ii libyaml-libyaml-perl 0.76+repack-1
ii man-db 2.8.5-2
ii patchutils 0.3.4-2
ii perl 5.28.1-4
ii t1utils 1.41-3
ii xz-utils 5.2.4-1
Versions of packages lintian recommends:
ii libperlio-gzip-perl 0.19-1+b5
Versions of packages lintian suggests:
pn binutils-multiarch <none>
ii libhtml-parser-perl 3.72-3+b3
ii libtext-template-perl 1.55-1
-- no debconf information
Reply to: