Refactorings and updates.

1 files changed, 81 insertions, 28 deletions

diff --git a/doc/bmc.html b/doc/bmc.html
index 87e499d..744e140 100644
--- a/doc/bmc.html
+++ b/doc/bmc.html
@@ -19,20 +19,30 @@ td {vertical-align:top; padding:5px}
 <h3>Overview</h3>
 The BMC client program (<code>bmc</code>) is a program that communicates with
 a BMC server via the BMC protocol (described elsewhere). The program accepts
-input via command-line arguments and/or environment variables, and writes any
-successful output and/or any error/debug messages to standard output and
-standard error respectively.
+input via command-line arguments, environment variables, or standard input.
+The program writes output (if any) to standard output or standard error.
 
-<h3>Help</h3>
-Running the program without options (or passing the <code>-help</code> option)
-prints out a summary of the different options:
+<h3>Modes</h3>
+If the program is run without any command-line arguments it is run in <i>CGI
+mode</i>. In this case, the program is assumed to be launched by a web server
+in response to a request from a web client. Arguments are extracted from the
+environment and output is written to standard output in a format suitable for
+being sent back to and processed by the web client.
+
+<p />
+If command-line arguments are present the program is run in <i>raw mode</i>.
+
+<h3>Help (raw mode only)</h3>
+In raw mode, passing <code>help</code> to the program prints out a usage summary:
 
 <pre>
-    ./bmc
+    ./bmc help
 </pre>
 
 <h3>Server Location</h3>
-The server location may be specified either by passing the
+
+<h4>Raw mode</h4>
+In raw mode, the server location may be specified either by passing the
 <code>-server</code> option, e.g.:
 <pre>
     ./bmc -server localhost:1104 ...
@@ -43,20 +53,30 @@ or via the <code>BMCSERVER</code> environment variable, e.g.:
     ./bmc ...
 </pre>
 
+<h4>CGI mode</h4>
+<span style="color:red">2 B DONE</span>
+
 <h3>Commands</h3>
 
+<b>Note:</b> The 'Command' column in the table below shows the raw mode
+command line syntax. In CGI mode the initial arguments (passed in environment
+variables) are converted internally to a format that is equivalent to the raw
+mode command line.
+<br /><br />
+
 <table border=1>
 <tr>
     <th>Command</th>
     <th>Description</th>
-    <th>Standard output</th>
+    <th>Standard output (raw mode)</th>
+    <th>Standard output (CGI mode)</th>
 </tr>
 
 <!-- ---------------------------------------------------------------------------------- -->
 <tr>
 <td>
 <pre class="command">
-./bmc add -results &lt;file&gt; \
+./bmc add results &lt;file&gt; \
     &lt;platform&gt; &lt;host&gt; \
     &lt;git repo&gt; [&lt;git dir&gt;]
 </pre>
@@ -66,17 +86,43 @@ Adds new results to the database.
 <br /><br />
 The file is assumed to have the same XML structure as the one produced by
 QTestLib.
+<br /><br />
+The git directory must be accessible from the local file system and the git
+command needs to be installed (i.e. the program needs to run the git command
+from the git directory). By default, the git directory is the current
+directory.
+<br /><br />
+The new results are assumed to have been generated using a product built from
+a clean checkout of the current head commit of the current git branch in the
+git directory.
+<br /><br />
+The sha1 to be stored in the database is assumed to be the current head commit
+in the git directory (extracted running <span class="command"> git log -1 HEAD
+--pretty=format:"%H"</span> or equivalent).
+<br /><br />
+The timestamp to be stored in the database is the Unix timestamp of the
+committer date (extracted running <span class="command">git log -1 HEAD
+--pretty=format:"%ct"</span> or equivalent).
+<br /><br />
+The git repository must be passed explicitly since it cannot in general be
+derived from the git directory (e.g. in the case of a local, standalone
+repository).
 </td>
+
 <td><i>none</i></td>
