initial revision

15 files changed, 331 insertions, 0 deletions

diff --git a/doc/manual_src/Makefile b/doc/manual_src/Makefile
new file mode 100644
index 0000000..76fdbda
--- /dev/null
+++ b/doc/manual_src/Makefile
@@ -0,0 +1,10 @@
+
+DOCS := $(patsubst %.md,%.html,$(wildcard *.md))
+
+all: $(DOCS)
+
+clean:
+	$(RM) $(DOCS)
+
+%.html: %.md
+	pandoc $< -o $@ -s --highlight-style=kate
diff --git a/doc/manual_src/figures/chrome-adding.png b/doc/manual_src/figures/chrome-adding.png
new file mode 100644
index 0000000..6b25ddd
--- /dev/null
+++ b/doc/manual_src/figures/chrome-adding.png
diff --git a/doc/manual_src/figures/chrome-confirm-add-fiveui.png b/doc/manual_src/figures/chrome-confirm-add-fiveui.png
new file mode 100644
index 0000000..fa1e29c
--- /dev/null
+++ b/doc/manual_src/figures/chrome-confirm-add-fiveui.png
diff --git a/doc/manual_src/figures/chrome-file-url.png b/doc/manual_src/figures/chrome-file-url.png
new file mode 100644
index 0000000..4cb7ee3
--- /dev/null
+++ b/doc/manual_src/figures/chrome-file-url.png
diff --git a/doc/manual_src/figures/chrome-install-done.png b/doc/manual_src/figures/chrome-install-done.png
new file mode 100644
index 0000000..d1774ef
--- /dev/null
+++ b/doc/manual_src/figures/chrome-install-done.png
diff --git a/doc/manual_src/figures/chrome-menu.png b/doc/manual_src/figures/chrome-menu.png
new file mode 100644
index 0000000..9596abd
--- /dev/null
+++ b/doc/manual_src/figures/chrome-menu.png
diff --git a/doc/manual_src/figures/ff-add-on-installer.png b/doc/manual_src/figures/ff-add-on-installer.png
new file mode 100644
index 0000000..ade0fe2
--- /dev/null
+++ b/doc/manual_src/figures/ff-add-on-installer.png
diff --git a/doc/manual_src/figures/ff-add-rule-set.png b/doc/manual_src/figures/ff-add-rule-set.png
new file mode 100644
index 0000000..fd1586c
--- /dev/null
+++ b/doc/manual_src/figures/ff-add-rule-set.png
diff --git a/doc/manual_src/figures/ff-addon-bar.png b/doc/manual_src/figures/ff-addon-bar.png
new file mode 100644
index 0000000..67f08cc
--- /dev/null
+++ b/doc/manual_src/figures/ff-addon-bar.png
diff --git a/doc/manual_src/figures/ff-heading-highlight.png b/doc/manual_src/figures/ff-heading-highlight.png
new file mode 100644
index 0000000..0c64937
--- /dev/null
+++ b/doc/manual_src/figures/ff-heading-highlight.png
diff --git a/doc/manual_src/figures/ff-menu.png b/doc/manual_src/figures/ff-menu.png
new file mode 100644
index 0000000..f60d822
--- /dev/null
+++ b/doc/manual_src/figures/ff-menu.png
diff --git a/doc/manual_src/figures/trac-aria1.png b/doc/manual_src/figures/trac-aria1.png
new file mode 100644
index 0000000..d8cc0a6
--- /dev/null
+++ b/doc/manual_src/figures/trac-aria1.png
diff --git a/doc/manual_src/figures/trac-rule-set.png b/doc/manual_src/figures/trac-rule-set.png
new file mode 100644
index 0000000..58de6af
--- /dev/null
+++ b/doc/manual_src/figures/trac-rule-set.png
diff --git a/doc/manual_src/gettingStarted.md b/doc/manual_src/gettingStarted.md
new file mode 100644
index 0000000..8eb49d4
--- /dev/null
+++ b/doc/manual_src/gettingStarted.md
@@ -0,0 +1,236 @@
+% Getting Started with FiveUI
+
+# Configuring FiveUI
+
+Once FiveUI has been installed, some initial configuration will need to be done
+to make the extension useful.
+
+The options page allows the user to configure `URL Patterns` that will apply
+when the browser is navigating to new URLs, and `Rule Sets` which categorize
+user interface guidelines into named groups.
+
+## Options in Chrome
+
+The options page in `Chrome` can be accessed either through the
+options link on the extensions page, or through the options item on
+the context menu off of the FiveUI button (accessed by right-clicking
+on the FiveUI button).
+
+## Options in FireFox
+
+The options page in `FireFox` can be accessed via the FiveUI gear widget, which
+should be added in addition to the FiveUI widget when the addon is installed.
+Once clicked, a new tab should appear which serves as the options interface for
+the addon.
+
+The FiveUI Widgets are initially placed on the Firefox `Add-on bar`,
+as shown in the figure.
+
+![FiveUI Widgets in the Firefox Add-on Bar.](figures/ff-addon-bar.png)
+
+# The Options Page
+
+The options page allows the user to configure `URL Patterns` that will apply
+when the browser is navigating to new URLs, and `Rule Sets` which categorize
+user interface guidelines into named groups.  As it's required that one or more
+`Rule Sets` already exist to create a `URL Pattern`, let's start with the `Rule
+Sets` tab.
+
+## Rule Sets
+
+`Rule Sets` can be managed by clicking on the `Rule Sets` tab on the left-hand
+side of the options page.
+
+`Rule Sets` in FiveUi are specified as a json-like object that
+contains javascript functions for the rule implementations.  Each
+`Rule Set` contains a **name**, **description** and list of zero or
+more **rules**.  The following snippet exhibits the minimal definition
+for a `Rule Set`, providing only the **name** and **description**
+fields, along with an empty set of **rules**.
+
+```javascript
+{ "name": "Empty Rules"
+, "description": "An example of an empty rule set"
+, "rules": []
+}
+```
+
+### Rules
+
+The elements of the **rules** array in the `Rule Set` are also represented as
+json objects.  A minimal rule consists of three fields: **name**,
+**description** and **rule**.  While **name** and **description** are just
+strings, like the definition of a `Rule Set`, the **rule** field is a javascript
+function.
+
+The definition of the **rule** function consists of a single javascript function
+that expects no arguments and returns no value.  The rule will be invoked with
+no special context, and it is expected to perform its validation based on uses of
+the `FiveUI prelude`.  Rules are able to report problems to the in-page FivUI
+interface by invoking the *report* function.
+
+As a simple example, the following rule will log an error for each header tag
+that contains no text:
+
+```javascript
+{ "name": "Disallow Empty Headers"
+, "description": "Heading elements should contain text"
+, "rule": function() {
+    fiveui.query(':header').each(function(ix, elt) {
+      if($(elt).text() == '') {
+        report('Heading does not contain text', elt);
+      }
+    });
+  }
+}
+```
+
+### Creating a `Rule Set`
+
+Reusing the previous example and the skeleton of the first, we can create a
+simple `Rule Set` that applies the empty header rule:
+
+* Begin by copying this code block, so that it will be available to the `Rule
+   Set` editor later.
+
+```javascript
+{ "name": "Header Rule Set"
+, "description": "Simple rules about HTML headers."
+, "rules":
+  [ { "name": "Disallow Empty Headers"
+    , "description": "Heading elements should contain text."
+    , "rule": function() {
+        fiveui.query(':header').each(function(ix, elt) {
+          if($(elt).text() == '') {
+            report('Heading does not contain text', elt);
+          }
+        });
+      }
+    }
+  ]
+}
+```
+
+* Next, open the options page for the FiveUI extension.
+* Navigate to the `Rule Sets` preferences tab, by clicking the `Rule Sets` link
+  on the left-hand side of the page.
+* Click the `Add` button.
+* Paste in the contents of the example Rule Set into the text area that appears.
+  FiveUI should highlight the syntax of the rule.
+
+![FiveUI uses a rich Javascript editor to highlight rule sets.](figures/ff-add-rule-set.png)
+
+* Click the `Save` button.
+* An entry in the list above the `Add` button should appear, describing the rule
+  that was added in the previous steps.
+
+## URL Patterns
+
+`URL Patterns` can be managed by first clicking the `URL Patterns` tab on the
+left-hand side of the options page.
+
+`URL Patterns` represent the conditions in which a `Rule Set` will be applied to
+a page.  To create a `URL Pattern` first make sure that you have created a `Rule
+Set` with the instructions above.  If not, when you click the `Add` button on
+the `URL Patterns` tab, you will get an error dialog explaining that it is not
+possible to create a `URL Pattern` without one or more `Rule Sets` having been
+defined.
+
+If you have created a `Rule Set`, a new tab should appear that
+contains two fields, one text box for the rule pattern and a drop-down
+menu that contains all of the `Rule Sets` that have been defined thus
+far.
+
+### Pattern Language
+
+The **pattern** text in a `URL Pattern` uses the glob character
+`*`, to allow for a `URL Pattern` to apply to many URLs.  For example, if you
+would like to design a pattern that applies to all of the `http` pages under the
+www.example.com domain, then you could use a pattern such as:
+
+```
+http://www.example.com*
+```
+
+Note that `URL Patterns` match the protocol, domain, port and path
+portions of the url, so the pattern above will not apply to `https`
+urls.  The following pattern will apply to *any* site hosted at example.com:
+
+```
+*example.com*
+```
+
+# Using FiveUI
+
+Once some `Rule Sets` and `URL Patterns` exist in the FiveUI configuration, the
+rules can be applied to a web page.  Start off by navigating to a page that
+satisfies one of the `URL Patterns` defined in the FiveUI options page.  If that
+URL is matched by one of the patterns, the FiveUI icon will change from gray to
+red, and an overlay will display the number of rule violations present on the
+page.
+
+The primary user interface is hidden by default, to avoid obscuring
+the web page inadvertently.  To show the list of problems, simply
+click on the FiveUI icon to make the window visible.  The user
+interface is injected into the running page, and it should display on
+top of any other user interface elements present.
+
+As the user navigates around sites that are matched by `URL Patterns`,
+the problem list will have newly occurring problems appended to it.
+All state in the dialog is maintained by the extension on a per-tab
+basis, so different browser tabs can have distinct lists of problems.
+
+## Problems
+
+Problem entries will be added to the FiveUI dialog as rules report
+problems on the page.  Once a problem is reported, the user can click
+on the arrow to the left of the message to both expand the description
+of the problem, and to highlight the node of the DOM that is causing
+the problem.  One caveat to this is that if the node that generated
+the problem exists on a page that has since been navigated away from,
+the node will obviously not be highlighted.
+
+We illustrate this by first adding a new rule to our example Rule Set.
+This rule identifies headers that start with a lower-case letter.
+
+```javascript
+{ "name": "Header Rule Set"
+, "description": "Simple rules about HTML headers."
+, "rules":
+  [ { "name": "Disallow Empty Headers"
+    , "description": "Heading elements should contain text."
+    , "rule": function() {
+        fiveui.query(':header').each(function(ix, elt) {
+          if($(elt).text() == '') {
+            report('Heading does not contain text', elt);
+          }
+        });
+      }
+    },
+    { "name": "Headers should be capitalized"
+    , "description": "Heading elements should not start "
+                   + "with lowercase letters."
+    , "rule": function() {
+        fiveui.query(':header').each(function(ix, elt) {
+          if( !fiveui.word.capitalized($(elt).text()) ) {
+            report('Heading is not capitalized', elt);
+          }
+        });
+      }
+    },
+  ]
+}
+```
+
+This sample `Rule Set` demonstrates some new capabilities:
+ * Multiple rules in one Rule Set.
+ * Multi-line descriptions.
+ * The `fiveui.word.capitalized(...)` predicate, from the `FiveUI prelude`.
+The `FiveUI Prelude` is a small collection of utilities for creating rules.
+
+Once adding this `Rule Set` specifying a `URL Pattern`, we can view
+violations in the FiveUI Problem List.  Clicking on the `expand arrow`
+for a specific problem will highlight the element of the DOM that
+caused the violation.
+
+![Expanding a Problem entry in the FiveUI Problem List highlights the element of the DOM that caused the violation.](figures/ff-heading-highlight.png)
diff --git a/doc/manual_src/install.md b/doc/manual_src/install.md
new file mode 100644
index 0000000..2bded6c
--- /dev/null
+++ b/doc/manual_src/install.md
@@ -0,0 +1,85 @@
+% Install Guide
+
+# Installing the FiveUI Extension
+
+FiveUI is distributed as source code and as a browser extension for
+both Google Chrome and Mozilla Firefox.  This document describes the
+install process for these browsers, assuming that you have the FiveUI
+extension on your local computer.
+
+## Installing FiveUI in Firefox
+
+FiveUI is currently supported on Firefox 10, although it should also
+work on newer versions and Firefox 3.6.  Due to changes in the
+long-term support and Mozilla version numbering scheme, versions 4-9
+are not supported.
+
+The FiveUI Firefox extension is packaged in a file called
+`fiveui.xpi`.  Locate this file in your distribution (or download) and
+take note of the location for the following steps.  We will assume
+that it is located at `d:\binaries\fiveui.xpi`
+
+ * Open Firefox, and load the `Add-ons Manager` from the main Firefox
+   menu.
+
+![Access the Firefox Add-ons Manager from the main Firefox menu](figures/ff-menu.png)
+
+![The Add-ons Manager Gear menu has an install from file entry.](figures/ff-add-on-installer.png)
+
+ * Within the `Add-ons Manager`, open the Gear menu and select
+   `Install Add-on From File`.
+
+ * A file dialog should open, use this to browse to the `fiveui.xpi`
+   file (in our case, `d:\binaries\fiveui.xpi`.
+
+ * Click OK, and a warning dialog should appear.  This dialog warns
+   that the FiveUI author is not verified.  Because this is a
+   development release of FiveUI, the xpi file is not
+   cryptographically signed, and therefore, Firefox is unable to
+   verify the author identification.
+
+ * Click on the `Install Now` button once it becomes active.
+
+FiveUI is now installed.  The [Getting Started guide](gettingStarted)
+explains how to configure and use the extension.
+
+## Installing FiveUI in Chrome
+
+All recent versions of Google Chrome should support FiveUI.
+
+Chrome is primarily designed to install extensions from the on-line
+extension marketplace, however, local extensions can be installed by
+navigating to the extension on disk.  To do this, you must enter a
+`file:///` url in the url bar.
+
+The following steps describe how to install FiveUI in Chrome, using an
+extension file from the local file system.
+
+The FiveUI Chrome extension is packaged in a file called `fiveui.crx`.
+Locate this file in your distribution (or download) and take note of
+the location for the following steps.  We will assume that it is
+located at `d:\binaries\fiveui.crx`
+
+ * Open Google Chrome, and enter the `file:///` url in the url bar, as
+   shown.  In our case, the url is `file:///d:/binaries/fiveui.crx`.
+
+![Use a file:/// url to install local extensions in Chrome.](figures/chrome-file-url.png)
+
+ * Chrome should open a download and install bar at the bottom of the
+   window and begin adding FiveUI to the browser.
+
+![Chrome shows an install indicator at the bottom of the window](figures/chrome-adding.png)
+
+ * After a few minutes of processing, Chrome will open a confirmation
+   dialog, as shown.  Confirm the installation to complete the
+   process.
+
+![Confirm the FiveUI installation to finish adding the extension.](figures/chrome-confirm-add-fiveui.png)
+
+ * The FiveUI Button should appear in the Chrome toolbar after you
+   dismiss the confirmation dialog.
+
+![The FiveUI Button will be added to the Chrome toolbar.](figures/chrome-install-done.png)
+
+FiveUI is now installed.  The [Getting Started guide](gettingStarted)
+explains how to configure and use the extension.