You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2015/05/20 09:29:22 UTC

[5/8] isis git commit: ISIS-1133: adding anchors to all .adoc headers; fixing some xrefs.

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_persistence-xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_persistence-xml.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_persistence-xml.adoc
index 7933b17..f3045b4 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_persistence-xml.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_persistence-xml.adoc
@@ -1,4 +1,4 @@
-= `persistence.xml`
+= anchor:runtime_configuring_datanucleus[]`persistence.xml`
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_properties.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_properties.adoc
index af63f75..08f088d 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_properties.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_properties.adoc
@@ -1,4 +1,4 @@
-= Configuration Properties
+= anchor:runtime_configuring_datanucleus[]Configuration Properties
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_using-jndi-data-source.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_using-jndi-data-source.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_using-jndi-data-source.adoc
index 9888750..fef5b49 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_using-jndi-data-source.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_using-jndi-data-source.adoc
@@ -1,4 +1,4 @@
-= Using JNDI DataSource
+= anchor:runtime_configuring_datanucleus[]Using JNDI DataSource
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_web-xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_web-xml.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_web-xml.adoc
index 8be8f26..fd290e0 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_web-xml.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_web-xml.adoc
@@ -1,4 +1,4 @@
-= `web.xml`
+= anchor:runtime[]`web.xml`
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_security.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security.adoc
index b88673d..1237eb4 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security.adoc
@@ -1,4 +1,4 @@
-= Security
+= anchor:chapter[]Security
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/
@@ -14,7 +14,7 @@ Isis has two levels of permissions.  _Read_ permission means that the user can v
 
 Isis provides an API for both authentication and authorization, and provides an implementation that integrates with link:http://shiro.apache.org[Apache Shiro].  Shiro in turn uses the concept of a _realm_ as a source for both authentication and optionally authorization.
 
-Shiro ships with a simple text-based realm -- the `IniRealm` -- which reads users (and password), user roles and role permissions from the `WEB-INF/shiro.ini` file.  The xref:_simpleapp_archetype[SimpleApp archetype] is configured to use this realm.
+Shiro ships with a simple text-based realm -- the `IniRealm` -- which reads users (and password), user roles and role permissions from the `WEB-INF/shiro.ini` file.  The xref:__a_id_getting_started_a_simpleapp_archetype[SimpleApp archetype] is configured to use this realm.
 
 Shiro also ships with an implementation of an LDAP-based realm; LDAP is often used to manage user/passwords and corresponding user groups.  Isis in turn extends this with its `IsisLdapRealm`, which provides more flexibility for both group/role and role/permissions management.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_api-for-applications.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_api-for-applications.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_api-for-applications.adoc
index 33cdd19..d601e9d 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_api-for-applications.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_api-for-applications.adoc
@@ -1,4 +1,4 @@
-= API for Applications
+= anchor:security[]API for Applications
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_configuring-isis-to-use-bypass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_configuring-isis-to-use-bypass.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_configuring-isis-to-use-bypass.adoc
index f80fb37..687dc31 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_configuring-isis-to-use-bypass.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_configuring-isis-to-use-bypass.adoc
@@ -1,4 +1,4 @@
-= Bypass Security
+= anchor:security[]Configuring Isis to bypass Security
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_configuring-isis-to-use-shiro.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_configuring-isis-to-use-shiro.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_configuring-isis-to-use-shiro.adoc
index 12f919d..04dd49f 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_configuring-isis-to-use-shiro.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_configuring-isis-to-use-shiro.adoc
@@ -1,4 +1,4 @@
-= Configuring Isis to use Shiro
+= anchor:security[]Configuring Isis to use Shiro
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/
@@ -8,7 +8,7 @@ Apache Isis' security mechanism is configurable, specifying an `Authenticator` a
 
 [TIP]
 ====
-The xref:_simpleapp_archetype[SimpleApp archetype] is pre-configured to use Apache Shiro, so much of what follows is set up already.
+The xref:__a_id_getting_started_a_simpleapp_archetype[SimpleApp archetype] is pre-configured to use Apache Shiro, so much of what follows is set up already.
 ====
 
 == Specifying Shiro as the security mechanism

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-caching.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-caching.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-caching.adoc
index deb94b9..28bed74 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-caching.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-caching.adoc
@@ -1,4 +1,4 @@
-= Caching and other Shiro Features
+= anchor:security[]Caching and other Shiro Features
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-ini-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-ini-realm.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-ini-realm.adoc
index 21289a4..8badeba 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-ini-realm.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-ini-realm.adoc
@@ -1,4 +1,4 @@
-= Shiro Ini Realm
+= anchor:security[]Shiro Ini Realm
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/
@@ -6,7 +6,7 @@
 
 Probably the simplest realm to use is Shiro's built-in `IniRealm`, which reads from the (same) `WEB-INF/shiro.ini` file.
 