+
+<td><span style="color:red">2 B DONE</span></td>
+
 </tr>
 
 <!-- ---------------------------------------------------------------------------------- -->
 <tr>
 <td>
 <pre class="command">
-./bmc list -snapshots \
+./bmc list snapshots \
     &lt;test case&gt; &lt;test function&gt; \
-    &lt;data tag&gt; &lt;metric&gt; &lt;host&gt; \
+    &lt;data tag&gt; &lt;metric&gt; \
+    &lt;platform&gt; &lt;host&gt; \
     &lt;git repo&gt; &lt;git branch&gt;
 </pre>
 </td>
@@ -92,13 +138,14 @@ Lists snapshots available for a particular context.
 ...
 </pre>
 </td>
+<td><span style="color:red">2 B DONE</span></td>
 </tr>
 
 <!-- ---------------------------------------------------------------------------------- -->
 <tr>
 <td>
 <pre class="command">
-./bmc list -benchmarks \
+./bmc list benchmarks \
     [-metric &lt;metric&gt;] \
     [-platform &lt;platform&gt;] \
     [-host &lt;host&gt;] \
@@ -129,13 +176,14 @@ exists in combination with those values.
 ...
 </pre>
 </td>
+<td><span style="color:red">2 B DONE</span></td>
 </tr>
 
 <!-- ---------------------------------------------------------------------------------- -->
 <tr>
 <td>
 <pre class="command">
-./bmc list -metrics \
+./bmc list metrics \
     [-benchmark &lt;test case&gt; \
         &lt;test function&gt; &lt;data tag&gt;] \
     [-platform &lt;platform&gt;] \
@@ -145,7 +193,7 @@ exists in combination with those values.
 </td>
 <td class="commandDescr">
 Lists available metrics.
-Behaves similarly to <span class="command">./bmc list -benchmarks ...</span> (see this).
+Behaves similarly to <span class="command">./bmc list benchmarks ...</span> (see this).
 </td>
 <td>
 <pre>
