Formatted first half of README.

2 files changed, 150 insertions, 143 deletions

diff --git a/README.md b/README.md
index e1a0815..57d9afa 100644
--- a/README.md
+++ b/README.md
@@ -1,118 +1,97 @@
-I. INTRODUCTION
-These scripts provide a common way for creating, running, parsing, and
-plotting experiments under LITMUS^RT. They are designed with the
-following principles in mind:
-
-1. Little or no configuration: all scripts use certain parameters to
-configure behavior. However, if the user does not give these
-parameters, the scripts will examine the properties of the user's
-system to pick a suitable default. Requiring user input is a last
-resort.
-
-2. Interruptability: the scripts save their work as they evaluate
-multiple directories. When the scripts are interrupted, or if new data
-is added to those directories, the scripts can be re-run and they will
-resume where they left off. This vastly decreases turnaround time for
-testing new features.
-
-3. Maximum Safety: where possible, scripts save metadata in their output
-directories about the data contained. This metadata can be used by
-the other scripts to safely use the data later.
-
-4. Independence / legacy support: none of these scripts assume their
-input was generated by another of these scripts. Three are designed to
-recognize generic input formats inspired by past LITMUS^RT
-experimental setups. (The exception to this is gen_exps.py, which
-has only user intput and creates output only for run_exps.py)
-
-5. Save everything: all output and parameters (even from subprocesses)
-is saved for debugging / reproducability. This data is saved in tmp/
-directories while scripts are running in case scripts fail.
-
-These scripts require that the following repos are in the user's PATH:
-1. liblitmus - for real-time executable simulation and task set release
-2. feather-trace-tools - for recording and parsing overheads and
-   scheduling events
-
-Optionally, additional features will be enabled if these repos are
-present in the PATH:
-1. rt-kernelshark - to record ftrace events for kernelshark visualization
-2. sched_trace - to output a file containing scheduling events as
-strings
-
-Each of these scripts is designed to operate independently of the
-others. For example, the parse_exps.py will find any feather trace
-files resembling ft-xyz.bin or xyz.ft and print out overhead
-statistics for the records inside. However, the scripts provide the
-most features (especially safety) when their results are chained
-together, like so:
+# About
+These Python scripts provide a common way for creating, running, parsing, and plotting experiments using [LITMUS^RT][litmus]. These scripts are:
 
+1. `gen_exps.py`: for creating sets of experiments
+2. `run_exps.py`: for running and tracing experiments
+3. `parse_exps.py`: for parsing LITMUS^RT trace data
+4. `plot_exps.py`: for plotting directories of csv data
+
+They are designed with the following principles in mind:
+
+1. Little or no configuration: all scripts use certain parameters to configure behavior. However, if the user does not give these parameters, the scripts will examine the properties of the user's system to pick a suitable default. Requiring user input is a last resort.
+
+2. Interruptability: the scripts save their work as they evaluate multiple directories. When the scripts are interrupted, or if new data is added to those directories, the scripts can be re-run and they will resume where they left off. This vastly decreases turnaround time for testing new features.
+
+3. Maximum Safety: where possible, scripts save metadata in their output directories about the data contained. This metadata can be used by the other scripts to safely use the data later.
+
+4. Independence / legacy support: none of these scripts assume their input was generated by another of these scripts. Three are designed to recognize generic input formats inspired by past LITMUS^RT experimental setups. (The exception to this is gen_exps.py, which has only user intput and creates output only for run_exps.py)
+
+5. Save everything: all output and parameters (even from subprocesses) is saved for debugging / reproducability. This data is saved in tmp/ directories while scripts are running in case scripts fail.
+
+# Dependencies
+These scripts were tested using Python 2.7.2. They have not been tested using Python 3. The [Matplotlib][matplotlib] Python library is needed for plotting.
+
+The `run_exps.py` script should almost always be run using a LITMUS^RT kernel. In addition to the kernel, the following LITMUS-related repos must be in the user's `PATH`:
+1. [liblitmus][liblitmus]: for real-time executable simulation and task set release
+2. [feather-trace-tools][feather-trace-tools]: for recording and parsing overheads and scheduling events
+
+Additional features will be enabled if these repos are present in the `PATH`:
+1. [rt-kernelshark][rt-kernelshark]: to record ftrace events for kernelshark visualization
+2. sched_trace ([UNC internal][rtunc]) to output a file containing scheduling events as strings
+
+# Details
+Each of these scripts is designed to operate independently of the others. For example, `parse_exps.py` will find any feather trace files resembling `ft-xyz.bin` or `xyz.ft` and print out overhead statistics for the records inside. However, the scripts provide the most features (especially safety) when their results are chained together, like so:
+
+```
 gen_exps.py --> [exps/*] --> run_exps.py  --> [run-data/*] --.
 .------------------------------------------------------------'
 '--> parse_exps.py --> [parse-data/*] --> plot_exps.py --> [plot-data/*.pdf]
+```
+
+1. Create experiments with `gen_exps.py` or some other script.
+2. Run experiments using `run_exps.py`, generating binary files in `run-data/`.
+3. Parse binary data in `run-data/` using `parse_exps.py`, generating csv files in `parse-data/`.
+4. Plot `parse-data` using `plot_exps.py`, generating pdfs in `plot-data/`.
+
+Each of these scripts will be described. The `run_exps.py` script is first because `gen_exps.py` creates schedule files which depend on `run_exps.py`.
+
 
