hypothesis/h — pull request #1417 by csillag (2014-08-19 21:26:05+00:00)
Title: WIP: add support for packaging with PDF.js extension 

* Update Annotator code to work with latest PDF.js release (which will be part of FF32)
* Don't load the document plugin for PDF.js documents, because the PDF plugin now handles handles this.
* Unify the two different routes for determining the URL of the document we are looking at, as requested at https://github.com/hypothesis/annotator/issues/67
* Re-add the ability to bundle PDF.js code with the Chrome extension; but this time, using PDF.js instead of the native PDF viewer is optional, as it was [originally planned](https://github.com/hypothesis/h/issues/512#issuecomment-24704922), and as it is discussed in #1120.

Most non-annotator changes are located in our extension code.
I have introduced one more state tracker map for the tabs, besides `state`: `pdfState`. This is used to flag that a given tab is displaying PDF content (either with the native viewer, or with PDF.js). Now the decisions about behavior are made based on observing the values of both variables.

Another option would be to keep using only one variable, but extend the set of possible values for it. Maybe it would simplify the logic a bit; I have no strong opinion.

The extension is built like this:
* First we build the pdf.js extension, from the unadulterated upstream source.
* Then we build our stuff
* Then we copy the results of both builds into the same directory, merging them into one.

During the merge process, if a file exists in both the H and the PDF.js build, the H version wins.

In other words, we modify PDF.js's functionality not by changing their code, but by "shadowing" some files; which means that we put our modified version to [h/browser/chrome](https://github.com/hypothesis/h/tree/1334-latest-pdfjs-2/h/browser/chrome), which will overwrite their version during the build process.

We are currently shadowing these files:
* [viewer.html](https://github.com/hypothesis/h/blob/1334-latest-pdfjs-2/h/browser/chrome/content/web/viewer.html) (Because we integrate H into it)
* [contentscript.js](https://github.com/hypothesis/h/blob/1334-latest-pdfjs-2/h/browser/chrome/contentscript.js) (because we have do disable automatic insertion here)
* [extension-router.js](https://github.com/hypothesis/h/blob/1334-latest-pdfjs-2/h/browser/chrome/extension-router.js) (because we have to disable PDF.js's own page action)
* [pdfHandler.js](https://github.com/hypothesis/h/blob/1334-latest-pdfjs-2/h/browser/chrome/pdfHandler.js) (because we have to add some logic to the insertion code, so that we only use PDF.js when we want to.)

Those are all the changes we need to make in PDF.js. Before merding, I will re-do the GIT history in a way that separates the adding of the original "shadow" files and our modifications in them, so that it will be easier to forward-port these changes, as needed, when we more to newer versions of PDF.js.

Until that, the easiest way to identify our changes is searching for the string "Hypothes.is" in the source.
(Like [here](https://github.com/hypothesis/h/blob/4a650f9bf79183ee10762335b363daf700e8b05f/h/browser/chrome/pdfHandler.js#L116).)