Updates.

2 files changed, 214 insertions, 83 deletions

diff --git a/doc/bmcp.html b/doc/bmcp.html
index 6ab449f..d70ef77 100644
--- a/doc/bmcp.html
+++ b/doc/bmcp.html
@@ -38,6 +38,23 @@ multiple byte integers are in big endian order (most significant byte first).
 The following structured types typically occur in several places and will be
 referred to only by their names for brevity:
 
+<!-- --------------------------------- -->
+<hr />
+<p class="alias">BENCHMARK</p>
+
+<table border=0>
+<thead><tr><th>No. of bytes</th><th>Type</th><th>Description</th></tr></thead>
+
+<tr><td>4</td><td>U32</td><td>test case size</td></tr>
+<tr><td>test case size</td><td>U8 array</td><td>test case</td></tr>
+
+<tr><td>4</td><td>U32</td><td>test function size</td></tr>
+<tr><td>test function size</td><td>U8 array</td><td>test function</td></tr>
+
+<tr><td>4</td><td>U32</td><td>data tag size</td></tr>
+<tr><td>data tag size</td><td>U8 array</td><td>data tag</td></tr>
+
+</table>
 
 <!-- --------------------------------- -->
 <hr />
@@ -68,24 +85,6 @@ referred to only by their names for brevity:
 
 <!-- --------------------------------- -->
 <hr />
-<p class="alias">BENCHMARK</p>
-
-<table border=0>
-<thead><tr><th>No. of bytes</th><th>Type</th><th>Description</th></tr></thead>
-
-<tr><td>4</td><td>U32</td><td>test case size</td></tr>
-<tr><td>test case size</td><td>U8 array</td><td>test case</td></tr>
-
-<tr><td>4</td><td>U32</td><td>test function size</td></tr>
-<tr><td>test function size</td><td>U8 array</td><td>test function</td></tr>
-
-<tr><td>4</td><td>U32</td><td>data tag size</td></tr>
-<tr><td>data tag size</td><td>U8 array</td><td>data tag</td></tr>
-
-</table>
-
-<!-- --------------------------------- -->
-<hr />
 <p class="alias">BMCONTEXT</p>
 <table border=0>
 <thead><tr><th>No. of bytes</th><th>Type</th><th>Description</th></tr></thead>
@@ -238,6 +237,161 @@ being generated.
 <hr />
 
 <p class="msgDescr">
