some more fixes

3 files changed, 28 insertions, 26 deletions

diff --git a/doc/tracing.html b/doc/tracing.html
index 5d40ab7..55d0085 100644
--- a/doc/tracing.html
+++ b/doc/tracing.html
@@ -42,9 +42,9 @@ This document is part of the documentation of the <a href="../index.html">LITMUS
 <ol>
 <li><p><code>litmus_log</code>: This trace contains text messages (created with the <code>TRACE()</code>
 macro, see <code>litmus.h</code>) that convey information useful for debugging. There is one global
-<code>litmus_log</code> buffer for the whole system. Debug tracing must be enabled at compile time. Note that debug tracing creates significant overhead because string formatting takes place.</p></li>
+<code>litmus_log</code> buffer for the whole system. The <code>litmus_log</code> facility is essentially a replacement for <code>printk()</code>, which cannot be invoked from scheduling code without risking deadlock. Debug tracing must be enabled at compile time. Note that debug tracing creates significant overhead because string formatting takes place. </p></li>
 <li><p><code>ft_trace</code>: This trace contains binary-encoded time stamps. It is used for overhead tracing. There is one global <code>ft_trace</code> buffer for the whole system. The "ft" stands for <a href="http://www.cs.unc.edu/~bbb/feather-trace">Feather-Trace</a>. Feather-Trace is designed to create only negligible overhead when event sources are disabled, and to incur only low overhead when recording time stamps.</p></li>
-<li><p><code>sched_trace</code>: This trace contains binary-encoded scheduling event information, <em>e.g.</em>, an event can be recorded whenever a task got scheduled, a job was released, a job completed, etc. There is one <code>sched_trace</code> buffer per processor. <code>sched_trace</code> is also based on Feather-Trace and hence incurs only neglible overhead when event sources are disabled.</p></li>
+<li><p><code>sched_trace</code>: This trace contains binary-encoded scheduling event information, <em>e.g.</em>, an event can be recorded whenever a task got scheduled, a job was released, a job completed, etc. There is one <code>sched_trace</code> buffer per processor. <code>sched_trace</code> is based on Feather-Trace and hence also incurs only negligible overhead when event sources are disabled.</p></li>
 </ol>
 
 <h2>Accessing Trace Buffers</h2>
@@ -81,8 +81,9 @@ done
 
 <p>Kill the <code>cat</code> process to stop recording debug messages.</p>
 
-<p>No post-processing is required since the debug messages are plain text. However, note that messages may appear in a different order than how they occured at runtime. If order is important (for example when debugging race conditions), then recorded messages can be sorted offline with the help of the <em>sequence number</em> at the start of each recorded message. <br />
-Example:</p>
+<p>No post-processing is required since the debug messages are plain text. However, note that messages may appear in an order that differs from the sequence of events at runtime. If order is important (for example when debugging race conditions), then recorded messages can be sorted offline with the help of the <em>sequence number</em> at the start of each recorded message.</p>
+
+<p>Example:</p>
 
 <pre><code>sort -n my_debug_log &gt; my_sorted_debug_log
 </code></pre>
@@ -93,7 +94,7 @@ Example:</p>
 
 <p>Feather-Trace allows for much more fine-grained tracing than the simple debug stream realized by <code>litmus_log</code> and hence requires special-purpose tools to be used. These tools are available as part of the <code>ft_tools</code> package, which is available on the <a href="../index.html#download">LITMUS<sup>RT</sup> download page</a>.</p>
 
-<p>Feather-Trace events can be enabled on a per-event basis. Each event is identified by a unique 32-bit ID. Intially, when the device buffer is not being accessed by any user space programs (<em>i.e.</em>, when the device driver is unused), all events are disabled. Events can be enabled (and subsequently disabled again) by writing binary commands to the buffer device file. Once events are enabled they can generate trace records, which are stored in the trace buffer. Userspace programs can obtain these records by reading from the device file. Reading a trace record removes it from the buffer, <em>i.e.</em>, each record can be read exactly once. Since buffer capacity is limited records should be consumed shortly after they were created.</p>
+<p>Feather-Trace events can be enabled on a per-event basis. Each event is identified by a unique 32-bit ID. Initially, when the device buffer is not being accessed by any user space programs (<em>i.e.</em>, when the device driver is unused), all events are disabled. Events can be enabled (and subsequently disabled again) by writing binary commands to the buffer device file. Once events are enabled they can generate trace records, which are stored in the trace buffer. User space programs can obtain these records by reading from the device file. Reading a trace record removes it from the buffer, <em>i.e.</em>, each record can be read exactly once. Records should be consumed shortly after they were created since buffer capacity is limited.</p>
 
 <p>The tool <code>ftcat</code>, which is part of the <code>ft_tools</code> package (see above), automates the process of enabling events and retrieving trace records. It takes the name of the <code>ft_trace</code> device file and the events of interest as arguments:</p>
 
