Quoting Helmut Grohne (2013-02-26 22:30:00)
** First embedding of jquery: src:doxygen
The current situation is that doxygen upstream downloads various parts
of jquery in various versions, then obfuscates (or is it called
compresses?) the source and stores those parts in their svn. Then
they convert the jquery library into a C header file which is also
stored in their svn. The lack of source for jquery in the sense of
preferred form for modification is tracked as #625956. According to
upstream svn these copies are usually generated immediately before
releasing a new version of doxygen.
I believe the Debian packaging should ignore the prebuild stuff shipped
by upstream, and during the Debian build mimic same steps as done
upstream but build-depending on and using Debian-packaged jquery files
(either uncompressed or compressed - but most likely the best result
comes from joining all needed files uncompressed and compress them all
at once).
** Second embedding of jquery: doxygen
The header is compiled to the doxygen binary, so the binary package
also includes a copy of jquery. Once you generate documentation this
version is copied to your documentation tree.
Ideally doxygen should be patched to not work like that but instead at
runtime use the Debian-packaged files (then also solving above first
embedding of jquery).
Assuming that is too difficult, I would suggest do a dirty trick of
depending versioned on jquery - even if not actually using it for
anything, and have the versioning autoresolved during build to be
tightened to current install of it, so as to force requiring a rebuild
of doxygen every time jquery changes.
(less dirty would be to tighten build-dependency, but that would require
sourceful rebuild due to Debian Policy not allowing build-dependencies
to change during build.
** Third embedding of jquery: reverse build dependencies of doxygen
About 50 packages use doxygen to build their documentation. Unless the
maintainer explicitly replaces the doxygen generated copy of jquery,
the respective package includes it as well.
(see below...)
[snip]
For the regular user a doxygen generated tree should be usable
stand-alone. That is doxygen will keep copying jquery during
documentation generation.
Makes sense.
A debhelper dh_doxygen called from documentation packages during build
could be used to replace these (thired) copies of the jquery
conglomerate by symbolic links to a newly created doxygen-common
package. (See Jakub Wilk's dh_sphinxdoc for a similar tool.) This
raises an important question though: What happens when upgrading
doxygen-common? How to ensure that previously generated documentation
does not break with an upgraded doxygen-common?
I suggest to have doxygen build a doxygenXXX-common binary package which
depends versioned (as tightly as needed) on appropriate jquery packages,
with XXX bumped every time the micture of dependent jquery packages
changes.
...and then have the main doxygen package provide such dh_doxygen tool,
which both a) replaces javascript files with symlinks and b) adds a
dependency on the current doxygenXXX-common package.
When doxygenXXX-common is bumped, you will then need to check if any
package anywhere in the archive actually depend on the old one, and if
so have your new package also keep creating that old old, or...
Note that if there are backwards-incompatible changes, we have to
rebuild about 50 reverse dependencies of doxygen, and there is no such
thing as binNMU for them, because they are mostly Architecture: all.
...file severe bugreports to have those packages be rebuilt (not all 50,
only the ones actually depending on the particular obsolete
doxygenXXX-common package).
Ideally which step should be generating the jquery.js file to be copied
into a documentation tree?
A: Upstream
B: During build of doxygen
C: During the invocation of doxygen
Ideal to upstream: A
Ideal to distrutors: C - by help of node-uglify.
If the answer to the previous question is A: What can we do about the
(first) copy of jquery in the doxygen source package? Reverse
engineering the jqeury components embedded in each new release appears
like a tedious task. In what way can this situation be improved
upstream?
What I think is reasonable to try persuade upstream to do is leave an
automated trace of which sources was used for generating the shipped
JavaScript code, so as to help distributors like us avoid the need for
reverse engineering.
When creating a doxygen-common package (and we are not in case C),
should that package contain the copy of jquery used to embed into
documentation or should it contain a javascript file loading the
remainders from libjs-something packages?
When not in case C then we have lost the goal of avoiding code copies
and I see no point in complicating further by replacing full-copies of
jquery with some (potentially slower or less
