Site: anchor link location fixed (#26) plus a few minor adjustments […

…skip ci]

src/site/markdown/Compatibility.md

@@ -1,8 +1,8 @@
 
 # Compatibility
 
+&nbsp; <a name="Drivers"></a>
 ## JDBC drivers
-<a name="Drivers"></a>
 
 JDBDT is expected to work with any (sane) JDBC driver.
 The JDBDT build currently tests integration with:
@@ -14,11 +14,12 @@ The JDBDT build currently tests integration with:
 * [PostgreSQL](http://postgresql.org)
 * [SQLite](https://www.sqlite.org) through [xerial's JDBC driver](https://github.com/xerial/sqlite-jdbc)
 
+&nbsp; <a name="KnownIssues"></a>
 ## Known issues
-<a name="KnownIssues"></a>
 
+&nbsp; <a name="KnownIssues_PostgreSQL"></a>
 ### PostgreSQL
-<a name="KnownIssues_PostgreSQL"></a>
+
 
 #### Auto-commit off / Rollback on error
 
@@ -46,8 +47,9 @@ The `assertXXX` JDBDT assertion above (or any other code that issues a database
 
 A possible workaround is to issue a rollback statement before any further operations, i.e., before `assertXXX` in the example snippet above.
 
+&nbsp;<a name="KnownIssues_sqlite"></a>
 ### sqlite
-<a name="KnownIssues_sqlite"></a>
+
 
 #### Statement reuse
 

src/site/markdown/DB.md

@@ -3,8 +3,8 @@
 A database handle encapsulates access to a database 
 connection.
 
+&nbsp;<a name="Creation"></a>
 ## Creation and teardown
-<a name="Creation"></a>
 
 A database handle is created using the `database` facade method, for instance
 supplying as argument a database URL. Once the database handle is no longer required,
@@ -27,8 +27,8 @@ internal resources may be freed up using the `teardown` method.
 	// In this case we close the connection.
 	teardown(db, true);
 
+&nbsp;<a name="Configuration"></a>
 ## Configuration 
-<a name="Configuration"></a>
 
 Database handle options are defined by the `DB.Option` enumeration.
 They may be enabled and disabled using  `enable` and `disable`, respectively. 
@@ -43,8 +43,9 @@ The available options relate to logging and a few other features discussed below
 	DB db = database(...);
 	db.enable(Option.LOG_SETUP);
 
+&nbsp; <a name="Logging"></a>
 ### Logging
-<a name="Logging"></a>
+
 
 For debugging purposes or report generation, trace output may be written to a [log file](Logs.html).
 The following logging options are defined in `DB.Option`
@@ -79,8 +80,8 @@ Note that if you use a `.gz` extension for log files, they will be GZIP-compress
 
 	db.setLog(new File("MyLog.jdbdt.xml.gz"));
 
+&nbsp; <a name="StatementReuse"></a>
 ### Statement reuse
-<a name="StatementReuse"></a>
 
 A database handle internally reuses `java.sql.PreparedStatement` objects
 to avoid re-compiling SQL code, regardless of any statement pooling in place
@@ -102,13 +103,15 @@ the `REUSE_STATEMENTS` option should be disabled as follows:
 [xerial's JDBC driver for sqlite](Compatibility.html#KnownIssues).
 No problems were detected for [all other JDBC drivers tested in the JDBDT build](Compatibility.html#Drivers).
 
+
+&nbsp; <a name="BatchUpdates"></a>
 ### Batch updates
 
 The `BATCH_UPDATES` option indicates that database insertions should use the JDBC batch update mechanism, unless the JDBC driver in does not support this feature 
 (in this case the option will have no effect). The option is enabled by default.
 
-## Summary of methods
-<a name="MethodReference"></a>
+&nbsp; <a name="SummaryOfMethods"></a>
+## Summary of API methods
 
 ### `JDBDT`
 

src/site/markdown/DBAssertions.md

@@ -9,7 +9,11 @@ incremental changes, i.e., a **database delta**.
 * You may also perform complementary verifications, e.g., to compare data sets sets or 
 to check for the existence of database tables. 
 
-## Delta assertions <a name="DeltaAssertions"></a>
+&nbsp;<a name="DeltaAssertions"></a>
+## Delta assertions 
+
+&nbsp; <a name="Delta_About"></a>
+### &delta; assertions ? What do you mean ?
 
 &delta;-assertions state the expected incremental changes made to the database,
 i.e., an expected database delta. The figure below illustrates the mechanism. 
@@ -25,9 +29,9 @@ The programming pattern in line with this scheme is as follows:
 	Define reference snapshot(s) for the data source(s) of interest
 	theSUT.changesTheDB();
 	Call delta assertion method(s)
-
+
+&nbsp; <a name="Snapshots"></a>	
 ### Snapshots 
-<a name="Snapshots"></a>
 
 A data source **snapshot** is a data set that is used as reference for subsequent delta
 assertions. It can be defined in two ways for a data source `s`:
@@ -53,7 +57,8 @@ will issue a fresh database query, and record the obtained data set as the snaps
 	// [2] OR take a snapshot.
 	DataSource s = ... ; // 's' can be a Table or Query
 	takeSnapshot(s); // --> internally takes and records a snapshot 
-
+
+&nbsp; <a name="Assertion_Methods"></a>
 ### Assertion methods 
 
 The elementary &delta;-assertion method is `assertDelta`. 
@@ -130,8 +135,8 @@ A number of other assertion methods are defined for convenience, all of which in
 	letTheSUT_updatePassword(999, "dontDoeIt")
 	assertDelta(before, after);
 
-	
-## State assertions <a name="StateAssertions"></a>
+&nbsp; <a name="StateAssertions"></a>
+## State assertions 
 
 A state assertion checks that the database contents in full, and
 is executed by calling `assertState`. 
@@ -169,12 +174,16 @@ it verifies that the given data source has no defined rows.
 	letTheSUT_insertOneUser( ... ); 
 	assertState(expected);
 
+&nbsp; <a name="OtherAssertions"></a>
 ## Other assertions
 
-### Data set assertions <a name="DataSetAssertions"></a>	
+&nbsp; <a name="DataSetAssertions"></a>	
+### Data set comparison  
+
+Two given data sets can be verified as equivalent using the `assertEquals` method.
+Note that an assertion of this kind will be insensitive to the order of rows in each data set (like all JDBDT delta or state assertions).
 
-A data set assertion verifies that two given data sets are equivalent.
-This can be done using the `assertEquals` method.
+**For JUnit users**: also beware not to confuse `assertEquals` with [JUnit](http://junit.org) methods that go by the same name. JUnit's `assertEquals` will not work properly, since `DataSet` (deliberately) does *not* override `Object.equals`. All will go well if you use [a static import for all methods in the JDBDT facade](Facade.html#StaticImport).
 
 *Illustration*
 
@@ -194,8 +203,8 @@ This can be done using the `assertEquals` method.
 	assertEquals(expected, actual);
 
 
-**Note for JUnit users**: beware not to confuse `assertEquals` with [JUnit](http://junit.org) methods that go by the same name. JUnit's `assertEquals` will not work properly, since `DataSet` (deliberately) does *not* override `Object.equals`. All will go well if you use [a static import for all methods in the JDBDT facade](Facade.html#StaticImport).
 
+&nbsp; <a name="TableExistenceAssertions"></a>	
 ## Table existence assertions
 
 The `assertTableExists` assertion methods verifies if a given table exists in the database. Symmetrically, `assertTableDoesNotExist` verifies that a table does not

src/site/markdown/DataSets.md

@@ -2,17 +2,18 @@
 # Data sets
 
 A `DataSet` object represents a collection of rows for a [data source](DataSources.html)
-that may be used for database [setup](DBSetup.html) or [verification](DBAssertions.html).
+that may be used for database [setup](DBSetup.html) or [assertions](DBAssertions.html).
 
+&nbsp; <a name="Creation"></a>
 ## Creation
-<a name="Creation"></a>
+
 
 The examples below define data sets for a [table](DataSources.html#Table) (`Table`) object, 
 but the definition of data sets works similarly for
 [queries](DataSources.html#Query) (`Query`).
 
+&nbsp; <a name="Creation.Plain"></a>
 ### Plain definition 
-<a name="Creation.Plain"></a>
 
 In the simplest manner, 
 `DataSet` objects are created through the `data` JDBDT facade method,
@@ -37,8 +38,9 @@ typically followed by a chained sequence of calls.
 	    .row(102, "harry", "Harry H",    "meta",      Date.valueOf("2016-01-01"))
 	    .row(103, "guest", "Guest User", "welcome",   Date.valueOf("2016-01-02"));
 
+
+&nbsp; <a name="Creation.Typed"></a>
 ### Typed data sets
-<a name="Creation.Typed"></a>
 
 `TypedDataSet` is a typed extension of `DataSet`. It allows for a simple
 form of (one-way) object-relational mapping through conversion functions expressed
@@ -73,8 +75,8 @@ of column values.
 		.rows(john, harry, guest)
 		.rows(listOfOtherUsers);
 
+&nbsp; <a name="Creation.Builder"></a>
 ### Data set builders
-<a name="Creation.Builder"></a>
 
 A `DataSetBuilder` instance can be used to define or augment a data set 
 with the aid of expressive column filler methods. For instance,
@@ -122,18 +124,17 @@ set.
         .nullValue("CREATED") // set to NULL
         .generate(500);
 
+&nbsp; <a name="ReadOnly"></a>
 ## Read-only data sets
-<a name="ReadOnly"></a>
 
 A data set is marked read-only when defined as a [database snapshot](DBAssertions.html#Snapshots).
 Any attempt to modify it subsequently will cause an `InvalidOperationException`.
 
-## Summary of methods
-<a name="MethodReference"></a>
+&nbsp; <a name="SummaryOfMethods"></a>
+## Summary of API methods
 
 ### `JDBDT`
 
-
 Object creation - for a [data source](DataSources.html) `s`:
 
 - `data(s)` creates a new data set.
@@ -182,7 +183,3 @@ Utility methods (all `static`):
 - `sequence(column, ...)`  defines a sequence fillers for `column` (several method variants).
 - `random(column, ...)` defines a pseudo-random filler for `column` (several method variants).
 - `set(column, filler)` defines a custom column filler for `column`. 
-
-
-
-

src/site/markdown/DataSources.md

@@ -4,8 +4,11 @@
 `DataSource` objects represent tables and queries that are used for database 
  [setup](DBSetup.html) or [assertions](DBAssertions.html).
 
+&nbsp; <a name="Table"></a>
 ## Tables
-<a name="Table"></a>
+
+&nbsp; <a name="Table_Builder"></a>
+### Using table builders
 
 Tables are represented by `Table`, a subclass of `DataSource`. A table is created
 using a builder (`TableBuilder`), as returned by the `table` facade method.
@@ -23,6 +26,8 @@ and the `build` method to build the actual `Table` object in association to a [d
 	                 .columns("LOGIN", "NAME", "PASSWORD", "CREATED")
 	                 .build(db);
 
+&nbsp; <a name="Table_Key"></a>
+### Key columns for a table
 In addition, if you wish to perform updates and deletes using data sets, `key` can be used to define the columns that form 
 the table's primary key (or that in some other form identify each database row uniquely) 
 
@@ -33,14 +38,14 @@ the table's primary key (or that in some other form identify each database row u
 	                  .key("LOGIN")
 	                  .build(db);
 
+&nbsp; <a name="Query"></a>
 ## Queries
-<a name="Query"></a>
 
 Queries are represented by `Query`, a subclass of `DataSource`. 
 A `Query` object can be created from a raw SQL statements or using a `QueryBuilder`.    
-
+
+&nbsp; <a name="RawQuery"></a>
 ### Definition from raw SQL 
-<a name="RawQuery"></a>
 
 The `query` facade method may be used to define a query using raw SQL.
 
@@ -55,8 +60,8 @@ The `query` facade method may be used to define a query using raw SQL.
     int idArgument = ...;
     Query q = query(db, "SELECT LOGIN, NAME FROM USER WHERE ID = ?", idArgument);
 
+&nbsp; <a name="QueryBuilder"></a>
 ### Definition using `QueryBuilder`
-<a name="QueryBuilder"></a>
 
 `QueryBuilder` objects can be used to define queries programmatically.
 The `select` facade method creates a query builder that can be parameterized
@@ -111,7 +116,8 @@ to the order of query results, but the use of `orderBy` may make it easier to in
               .from("USER u1", "USER u2")
               .where("u1.LOGIN <> u2.LOGIN AND u1.PASSWORD = u2.PASSWORD")
               .build(db);
-
+              
+&nbsp; <a name="SummaryOfMethods"></a>  
 ## Summary of methods
 
 ### `JDBDT`

src/site/markdown/Facade.md

@@ -6,14 +6,16 @@ The `org.jdbdt.JDBDT` class  is the facade for the JDBDT API,
 providing the core interface methods for database setup, verification,
 and API object creation. 
 
+&nbsp; <a name="StaticImport"></a>
 ## Static import
-<a name="StaticImport"></a>
+
 
 The following static import 
 may be convenient to refer to the API methods concisely.
 
     import static org.jdbdt.JDBDT.*;
 
+&nbsp; <a name="Overview"></a>
 ## Overview of functionality
 
 [(browse Javadoc instead)](apidocs/index.html?org/jdbdt/JDBDT.html)

src/site/markdown/Logs.md

@@ -3,7 +3,8 @@
 
 An XML format is used for [JDBDT log files](DB.html#Logging) and for the output of calls to `JDBDT.dump`. 
 
-## Generic format <a name="Generic"></a>
+&nbsp; <a name="Generic"></a>
+## Generic format 
 
 Every JDBDT log message is defined by a `jdbdt-log-message` XML node.
 For each node of this type:
@@ -48,8 +49,8 @@ and SQL type (`sql-type`).
         <sql><![CDATA[SELECT login, name, password, created FROM Users]]></sql>
       </data-source>
 
-
-## Data sets <a name="DataSets"></a>
+&nbsp; <a name="DataSets"></a>
+## Data sets 
 
 A `data-set` node displays the contents of a [data set](DataSets.html) that associates 
 to some JDBDT operation (e.g., `populate`, `dump`). 
@@ -88,7 +89,7 @@ column label (`label` attribute) and Java type (`java-type`).
 	    </rows>
 	  </data-set>
 
-
+&nbsp; <a name="StateAndDataSetAssertions"></a>
 ## State and data set assertions
 
 An `assertion` node refers to a [database state assertion](DBAssertions.html#StateAssertions) or a [data set assertion](DBAssertions.html#DataSetAssertions). It comprises:
@@ -148,8 +149,9 @@ The `steve` and `bill` "users" were matched.
         </expected>
       </errors>
     </assertion>
-
-## Delta assertions <a name="DeltaAssertions"></a>
+
+&nbsp; <a name="DeltaAssertions"></a>  
+## Delta assertions 
 
 A `delta-assertion` node refers to a [database delta assertion](DBAssertions.html#DeltaAssertions). For an  assertion
 where the expected delta is **&delta; = (O, N)** and the actual delta