+This request adds a new benchmark to the database.
+</p>
+
+<h4 class="msgName">AddBenchmarkRequest</h4>
+<table border=0>
+<thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
+<tr><td>1</td><td>U8</td><td>2</td><td>message type</td></tr>
+<tr><td>BENCHMARK size</td><td class="alias">BENCHMARK</td><td></td><td></td></tr>
+</table>
+
+<h4 class="msgName">AddBenchmarkReply</h4>
+<table border=0>
+<thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
+<tr><td>1</td><td>U8</td><td>3</td><td>message type</td></tr>
+</table>
+
+<p class="msgDescr">
+<b>Note</b>: In this case the reply message serves as a silent acknowledgement only.
+</p>
+
+
+<!-- ---------------------------------------------------------------------------------- -->
+<hr />
+
+<p class="msgDescr">
+This request adds a new metric to the database.
+</p>
+
+<h4 class="msgName">AddMetricRequest</h4>
+<table border=0>
+<thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
+<tr><td>1</td><td>U8</td><td>4</td><td>message type</td></tr>
+<tr><td>METRIC size</td><td class="alias">METRIC</td><td></td><td></td></tr>
+</table>
+
+<h4 class="msgName">AddMetricReply</h4>
+<table border=0>
+<thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
+<tr><td>1</td><td>U8</td><td>5</td><td>message type</td></tr>
+</table>
+
+<p class="msgDescr">
+<b>Note</b>: In this case the reply message serves as a silent acknowledgement only.
+</p>
+
+
+<!-- ---------------------------------------------------------------------------------- -->
+<hr />
+
+<p class="msgDescr">
+This request adds a new platform to the database.
+</p>
+
+<h4 class="msgName">AddPlatformRequest</h4>
+<table border=0>
+<thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
+<tr><td>1</td><td>U8</td><td>6</td><td>message type</td></tr>
+<tr><td>PLATFORM size</td><td class="alias">PLATFORM</td><td></td><td></td></tr>
+</table>
+
+<h4 class="msgName">AddPlatformReply</h4>
+<table border=0>
+<thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
+<tr><td>1</td><td>U8</td><td>7</td><td>message type</td></tr>
+</table>
+
+<p class="msgDescr">
+<b>Note</b>: In this case the reply message serves as a silent acknowledgement only.
+</p>
+
+
+<!-- ---------------------------------------------------------------------------------- -->
+<hr />
+
+<p class="msgDescr">
+This request adds a new host to the database.
+</p>
+
+<h4 class="msgName">AddHostRequest</h4>
+<table border=0>
+<thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
+<tr><td>1</td><td>U8</td><td>8</td><td>message type</td></tr>
+<tr><td>HOST size</td><td class="alias">HOST</td><td></td><td></td></tr>
+</table>
+
+<h4 class="msgName">AddHostReply</h4>
+<table border=0>
+<thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
+<tr><td>1</td><td>U8</td><td>9</td><td>message type</td></tr>
+</table>
+
+<p class="msgDescr">
+<b>Note</b>: In this case the reply message serves as a silent acknowledgement only.
+</p>
+
+
+<!-- ---------------------------------------------------------------------------------- -->
+<hr />
+
+<p class="msgDescr">
+This request adds a new branch to the database.
+</p>
+
+<h4 class="msgName">AddBranchRequest</h4>
+<table border=0>
+<thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
+<tr><td>1</td><td>U8</td><td>10</td><td>message type</td></tr>
+<tr><td>BRANCH size</td><td class="alias">BRANCH</td><td></td><td></td></tr>
+</table>
+
+<h4 class="msgName">AddBranchReply</h4>
+<table border=0>
+<thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
+<tr><td>1</td><td>U8</td><td>11</td><td>message type</td></tr>
+</table>
+
+<p class="msgDescr">
+<b>Note</b>: In this case the reply message serves as a silent acknowledgement only.
+</p>
+
+
+<!-- ---------------------------------------------------------------------------------- -->
+<hr />
+
+<p class="msgDescr">
+This request adds new results to the database.
+</p>
+
+<h4 class="msgName">AddResultsRequest</h4>
+<table border=0>
+<thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
+<tr><td>1</td><td>U8</td><td>12</td><td>message type</td></tr>
+<tr><td>PLATFORM size</td><td class="alias">PLATFORM</td><td></td><td></td></tr>
+<tr><td>HOST size</td><td class="alias">HOST</td><td></td><td></td></tr>
+<tr><td>BRANCH size</td><td class="alias">BRANCH</td><td></td><td></td></tr>
+<tr><td>SNAPSHOT size</td><td class="alias">SNAPSHOT</td><td></td><td></td></tr>
+<tr><td>TESTCASERESULTS size</td><td
+class="alias">TESTCASERESULTS</td><td></td><td></td></tr>
+</table>
+
+<h4 class="msgName">AddResultsReply</h4>
+<table border=0>
+<thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
+<tr><td>1</td><td>U8</td><td>13</td><td>message type</td></tr>
+</table>
+
+<p class="msgDescr">
+<b>Note</b>: In this case the reply message serves as a silent acknowledgement only.
+</p>
+
+
+<!-- ---------------------------------------------------------------------------------- -->
+<hr />
+
+<p class="msgDescr">
 This request compares results of a particular BMCONTEXT/BRANCH combination
 since a particular SNAPSHOT.
 </p>
@@ -245,7 +399,7 @@ since a particular SNAPSHOT.
 <h4 class="msgName">CompareHistoryRequest</h4>
 <table border=0>
 <thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
-<tr><td>1</td><td>U8</td><td>2</td><td>message type</td></tr>
+<tr><td>1</td><td>U8</td><td>14</td><td>message type</td></tr>
 <tr><td>BMCONTEXT size</td><td class="alias">BMCONTEXT</td><td></td><td></td></tr>
 <tr><td>BRANCH size</td><td class="alias">BRANCH</td><td></td><td></td></tr>
 <tr><td>SNAPSHOT size</td><td class="alias">SNAPSHOT</td><td></td><td></td></tr>
