Updated README.

- Added table for commands to run - Added styling for tables and code - Added script to generated html - Changed command to run docker (with using volumes)

Updated README.
dce064b4 · René Schöne · 6e8075c3 · dce064b4 · dce064b4 · dce064b4
Commit dce064b4 authored 6 years ago by René Schöne
--- a/README.html
+++ b/README.html
@@ -6,11 +6,35 @@
  <meta name="generator" content="pandoc" />
  <title></title>
  <style type="text/css">code{white-space: pre;}</style>
+  <style type="text/css">
+  table {
+      border-spacing: 0;
+      border-bottom: 2px solid black;
+      border-top: 2px solid black;
+  }
+  table th {
+      padding: 3px 10px;
+      background-color: white;
+      border-top: none;
+      border-left: none;
+      border-right: none;
+      border-bottom: 1px solid black;
+  }
+  table td {
+      padding: 3px 10px;
+      border-top: none;
+      border-left: none;
+      border-bottom: none;
+      border-right: none;
+  }
+  code {
+      background-color: lightgrey;
+  }
+  </style>
 </head>
 <body>
 <h1 id="artifacts-for-continuous-model-validation-using-reference-attribute-grammars">Artifacts for &quot;Continuous Model Validation Using Reference Attribute Grammars&quot;</h1>
-<p><em>Note: please use the HTML version of this README.</em></p>
+<p><em>Note: There is a variant of this submission including a docker image (provided as a link) and one without it (uploaded in HotCRP). We ecourage using the one including the image, since building the image takes a long time.</em></p>
-<p><em>Also Note: There is a variant of this submission including a docker image (provided as a link) and one without it (uploaded in HotCRP). We ecourage using the one including the image, since building the image takes a long time.</em></p>
 <h3 id="authors">Authors</h3>
 <ul>
 <li>Johannes Mey <a href="mailto:johannes.mey@tu-dresden.de">johannes.mey@tu-dresden.de</a></li>
@@ -66,11 +90,15 @@
 </tr>
 </tbody>
 </table>
-<h2 id="the-grammar-extension-preprocessor-relast">The Grammar Extension Preprocessor <code>RelAst</code></h2>
+<h2 id="the-grammar-extension-preprocessor-relast">The Grammar Extension Preprocessor <em>RelAst</em></h2>
 <p>To transform the grammar extension we provide a preprocessor for JastAdd. This preprocessor including its source code is provided in the <code>preprocessor</code> subdirectory.</p>
-<p>Its usage is: - Run preprocessor on train benchmark (output written to standard output):<br />
+<p>Its usage is:</p>
- <code>cat examples/TrainBenchmark.relast</code> - <code>java -jar relast-compiler.jar examples/TrainBenchmark.relast</code></p>
 <ul>
+<li>Run preprocessor on train benchmark (output written to standard output):
+<ul>
+<li><code>cat examples/TrainBenchmark.relast</code></li>
+<li><code>java -jar relast-compiler.jar examples/TrainBenchmark.relast</code></li>
+</ul></li>
 <li>Run preprocessor and write output to files:
 <ul>
 <li><code>java -jar relast-compiler.jar examples/TrainBenchmark.relast --file</code></li>
@@ -135,19 +163,18 @@
 <li><a href="trainbenchmark/trainbenchmark-tool-jastadd-base">Common JastAdd Code</a></li>
 </ul>
 <h3 id="reproducing-the-measurements">Reproducing the Measurements</h3>