-This is suitable for prototyping, but isn't intended for production use, if only because user/password credentials are stored in plain text.  Nevertheless, it's a good starting point.  The app generated by the xref:_simpleapp_archetype[SimpleApp archetype] is configured to use this realm.
+This is suitable for prototyping, but isn't intended for production use, if only because user/password credentials are stored in plain text.  Nevertheless, it's a good starting point.  The app generated by the xref:__a_id_getting_started_a_simpleapp_archetype[SimpleApp archetype] is configured to use this realm.
 
 The diagram below shows the Isis and components involved:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isis-enhanced-wildcard-permission.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isis-enhanced-wildcard-permission.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isis-enhanced-wildcard-permission.adoc
index 5b21d0a..c805495 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isis-enhanced-wildcard-permission.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isis-enhanced-wildcard-permission.adoc
@@ -1,4 +1,4 @@
-= Enhanced Wildcard Permission
+= anchor:security[]Enhanced Wildcard Permission
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isis-ldap-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isis-ldap-realm.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isis-ldap-realm.adoc
index 59c0192..a3c5cbc 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isis-ldap-realm.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isis-ldap-realm.adoc
@@ -1,4 +1,4 @@
-= Isis Ldap Realm
+= anchor:security[]Isis Ldap Realm
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isisaddons-security-module-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isisaddons-security-module-realm.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isisaddons-security-module-realm.adoc
index 7f99cb0..4ede992 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isisaddons-security-module-realm.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isisaddons-security-module-realm.adoc
@@ -1,4 +1,4 @@
-= Security Module Realm
+= anchor:security[]Security Module Realm
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-jdbc-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-jdbc-realm.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-jdbc-realm.adoc
index c90957d..591dc22 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-jdbc-realm.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-jdbc-realm.adoc
@@ -1,4 +1,4 @@
-= Shiro JDBC Realm
+= anchor:security[]Shiro JDBC Realm
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_usage-by-isis-viewers.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_usage-by-isis-viewers.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_usage-by-isis-viewers.adoc
index 8aac375..1df3cc7 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_usage-by-isis-viewers.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_usage-by-isis-viewers.adoc
@@ -1,4 +1,4 @@
-= Usage by Isis' Viewers
+= anchor:security[]Usage by Isis' Viewers
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing.adoc
index fcc80c7..ba50907 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing.adoc
@@ -1,4 +1,4 @@
-= Testing
+= anchor:chapter[]Testing
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/
@@ -8,7 +8,7 @@
 If you are going to use Apache Isis for developing complex business-critical applications, then being able to write automated tests for those applications becomes massively important.  As such Apache Isis treats the topic of testing very seriously, and (though we say it ourselves) has support that goes way above what is provided by other application frameworks.
 
 
-include::_ug_testing_overview.adoc[leveloffset=+1]
+include::_ug_testing_aaa.adoc[leveloffset=+1]
 include::_ug_testing_unit-test-support.adoc[leveloffset=+1]
 include::_ug_testing_integ-test-support.adoc[leveloffset=+1]
 include::_ug_testing_bdd-spec-support.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_aaa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_aaa.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_aaa.adoc