@@ -254,7 +408,7 @@ since a particular SNAPSHOT.
 <h4 class="msgName">CompareHistoryReply</h4>
 <table border=0>
 <thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
-<tr><td>1</td><td>U8</td><td>3</td><td>message type</td></tr>
+<tr><td>1</td><td>U8</td><td>15</td><td>message type</td></tr>
 <tr><td>4</td><td>U32</td><td></td><td>history size</td></tr>
 <tr><td>SNAPSHOTRESULT size</td><td
 class="alias">SNAPSHOTRESULT</td><td></td><td>result 1</td></tr>
@@ -274,7 +428,7 @@ This request compares the results of two branches.
 <h4 class="msgName">CompareBranchesRequest</h4>
 <table border=0>
 <thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
-<tr><td>1</td><td>U8</td><td>4</td><td>message type</td></tr>
+<tr><td>1</td><td>U8</td><td>16</td><td>message type</td></tr>
 <tr><td>BMCONTEXT size</td><td class="alias">BMCONTEXT</td><td></td><td></td></tr>
 <tr><td>BRANCH size</td><td
 class="alias">BRANCH</td><td></td><td>branch 1</td></tr>
@@ -289,7 +443,7 @@ class="alias">SNAPSHOT</td><td></td><td>snapshot 2</td></tr>
 <h4 class="msgName">CompareBranchesReply</h4>
 <table border=0>
 <thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
-<tr><td>1</td><td>U8</td><td>5</td><td>message type</td></tr>
+<tr><td>1</td><td>U8</td><td>17</td><td>message type</td></tr>
 <tr><td>SNAPSHOTRESULT size</td><td
 class="alias">SNAPSHOTRESULT</td><td></td><td>result 1</td></tr>
 <tr><td>SNAPSHOTRESULT size</td><td
@@ -307,7 +461,7 @@ This request compares a result in the database to an explicitly given result.
 <h4 class="msgName">CompareDirectRequest</h4>
 <table border=0>
 <thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
-<tr><td>1</td><td>U8</td><td>6</td><td>message type</td></tr>
+<tr><td>1</td><td>U8</td><td>18</td><td>message type</td></tr>
 <tr><td>BMCONTEXT size</td><td class="alias">BMCONTEXT</td><td></td><td></td></tr>
 <tr><td>BRANCH size</td><td class="alias">BRANCH</td><td></td><td></td></tr>
 <tr><td>SNAPSHOT size</td><td class="alias">SNAPSHOT</td><td></td><td></td></tr>
@@ -317,7 +471,7 @@ This request compares a result in the database to an explicitly given result.
 <h4 class="msgName">CompareDirectReply</h4>
 <table border=0>
 <thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
-<tr><td>1</td><td>U8</td><td>7</td><td>message type</td></tr>
+<tr><td>1</td><td>U8</td><td>19</td><td>message type</td></tr>
 <tr><td>SNAPSHOTRESULT size</td><td
 class="alias">SNAPSHOTRESULT</td><td></td><td></td></tr>
 <tr><td>RESULT size</td><td
@@ -330,43 +484,13 @@ request)</td></tr>
 <hr />
 
 <p class="msgDescr">