-<p><strong>Please Note: Reproducing the graphs as presented in the paper and supplied here takes a very long time depending on the utilized hardware. It is strongly suggested to run the benchmark with a smaller maximum problem size, less repetitions, and a shorter timeout.</strong> Most results of the benchmark are observable with more restricted setup as well. In the following, we will provide a suggested way to run the benchmark in different sizes. Note that running the benchmark requires a significant amount of disk space (up to 10GB when running the full benchmark).</p>
+<p><strong><span style="color:red">Please Note: Reproducing the graphs as presented in the paper and supplied here takes a very long time depending on the utilized hardware. It is strongly suggested to run the benchmark with a smaller maximum problem size, less repetitions, and a shorter timeout.</span></strong> Most results of the benchmark are observable with more restricted setup as well. In the following, we will provide a suggested way to run the benchmark in different sizes. Note that running the benchmark requires a significant amount of disk space (up to 10GB when running the full benchmark).</p>
 <p>To reproduce the measurements, there are several options. We provide a prepared Docker image that can be run directly. Alternatively, it is, on course, also possible to simply run the provided gradle build scripts. However, since there are some software requirements imposed by the benchmark, particularly for creating the diagrams using R. We stronly suggest running the Docker variant.</p>
 <h4 id="running-the-benchmark-with-docker">Running the Benchmark with Docker</h4>
 <h5 id="loading-the-docker-image">Loading the Docker Image</h5>
 <ul>
-<li>Variant 1 (recommended): Load the provided docker image
+<li>Variant 1 (<em>recommended</em>): Load the provided docker image
 <ul>
 <li>Prerequisites: An installation of Docker in the <code>PATH</code></li>
 <li>Steps:
 <ul>
 <li>Unpack the provided archive and open a terminal in the extracted directory</li>
 <li><code>docker load --input trainbenchmark-docker.tar</code></li>
-<li><code>docker run -it trainbenchmark</code></li>
 </ul></li>
 </ul></li>
 <li>Variant 2: Build the docker image from the provided Dockerfile
@@ -162,21 +189,54 @@
 </ul>
 <h5 id="running-the-docker-image">Running the Docker Image</h5>
 <ul>
-<li><code>docker run -it trainbenchmark</code>
+<li><code>docker run -it -v &quot;$PWD&quot;/docker-results:/trainbenchmark/results:Z -v &quot;$PWD&quot;/docker-diagrams:/trainbenchmark/diagrams:Z trainbenchmark</code></li>
-<ul>
+<li>This makes the results and diagrams available outside the container in the directories <code>docker-results</code> and <code>docker-diagrams</code> respectively</li>
-<li>To make the results available outside the container, run <code>docker run -it -v &quot;$PWD&quot;/docker-results:/trainbenchmark/results:Z -v &quot;$PWD&quot;/docker-diagrams:/trainbenchmark/diagrams:Z trainbenchmark</code></li>
+<li>Once running, a command prompt is opened and some information is displayed</li>
-</ul></li>
-<li>A command prompt is opened and some information is displayed</li>
 <li>Follow the instructions below</li>
 </ul>
 <h4 id="running-the-benchmark-directly">Running the Benchmark directly</h4>
 <ul>
-<li>For running a standard run,
+<li>For running a standard run, use one of the following commands:</li>
+</ul>
+<table>
+<thead>
+<tr class="header">
+<th>Name</th>
+<th>Command</th>
+<th>Minimum size</th>
+<th>Maximum size</th>
+<th>Timeout</th>
+<th>Runs</th>
+</tr>
+</thead>
+<tbody>
+<tr class="odd">
+<td>Small</td>
+<td><code>./run_small</code></td>
+<td>1</td>
+<td>32</td>
+<td>60s</td>
+<td>1</td>
+</tr>
+<tr class="even">
+<td>Medium</td>
+<td><code>./run_medium</code></td>
+<td>1</td>
+<td>64</td>
+<td>10min</td>
+<td>5</td>
+</tr>
+<tr class="odd">
+<td>Full</td>
+<td><code>./run_full</code></td>
+<td>1</td>
+<td>512</td>
+<td>15min</td>
+<td>10</td>
+</tr>
+</tbody>
+</table>
 <ul>
-<li><code>./run_small</code></li>
-<li><code>./run_medium</code></li>
-<li><code>./run_full</code></li>
-</ul></li>
 <li>For running a custom run,
 <ul>
 <li>run <code>./gradlew preprocess</code> to generate the grammar from the extended grammar specification</li>
@@ -184,7 +244,7 @@
 <li>run <code>./gradlew initScripts</code></li>
 <li>configure the scripts by running <code>./scripts/configure.sh 1 &lt;MAXSIZE&gt; &lt;TIMEOUT in s&gt; &lt;REPETITIONS&gt;</code>
 <ul>