@@ -102,7 +103,7 @@ Example:</p>
 
 <p>The tool enables the specified events and copies all recorded events to <code>stdout</code>.</p>
 
-<p>Events can be specified either by their ID (see <code>include/litmus/trace.h</code> in the kernel directory for a list of timestamp-generating events) or by their symbolic name. The following symbolic names are recognized:</p>
+<p>Events can be specified either by their ID (see <code>include/litmus/trace.h</code> in the kernel directory for a list of time stamp generating events) or by their symbolic name. The following symbolic names are recognized:</p>
 
 <ul>
 <li><code>SCHED_START</code>, <code>SCHED_END</code>: <br />
@@ -110,14 +111,14 @@ Used to measure the time spent to make a scheduling decision.</li>
 <li><code>CXS_START</code>, <code>CXS_END</code>: <br />
 Used to record the time spent to make a context switch.</li>
 <li><code>SCHED2_START</code>, <code>SCHED2_END</code>: <br />
-Used to measure the time spent to perform post-context-switch cleanup and management activities. (This is part of the scheduling overhead but for technical reasons cannot be measured as part of the interval [<code>SCHED_START</code>, <code>SCHED_END</code>].</li>
+Used to measure the time spent to perform post-context-switch cleanup and management activities. This is part of the scheduling overhead but for technical reasons cannot be measured as part of the interval [<code>SCHED_START</code>, <code>SCHED_END</code>].</li>
 <li><code>TICK_START</code>, <code>TICK_END</code>: <br />
 Used to measure the overhead incurred at the beginning of a scheduling quantum.</li>
 <li><code>PLUGIN_TICK_START</code>, <code>PLUGIN_TICK_END</code>: <br />
 Like [<code>TICK_START</code>, <code>TICK_END</code>], but only measures the time spent by the active scheduling plugin.</li>
 <li><code>PLUGIN_SCHED_START</code>, <code>PLUGIN_SCHED_END</code>: <br />
 Like [<code>SCHED_START</code>, <code>SCHED_END</code>], but only measures the time spent by the active scheduling plugin. There is no equivalent <code>SCHED2</code> counterpart because the scheduling plugins do not directly compute to the <code>SCHED2</code> overhead.</li>
-<li><code>RELEASE_START</code>, <code>RELEASE_END</code>:
+<li><code>RELEASE_START</code>, <code>RELEASE_END</code>: <br />
 Used to measure the time spent to enqueue a newly-released job in a ready queue.</li>
 </ul>
 
@@ -134,7 +135,7 @@ Used to measure the time spent to enqueue a newly-released job in a ready queue.
 
 <p>The binary event stream recorded by <code>ftcat</code> is of course of limited direct use&mdash;the data has yet to be exported for analysis. This can be achieved with the tool <code>ft2csv</code>, which is also part of the <code>ft_tools</code> package.</p>
 
-<p>As the name suggests, <code>ft2csv</code> extracts intervals defined by pairs of timestamps in a recorded trace and displayse them as <em>comma-separated values</em> (CSV). It takes the name of an overhead trace and one start event as arguments:</p>
+<p>As the name suggests, <code>ft2csv</code> extracts intervals defined by pairs of time stamps in a recorded trace and displays them as <em>comma-separated values</em> (CSV). It takes the name of an overhead trace and one start event as arguments:</p>
 
 <pre><code>ft2csv &lt;start event&gt; &lt;overhead trace&gt;
 </code></pre>
@@ -151,9 +152,9 @@ Used to measure the time spent to enqueue a newly-released job in a ready queue.
 
 <p>For each event, the start time (in clock cycles) is given in the first column, the end time is given in the second column, and the length is given in the third column (again, in cycles).</p>
 
-<p><code>ft2csv</code> accepts a few options that affect how events are filtered. By default, events that do not involve real-time tasks are ignored. This can be changed by specifiying the <code>-b</code> option. If one happens to be processing output on a little-endian host that was produced on a big-endian host then the <code>-e</code> option can come in handy.</p>
+<p><code>ft2csv</code> accepts a few options that affect how events are filtered. By default, events that do not involve real-time tasks are ignored. This can be changed by specifying the <code>-b</code> option. If one happens to be processing output on a little-endian host that was produced on a big-endian host then the <code>-e</code> option can come in handy.</p>
 
-<p>Once the recorded overheads have been exported to CSV files they can be easily analyzed with tools such as Python, Octave, or Matlab.</p>
+<p>Once the recorded overheads have been exported to CSV files they can be easily analyzed with tools such as Python's <code>csv</code> module, Octave, or Matlab.</p>
 
 <h2>Recording and Post-Processing Scheduling Traces</h2>
 
@@ -182,7 +183,7 @@ Disabling 9 events.
 
 <p>Note that <code>st_trace</code> may have to modified to change the default <code>sched_trace</code> device locations.</p>
 
-<p><strong>Hint</strong>: To study/test the behavior of a scheduler plugin the dummy real-time task <code>rtspin</code> (distributed as part of the <code>liblitmus</code> package) may be useful.</p>
+<p><strong>Hint</strong>: The dummy real-time task <code>rtspin</code> (distributed as part of the <code>liblitmus</code> package) may be useful when studying/testing the behavior of a scheduler plugin.</p>
 
 <h2>Post-Processing Overhead Traces</h2>
 
@@ -192,7 +193,7 @@ Disabling 9 events.
 
 <h2>Concluding Remarks</h2>
 
-<p>At this point we only offer data <em>acquisition</em> tools since we have not yet had the time to develop release-quality <em>analysis</em> tools. <strong>Patches to improve the acquisition tools and contributions of analysis and visualization tools are very much welcome!</strong></p>
+<p>At this point we only offer data <em>acquisition</em> tools since we have not yet had the time to develop release-quality <em>analysis</em> tools. <strong>Patches that improve the existing tools and contributions of new analysis and visualization tools are very much welcome!</strong></p>
 
 <p>For any questions please contact the current LITMUS<sup>RT</sup> maintainer (as indicated on the <a href="../index.html#collaborators">LITMUS<sup>RT</sup> homepage</a>).</p>
 
diff --git a/doc/tracing.text b/doc/tracing.text
index 3421cd2..f31cb39 100644
--- a/doc/tracing.text
+++ b/doc/tracing.text
@@ -32,11 +32,11 @@ As of version 2008.2, there are three tracing mechanisms available in LITMUS<sup
 
 1. `litmus_log`: This trace contains text messages (created with the `TRACE()`
 macro, see `litmus.h`) that convey information useful for debugging. There is one global
-`litmus_log` buffer for the whole system. Debug tracing must be enabled at compile time. Note that debug tracing creates significant overhead because string formatting takes place.
+`litmus_log` buffer for the whole system. The `litmus_log` facility is essentially a replacement for `printk()`, which cannot be invoked from scheduling code without risking deadlock. Debug tracing must be enabled at compile time. Note that debug tracing creates significant overhead because string formatting takes place. 
 
 2. `ft_trace`: This trace contains binary-encoded time stamps. It is used for overhead tracing. There is one global `ft_trace` buffer for the whole system. The "ft" stands for [Feather-Trace](http://www.cs.unc.edu/~bbb/feather-trace). Feather-Trace is designed to create only negligible overhead when event sources are disabled, and to incur only low overhead when recording time stamps.
 
-3. `sched_trace`: This trace contains binary-encoded scheduling event information, *e.g.*, an event can be recorded whenever a task got scheduled, a job was released, a job completed, etc. There is one `sched_trace` buffer per processor. `sched_trace` is also based on Feather-Trace and hence incurs only neglible overhead when event sources are disabled.
+3. `sched_trace`: This trace contains binary-encoded scheduling event information, *e.g.*, an event can be recorded whenever a task got scheduled, a job was released, a job completed, etc. There is one `sched_trace` buffer per processor. `sched_trace` is based on Feather-Trace and hence also incurs only negligible overhead when event sources are disabled.
 
 Accessing Trace Buffers
 -----------------------
@@ -72,7 +72,8 @@ The `litmus_log` buffer can be read by simply opening the file and reading its c
 
 Kill the `cat` process to stop recording debug messages.
 
-No post-processing is required since the debug messages are plain text. However, note that messages may appear in a different order than how they occured at runtime. If order is important (for example when debugging race conditions), then recorded messages can be sorted offline with the help of the *sequence number* at the start of each recorded message.  
+No post-processing is required since the debug messages are plain text. However, note that messages may appear in an order that differs from the sequence of events at runtime. If order is important (for example when debugging race conditions), then recorded messages can be sorted offline with the help of the *sequence number* at the start of each recorded message.
+
 Example:
 
         sort -n my_debug_log > my_sorted_debug_log
@@ -84,7 +85,7 @@ Recording  Overhead Traces
 
 Feather-Trace allows for much more fine-grained tracing than the simple debug stream realized by `litmus_log` and hence requires special-purpose tools to be used. These tools are available as part of the `ft_tools` package, which is available on the [LITMUS<sup>RT</sup> download page](../index.html#download).
 
-Feather-Trace events can be enabled on a per-event basis. Each event is identified by a unique 32-bit ID. Intially, when the device buffer is not being accessed by any user space programs (*i.e.*, when the device driver is unused), all events are disabled. Events can be enabled (and subsequently disabled again) by writing binary commands to the buffer device file. Once events are enabled they can generate trace records, which are stored in the trace buffer. Userspace programs can obtain these records by reading from the device file. Reading a trace record removes it from the buffer, *i.e.*, each record can be read exactly once. Since buffer capacity is limited records should be consumed shortly after they were created.
+Feather-Trace events can be enabled on a per-event basis. Each event is identified by a unique 32-bit ID. Initially, when the device buffer is not being accessed by any user space programs (*i.e.*, when the device driver is unused), all events are disabled. Events can be enabled (and subsequently disabled again) by writing binary commands to the buffer device file. Once events are enabled they can generate trace records, which are stored in the trace buffer. User space programs can obtain these records by reading from the device file. Reading a trace record removes it from the buffer, *i.e.*, each record can be read exactly once. Records should be consumed shortly after they were created since buffer capacity is limited.
 
 The tool `ftcat`, which is part of the `ft_tools` package (see above), automates the process of enabling events and retrieving trace records. It takes the name of the `ft_trace` device file and the events of interest as arguments:
 
@@ -92,21 +93,21 @@ The tool `ftcat`, which is part of the `ft_tools` package (see above), automates
 
 The tool enables the specified events and copies all recorded events to `stdout`.
 
-Events can be specified either by their ID (see `include/litmus/trace.h` in the kernel directory for a list of timestamp-generating events) or by their symbolic name. The following symbolic names are recognized:
+Events can be specified either by their ID (see `include/litmus/trace.h` in the kernel directory for a list of time stamp generating events) or by their symbolic name. The following symbolic names are recognized:
 
 - `SCHED_START`, `SCHED_END`:  
 Used to measure the time spent to make a scheduling decision.
 - `CXS_START`, `CXS_END`:  
 Used to record the time spent to make a context switch.
 - `SCHED2_START`, `SCHED2_END`:  
-Used to measure the time spent to perform post-context-switch cleanup and management activities. (This is part of the scheduling overhead but for technical reasons cannot be measured as part of the interval [`SCHED_START`, `SCHED_END`].
+Used to measure the time spent to perform post-context-switch cleanup and management activities. This is part of the scheduling overhead but for technical reasons cannot be measured as part of the interval [`SCHED_START`, `SCHED_END`].
 - `TICK_START`, `TICK_END`:  
 Used to measure the overhead incurred at the beginning of a scheduling quantum.
 - `PLUGIN_TICK_START`, `PLUGIN_TICK_END`:  
 Like [`TICK_START`, `TICK_END`], but only measures the time spent by the active scheduling plugin.
 - `PLUGIN_SCHED_START`, `PLUGIN_SCHED_END`:  
 Like [`SCHED_START`, `SCHED_END`], but only measures the time spent by the active scheduling plugin. There is no equivalent `SCHED2` counterpart because the scheduling plugins do not directly compute to the `SCHED2` overhead.
-- `RELEASE_START`, `RELEASE_END`:
+- `RELEASE_START`, `RELEASE_END`:  
 Used to measure the time spent to enqueue a newly-released job in a ready queue.
 
 For example, the following command can be used to store the length of context switches and scheduling decisions in the file `my_trace`.
@@ -122,7 +123,7 @@ Post-Processing Overhead Traces
 
 The binary event stream recorded by `ftcat` is of course of limited direct use&mdash;the data has yet to be exported for analysis. This can be achieved with the tool `ft2csv`, which is also part of the `ft_tools` package.
 
-As the name suggests, `ft2csv` extracts intervals defined by pairs of timestamps in a recorded trace and displayse them as *comma-separated values* (CSV). It takes the name of an overhead trace and one start event as arguments:
+As the name suggests, `ft2csv` extracts intervals defined by pairs of time stamps in a recorded trace and displays them as *comma-separated values* (CSV). It takes the name of an overhead trace and one start event as arguments:
 
         ft2csv <start event> <overhead trace>
 
@@ -137,9 +138,9 @@ Events are specified in the same way as with `ftcat`. For example, the following
 
 For each event, the start time (in clock cycles) is given in the first column, the end time is given in the second column, and the length is given in the third column (again, in cycles).
 
-`ft2csv` accepts a few options that affect how events are filtered. By default, events that do not involve real-time tasks are ignored. This can be changed by specifiying the `-b` option. If one happens to be processing output on a little-endian host that was produced on a big-endian host then the `-e` option can come in handy.
+`ft2csv` accepts a few options that affect how events are filtered. By default, events that do not involve real-time tasks are ignored. This can be changed by specifying the `-b` option. If one happens to be processing output on a little-endian host that was produced on a big-endian host then the `-e` option can come in handy.
 
-Once the recorded overheads have been exported to CSV files they can be easily analyzed with tools such as Python, Octave, or Matlab.
+Once the recorded overheads have been exported to CSV files they can be easily analyzed with tools such as Python's `csv` module, Octave, or Matlab.
 
 Recording and Post-Processing Scheduling Traces
 -----------------------------------------------
@@ -168,7 +169,7 @@ The following example illustrates how a `st_trace` is used with the tag `global-
 
 Note that `st_trace` may have to modified to change the default `sched_trace` device locations.
 
-**Hint**: To study/test the behavior of a scheduler plugin the dummy real-time task `rtspin` (distributed as part of the `liblitmus` package) may be useful.
+**Hint**: The dummy real-time task `rtspin` (distributed as part of the `liblitmus` package) may be useful when studying/testing the behavior of a scheduler plugin.
 
 Post-Processing Overhead Traces
 -------------------------------
@@ -180,7 +181,7 @@ The tool `showst` (distributed as part of `liblitmus`) can be used to inspect th
 Concluding Remarks
 ------------------
 
-At this point we only offer data *acquisition* tools since we have not yet had the time to develop release-quality *analysis* tools. **Patches to improve the acquisition tools and contributions of analysis and visualization tools are very much welcome!**
+At this point we only offer data *acquisition* tools since we have not yet had the time to develop release-quality *analysis* tools. **Patches that improve the existing tools and contributions of new analysis and visualization tools are very much welcome!**
 
 For any questions please contact the current LITMUS<sup>RT</sup> maintainer (as indicated on the [LITMUS<sup>RT</sup> homepage](../index.html#collaborators)).
 
diff --git a/inc/format-doc.css b/inc/format-doc.css
index 78637f9..e70fe6c 100644
--- a/inc/format-doc.css
+++ b/inc/format-doc.css
@@ -89,7 +89,7 @@ h1 {
 
 h2 {
         font: normal normal 18pt Georgia, "Times New Roman", Times, serif;
-        padding-top: 0.75cm;
+        padding-top: 0.50cm;
 }
 
 .relname {