-This request adds new results to the database.
-</p>
-
-<h4 class="msgName">AddResultsRequest</h4>
-<table border=0>
-<thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
-<tr><td>1</td><td>U8</td><td>8</td><td>message type</td></tr>
-<tr><td>PLATFORM size</td><td class="alias">PLATFORM</td><td></td><td></td></tr>
-<tr><td>HOST size</td><td class="alias">HOST</td><td></td><td></td></tr>
-<tr><td>BRANCH size</td><td class="alias">BRANCH</td><td></td><td></td></tr>
-<tr><td>SNAPSHOT size</td><td class="alias">SNAPSHOT</td><td></td><td></td></tr>
-<tr><td>TESTCASERESULTS size</td><td
-class="alias">TESTCASERESULTS</td><td></td><td></td></tr>
-</table>
-
-<h4 class="msgName">AddResultsReply</h4>
-<table border=0>
-<thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
-<tr><td>1</td><td>U8</td><td>9</td><td>message type</td></tr>
-</table>
-
-<p class="msgDescr">
-<b>Note</b>: In this case the reply message serves as a silent acknowledgement only.
-</p>
-
-
-<!-- ---------------------------------------------------------------------------------- -->
-<hr />
-
-<p class="msgDescr">
 This request lists all snapshots available for a particular BMCONTEXT/BRANCH combination.
 </p>
 
 <h4 class="msgName">ListAvailableSnapshotsRequest</h4>
 <table border=0>
 <thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
-<tr><td>1</td><td>U8</td><td>10</td><td>message type</td></tr>
+<tr><td>1</td><td>U8</td><td>20</td><td>message type</td></tr>
 <tr><td>BMCONTEXT size</td><td class="alias">BMCONTEXT</td><td></td><td></td></tr>
 <tr><td>BRANCH size</td><td class="alias">BRANCH</td><td></td><td></td></tr>
 </table>
@@ -374,7 +498,7 @@ This request lists all snapshots available for a particular BMCONTEXT/BRANCH com
 <h4 class="msgName">ListAvailableSnapshotsReply</h4>
 <table border=0>
 <thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
-<tr><td>1</td><td>U8</td><td>11</td><td>message type</td></tr>
+<tr><td>1</td><td>U8</td><td>21</td><td>message type</td></tr>
 <tr><td>1</td><td>U32</td><td></td><td>n</td></tr>
 <tr><td>SNAPSHOT size</td><td class="alias">SNAPSHOT</td><td></td><td>item 1</td></tr>
 <tr><td>SNAPSHOT size</td><td class="alias">SNAPSHOT</td><td></td><td>item 2</td></tr>
@@ -387,16 +511,18 @@ This request lists all snapshots available for a particular BMCONTEXT/BRANCH com
 <hr />
 
 <p class="msgDescr">
-This request lists benchmarks that occur in combination with zero or more
-other entities (i.e. at least one result exists for this combination of entity
-values). An empty entity value (size = 0) is not part of the combination
-restriction (i.e. any value will match).
+This request lists available benchmarks. One or more additional entity values
+(metric, platform, host, or branch) may be specified as non-empty values to
+restrict the output to only those benchmarks for which at least one result
+exists in combination with that combination of values. If all additional
+entity values are empty, the output will include all available benchmarks,
+even those that haven't been associated with any result yet.
 </p>
 
 <h4 class="msgName">ListAvailableBenchmarksRequest</h4>
 <table border=0>
 <thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
-<tr><td>1</td><td>U8</td><td>12</td><td>message type</td></tr>
+<tr><td>1</td><td>U8</td><td>22</td><td>message type</td></tr>
 <tr><td>METRIC size</td><td class="alias">METRIC</td><td></td><td></td></tr>
 <tr><td>PLATFORM size</td><td class="alias">PLATFORM</td><td></td><td></td></tr>
 <tr><td>HOST size</td><td class="alias">HOST</td><td></td><td></td></tr>
@@ -406,7 +532,7 @@ restriction (i.e. any value will match).
 <h4 class="msgName">ListAvailableBenchmarksReply</h4>
 <table border=0>
 <thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
-<tr><td>1</td><td>U8</td><td>13</td><td>message type</td></tr>
+<tr><td>1</td><td>U8</td><td>23</td><td>message type</td></tr>
 <tr><td>1</td><td>U32</td><td></td><td>n</td></tr>
 <tr><td>BENCHMARK size</td><td class="alias">BENCHMARK</td><td></td><td>item 1</td></tr>
 <tr><td>BENCHMARK size</td><td class="alias">BENCHMARK</td><td></td><td>item 2</td></tr>
@@ -425,7 +551,7 @@ This request behaves similarly to ListAvailableBenchmarks* (see this).
 <h4 class="msgName">ListAvailableMetricsRequest</h4>
 <table border=0>
 <thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