-<li>Where MAXSIZE is one of 2,4,8,16,32,64,128,256,512,1024. The larger sizes use <strong>a lot of</strong> disk space!</li>
+<li>Where MAXSIZE is one of 2, 4, 8, 16, 32, 64, 128, 256, 512, or, 1024. The larger sizes use <strong>a lot of</strong> disk space!</li>
 </ul></li>
 <li>run <code>./gradlew initScripts</code></li>
 <li>run <code>./gradlew generate</code></li>

--- a/README.md
+++ b/README.md
 # Artifacts for "Continuous Model Validation Using Reference Attribute Grammars"
 *Note: please use the HTML version of this README.*
-*Also Note: There is a variant of this submission including a docker image (provided as a link) and one without it (uploaded in HotCRP). We ecourage using the one including the image, since building the image takes a long time.*
+*Also Note: There is a variant of this submission including a docker image (provided as a link) and one without it (uploaded in HotCRP). We encourage using the one including the image, since building the image takes a long time.*
 ### Authors
@@ -50,12 +49,13 @@ The following table shows the relation of the terminology used in the paper and
 | Grammar Extension     | Jastadd (Specialized)       | jastadd-specialized        |
 +-----------------------+-----------------------------+----------------------------+
-## The Grammar Extension Preprocessor `RelAst`
+## The Grammar Extension Preprocessor *RelAst*
 To transform the grammar extension we provide a preprocessor for JastAdd.
 This preprocessor including its source code is provided in the `preprocessor` subdirectory.
 Its usage is:
 - Run preprocessor on train benchmark (output written to standard output):  
    - `cat examples/TrainBenchmark.relast`
    - `java -jar relast-compiler.jar examples/TrainBenchmark.relast`
@@ -120,10 +120,10 @@ The benchmark is structured in modules, some of which form the code of the bench
 There are some naming conventions:
 - Tool-related modules are in directories starting with `trainbenchmark-tool`.
 - Model serialization-related modules start with `trainbenchmark-generator`.
- All other modules are core modules of the bechmark.
+- All other modules are core modules of the benchmark.
 The JastAdd-based solutions use a preprocessor to generate Java files, for the presented variant.
-Each JastAdd configuraration must be presented to the benchmark as a separate tool. Thus there are two directories for each variant, one for the batch processing mode and one for the incremental mode.
+Each JastAdd configuration must be presented to the benchmark as a separate tool. Thus, there are two directories for each variant, one for the batch processing mode and one for the incremental mode.
 Because these two modes share almost all the source code, a third directory is used to store this shared code.
 Finally, there is a directory for code shared between all JastAdd variants.
 These are the important directories:
@@ -144,17 +144,17 @@ These are the important directories:
 ### Reproducing the Measurements
-**Please Note: Reproducing the graphs as presented in the paper and supplied here takes a very long time depending on the utilized hardware. It is strongly suggested to run the benchmark with a smaller maximum problem size, less repetitions, and a shorter timeout.** Most results of the benchmark are observable with more restricted setup as well. In the following, we will provide a suggested way to run the benchmark in different sizes. Note that running the benchmark requires a significant amount of disk space (up to 10GB when running the full benchmark).
+**<span style="color:red">Please Note: Reproducing the graphs as presented in the paper and supplied here takes a very long time depending on the utilized hardware. It is strongly suggested running the benchmark with a smaller maximum problem size, fewer repetitions, and a shorter timeout.</span>** Most results of the benchmark are observable with more restricted setup as well. In the following, we will provide a suggested way to run the benchmark in different sizes. Note that running the benchmark requires a significant amount of disk space (up to 10GB when running the full benchmark).
 To reproduce the measurements, there are several options. We provide a prepared Docker image that can be run directly.
 Alternatively, it is, on course, also possible to simply run the provided gradle build scripts.
-However, since there are some software requirements imposed by the benchmark, particularly for creating the diagrams using R. We stronly suggest running the Docker variant.
+However, since there are some software requirements imposed by the benchmark, particularly for creating the diagrams using R. We strongly suggest running the Docker variant.
 #### Running the Benchmark with Docker
 ##### Loading the Docker Image
