doxygen/debian

Doxygen embeds jquery
=====================

This document describes how and why Doxygen embeds jquery. It serves as an
explanation of what problems need to be addressed before removing these
embeddings. If you are not interested in the reasons, skip to consequences.

Where?
======

 1. The Doxygen source contains jquery library sources in the `jquery/` folder.
 2. These are minified at release time by the Doxygen upstream and stored as
    `src/*.js`. See `jquery/Makefile`.
 3. They are then converted to C header files and stored as
    `generated_src/doxygen/*_js.h`.  See `src/libdoxygen.t`.
 4. At build-time these headers are compiled into the `doxygen` binary and
    installed as `usr/bin/doxygen` into the `doxygen` binary package.
 5. When running Doxygen the jquery libraries are embedded into the generated
    documentation.
 6. Packages using Doxygen as a build-dependency for creating their
    documentation therefore also embed these jquery libraries.

Why?
====

While it would be nice to remove the need for any of these embedding, it is
practically difficult to do so.

 6. It was considered to introduce a `doxygen-common` package that pulls in the
    relevant jquery libraries and provides them at a canonical location for
    usage with symbolic links. When doing this the question of how to handle
    upgrades of Doxygen arises. [Upstream indicated] that the documentation
    generated with one version of Doxygen will not necessarily work with the
    jquery libraries from a different version of Doxygen. This leaves two
    options:

    * Ship all previous versions of jquery libraries in the `doxygen-common`
      package.
    * Rebuild all reverse build dependencies of Doxygen whenever uploading a
      new version of Doxygen.

    Both options were deemed infeasible. The first option simply is
    unmaintainable. The second option requires architecture independent
    binNMUs. Since the archive does not do any architecture independent
    auto-building this is not available either. (This was discussed with the
    buildd maintainers during DebConf13.)

 5. This is simply how Doxygen is designed to operate. The generated
    documentation should be usable as is without dependencies on external
    files.

 4. To facilitate embedding 5 the `doxygen` binary needs some kind of access
    to the jquery libraries. Changing this aspect would require significant
    modification of the Doxygen source.

 3. These files are regenerated during a regular build.

 2. The Debian package recreates these artifacts from step 1 by running `make
    -C jquery install` before the build.

 1. This is an aspect of the upstream source and build system. Each doxygen
    release ships a tightly coupled conglomerate of various javascript
    libraries. Replacing them with system copies is simply unmaintainable,
    because it is not mechanically testable.

One of the major reasons behind removing embedded copies of code is to be able
to do security updates. Arguably there are little options to exploit a
vulnerable jquery library as embedded by Doxygen, because from a user point of
view it is static data. Thus one of the primary motivations to remove embedded
copies does not apply in this case.

[Upstream indicated]: http://doxygen.10944.n7.nabble.com/release-tarballs-td5837.html

Consequences
============

It is not considered a problem for Doxygen or packages using Doxygen to embed
jquery. In fact replacing the `jquery.js` file created by Doxygen likely
results in broken documentation. Packages doing that are buggy. Lintian will
have to learn that a `jquery.js` embedded by Doxygen is a normal thing.

Helmut Grohne