-<tr><td>1</td><td>U8</td><td>14</td><td>message type</td></tr>
+<tr><td>1</td><td>U8</td><td>24</td><td>message type</td></tr>
 <tr><td>BENCHMARK size</td><td class="alias">BENCHMARK</td><td></td><td></td></tr>
 <tr><td>PLATFORM size</td><td class="alias">PLATFORM</td><td></td><td></td></tr>
 <tr><td>HOST size</td><td class="alias">HOST</td><td></td><td></td></tr>
@@ -435,7 +561,7 @@ This request behaves similarly to ListAvailableBenchmarks* (see this).
 <h4 class="msgName">ListAvailableMetricsReply</h4>
 <table border=0>
 <thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
-<tr><td>1</td><td>U8</td><td>15</td><td>message type</td></tr>
+<tr><td>1</td><td>U8</td><td>25</td><td>message type</td></tr>
 <tr><td>1</td><td>U32</td><td></td><td>n</td></tr>
 <tr><td>METRIC size</td><td class="alias">METRIC</td><td></td><td>item 1</td></tr>
 <tr><td>METRIC size</td><td class="alias">METRIC</td><td></td><td>item 2</td></tr>
@@ -454,7 +580,7 @@ This request behaves similarly to ListAvailableBenchmarks* (see this).
 <h4 class="msgName">ListAvailablePlatformsRequest</h4>
 <table border=0>
 <thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
-<tr><td>1</td><td>U8</td><td>16</td><td>message type</td></tr>
+<tr><td>1</td><td>U8</td><td>26</td><td>message type</td></tr>
 <tr><td>BENCHMARK size</td><td class="alias">BENCHMARK</td><td></td><td></td></tr>
 <tr><td>METRIC size</td><td class="alias">METRIC</td><td></td><td></td></tr>
 <tr><td>HOST size</td><td class="alias">HOST</td><td></td><td></td></tr>
@@ -464,7 +590,7 @@ This request behaves similarly to ListAvailableBenchmarks* (see this).
 <h4 class="msgName">ListAvailablePlatformsReply</h4>
 <table border=0>
 <thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
-<tr><td>1</td><td>U8</td><td>17</td><td>message type</td></tr>
+<tr><td>1</td><td>U8</td><td>27</td><td>message type</td></tr>
 <tr><td>1</td><td>U32</td><td></td><td>n</td></tr>
 <tr><td>PLATFORM size</td><td class="alias">PLATFORM</td><td></td><td>item 1</td></tr>
 <tr><td>PLATFORM size</td><td class="alias">PLATFORM</td><td></td><td>item 2</td></tr>
@@ -483,7 +609,7 @@ This request behaves similarly to ListAvailableBenchmarks* (see this).
 <h4 class="msgName">ListAvailableHostsRequest</h4>
 <table border=0>
 <thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
-<tr><td>1</td><td>U8</td><td>18</td><td>message type</td></tr>
+<tr><td>1</td><td>U8</td><td>28</td><td>message type</td></tr>
 <tr><td>BENCHMARK size</td><td class="alias">BENCHMARK</td><td></td><td></td></tr>
 <tr><td>METRIC size</td><td class="alias">METRIC</td><td></td><td></td></tr>
 <tr><td>PLATFORM size</td><td class="alias">PLATFORM</td><td></td><td></td></tr>
@@ -493,7 +619,7 @@ This request behaves similarly to ListAvailableBenchmarks* (see this).
 <h4 class="msgName">ListAvailableHostsReply</h4>
 <table border=0>
 <thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
-<tr><td>1</td><td>U8</td><td>19</td><td>message type</td></tr>
+<tr><td>1</td><td>U8</td><td>29</td><td>message type</td></tr>
 <tr><td>1</td><td>U32</td><td></td><td>n</td></tr>
 <tr><td>HOST size</td><td class="alias">HOST</td><td></td><td>item 1</td></tr>
 <tr><td>HOST size</td><td class="alias">HOST</td><td></td><td>item 2</td></tr>
