+This manual is for people who want to build the widget set from
+source, develop the widget set's core code, or (more likely) create
+their own widgets as extensions to the main set.
+
+Those who want to use existing widgets should read
+[The MKWS manual: embedded metasearching with the MasterKey Widget
+Set](mkws-manual.html) instead.
+
+
+Required development tools
+==========================
+
+If you are building the widget set, you will need the following Debian
+packages (or their equivalents on your operating system):
+
+ $ sudo apt-get install curl git make unzip apache2 \
+ pandoc libbsd-resource-perl
+
+You also need Node.js, but unfortunately the `node-js` package is not
+available for Debian wheezy. You can either get it from
+wheezy-backports or download the source from
+http://nodejs.org/download/ and build it yourself. You need both Node
+itself and its package manager NPM: `make install` puts them into
+`/usr/local/bin`.
+
+
+Concepts
+========
+
+Code structure
+--------------
+
+The code of the widget set is in four main layers, described here from
+the bottom up:
+
+1. The core code, which manages the set of widget teams, default
+options, authentication onto the Service Proxy, and the creation of
+widgets from HTML elements.
+This code is in `mkws-core.js`
+
+2. The team code, which manages teams of widgets. This is responsible
+for the collections of widgets that make up teams, event queues, and
+handling search-and-retrieval events
+This code is in `mkws-team.js`
+
+3. The generic widget code, which handles the creation of widget
+objects, parsing configuration attributes from their HTML elements,
+and firing off automatic searches.
+
+4. The code for individual widgets, which is specific to those
+widgets. It often involves subscribing to events and responding to
+them by setting the HTML of the widget element, but need not do
+so. The code for many of the most important widgets is in
+`mkws-widget-main.js`, but certain other widgets are defined in other
+files beginning with the prefix `mkws-widget-`.
+
+In addition to this code, there are several source files containing
+support code:
+
+* `mkws-filter.js` contains support routine implementing the
+filter-set data structure, which contains information about which
+filters (e.g. by target, or by facet) are in force.
+
+* `mkws-handlebars.js` contains Handlebars helpers which can be used
+by the HTML templates.
+
+* `mkws-popup.js` defines a special widget for creating popup
+ windows. These may, but need not, contain other MKWS widgets,
+ forming a popup searching application.
+
+The final component of the source code is the set of Handlebars
+templates, in the `templates` directory, which are used to emit the
+HTML of the various widgets' contents. These are compiled into the
+file `mkws-templates.js`.
+
+
+
+Event passing
+-------------
+
+The primary method of communication between components of the widget
+set -- specifically, between teams and their widgets -- is event
+passing. Widgets subscribe to named events; when something relevant
+happens (such as the reception of a message from metasearch
+middleware), the event is published, along with the relevant data. All
+widgets that susbcribed to the event are then notified, and can take
+appropriate action.
+
+Different kinds of events have different data associated with
+them. This data is passed when the event is published, and so is made
+available to the subscribing code.
+
+The possible events, and their associated data, are described
+[below](#events).
+
+
+Defining new types of widget
+----------------------------
+