- Variant 1 (recommended): Load the provided docker image
+- Variant 1 (*recommended*): Load the provided docker image
    - Prerequisites: An installation of Docker in the `PATH`
    - Steps:
        - Unpack the provided archive and open a terminal in the extracted directory
@@ -167,23 +167,27 @@ However, since there are some software requirements imposed by the benchmark, pa
 ##### Running the Docker Image
- `docker run -it trainbenchmark`
+- `docker run -it -v "$PWD"/ :/trainbenchmark/results:Z -v "$PWD"/docker-diagrams:/trainbenchmark/diagrams:Z trainbenchmark`
-    - To make the results available outside the container, run `docker run -it -v "$PWD"/docker-results:/trainbenchmark/results:Z -v "$PWD"/docker-diagrams:/trainbenchmark/diagrams:Z trainbenchmark`
+- This makes the results and diagrams available outside the container in the directories `docker-results` and `docker-diagrams` respectively
- A command prompt is opened and some information is displayed
+- Once running, a command prompt is opened and some information is displayed
 - Follow the instructions below
 #### Running the Benchmark directly
- For running a standard run,
+- For running a standard run, use one of the following commands:
-    - `./run_small`
-    - `./run_medium`
+| Name   | Command        | Minimum size | Maximum size | Timeout | Runs |
-    - `./run_full`
+| ------ | -------------- | ------------ | ------------ | ------- | ---- |
+| Small  | `./run_small`  | 1            | 32           | 60s     | 1    |
+| Medium | `./run_medium` | 1            | 64           | 10min   | 5    |
+| Full   | `./run_full`   | 1            | 512          | 15min   | 10   |
 - For running a custom run,
    - run `./gradlew preprocess` to generate the grammar from the extended grammar specification
    - run `./gradlew build shadowJar -x test`
    - run `./gradlew initScripts`
    - configure the scripts by running `./scripts/configure.sh 1 <MAXSIZE> <TIMEOUT in s> <REPETITIONS>`
-        - Where MAXSIZE is one of 2,4,8,16,32,64,128,256,512,1024. The larger sizes use **a lot of** disk space!
+        - Where MAXSIZE is one of 2, 4, 8, 16, 32, 64, 128, 256, 512, or, 1024. The larger sizes use **a lot of** disk space!
    - run `./gradlew initScripts`
    - run `./gradlew generate`
    - run the benchmark

--- a/README.txt
+++ b/README.txt
 # Artifacts for "Continuous Model Validation Using Reference Attribute Grammars"
 *Note: please use the HTML version of this README.*
 *Also Note: There is a variant of this submission including a docker image (provided as a link) and one without it (uploaded in HotCRP). We ecourage using the one including the image, since building the image takes a long time.*
@@ -50,12 +49,13 @@ The following table shows the relation of the terminology used in the paper and
 | Grammar Extension     | Jastadd (Specialized)       | jastadd-specialized        |
 +-----------------------+-----------------------------+----------------------------+
-## The Grammar Extension Preprocessor `RelAst`
+## The Grammar Extension Preprocessor *RelAst*
 To transform the grammar extension we provide a preprocessor for JastAdd.
 This preprocessor including its source code is provided in the `preprocessor` subdirectory.
 Its usage is:
 - Run preprocessor on train benchmark (output written to standard output):  
    - `cat examples/TrainBenchmark.relast`
    - `java -jar relast-compiler.jar examples/TrainBenchmark.relast`
@@ -144,7 +144,7 @@ These are the important directories:
 ### Reproducing the Measurements
-**Please Note: Reproducing the graphs as presented in the paper and supplied here takes a very long time depending on the utilized hardware. It is strongly suggested to run the benchmark with a smaller maximum problem size, less repetitions, and a shorter timeout.** Most results of the benchmark are observable with more restricted setup as well. In the following, we will provide a suggested way to run the benchmark in different sizes. Note that running the benchmark requires a significant amount of disk space (up to 10GB when running the full benchmark).
+**<span style="color:red">Please Note: Reproducing the graphs as presented in the paper and supplied here takes a very long time depending on the utilized hardware. It is strongly suggested to run the benchmark with a smaller maximum problem size, less repetitions, and a shorter timeout.</span>** Most results of the benchmark are observable with more restricted setup as well. In the following, we will provide a suggested way to run the benchmark in different sizes. Note that running the benchmark requires a significant amount of disk space (up to 10GB when running the full benchmark).
 To reproduce the measurements, there are several options. We provide a prepared Docker image that can be run directly.
 Alternatively, it is, on course, also possible to simply run the provided gradle build scripts.
