Brought documentation up to date

2 files changed, 105 insertions, 71 deletions

diff --git a/doc/header.html b/doc/header.html
index 58dc0da..b53a7a3 100644
--- a/doc/header.html
+++ b/doc/header.html
@@ -23,6 +23,10 @@
         margin-top: 50px;
         text-align: center;
     }
+    h3 {
+        margin-top: 30px;
+        text-align: center;
+    }
     codeblock {
         padding: 0px 15px;
         margin: 5px 0 15px;
diff --git a/doc/index.txt b/doc/index.txt
index 78551c9..69aa971 100644
--- a/doc/index.txt
+++ b/doc/index.txt
@@ -13,100 +13,129 @@ information about scheduler behavior.
 This document contains instructions for people who want to use and/or contribute to Unit-Trace.
 It is the complete documentation for Unit-Trace.
 
-## Architecture ##
-Before trying to use Unit-Trace, it will help to understand the architecture of Unit-Trace.
-
-Unit-Trace performs various options on **trace files**. Oftentimes, when scheduler tracing takes
-place, multiple trace files are generated for each experiment (e.g. one per CPU). We call a
-related group of trace files a **trace**.
-
-The user interacts with the tool using `unit-trace`, a Python script which is to be installed
-on the local executable path.
-`unit-trace` invokes operations provided by the `unit_trace` Python module, which is installed
-in the local `site_packages` directory (the default install location for Python modules).
-
-The `unit_trace` module provides submodule(s) for parsing trace files into a **stream** of Python objects (which we call **records**).
-This stream is then passed from one `unit_trace` submodule to the next (like a pipe), undergoing
-various transformations in the process, and ultimately arriving at one or more output submodules.
-Intermediate modules generally add records; for example, the `gedf_test` module adds records to indicate
-priority inversions, which can be treated appropriately by output submodules.
-
-This architecture provides a clean and easy-to-use interface for both users and contributors.
-The stream is implemented using Python iterators.
-This allows records are evaluated lazily (i.e. on an as-needed basis), making it possible to pull into memory only
-the records that are needed, and only as long as they are needed.
-This is important for dealing with very large traces.
-
 ## Obtaining Unit-Trace ##
-Members of UNC's Real-Time Group can obtain Unit-Trace using:  
+Members of UNC's Real-Time Group can obtain Unit-Trace using:<br>
 <codeblock>git clone ssh://cvs.cs.unc.edu/cvs/proj/litmus/repo/unit-trace.git</codeblock>
 
 ## Installing Unit-Trace ##
 Unit-Trace is based on Python 2.6, so make sure that is available on your system.
 
-Unit-Trace can be installed manually by copying the `unit-trace` script and `unit_trace` Python module, as described previously.
-Alternatively, you can use `sudo install.py` to (re)install Unit-Trace.
+Unit_Trace consists of a Python module called `unit_trace` (encapsulated in the `unit_trace` directory) and a font-end script called `unit-trace`.
+
+You can use `install.py` to install unit-trace, or install manually by copying the `unit-trace` script and the `unit_trace` directory
+to `~/bin`.
+
+Make sure `~/bin` is on your `PATH`.
 
 ## Using Unit-Trace ##
-Type `unit-trace` (without options) to view usage information.
-
-In summary, trace files must be specified.
-Flags are used to enable any desired submodules.
-Some flags have accompanying parameter(s) that are passed to the submodule.
-The order in which submodules process records is pre-determined by the `unit-trace` script,
-so the user can specify flags on the command line in any order.
-
-## Example/Use Case ##
-Suppose that Alice wants to perform G-EDF testing on the LITMUS<sup>RT</sup> traces included in the sample_traces/ folder.
-
-The LITMUS<sup>RT</sup> tracing mechanism outputs superfluous events at the beginning of the trace that will not appear "correct" for
-G-EDF testing (for example, multiple job releases that never complete, indicating the initialization of a task).
-Alice uses the following command to print out (-o) the first 50 records (-m 50), looking for the end of the bogus records:  
-<codeblock>unit-trace -m 50 -o *.bin</codeblock>.
-
-Seeing that she hasn't yet reached useful records, she uses the following command to print out (-o) 50 records (-m 50), skipping the
-first 50 (-s 50).  
-<codeblock>unit-trace -m 50 -s 50 -o *.bin</codeblock>.  
-She is able to see that meaningful releases begin at time `37917282934190`.
-
-She now commences G-EDF testing (-g), starting at the time of interest (-e <earliest time>).
-Because of the lengthy output to be expected, she redirects to standard out.
-She also uses the -c option to clean up additional records that are known to be erroneous, and
-will break the G-EDF tester.  
-<codeblock>unit-trace -c -e 37917282934190 -g -o *.bin > output</codeblock>.
-
-OK, everything worked. Alice can now grep through the output file and see priority inversions.
-She sees a particularly long priority inversion, and decides to generate a visualization (-v) of part of the schedule.  
-<codeblock>unit-trace -c -e 37918340000000 -l 37919000000000 -v *.bin</codeblock>.  
-(NOTE: Currently, this still shows the entire schedule, which likely won't be feasible for larger traces and is a bug.)
-
-## Submodules ##
+Command line usage:<br>
+<codeblock>unit-trace &lt;one or more trace files&gt; [flags]</codeblock>.  
+
+Each flag turns on or off a unit-trace submodule. The available submodules are
+given below.
+
+You can specify module flags in any order.
+
+For a quick usage reference (including a list of modules), type `unit-trace` on the command line, without any arguments.
+
+### Example Use Case ###
+Let's assume you're in a directory with a bunch of trace files with
+the extension `.bin`. 
+(Each trace file is assumed to be the trace of a single CPU, and all trace files in the directory are from the same experimental run.)
+
+Suppose you want to get a list of the 10 longest priority inversions in a LITMUS<sup>RT</sup>trace.
+Use the following command:<br>
+<codeblock>unit-trace *.bin -c -g -i 10</codeblock>.
+
+Now, suppose you want to visualize one of those priority inversions.
+Given in the output for each one are the event IDs at the beginning and end of the priority inversion.
+Use the following command:<br>
+<codeblock>unit-trace *.bin -e &lt;the first event ID&gt; -l &lt;the second event ID&gt; -v</codeblock>.
+
+Note that if the visualizer stops at the second specified event (which it will), it will not be able to render anything that happens after that.
+Since you're probably interested in what happened after the priority inversion ended (for at least a little while), you should probably specify
+a slightly later second event ID (e.g. 100 greater than the actual ending event ID).
+
+Now, suppose you want to see specific textual output for all events. (You could also specify a range if you wanted to.)<br>
+<codeblock>unit-trace *.bin -o > output</codeblock>
+
+This example provides a basic overview of what you can do with Unit-Trace. Detailed information about all available submodules is provided in
+the next section.
+
+## List of Submodules ##
+
+There are five basic kinds of submodules.
+
+- Input submodules, which read trace files
+- Filter submodules, which filter out event records
+- Test submodules, which perform some kind of test
+- Output modules, which display the results
+- Miscellaneous
+
+All submodules are listed and summarized in the tables below.
+Some submodules have further documentation, appearing later in this document.
+
 ### Input Submodules ###
 <table border=1>
-<tr><td>Name</td><td>Flag</td><td>Options</td><td>Description</td></tr>
+<tr><td>Name</td><td>Flag</td><td>Parameters</td><td>Description</td></tr>
 <tr><td>trace_parser</td><td>(on by default)</td><td>(None)</td><td>Parses LITMUS<sup>RT</sup> traces</td></tr>
 </table>
-### Intermediate Submodules ###
+### Filter Submodules ###
 <table border=1>
-<tr><td>Name</td><td>Flag</td><td>Options</td><td>Description</td></tr>
-<tr><td>earliest</td><td>-e</td><td>time</td><td>Filters out records before the given time</td></tr>
-<tr><td>latest</td><td>-l</td><td>time</td><td>Filters out records after the given time</td></tr>
+<tr><td>Name</td><td>Flag</td><td>Parameters</td><td>Description</td></tr>
+<tr><td>earliest</td><td>-e</td><td>time</td><td>Filters out records before the given event ID. (Event IDs are assigned in order of event record timestamp, and are displayed by the `stdio_printer` submodule.)</td></tr>
+<tr><td>latest</td><td>-l</td><td>time</td><td>Filters out records after the given event ID.</td></tr>
 <tr><td>skipper</td><td>-s</td><td>number n</td><td>Skips the first n records</td></tr>
 <tr><td>maxer</td><td>-m</td><td>number n</td><td>Allows at most n records to be parsed</td></tr>
-<tr><td>sanitizer</td><td>-c</td><td>(None)</td><td>Cleans up LITMUS<sup>RT</sup> traces for G-EDF testing.</td></tr>
-<tr><td>progress</td><td>-p</td><td>(None)</td><td>Outputs progress info (e.g number of records parsed so far, total time to process trace) to std error.</td></tr>
-<tr><td>stats</td><td>-i</td><td>(None)</td><td>Outputs statistics about G-EDF inversions. To be deprecated (incorporated into G-EDF tester).</td></tr>
+<tr><td>sanitizer</td><td>-c</td><td>(None)</td><td>Modifies LITMUS<sup>RT</sup> traces. To be used in conjunction with the G-EDF tester. To summarize, LITMUS<sup>RT</sup> traces have some bogus records that need to be removed or altered in order for a (potentially) valid schedule to be represented.</td></tr>
+</table>
+### Test Submodules ###
+<table border=1>
+<tr><td>Name</td><td>Flag</td><td>Options</td><td>Description</td></tr>
 <tr><td>gedf_test</td><td>-g</td><td>(None)</td><td>Performs G-EDF testing.</td></tr>
 </table>
 ### Output Submodules ###
 <table border=1>
 <tr><td>Name</td><td>Flag</td><td>Options</td><td>Description</td></tr>
-<tr><td>stdout_printer</td><td>-o</td><td>(None)</td><td>Prints records to standard out</td></tr>
-<tr><td>visualizer</td><td>-v</td><td>(None)</td><td>Visualizes records</td></tr>
+<tr><td>stdout_printer</td><td>-o</td><td>(None)</td><td>Prints records to standard out. You should probably redirect the output to a file when you use this.</td></tr>
+<tr><td>visualizer</td><td>-v</td><td>(None)</td><td>Visualizes records. You should probably use filters in conjunction with this submodule. Otherwise, it'll take forever to render, and do you _really_ want to visualize the _entire_ trace, anyway?</td></tr>
+<tr><td>gedf_inversion_stat_printer</td><td>-i</td><td>number n</td><td>Outputs statistics about G-EDF inversions, and the n longest inversions. (You can specify n as 0 if you want.)</td></tr>
 </table>
+### Miscellaneous Submodules ###
+<table border=1>
+<tr><td>Name</td><td>Flag</td><td>Options</td><td>Description</td></tr>
+<tr><td>progress</td><td>-p</td><td>(None)</td><td>Outputs progress info (e.g number of records parsed so far, total time to process trace) to std error.</td></tr>
+</table>
+
+## Specific Submodule Documentation ##
+
+Here, documentation is provided for submodules for which relevant information is not considered to be self-evident.
+
+(So far, it hasn't been necessary to add anything here, but once questions arise, it will become clear which submodules need to be documented more fully.)
 
 ## Development ##
-TODO: Information on how to contribute will be documented thoroughly here.
+Please send patches to [Mac Mollison][mac] or, if you are in the `litmus` group at UNC, just work with the git repo directly.
+
+The following "rules" are currently in place:
+
+- Please follow PEP 8 style guidelines when possible.
+- Update the documentation when you do something that makes it obsolete or incomplete
+- Don't break the overall architecture (described below)
+
+### Architecture ###
+If you are interested in contributing to Unit-Trace, you probably ought to know a bit about its overall architecture.
+
+Generally speaking, each Unit-Trace submodules is a Python generator. It accepts a Python iterator object as input and returns a Python iterator
+object as output. (You may want to look up the relevant Python terminology.)
+
+The exceptions are input submodules, which do not take any input other than a list of trace files, and the output submodules, which do not return
+iterator objects.
+
+The `unit-trace` script connects together the desired modules (i.e. those specified on the command line) using Python iterators.
+
+This architecture provides two advantages.
+First, because Python iterators are evaluated lazily, it is not necessary to read an entire trace file into memory in order to run `unit-trace` on it.
+Second, it provides an easy-to-understand programming model.
 
 ## Documentation ##
 The source code for this page is included in the `doc` folder that comes with Unit-Trace.
@@ -130,3 +159,4 @@ We hope to have additional contributors in the future.
 [ospert_paper]: http://www.cs.unc.edu/%7Eanderson/papers/ospert09.pdf
 [ospert]: http://www.artist-embedded.org/artist/Overview,1750.html
 [markdown]: http://daringfireball.net/projects/markdown/
+[mac]: mailto:mollison@cs.unc.edu