new file mode 100644
index 0000000..de06b17
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_aaa.adoc
@@ -0,0 +1,165 @@
+= anchor:testing[]Overview
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+== Unit tests vs Integ tests
+
+We divide automated tests into two broad categories:
+
+- unit tests exercise a single unit (usually a method) of a domain object, in isolation.  +
++
+Dependencies of that object are mocked out.  These are written by a developer and for a developer; they are to ensure that a particular "cog in the machine" works correctly
+
+- integration tests exercise the application as a whole, usually focusing on one particular business operation (action).  +
++
+These are tests that represent the acceptance criteria of some business story; their intent should make sense to the domain expert (even if the domain expert is "non-technical")
+
+To put it another way:
+
+[TIP]
+====
+Integration tests help ensure that you are *_building the right system_*
+
+Unit tests help ensure that you are *_building the system right_*.
+====
+
+
+
+== Integ tests vs BDD Specs
+
+We further sub-divide integration tests into:
+
+* those that are implemented in Java and JUnit (we call these simply _"integration tests"_) +
++
+Even if a domain expert understands the intent of these tests, the actual implementation will be opaque to them.  Also, the only output from the tests is a (hopefully) green CI job
+
+* tests (or rather, specifications) that are implemented in a _behaviour-driven design_ (BDD) language such as link:https://cucumber.io/[Cucumber] (we call these _"BDD specs"_) +
++
+The natural language specification then maps down onto some glue code that is used to drive the application.  But the benefits of taking a BDD approach include the fact that your domain expert will be able to read the tests/specifications, and that when you run the specs, you also get documentation of the application's behaviour ("living documentation").
+
+It's up to you whether you use BDD specs for your apps; it will depend on your development process and company culture.  But you if don't then you certainly should write integration tests: acceptance criteria for user stories should be automated!
+
+
+
+
+
+== Simulated UI (`WrapperFactory`)
+
+When we talk about integration tests/specs here, we mean tests that exercise the domain object logic, through to the actual database.  But we also want the tests to exercise the app from the users's perspective, which means including the user interface.
+
+For most other frameworks that would require having to test the application in a very heavy weight/fragile fashion using a tool such as link:http://seleniumhq.org[Selenium], driving a web browser to navigate .  In this regard though, Isis has a significant trick up its sleeve.  Because Isis implements the naked objects pattern, it means that the UI is generated automatically from the UI.  This therefore allows for other implementations of the UI.
+
+The xref:_wrapper_factory[`WrapperFactory`] domain service allows a test to wrap domain objects and thus to interact with said objects "as if" through the UI:
+
+image::{_imagesdir}testing/integ-tests.png[width="700px"]
+
+If the test invokes an action that is disabled, then the wrapper will throw an appropriate exception.  If the action is ok to invoke, it delegates through.
+
+What this means is that an Isis application can be tested end-to-end without having to deploy it onto a webserver; the whole app can be tested while running in-memory.  Although integration tests re (necessarily) slower than unit tests, they are not any harder to write (in fact, in some respects they are easier).
+
+
+
+
+== Dependency Injection
+
+Isis provides autowiring dependency injection into every domain object.  This is most useful when writing unit tests; simply mock out the service and inject into the domain object.
+
+There are a number of syntaxes supported, but the simplest is to use `@javax.inject.Inject` annotation; for example:
+
+[source,java]
+----
+@javax.inject.Inject
+CustomerRepository customers;
+----
+
+Isis can inject into this even if the field has package-level (or even `private`) visibility.  We recommend that you use package-level visibility, though, so that your unit tests (in the same package as the class under test) are able to inject mocks.
+
+Isis does also support a couple of other syntaxes:
+
+[source,java]
+----
+public void setCustomerRepository(CustomerRepository customers) { ... }
+----
+
+or
+
+[source,java]
+----
+public void injectCustomerRepository(CustomerRepository customers) { ... }
+----
+
+
+[TIP]
+====
+Apache Isis also supports automatic dependency injection into integration tests; just declare the service dependency in the usual fashion and it will be automatically injected.
+====
+
+
+
+
+== Given/When/Then
+
+Whatever type of test/spec you are writing, we recommend you follow the given/when/then idiom:
+
+* *given* the system is in this state (preconditions)
+* *when* I poke it with a stick
+* *then* it looks like this (postconditions)
+
+A good test should be 5 to 10 lines long; the test should be there to help you reason about the behaviour of the system.  Certainly if the test becomes more than 20 lines it'll be too difficult to understand.
+
+The "when" part is usually a one-liner, and in the "then" part there will often be only two or three assertions that you want to make that the system has changed as it should.
+
+For unit test the "given" part shouldn't be too difficult either: just instantiate the class under test, wire in the appropriate mocks and set up the expectations.  And if there are too many mock expectations to set up, then "listen to the tests" ... they are telling you your design needs some work.
+
+Where things get difficult though is the "given" for integration tests; which is the topic of the next section...
+
+
+
+
+== Fixture Management
+
+In the previous section we discussed using given/when/then as a form of organizing tests, and why you should keep your tests small.
+
+For integration tests though it can be difficult to keep the "given" short; there could be a lot of prerequisite data that needs to exist before you can actually exercise your system.  Moreover, however we do set up that data, but we also want to do so in a way that is resilient to the system changing over time.
+
+The solution that Isis provides is a domain service called xref:_fixture_scripts[Fixture Scripts], that defines a pattern and supporting classes to help ensure that the "data setup" for your tests are reusable and maintainable over time.
+
+
+
+
+
+== Fake data
+
+In any given test there are often quite a few variables involved, to initialize the state of the objects, or to act as arguments for invoking a method, or when asserting on post-conditions.  Sometimes those values are important (eg verifying that an `Order`'s state went from PENDING to SHIPPED, say), but often they aren't (a customer's name, for example) but nevertheless need to be set up (especially in integration tests).
+
+We want our tests to be easily understood, and we want the reader's eye to be drawn to the values that are significant and ignore those that are not.
+
+One way to do this is to use random (or fake) values for any insignificant data.  This in effect tells the reader that "any value will do".  Moreover, if it turns out that any data won't do, and that there's some behaviour that is sensitive to the value, then the test will start to flicker, passing and then failing depending on inputs.  This is A Good Thing™.
+
+Apache Isis does not, itself, ship with a fake data library.  However, the http://github.com/isisaddons/isis-module-fakedata}[Isis addons' fakedata] module (non-ASF) does provide exactly this capability.
+
+[TIP]
+====
+Using fake data works very well with fixture scripts; the fixture script can invoke the business action with sensible (fake/random) defaults, and only require that the essential information is passed into it by the test.
+====
+
+
+
+
+== Feature Toggles
+
+Writing automated tests is just good development practice.  Also good practice is developing on the mainline (master, trunk); so that your continuous integration system really is integrating all code.  Said another way: link:http://martinfowler.com/bliki/FeatureBranch.html[don't use branches]!
+
+Sometimes, though, a feature will take longer to implement than your iteration cycle.  In such a case, how do you use continuous integration to keep everyone working on the mainline without revealing a half-implemented feature on your releases?  One option is to use link:http://martinfowler.com/bliki/FeatureToggle.html[feature toggle]s.
+
+Apache Isis does not, itself, ship with a feature toggle library.  However, the http://github.com/isisaddons/isis-module-togglz}[Isis addons' togglz] module (non-ASF) does provide exactly this capability.
+
+
+
+
+
+With all that said, let's look in detail at the testing features provided by Apache Isis.
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support.adoc
index bb07e2f..472d651 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support.adoc
@@ -1,4 +1,4 @@
-= BDD Spec Support
+= anchor:testing[]BDD Spec Support
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_bdd-tooling.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_bdd-tooling.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_bdd-tooling.adoc
index ede2b2a..a8d6f0d 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_bdd-tooling.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_bdd-tooling.adoc
@@ -1,4 +1,4 @@
-= BDD Tooling
+= anchor:testing_bdd-spec-support[]BDD Tooling
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_how-it-works.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_how-it-works.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_how-it-works.adoc
index 27d0e49..983dd78 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_how-it-works.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_how-it-works.adoc
@@ -1,4 +1,4 @@
-= How it works
+= anchor:testing_bdd-spec-support[]How it works
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_key-classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_key-classes.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_key-classes.adoc
index 38de5d1..a68c357 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_key-classes.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_key-classes.adoc
@@ -1,4 +1,4 @@
-= Key classes
+= anchor:testing_bdd-spec-support[]Key classes
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_maven-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_maven-configuration.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_maven-configuration.adoc
index 396c1a4..5dacf53 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_maven-configuration.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_maven-configuration.adoc
@@ -1,4 +1,4 @@
-= Maven Configuration
+= anchor:testing_bdd-spec-support[]Maven Configuration
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/
@@ -6,7 +6,7 @@
 
 
 
-Apache Isis' BDD spec support is automatically configured if you use the xref:_simpleapp_archetype[SimpleApp archetype].  To set it up manually, update the `pom.xml` of your domain object model module:
+Apache Isis' BDD spec support is automatically configured if you use the xref:__a_id_getting_started_a_simpleapp_archetype[SimpleApp archetype].  To set it up manually, update the `pom.xml` of your domain object model module:
 
 [source,xml]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_writing-a-bdd-spec.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_writing-a-bdd-spec.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_writing-a-bdd-spec.adoc
index c86bb09..10a357b 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_writing-a-bdd-spec.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_writing-a-bdd-spec.adoc
@@ -1,4 +1,4 @@
-= Writing a BDD spec
+= anchor:testing_bdd-spec-support[]Writing a BDD spec
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/
@@ -23,7 +23,7 @@ The `glue` attribute of the Cucumber-JVM JUnit runner eallows you to indicate wh
 * a system initializer class.  You can reuse the  system initializer from any integration tests (as described in xref:_integration_test_support[Integration Test Support], bootstrapping section).
 
 
-Here's an example of a feature from the xref:_simpleapp_archetype[SimpleApp archetype]:
+Here's an example of a feature from the xref:__a_id_getting_started_a_simpleapp_archetype[SimpleApp archetype]:
 
 [source]
 ----
@@ -48,7 +48,7 @@ Apache Isis does also support running BDD specs in unit test mode; by annotating
 
 To support unit testing scope Isis provides the `InMemoryDB` class; a glorified hashmap of "persisted" objects.  Use of this utility class is optional.
 
-Writing a BDD spec that supports both modes of operation therefore takes more effort and we expect most users interested in BDD will use integration-testing scope; for these reasons we have chosen _not_ to include unit-testing support in the xref:_simpleapp_archetype[SimpleApp archetype].  For those who do require faster-executing test suite, it's worthwhile knowing that Isis can support this.
+Writing a BDD spec that supports both modes of operation therefore takes more effort and we expect most users interested in BDD will use integration-testing scope; for these reasons we have chosen _not_ to include unit-testing support in the xref:__a_id_getting_started_a_simpleapp_archetype[SimpleApp archetype].  For those who do require faster-executing test suite, it's worthwhile knowing that Isis can support this.
 
 ====
 
@@ -71,7 +71,7 @@ public class RunSpecs {
 }
 ----
 
-The JSON formatter allows integration with enhanced reports, for example as provided by http://www.masterthought.net/section/cucumber-reporting[Masterthought.net] (screenshots at end of page). (Commented out) configuration for this is provided in the xref:_simpleapp_archetype[SimpleApp archetype].
+The JSON formatter allows integration with enhanced reports, for example as provided by http://www.masterthought.net/section/cucumber-reporting[Masterthought.net] (screenshots at end of page). (Commented out) configuration for this is provided in the xref:__a_id_getting_started_a_simpleapp_archetype[SimpleApp archetype].
 
 The bootstrapping of Isis can be moved into a `BootstrappingGlue` step definition:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts.adoc
index c15e9c7..668c7dd 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts.adoc
@@ -1,4 +1,4 @@
-= Fixture Scripts
+= anchor:testing[]Fixture Scripts
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts_api-and-usage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts_api-and-usage.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts_api-and-usage.adoc
index 86b0ed4..293009f 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts_api-and-usage.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts_api-and-usage.adoc
@@ -1,4 +1,4 @@
-= API and Usage
+= anchor:testing_fixture-scripts[]API and Usage
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/
@@ -14,7 +14,7 @@ Let's look at `FixtureScripts` domain service in more detail first.
 
 == `FixtureScripts`
 
-In your code you subclass `FixtureScripts` domain service primarily just to specify which package to search for.  For example, here's the service that's generated by the xref:_simpleapp_archetype[SimpleApp archetype]:
+In your code you subclass `FixtureScripts` domain service primarily just to specify which package to search for.  For example, here's the service that's generated by the xref:__a_id_getting_started_a_simpleapp_archetype[SimpleApp archetype]:
 
 [source,java]
 ----
@@ -77,7 +77,7 @@ If you had defined many fixture scripts then a drop-down might become unwieldy,
 
 ----
 
-You are free, of course, to add additional "convenience" actions into it if you wish for the most commonly used/demo'd setups ; you'll find that the xref:_simpleapp_archetype[SimpleApp archetype] adds this additional action:
+You are free, of course, to add additional "convenience" actions into it if you wish for the most commonly used/demo'd setups ; you'll find that the xref:__a_id_getting_started_a_simpleapp_archetype[SimpleApp archetype] adds this additional action:
 
 [source,java]
 ----
@@ -100,7 +100,7 @@ Let's now look at the `FixtureScript` class, where there's a bit more going on.
 
 A fixture script is ultimately just a block of code that can be executed, so it's up to you how you implement it to set up the system.  However, we strongly recommend that you use it to invoke actions on business objects, in essence to replay what a real-life user would have done.  That way, the fixture script will remain valid even if the underlying implementation of the system changes in the future.
 
-Here's the `RecreateSimpleObjects` fixture script from the xref:_simpleapp_archetype[SimpleApp archetype]:
+Here's the `RecreateSimpleObjects` fixture script from the xref:__a_id_getting_started_a_simpleapp_archetype[SimpleApp archetype]:
 
 [source,java]
 ----
@@ -212,7 +212,7 @@ public class SimpleObjectCreate extends FixtureScript {       // <1>
 
 Fixture scripts can be called from integration tests just the same way that fixture scripts can call one another.
 
-For example, here's an integration test from the xref:_simpleapp_archetype[SimpleApp archetype]:
+For example, here's an integration test from the xref:__a_id_getting_started_a_simpleapp_archetype[SimpleApp archetype]:
 
 [source,java]
 ----
@@ -255,7 +255,7 @@ public class SimpleObjectIntegTest extends SimpleAppIntegTest {
 
 There are lots of ways to organize fixture scripts, but we've used them as either:
 
-* a fairly flat style, eg as in the xref:_simpleapp_archetype[SimpleApp archetype], also as in the http://github.com/isisaddons/isis-app-todoapp}[Isis addons' todoapp];
+* a fairly flat style, eg as in the xref:__a_id_getting_started_a_simpleapp_archetype[SimpleApp archetype], also as in the http://github.com/isisaddons/isis-app-todoapp}[Isis addons' todoapp];
 
 * in a "composite pattern" style, eg as in the https://github.com/estatio/estatio/blob/ea20a6ce257acede50de6ce4fd2ff29713fcd689/estatioapp/fixture/src/main/java/org/estatio/fixture/invoice/InvoiceForLeaseItemTypeOfDiscountOneQuarterForOxfMiracle005.java#L66)[Estatio open source app].
 
@@ -277,7 +277,7 @@ image::{_imagesdir}testing/fixture-scripts/composite.png[width="550px",link="_im
 
 Back in the earlier xref:_fixturescripts[`FixtureScripts`] section we noted the `MultipleExecutionStrategy` setting.  We can now explain the meaning of this: the enum value of `EXECUTE` is designed for the flat style (where every fixture script will be called), whereas the enum value of `IGNORE` is designed for the composite style, and ensures that any fixture scripts visited more than once (eg TearDown) are only every executed the first time.
 
-As already noted , the app generated by the xref:_simpleapp_archetype[SimpleApp archetype] uses the flat structure, and we feel that it's a better at separating out the "how" (how we set up some graph of domain objects into a known state, eg a customer with shipped placed orders and a newly placed order) from the "what" (what data should we actually use for the customer's name, say).
+As already noted , the app generated by the xref:__a_id_getting_started_a_simpleapp_archetype[SimpleApp archetype] uses the flat structure, and we feel that it's a better at separating out the "how" (how we set up some graph of domain objects into a known state, eg a customer with shipped placed orders and a newly placed order) from the "what" (what data should we actually use for the customer's name, say).
 
 The composite style tends to combine these, which one could argue does not separate responsibilities well enough.  On the other hand, one could also make an argument that the composite style is a good way to implement precanned personas, eg "Joe", the customer who has a newly placed order, from "Mary" customer who has none.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts_sudo-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts_sudo-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts_sudo-service.adoc
index dea52eb..0b0dc57 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts_sudo-service.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts_sudo-service.adoc
@@ -1,4 +1,4 @@
-= SudoService (1.9.0-SNAPSHOT)
+= anchor:testing_fixture-scripts[]SudoService (1.9.0-SNAPSHOT)
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support.adoc
index 2501012..aad20ac 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support.adoc
@@ -1,4 +1,4 @@
-= Integration Test Support
+= anchor:testing[]Integration Test Support
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_bootstrapping.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_bootstrapping.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_bootstrapping.adoc
index 5db4c63..7514186 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_bootstrapping.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_bootstrapping.adoc
@@ -1,4 +1,4 @@
-= Bootstrapping
+= anchor:testing_integ-test-support[]Bootstrapping
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/
@@ -15,7 +15,7 @@ Since the integration tests don't depend on the `webapp` module, it's necessary
 We hope to simplify the way this works in future versions of Isis.
 ====
 
-The example code in this section is taken from the app generated by the xref:_simpleapp_archetype[SimpleApp archetype].
+The example code in this section is taken from the app generated by the xref:__a_id_getting_started_a_simpleapp_archetype[SimpleApp archetype].
 
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_maven-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_maven-configuration.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_maven-configuration.adoc
index ddbff67..9b6fd9f 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_maven-configuration.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_maven-configuration.adoc
@@ -1,10 +1,10 @@
-= Maven Configuration
+= anchor:testing_integ-test-support[]Maven Configuration
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/
 
 
-Apache Isis' integration test support is automatically configured if you use the xref:_simpleapp_archetype[SimpleApp archetype].  To set it up manually, update the `pom.xml` of your domain object model module:
+Apache Isis' integration test support is automatically configured if you use the xref:__a_id_getting_started_a_simpleapp_archetype[SimpleApp archetype].  To set it up manually, update the `pom.xml` of your domain object model module:
 
 [source]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_typical-usage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_typical-usage.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_typical-usage.adoc
index 4e634a2..ad07aaa 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_typical-usage.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_typical-usage.adoc
@@ -1,4 +1,4 @@
-= Typical Usage
+= anchor:testing_integ-test-support[]Typical Usage
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_wrapper-factory.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_wrapper-factory.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_wrapper-factory.adoc
index 6faec56..3c8a970 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_wrapper-factory.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_wrapper-factory.adoc
@@ -1,4 +1,4 @@
-= Wrapper Factory
+= anchor:testing_integ-test-support[]Wrapper Factory
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_overview.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_overview.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_overview.adoc
deleted file mode 100644
index d61c0e3..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_overview.adoc
+++ /dev/null
@@ -1,165 +0,0 @@
-= Overview
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-== Unit tests vs Integ tests
-
-We divide automated tests into two broad categories:
-
-- unit tests exercise a single unit (usually a method) of a domain object, in isolation.  +
-+
-Dependencies of that object are mocked out.  These are written by a developer and for a developer; they are to ensure that a particular "cog in the machine" works correctly
-
-- integration tests exercise the application as a whole, usually focusing on one particular business operation (action).  +
-+
-These are tests that represent the acceptance criteria of some business story; their intent should make sense to the domain expert (even if the domain expert is "non-technical")
-
-To put it another way:
-
-[TIP]
-====
-Integration tests help ensure that you are *_building the right system_*
-
-Unit tests help ensure that you are *_building the system right_*.
-====
-
-
-
-== Integ tests vs BDD Specs
-
-We further sub-divide integration tests into:
-
-* those that are implemented in Java and JUnit (we call these simply _"integration tests"_) +
-+
-Even if a domain expert understands the intent of these tests, the actual implementation will be opaque to them.  Also, the only output from the tests is a (hopefully) green CI job
-
-* tests (or rather, specifications) that are implemented in a _behaviour-driven design_ (BDD) language such as link:https://cucumber.io/[Cucumber] (we call these _"BDD specs"_) +
-+
-The natural language specification then maps down onto some glue code that is used to drive the application.  But the benefits of taking a BDD approach include the fact that your domain expert will be able to read the tests/specifications, and that when you run the specs, you also get documentation of the application's behaviour ("living documentation").
-
-It's up to you whether you use BDD specs for your apps; it will depend on your development process and company culture.  But you if don't then you certainly should write integration tests: acceptance criteria for user stories should be automated!
-
-
-
-
-
-== Simulated UI (`WrapperFactory`)
-
-When we talk about integration tests/specs here, we mean tests that exercise the domain object logic, through to the actual database.  But we also want the tests to exercise the app from the users's perspective, which means including the user interface.
-
-For most other frameworks that would require having to test the application in a very heavy weight/fragile fashion using a tool such as link:http://seleniumhq.org[Selenium], driving a web browser to navigate .  In this regard though, Isis has a significant trick up its sleeve.  Because Isis implements the naked objects pattern, it means that the UI is generated automatically from the UI.  This therefore allows for other implementations of the UI.
-
-The xref:_wrapper_factory[`WrapperFactory`] domain service allows a test to wrap domain objects and thus to interact with said objects "as if" through the UI:
-
-image::{_imagesdir}testing/integ-tests.png[width="700px"]
-
-If the test invokes an action that is disabled, then the wrapper will throw an appropriate exception.  If the action is ok to invoke, it delegates through.
-
-What this means is that an Isis application can be tested end-to-end without having to deploy it onto a webserver; the whole app can be tested while running in-memory.  Although integration tests re (necessarily) slower than unit tests, they are not any harder to write (in fact, in some respects they are easier).
-
-
-
-
-== Dependency Injection
-
-Isis provides autowiring dependency injection into every domain object.  This is most useful when writing unit tests; simply mock out the service and inject into the domain object.
-
-There are a number of syntaxes supported, but the simplest is to use `@javax.inject.Inject` annotation; for example:
-
-[source,java]
-----
-@javax.inject.Inject
-CustomerRepository customers;
-----
-
-Isis can inject into this even if the field has package-level (or even `private`) visibility.  We recommend that you use package-level visibility, though, so that your unit tests (in the same package as the class under test) are able to inject mocks.
-
-Isis does also support a couple of other syntaxes:
-
-[source,java]
-----
-public void setCustomerRepository(CustomerRepository customers) { ... }
-----
-
-or
-
-[source,java]
-----
-public void injectCustomerRepository(CustomerRepository customers) { ... }
-----
-
-
-[TIP]
-====
-Apache Isis also supports automatic dependency injection into integration tests; just declare the service dependency in the usual fashion and it will be automatically injected.
-====
-
-
-
-
-== Given/When/Then
-
-Whatever type of test/spec you are writing, we recommend you follow the given/when/then idiom:
-
-* *given* the system is in this state (preconditions)
-* *when* I poke it with a stick
-* *then* it looks like this (postconditions)
-
-A good test should be 5 to 10 lines long; the test should be there to help you reason about the behaviour of the system.  Certainly if the test becomes more than 20 lines it'll be too difficult to understand.
-
-The "when" part is usually a one-liner, and in the "then" part there will often be only two or three assertions that you want to make that the system has changed as it should.
-
-For unit test the "given" part shouldn't be too difficult either: just instantiate the class under test, wire in the appropriate mocks and set up the expectations.  And if there are too many mock expectations to set up, then "listen to the tests" ... they are telling you your design needs some work.
-
-Where things get difficult though is the "given" for integration tests; which is the topic of the next section...
-
-
-
-
-== Fixture Management
-
-In the previous section we discussed using given/when/then as a form of organizing tests, and why you should keep your tests small.
-
-For integration tests though it can be difficult to keep the "given" short; there could be a lot of prerequisite data that needs to exist before you can actually exercise your system.  Moreover, however we do set up that data, but we also want to do so in a way that is resilient to the system changing over time.
-
-The solution that Isis provides is a domain service called xref:_fixture_scripts[Fixture Scripts], that defines a pattern and supporting classes to help ensure that the "data setup" for your tests are reusable and maintainable over time.
-
-
-
-
-
-== Fake data
-
-In any given test there are often quite a few variables involved, to initialize the state of the objects, or to act as arguments for invoking a method, or when asserting on post-conditions.  Sometimes those values are important (eg verifying that an `Order`'s state went from PENDING to SHIPPED, say), but often they aren't (a customer's name, for example) but nevertheless need to be set up (especially in integration tests).
-
-We want our tests to be easily understood, and we want the reader's eye to be drawn to the values that are significant and ignore those that are not.
-
-One way to do this is to use random (or fake) values for any insignificant data.  This in effect tells the reader that "any value will do".  Moreover, if it turns out that any data won't do, and that there's some behaviour that is sensitive to the value, then the test will start to flicker, passing and then failing depending on inputs.  This is A Good Thing&#8482;.
-
-Apache Isis does not, itself, ship with a fake data library.  However, the http://github.com/isisaddons/isis-module-fakedata}[Isis addons' fakedata] module (non-ASF) does provide exactly this capability.
-
-[TIP]
-====
-Using fake data works very well with fixture scripts; the fixture script can invoke the business action with sensible (fake/random) defaults, and only require that the essential information is passed into it by the test.
-====
-
-
-
-
-== Feature Toggles
-
-Writing automated tests is just good development practice.  Also good practice is developing on the mainline (master, trunk); so that your continuous integration system really is integrating all code.  Said another way: link:http://martinfowler.com/bliki/FeatureBranch.html[don't use branches]!
-
-Sometimes, though, a feature will take longer to implement than your iteration cycle.  In such a case, how do you use continuous integration to keep everyone working on the mainline without revealing a half-implemented feature on your releases?  One option is to use link:http://martinfowler.com/bliki/FeatureToggle.html[feature toggle]s.
-
-Apache Isis does not, itself, ship with a feature toggle library.  However, the http://github.com/isisaddons/isis-module-togglz}[Isis addons' togglz] module (non-ASF) does provide exactly this capability.
-
-
-
-
-
-With all that said, let's look in detail at the testing features provided by Apache Isis.
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support.adoc
index 9a59a70..d18a486 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support.adoc
@@ -1,4 +1,4 @@
-= Unit Test Support
+= anchor:testing[]Unit Test Support
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_contract-tests.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_contract-tests.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_contract-tests.adoc
index 0de8cfd..a9150fb 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_contract-tests.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_contract-tests.adoc
@@ -1,4 +1,4 @@
-= Contract Tests
+= anchor:testing_unit-test-support[]Contract Tests
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_jmock-extensions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_jmock-extensions.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_jmock-extensions.adoc
index c58dcc3..7b9e3e33 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_jmock-extensions.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_jmock-extensions.adoc
@@ -1,4 +1,4 @@
-= JMock Extensions
+= anchor:testing_unit-test-support[]JMock Extensions
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_maven-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_maven-configuration.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_maven-configuration.adoc
index 5ed8f63..d678c51 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_maven-configuration.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_maven-configuration.adoc
@@ -1,10 +1,10 @@
-= Maven Configuration
+= anchor:testing_unit-test-support[]Maven Configuration
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/
 
 
-Apache Isis' unit test support is automatically configured if you use the xref:_simpleapp_archetype[SimpleApp archetype].  To set it up manually, update the `pom.xml` of your domain object model module:
+Apache Isis' unit test support is automatically configured if you use the xref:__a_id_getting_started_a_simpleapp_archetype[SimpleApp archetype].  To set it up manually, update the `pom.xml` of your domain object model module:
 
 [source,xml]
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_troubleshooting.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_troubleshooting.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_troubleshooting.adoc
index 994a048..5b2ebcc 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_troubleshooting.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_troubleshooting.adoc
@@ -1,4 +1,4 @@
-= Trouble Shooting
+= anchor:chapter[]Troubleshooting
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_troubleshooting_enabling-logging.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_troubleshooting_enabling-logging.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_troubleshooting_enabling-logging.adoc
index 0443cc2..1e35306 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_troubleshooting_enabling-logging.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_troubleshooting_enabling-logging.adoc
@@ -1,4 +1,4 @@
-= Enabling Logging
+= anchor:troubleshooting[]Enabling Logging
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/
@@ -17,7 +17,7 @@ As per the http://www.datanucleus.org/products/accessplatform/logging.html[DN lo
 
 Configure log4jdbc JDBC rather than the vanilla driver (see `WEB-INF/persistor_datanucleus.properties`) and configure log4j logging (see `WEB-INF/logging.properties`).
 
-There are examples of both in the xref:_simpleapp_archetype[SimpleApp archetype].
+There are examples of both in the xref:__a_id_getting_started_a_simpleapp_archetype[SimpleApp archetype].
 
 == In the Database
 

http://git-wip-us.apache.org/repos/asf/isis/blob/9ca96fbb/adocs/documentation/src/main/asciidoc/user-guide/_ug_tutorials.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_tutorials.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_tutorials.adoc
index 54fb016..116fd2a 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_tutorials.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_tutorials.adoc
@@ -1,4 +1,4 @@
-= Tutorials
+= anchor:chapter[]Tutorials
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 :_basedir: ../
 :_imagesdir: images/