[Pkg-javascript-devel] jquery embedding in doxygen

[Helmut Grohne]

Dear javascript maintainers,

I am writing to you, because I seek help with doxygen. For wheezy I
believe that Mònica Ramírez Arceda's patch is the way to go, so this
mail entirely applies to jessie.

** 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.

** 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.

** 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.

** So precisely what is copied?

This actually depends on the doxygen version in use. In earlier version
it used to copy jquery 1.3.2. For the current version Mònica Ramírez
Arceda thankfully examined the source and discovered:

jquery 1.7.1 including sizzle
jquery.ScrollTo 1.4.2
jquery hashchange event 1.3
jquery UI 1.8.18
jquery UI Mouse 1.8.18
jquery UI Resizable 1.8.18
jquery UI Widget 1.8.18

Jérémy Lal kindly explained that some parts of this (ScrollTo) are not
currently packaged for Debian, but most is.

** Which embeddings should we solve and how?

For the regular user a doxygen generated tree should be usable
stand-alone. That is doxygen will keep copying jquery during
documentation generation. 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?

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.

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

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?

In the other cases we could repack doxygen to remove the jquery files,
but we would still need some kind of upstream support to determine what
to generate.

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?

Note that I do not expect answers to all of these questions. I merely
wrote down the currently open issues and hope for some thoughts
advancing the matter.

Helmut