Reading the SOUP code

Being a user script, the SOUP source code is contained in a single JavaScript file. (In the future, I might move to a system where the final script file is automatically built out of separate parts, but for now, that's all there is.)

The file is structured roughly as follows:

1. The metadata block: This set of comment lines tells userscript managers like GreaseMonkey various things about the script, like what it's called, how and when to run it, and where to find updates for it.

   The SOUP repo also contains a copy of the metadata block in the SOUP.meta.js file. This file is used by userscript managers to check for new updates. To keep it up to date, run the command:

    perl extract-metadata.pl > SOUP.meta.js
   

   before each commit. (Someday, I may get around to making this a pre-commit hook.)

2. The license text: SOUP is licensed under the ISC license, a simple liberal BSD-style open source license. The full text of the license is included below the metadata block.

3. Function wrapper and hostname test: Some user script managers automatically run user scripts in a separate local scope. Some don't, so, just to be sure, the whole SOUP source code is wrapped in an anonymous function. That way, we can define local variables without having to worry about possibly polluting the window object.

   At the top of the function, we also re-check that the page we're running on is really on a Stack Exchange site. There are ways to install SOUP on some browsers (notably Opera) that cause the @match lines in the metadata block to be ignored, so this double check is necessary to keep it from running on other sites and potentially messing things up.

4. The fixes: This is the core of SOUP — a collection of CSS and JavaScript snippets that each make up a (more or less) self-contained fix for a particular Stack Exchange bug or shortcoming. See Adding a new fix for a description of the fix entry format.

   The fixes are divided into the following sections by type:

   1. General CSS-only fixes.
   2. Site-specific CSS fixes.
   3. Chat CSS fixes.
   4. General JS fixes (may also contain CSS).
   5. HTTPS-only fixes.
   6. MathJax-related fixes.

5. Initialization code and utility functions: Below the fixes themselves, there are a couple of functions named soupInit and soupLateSetup that take care of setting up the SOUP global JS object and the various infrastructure and utility methods in it. These are documented in more detail below.

6. Injection code: The last part of the SOUP source takes care of injecting the CSS and JS code defined above into the page at appropriate points. This is the only (non-trivial) part of the SOUP code that actually runs inside the user script manager; everything else is injected into the page DOM and runs there, just as if it were a normal part of the page.