package: lintian, sphinx-common, developers-reference
tags: help

hi,

when running lintian on the developers-reference binary packages
I get:

W: developers-reference-de: embedded-javascript-library please use sphinx [usr/share/developers-reference/de/_static/language_data.js]
W: developers-reference-fr: embedded-javascript-library please use sphinx [usr/share/developers-reference/fr/_static/language_data.js]
W: developers-reference-it: embedded-javascript-library please use sphinx [usr/share/developers-reference/it/_static/language_data.js]
W: developers-reference-ja: embedded-javascript-library please use sphinx [usr/share/developers-reference/ja/_static/language_data.js]
W: developers-reference-ru: embedded-javascript-library please use sphinx [usr/share/developers-reference/ru/_static/language_data.js]

while dev-ref uses "dh $@ --with sphinxdoc" and this also works in general,
which eg can be seen in the binary package developers-reference which ships
/usr/share/developers-reference/_static/language_data.js as a link to
/usr/share/javascript/sphinxdoc/1.0/language_data.js

As you might guess from me assigning this bug to three packages I'm not
really sure where the bugs are:

1.) I think lintian is buggy because it doesn't detect that all those
developers-reference-$lang packages already use sphinx. So the advice
"please use sphinx" is clearly wrong.

2.) /usr/share/javascript/sphinxdoc/1.0/language_data.js is 14 KB in size,
while /usr/share/developers-reference/de/_static/language_data.js is just
11 KB. No idea if this is to be exspected or a bug somewhere.

3.) should I override the lintian warning in dev-ref?

4.) something else?

Help welcome.

Please don't. Override should be reserved to pathological cases where a package
is a policy exception, not to hide lintian false postive.

Cheers,

I disagree. (But I also think this is the least interest aspect of this bug report.)

On Saturday, May 23, 2026 12:49:39 PM Mountain Standard Time Holger Levsen wrote:

When lintian has a false-positive that can be corrected in the logic of the
lintian check, I usually file a lintian bug report and override the false
positive with a link to the bug report while I am waiting for it to be fixed.

When lintian has a false-positive that is not possible for the lintian check
to detect (there are lots of these, for example the tag very-long-line-length-
in-source-file) then I override the lintian false positive with an explanation
of why it doesn’t apply.  Checks like these are valuable lintian tags because
they help me find problems in the source code, like minified JavaScript.  But
they can also flag files that aren’t problems, and it is important to be able
to mark those as overridden after they have been manually reviewed.

Note that this isn’t a comment on the best way to handle this situation, just
a note that overriding lintian false-positives is indeed the correct behavior
in many cases.

Control: reassign -1 sphinx-common, developers-reference

Lintian checks if the file in the question is either a regular file or a hardlink; it
will skip symlinks.

In this case, your assertion that this is link is wrong. I unpacked developers-reference-de and see:

$ ls -la ./usr/share/developers-reference/de/_static/language_data.js
-rw-r--r-- 1 nilesh nilesh 10911 May 19 16:53 ./usr/share/developers-reference/de/_static/language_data.js

This appears as a regular file to me, and lintian would detect this as a embedded copy without using
symlinks to sphinx javascript files. So there is something wrong with the shipped files.

As another data point, libuv1-doc package (recently uploaded a new revision)
also ships these files[1] (/usr/share/doc/libuv1/html/_static/language_data.js)
but it does not emit those lintian warnings[2]

This file correctly ships as a symlink

$ dpkg -c libuv1-doc_1.51.0-2_all.deb | grep language_data
lrwxrwxrwx root/root         0 2025-08-24 21:18 ./usr/share/doc/libuv1/html/_static/language_data.js -> ../../../../javascript/sphinxdoc/1.0/language_data.js

Even developers-reference binary package gets this right

$ dpkg -c developers-reference_14.9_all.deb | grep language_data
lrwxrwxrwx root/root         0 2026-05-19 16:53 ./usr/share/developers-reference/_static/language_data.js -> ../../javascript/sphinxdoc/1.0/language_data.js

That means sphinxdoc is doing its job for developers-reference, but there is something problematic in rest of the binary packages.

I don't think there's anything for lintian to do here, hence re-assigning. Hope that's okay.

[1] https://packages.debian.org/sid/all/libuv1-doc/filelist
[2] https://udd.debian.org/lintian/?packages=libuv1-doc

Best,
Nilesh

Hi,

dh_sphinxdoc currently supports symlinking language_data.js only for English.

I will see if I can add support for other languages. That will mean that
libjs-sphinxdoc package will increase in size several times, though.

control: reassign -1 sphinx-common
thanks

ah, that indeed explains, thank you!

I *believe* this is ok/better, cause else all these packages will ship
an embedded code copy without need.

Thank you!

control: clone -1 -2
control: reassign -2 lintian
control: retitle -2 lintian should warn if dh_sphinx doesnt link some files it should
control
thanks

my point was that lintian says I should depend on sphinx while I already do that.

indeed lintian correctly found a sphinx file which was included and not linked, however
the tag emitted only tells me to use sphinx which I do...

So in this case lintian should emit some other tag which clearly says that it has
detected i'm using dh_sphinx and ${sphinxdoc:Depends} while there still is a file
included which should be linked but isnt.

it's doing its job, but it's buggy. See -1 :)

as discussed on irc, cloning and reassining to lintian as -2.

Thanks for your work on lintian!