@@ -512,7 +638,7 @@ This request behaves similarly to ListAvailableBenchmarks* (see this).
 <h4 class="msgName">ListAvailableBranchesRequest</h4>
 <table border=0>
 <thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
-<tr><td>1</td><td>U8</td><td>20</td><td>message type</td></tr>
+<tr><td>1</td><td>U8</td><td>30</td><td>message type</td></tr>
 <tr><td>BENCHMARK size</td><td class="alias">BENCHMARK</td><td></td><td></td></tr>
 <tr><td>METRIC size</td><td class="alias">METRIC</td><td></td><td></td></tr>
 <tr><td>PLATFORM size</td><td class="alias">PLATFORM</td><td></td><td></td></tr>
@@ -522,7 +648,7 @@ This request behaves similarly to ListAvailableBenchmarks* (see this).
 <h4 class="msgName">ListAvailableBranchesReply</h4>
 <table border=0>
 <thead><tr><th>No. of bytes</th><th>Type</th><th>Value</th><th>Description</th></tr></thead>
-<tr><td>1</td><td>U8</td><td>21</td><td>message type</td></tr>
+<tr><td>1</td><td>U8</td><td>31</td><td>message type</td></tr>
 <tr><td>1</td><td>U32</td><td></td><td>n</td></tr>
 <tr><td>BRANCH size</td><td class="alias">BRANCH</td><td></td><td>item 1</td></tr>
 <tr><td>BRANCH size</td><td class="alias">BRANCH</td><td></td><td>item 2</td></tr>
diff --git a/doc/notes.txt b/doc/notes.txt
index 466e055..29062c8 100644
--- a/doc/notes.txt
+++ b/doc/notes.txt
@@ -34,6 +34,13 @@ Use case 1: Compare results for a given branch since a given snapshot:
 
     ./bmc compare -history BMCONTEXT -branch <branch> SNAPSHOT
 
+    Example:
+
+    ./bmc compare -history -testcase tst_QWidget -testfunc updateOpaque \
+        -datatag 10x10x1 -metric walltime -platform linux-g++ -host barbarella \
+        -branch qt master -timestamp first
+
+
 Use case 2: Compare the results of two branches:
 
     ./bmc compare -branches BMCONTEXT <branch1> SNAPSHOT1 <branch2> SNAPSHOT2
@@ -52,23 +59,21 @@ Use case 3: Compare a result of a given branch directly to an unregistered
 Use case 4: Add new results:
 
     ./bmc add -results <xml file> -platform <platform> -host <host> \
-        -gitrepo <product git repo> [-gitdir <product git dir>] [-sha1 <product sha1>]
+        -gitrepo <product git repo> [-gitdir <product git dir>]
 
     Notes:
        - <product git dir> must refer to a directory accessible from the local
-         file system.
+         file system. By default, <product git dir> is the current directory.
        - The new results are assumed to have been generated using a product
-         built from a working tree having <product sha1> as the head commit.
-       - By default, <product git dir> is the current directory.
-       - By default, <product sha1> is the current head commit of the working tree
+         built from a clean checkout of the current head commit of the current git branch
          in <product git dir>.
-       - The git branch is derived from <product git dir> (using the 'git branch' command).
-       - The timestamp (to accompany the sha1 in the database) is derived from
-         the combination of the git branch and <product sha1> in
-         <product git dir> (using the 'git show ... --pretty=raw' command).
-       - In general, the git repository name cannot be derived from <product
-         git dir> (e.g. in the case of a local, standalone repository). That's
-         why it must be passed explicitly.
+       - The sha1 of the snapshot is assumed to be the current head commit.
+       - The timestamp of the snapshot is derived from the combination of the git branch
+         and <product sha1> in <product git dir> (using the 'git show ... --pretty=raw' command).
+       - <product git repo> must be passed explicitly since it cannot in general
+         be derived from <product git dir> (e.g. in the case of a local, standalone
+         repository).
+
 
 ----------------------------------
 
@@ -88,4 +93,4 @@ Ditto for other entities:
 
 Use case 6: List available snapshots for a given branch:
 
-    ./bmc list snapshots BMCONTEXT <branch>
+    ./bmc list -snapshots BMCONTEXT <branch>