@@ -154,12 +154,11 @@ However, since there are some software requirements imposed by the benchmark, pa
 ##### Loading the Docker Image
- Variant 1 (recommended): Load the provided docker image
+- Variant 1 (*recommended*): Load the provided docker image
    - Prerequisites: An installation of Docker in the `PATH`
    - Steps:
        - Unpack the provided archive and open a terminal in the extracted directory
        - `docker load --input trainbenchmark-docker.tar`
-        - `docker run -it trainbenchmark`
 - Variant 2: Build the docker image from the provided Dockerfile
    - Prerequisites: An installation of Docker in the `PATH`
    - Steps:
@@ -168,23 +167,27 @@ However, since there are some software requirements imposed by the benchmark, pa
 ##### Running the Docker Image
- `docker run -it trainbenchmark`
+- `docker run -it -v "$PWD"/docker-results:/trainbenchmark/results:Z -v "$PWD"/docker-diagrams:/trainbenchmark/diagrams:Z trainbenchmark`
-    - To make the results available outside the container, run `docker run -it -v "$PWD"/docker-results:/trainbenchmark/results:Z -v "$PWD"/docker-diagrams:/trainbenchmark/diagrams:Z trainbenchmark`
+- This makes the results and diagrams available outside the container in the directories `docker-results` and `docker-diagrams` respectively
- A command prompt is opened and some information is displayed
+- Once running, a command prompt is opened and some information is displayed
 - Follow the instructions below
 #### Running the Benchmark directly
- For running a standard run,
+- For running a standard run, use one of the following commands:
-    - `./run_small`
-    - `./run_medium`
+| Name   | Command        | Minimum size | Maximum size | Timeout | Runs |
-    - `./run_full`
+| ------ | -------------- | ------------ | ------------ | ------- | ---- |
+| Small  | `./run_small`  | 1            | 32           | 60s     | 1    |
+| Medium | `./run_medium` | 1            | 64           | 10min   | 5    |
+| Full   | `./run_full`   | 1            | 512          | 15min   | 10   |
 - For running a custom run,
    - run `./gradlew preprocess` to generate the grammar from the extended grammar specification
    - run `./gradlew build shadowJar -x test`
    - run `./gradlew initScripts`
    - configure the scripts by running `./scripts/configure.sh 1 <MAXSIZE> <TIMEOUT in s> <REPETITIONS>`
-        - Where MAXSIZE is one of 2,4,8,16,32,64,128,256,512,1024. The larger sizes use **a lot of** disk space!
+        - Where MAXSIZE is one of 2, 4, 8, 16, 32, 64, 128, 256, 512, or, 1024. The larger sizes use **a lot of** disk space!
    - run `./gradlew initScripts`
    - run `./gradlew generate`
    - run the benchmark

--- a/make_readme.sh
+++ b/make_readme.sh
+cp README.md README.txt
+pandoc "README.md" -s -H style.css -t html -o README.html
+sed -i -e '/Note: please/d' -e 's/Also Note/Note/' README.html
--- a/style.css
+++ b/style.css
+<style type="text/css">
+table {
+    border-spacing: 0;
+    border-bottom: 2px solid black;
+    border-top: 2px solid black;
+}
+table th {
+    padding: 3px 10px;
+    background-color: white;
+    border-top: none;
+    border-left: none;
+    border-right: none;
+    border-bottom: 1px solid black;
+}
+table td {
+    padding: 3px 10px;
+    border-top: none;
+    border-left: none;
+    border-bottom: none;
+    border-right: none;
+}
+code {
+    background-color: lightgrey;
+}
+</style>