-0. Create experiments with gen_exps.py or some other script.
-1. Run experiments using run_exps.py, generating binary files in run-data/.
-2. Parse binary data in run-data using parse_exps.py, generating csv
-   files in parse-data/.
-3. Plot parse-data using plot_exps.py, generating pdfs in plot-data.
-
-Each of these scripts will be described. The run_exps.py script is
-first because gen_exps.py creates schedule files which depend on run_exps.py.
-
-
-II. RUN_EXPS
-Usage: run_exps.py [OPTIONS] [SCHED_FILE]... [SCHED_DIR]...
-       where a SCHED_DIR resembles:
-         SCHED_DIR/
-            SCHED_FILE
-            PARAM_FILE
-
-Output: OUT_DIR/[files] or OUT_DIR/SCHED_DIR/[files] or
-        OUT_DIR/SCHED_FILE/[files] depending on input
-        If all features are enabled, these files are:
-        OUT_DIR/[.*/]
-           trace.slog    # LITMUS logging
-           st-[1..m].bin # sched_trace data
-           ft.bin        # feather-trace overhead data
-           trace.dat     # ftrace data for kernelshark
-           params.py     # Schedule parameters
-           exec-out.txt  # Standard out from schedule processes
-           exec-err.txt  # Standard err '''
-
-Defaults: SCHED_FILE = sched.py, PARAM_FILE = params.py,
-          DURATION = 30, OUT_DIR = run-data/
-
-The run_exps.py script reads schedule files and executes real-time
-task systems, recording all overhead, logging, and trace data which is
-enabled in the system. For example, if trace logging is enabled,
-rt-kernelshark is found in the path, but feather-trace is disabled
-(the devices are not present), only trace-logs and kernelshark logs
-will be recorded.
-
-When run_exps.py is running a schedule file, temporary data is saved
-in a 'tmp' directory in the same directory as the schedule file. When
-execution completes, this data is moved into a directory under the
-run_exps.py output directory (default: 'run-data/', can be changed with
-the -o option). When multiple schedules are run, each schedule's data
-is saved in a unique directory under the output directory.
-
-If a schedule has been run and it's data is in the output directory,
-run_exps.py will not re-run the schedule unless the -f option is
-specified. This is useful if your system crashes midway through a set
-of experiments.
+## run_exps.py
+*Usage*: `run_exps.py [OPTIONS] [SCHED_FILE]... [SCHED_DIR]...`
+
+where a `SCHED_DIR` resembles:
+```
+SCHED_DIR/
+        SCHED_FILE
+        PARAM_FILE
+```
+
+*Output*: `OUT_DIR/[files]` or `OUT_DIR/SCHED_DIR/[files]` or `OUT_DIR/SCHED_FILE/[files]` depending on input
+
+If all features are enabled, these files are:
+```
+OUT_DIR/[SCHED_(FILE|DIR)/]
+        trace.slog    # LITMUS logging
+        st-[1..m].bin # sched_trace data
+        ft.bin        # feather-trace overhead data
+        trace.dat     # ftrace data for kernelshark
+        params.py     # Schedule parameters
+        exec-out.txt  # Standard out from schedule processes
+        exec-err.txt  # Standard err '''
+```
+
+*Defaults*: `SCHED_FILE = sched.py, PARAM_FILE = params.py, DURATION = 30, OUT_DIR = run-data/`
+
+This script reads *schedule files* (described below) and executes real-time task systems, recording all overhead, logging, and trace data which is enabled in the system. For example, if trace logging is enabled, rt-kernelshark is found in the path, but feather-trace is disabled (the devices are not present), only trace logs and rt-kernelshark logs will be recorded.
+
+When `run_exps.py` is running a schedule file, temporary data is saved in a `tmp` directory in the same directory as the schedule file. When execution completes, this data is moved into a directory under the `run_exps.py` output directory (default: `run-data/`, can be changed with the `-o` option). When multiple schedules are run, each schedule's data is saved in a unique directory under the output directory.
+
+If a schedule has been run and it's data is in the output directory, `run_exps.py` will not re-run the schedule unless the `-f` option is specified. This is useful if your system crashes midway through a set of experiments.
 
 Schedule files have one of the following two formats:
 
-a) simple format
+1. simple format
+```
        path/to/proc{proc_value}
        ...
        path/to/proc{proc_value}
        [real_time_task: default rtspin] task_arguments...
        ...
        [real_time_task] task_arguments...
+```
 
 b) python format
+```python
        {'proc':[
            ('path/to/proc','proc_value'),
             ...,
@@ -124,55 +103,67 @@ b) python format
            ('real_time_task', 'task_arguments')
         ]
        }
+```
 
-The following creates a simple 3-task system with utilization 2.0,
-which is then run under the GSN-EDF plugin:
+The following creates a simple 3-task system with utilization 2.0, which is then run under the `GSN-EDF` plugin:
 
+```bash
 $ echo "10 20
 30 40
 60 90" > test.sched