@@ -154,13 +202,14 @@ Behaves similarly to <span class="command">./bmc list -benchmarks ...</span> (se
 ...
 </pre>
 </td>
+<td><span style="color:red">2 B DONE</span></td>
 </tr>
 
 <!-- ---------------------------------------------------------------------------------- -->
 <tr>
 <td>
 <pre class="command">
-./bmc list -platforms \
+./bmc list platforms \
     [-benchmark &lt;test case&gt; \
         &lt;test function&gt; &lt;data tag&gt;] \
     [-metric &lt;metric&gt;] \
@@ -170,7 +219,7 @@ Behaves similarly to <span class="command">./bmc list -benchmarks ...</span> (se
 </td>
 <td class="commandDescr">
 Lists available platforms.
-Behaves similarly to <span class="command">./bmc list -benchmarks ...</span> (see this).
+Behaves similarly to <span class="command">./bmc list benchmarks ...</span> (see this).
 </td>
 <td>
 <pre>
@@ -179,13 +228,14 @@ Behaves similarly to <span class="command">./bmc list -benchmarks ...</span> (se
 ...
 </pre>
 </td>
+<td><span style="color:red">2 B DONE</span></td>
 </tr>
 
 <!-- ---------------------------------------------------------------------------------- -->
 <tr>
 <td>
 <pre class="command">
-./bmc list -hosts \
+./bmc list hosts \
     [-benchmark &lt;test case&gt; \
         &lt;test function&gt; &lt;data tag&gt;] \
     [-metric &lt;metric&gt;] \
@@ -195,7 +245,7 @@ Behaves similarly to <span class="command">./bmc list -benchmarks ...</span> (se
 </td>
 <td class="commandDescr">
 Lists available hosts.
-Behaves similarly to <span class="command">./bmc list -benchmarks ...</span> (see this).
+Behaves similarly to <span class="command">./bmc list benchmarks ...</span> (see this).
 </td>
 <td>
 <pre>
@@ -204,13 +254,14 @@ Behaves similarly to <span class="command">./bmc list -benchmarks ...</span> (se
 ...
 </pre>
 </td>
+<td><span style="color:red">2 B DONE</span></td>
 </tr>
 
 <!-- ---------------------------------------------------------------------------------- -->
 <tr>
 <td>
 <pre class="command">
-./bmc list -branches \
+./bmc list branches \
     [-benchmark &lt;test case&gt; \
         &lt;test function&gt; &lt;data tag&gt;] \
     [-metric &lt;metric&gt;] \
@@ -220,7 +271,7 @@ Behaves similarly to <span class="command">./bmc list -benchmarks ...</span> (se
 </td>
 <td class="commandDescr">
 Lists available branches.
-Behaves similarly to <span class="command">./bmc list -benchmarks ...</span> (see this).
+Behaves similarly to <span class="command">./bmc list benchmarks ...</span> (see this).
 </td>
 <td>
 <pre>
@@ -231,13 +282,14 @@ Behaves similarly to <span class="command">./bmc list -benchmarks ...</span> (se
 ...
 </pre>
 </td>
+<td><span style="color:red">2 B DONE</span></td>
 </tr>
 
 <!-- ---------------------------------------------------------------------------------- -->
 <tr>
 <td>
 <pre class="command">
-./bmc compare -history &lt;test case&gt; \
+./bmc compare history &lt;test case&gt; \
     &lt;test function&gt; &lt;data tag&gt; \
     &lt;metric&gt; &lt;platform&gt; &lt;host&gt; \
     &lt;git repo&gt; &lt;git branch&gt; \
@@ -270,13 +322,14 @@ exact value must exist.
 ...
 </pre>
 </td>
+<td><span style="color:red">2 B DONE</span></td>
 </tr>
 
 <!-- ---------------------------------------------------------------------------------- -->
 <tr>
 <td>
 <pre class="command">
-./bmc compare -branches &lt;test case&gt; \
+./bmc compare branches &lt;test case&gt; \
     &lt;test function&gt; &lt;data tag&gt; \
     &lt;metric&gt; &lt;platform&gt; &lt;host&gt; \
     &lt;git repo 1&gt; &lt;git branch 1&gt; \
@@ -292,7 +345,7 @@ Compares the results of two branches.
 <br /><br />
 The <span class="command">-timestamp</span> and <span
 class="command">-sha1</span> options behaves as for <span
-class="command">./bmc compare -history ...</span> (see this).
+class="command">./bmc compare history ...</span> (see this).
 </td>
 <td>
 <pre>
@@ -306,13 +359,14 @@ class="command">./bmc compare -history ...</span> (see this).
 &lt;iterations 2&gt;
 </pre>
 </td>
+<td><span style="color:red">2 B DONE</span></td>
 </tr>
 
 <!-- ---------------------------------------------------------------------------------- -->
 <tr>
 <td>
 <pre class="command">
-./bmc compare -direct &lt;test case&gt; \
+./bmc compare direct &lt;test case&gt; \
     &lt;test function&gt; &lt;data tag&gt; \
     &lt;metric&gt; &lt;platform&gt; &lt;host&gt; \
     &lt;git repo&gt; &lt;git branch&gt; \
@@ -332,7 +386,7 @@ combination.
 <br /><br />
 The <span class="command">-timestamp</span> and <span
 class="command">-sha1</span> options behaves as for <span
-class="command">./bmc compare -history ...</span> (see this).
+class="command">./bmc compare history ...</span> (see this).
 </td>
 <td>
 <pre>
@@ -344,10 +398,9 @@ class="command">./bmc compare -history ...</span> (see this).
 &lt;iterations (explicit)&gt;
 </pre>
 </td>
+<td><span style="color:red">2 B DONE</span></td>
 </tr>
 
-
-
 </table>
 
 </body>