[Pkg-javascript-devel] jquery embedding in doxygen

[Jonas Smedegaard]

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 reliable) bootstrapping 
code.


Hope that helps.


 - Jonas

-- 
 * Jonas Smedegaard - idealist & Internet-arkitekt
 * Tlf.: +45 40843136  Website: http://dr.jones.dk/

 [x] quote me freely  [ ] ask before reusing  [ ] keep private
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 836 bytes
Desc: signature
URL: <http://lists.alioth.debian.org/pipermail/pkg-javascript-devel/attachments/20130227/0c7a6bf3/attachment-0001.pgp>